From 668a5e506d1f4ffa9674a88d8ab551df3095ee03 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 17:25:05 +0800 Subject: [PATCH 01/10] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20plugin-f?= =?UTF-8?q?irst=20runtime=20rearchitecture=20=E2=80=94=20=E6=B6=88?= =?UTF-8?q?=E9=99=A4=20application/kernel/sdk=20crate=EF=BC=8C=E5=BB=BA?= =?UTF-8?q?=E7=AB=8B=20host-session=20/=20agent-runtime=20/=20plugin-host?= =?UTF-8?q?=20=E4=B8=89=E5=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除 kernel、sdk、application 三个 crate，将编排逻辑下沉至 server 组合根， 核心状态管理抽入新 host-session crate，turn loop 重构为独立 agent-runtime， 插件系统由 plugin-host 全部重写，替换旧 plugin crate。 core - 抽走 session_catalog / session_plan / workflow / projection / composer 到 host-session - 抽走 plugin/manifest、plugin/registry、projection 到对应新 crate - 新增 max_output_continuation_attempts 配置项（修复 max_consecutive_failures 误用为 continuation 限制的 bug） - 新增 prompt.rs 承接 system prompt 类型 session-runtime → agent-runtime - 重命名 crate，turn loop 由单一 TurnLoop struct 驱动 - 新增 TurnExecutionResources / TurnExecutionContext 分离无状态资源与可变状态 - 新增 hook_dispatch / tool_dispatch 抽象层 - output continuation 现由独立配置控制（默认 3 次，下限 1） application → server - 会话路由、terminal projection、conversation read model 全部迁入 server - HTTP 路由直接对接 session_catalog / agent_control_registry，不再经过 application 中间层 - 新增 AgentControlRegistry 管理代理树深度与并发限制 - 新增 session_runtime_port_adapter 适配 agent-runtime 接口 - 各 bootstrap 模块（capabilities、governance、plugins、providers）重写为直接组装 plugin → plugin-host - 全新插件生命周期：descriptor → backend plan → process spawn → negotiate → runtime catalog - 支持 builtin / external-process / http 三种 backend - 新增 descriptor / registry / snapshot / transport / host_dispatch 完整子系统 删除 - kernel crate（agent_tree、registry、gateway、surface 全部移入 server） - sdk crate（context、stream、hook、tool 迁入 plugin-host 或删除） - application crate（lib、session_use_cases、terminal、workflow 迁入 server） - plugin crate（loader、invoker、peer、supervisor 由 plugin-host 替代） - examples/example-plugin、examples/plugins/repo-inspector - session-runtime 大部分模块（actor、turn、state、query 由 agent-runtime + host-session 替代） docs / infra - PROJECT_ARCHITECTURE.md、AGENTS.md、CLAUDE.md 同步更新 - check-crate-boundaries.mjs 适配新 crate 图 - openspec 新增 plugin-first-runtime-rearchitecture change，归档旧 changes tests - agent-runtime loop：16 tests（含 continuation limit 回归测试） - adapter-llm dto：3 tests（OpenAI 消息序列化边界） - server mode compiler：3 tests（含 child fork mode 降级） - plugin-host：新增 host_tests.rs（3498 行覆盖 backend / registry / transport） --- AGENTS.md | 36 +- ASTRCODE_EXPLORATION_REPORT.md | 334 -- CLAUDE.md | 36 +- CODE_REVIEW_ISSUES.md | 94 + Cargo.lock | 81 +- Cargo.toml | 9 +- PROJECT_ARCHITECTURE.md | 404 +- README.md | 6 +- crates/adapter-llm/Cargo.toml | 1 + crates/adapter-llm/src/cache_tracker.rs | 2 +- crates/adapter-llm/src/lib.rs | 9 +- crates/adapter-llm/src/openai.rs | 520 ++- crates/adapter-llm/src/openai/dto.rs | 71 +- crates/adapter-mcp/Cargo.toml | 1 + crates/adapter-mcp/src/core_port.rs | 7 +- crates/adapter-prompt/Cargo.toml | 2 + crates/adapter-prompt/src/composer.rs | 3 +- crates/adapter-prompt/src/core_port.rs | 23 +- crates/adapter-prompt/src/layered_builder.rs | 2 +- crates/adapter-storage/Cargo.toml | 1 + .../src/session/batch_appender.rs | 3 +- .../adapter-storage/src/session/checkpoint.rs | 3 +- .../adapter-storage/src/session/repository.rs | 17 +- crates/adapter-tools/Cargo.toml | 1 + .../src/agent_tools/collaboration_executor.rs | 6 +- .../src/agent_tools/spawn_tool.rs | 5 +- crates/adapter-tools/src/agent_tools/tests.rs | 5 +- .../src/builtin_tools/exit_plan_mode.rs | 3 +- .../src/builtin_tools/session_plan.rs | 8 +- .../src/builtin_tools/upsert_session_plan.rs | 5 +- crates/adapter-tools/src/lib.rs | 2 +- .../Cargo.toml | 8 +- crates/agent-runtime/src/cancel.rs | 3 + .../src/context_window/compaction.rs | 165 +- .../src/context_window/compaction/protocol.rs | 41 +- .../src/context_window/compaction/sanitize.rs | 4 +- .../context_window/compaction/xml_parsing.rs | 0 .../src/context_window/file_access.rs | 115 +- .../src/context_window/micro_compact.rs | 187 + .../agent-runtime/src/context_window/mod.rs | 17 + .../src/context_window/prune_pass.rs | 100 + .../src/context_window/request.rs | 277 ++ .../src/context_window/settings.rs | 14 +- .../context_window/templates/compact/base.md | 0 .../templates/compact/incremental.md | 0 .../src/context_window/token_usage.rs | 149 + .../src/context_window}/tool_result_budget.rs | 299 +- .../src/context_window/tool_results.rs | 1 - crates/agent-runtime/src/hook_dispatch.rs | 69 + crates/agent-runtime/src/lib.rs | 38 + crates/agent-runtime/src/loop.rs | 1868 +++++++++ crates/agent-runtime/src/provider.rs | 189 + crates/agent-runtime/src/runtime.rs | 46 + crates/agent-runtime/src/stream.rs | 3 + crates/agent-runtime/src/tool_dispatch.rs | 22 + crates/agent-runtime/src/types.rs | 446 +++ crates/application/src/agent_use_cases.rs | 259 -- crates/application/src/composer/mod.rs | 181 - crates/application/src/execution/root.rs | 293 -- crates/application/src/lib.rs | 353 -- crates/application/src/ports/agent_kernel.rs | 235 -- crates/application/src/ports/agent_session.rs | 334 -- crates/application/src/ports/app_kernel.rs | 93 - crates/application/src/ports/app_session.rs | 283 -- .../src/ports/session_contracts.rs | 54 - crates/application/src/session_identity.rs | 11 - crates/application/src/session_plan.rs | 1058 ----- crates/application/src/session_use_cases.rs | 1353 ------- crates/application/src/terminal/contracts.rs | 269 -- crates/application/src/terminal/mod.rs | 328 -- .../src/terminal/runtime_mapping.rs | 621 --- .../src/terminal/stream_projection.rs | 71 - .../src/terminal_queries/cursor.rs | 43 - .../application/src/terminal_queries/mod.rs | 36 - .../src/terminal_queries/resume.rs | 317 -- .../src/terminal_queries/snapshot.rs | 130 - .../src/terminal_queries/summary.rs | 87 - .../application/src/terminal_queries/tests.rs | 756 ---- crates/application/src/test_support.rs | 430 -- crates/application/src/watch/mod.rs | 122 - crates/application/src/workflow/bridge.rs | 118 - crates/application/src/workflow/compiler.rs | 255 -- crates/application/src/workflow/definition.rs | 94 - crates/application/src/workflow/mod.rs | 19 - .../application/src/workflow/orchestrator.rs | 329 -- crates/application/src/workflow/service.rs | 596 --- crates/application/src/workflow/state.rs | 176 - crates/core/src/action.rs | 4 +- crates/core/src/agent/executor.rs | 40 - crates/core/src/agent/lifecycle.rs | 8 +- crates/core/src/agent/mod.rs | 3 +- crates/core/src/config.rs | 19 + crates/core/src/event/domain.rs | 8 + crates/core/src/event/types.rs | 8 +- crates/core/src/hook.rs | 98 +- crates/core/src/lib.rs | 163 +- crates/core/src/plugin/manifest.rs | 53 - crates/core/src/plugin/mod.rs | 14 - crates/core/src/plugin/registry.rs | 409 -- crates/core/src/ports.rs | 626 +-- crates/core/src/projection/mod.rs | 9 - crates/core/src/prompt.rs | 125 + crates/core/src/runtime/traits.rs | 4 +- .../{application => host-session}/Cargo.toml | 12 +- .../src/turn => host-session/src}/branch.rs | 124 +- crates/host-session/src/catalog.rs | 563 +++ crates/host-session/src/child_sessions.rs | 27 + crates/host-session/src/collaboration.rs | 398 ++ crates/host-session/src/compaction.rs | 89 + crates/{core => host-session}/src/composer.rs | 2 +- .../src/event_cache.rs} | 0 .../src/event_log.rs} | 14 +- crates/host-session/src/execution_surface.rs | 40 + crates/host-session/src/fork.rs | 285 ++ crates/host-session/src/input_queue.rs | 169 + crates/host-session/src/lib.rs | 73 + crates/host-session/src/model_selection.rs | 150 + crates/host-session/src/ports.rs | 294 ++ .../src/projection.rs} | 63 +- .../src}/projection_registry.rs | 29 +- crates/host-session/src/query.rs | 532 +++ .../src/session_catalog.rs | 0 .../src/session_plan.rs | 2 +- crates/host-session/src/state.rs | 492 +++ crates/host-session/src/tasks.rs | 49 + crates/host-session/src/turn_mutation.rs | 1314 +++++++ crates/host-session/src/turn_projection.rs | 36 + crates/{core => host-session}/src/workflow.rs | 5 +- crates/kernel/Cargo.toml | 15 - crates/kernel/src/agent_surface.rs | 348 -- crates/kernel/src/agent_tree/mod.rs | 949 ----- crates/kernel/src/agent_tree/state.rs | 88 - crates/kernel/src/agent_tree/tests.rs | 1810 --------- crates/kernel/src/error.rs | 23 - crates/kernel/src/events/mod.rs | 28 - crates/kernel/src/gateway/mod.rs | 104 - crates/kernel/src/kernel.rs | 111 - crates/kernel/src/lib.rs | 20 - crates/kernel/src/registry/mod.rs | 7 - crates/kernel/src/registry/router.rs | 345 -- crates/kernel/src/registry/tool.rs | 426 -- crates/kernel/src/surface/mod.rs | 134 - crates/{plugin => plugin-host}/Cargo.toml | 7 +- crates/plugin-host/src/backend.rs | 806 ++++ crates/plugin-host/src/descriptor.rs | 404 ++ crates/plugin-host/src/hooks.rs | 323 ++ crates/plugin-host/src/host.rs | 320 ++ crates/plugin-host/src/host_catalog.rs | 292 ++ crates/plugin-host/src/host_dispatch.rs | 447 +++ crates/plugin-host/src/host_reload.rs | 655 +++ crates/plugin-host/src/host_tests.rs | 3498 +++++++++++++++++ crates/plugin-host/src/lib.rs | 69 + crates/plugin-host/src/loader.rs | 323 ++ crates/plugin-host/src/manifest.rs | 80 + crates/plugin-host/src/modes.rs | 13 + crates/plugin-host/src/protocol.rs | 272 ++ crates/plugin-host/src/providers.rs | 105 + crates/plugin-host/src/registry.rs | 414 ++ crates/plugin-host/src/resource_provider.rs | 64 + crates/plugin-host/src/resources.rs | 347 ++ crates/plugin-host/src/snapshot.rs | 79 + crates/plugin-host/src/tools.rs | 169 + crates/plugin-host/src/transport.rs | 506 +++ crates/plugin/src/bin/fixture_worker.rs | 142 - crates/plugin/src/capability_mapping.rs | 66 - crates/plugin/src/capability_router.rs | 308 -- crates/plugin/src/invoker.rs | 280 -- crates/plugin/src/lib.rs | 83 - crates/plugin/src/loader.rs | 190 - crates/plugin/src/peer.rs | 916 ----- crates/plugin/src/process.rs | 130 - crates/plugin/src/streaming.rs | 117 - crates/plugin/src/supervisor.rs | 313 -- crates/plugin/src/transport/mod.rs | 27 - crates/plugin/src/transport/stdio.rs | 108 - crates/plugin/src/worker.rs | 84 - crates/plugin/tests/v4_stdio_e2e.rs | 295 -- crates/protocol/src/http/composer.rs | 42 +- crates/protocol/src/http/event.rs | 9 +- crates/protocol/src/http/runtime.rs | 22 +- crates/protocol/src/http/session_event.rs | 24 +- crates/sdk/Cargo.toml | 13 - crates/sdk/src/context.rs | 190 - crates/sdk/src/error.rs | 340 -- crates/sdk/src/hook.rs | 298 -- crates/sdk/src/lib.rs | 84 - crates/sdk/src/stream.rs | 177 - crates/sdk/src/tests.rs | 245 -- crates/sdk/src/tool.rs | 267 -- crates/server/Cargo.toml | 8 +- .../src/agent/context.rs | 47 +- .../{application => server}/src/agent/mod.rs | 24 +- .../src/agent/observe.rs | 17 +- .../src/agent/routing.rs | 3 +- .../src/agent/routing/child_send.rs | 5 +- .../src/agent/routing/parent_delivery.rs | 0 .../src/agent/routing/tests.rs | 29 +- .../src/agent/routing_collaboration_flow.rs | 2 +- .../src/agent/terminal.rs | 50 +- .../src/agent/test_support.rs | 303 +- .../{application => server}/src/agent/wake.rs | 33 +- crates/server/src/agent_control_bridge.rs | 56 + .../agent_control_registry}/delivery_queue.rs | 76 +- .../server/src/agent_control_registry/mod.rs | 533 +++ .../src/agent_control_registry/state.rs | 66 + .../src/agent_control_registry}/tree_ops.rs | 79 +- crates/server/src/agent_runtime_bridge.rs | 211 + crates/server/src/application_error_bridge.rs | 67 + crates/server/src/bootstrap/capabilities.rs | 226 +- .../server/src/bootstrap/composer_skills.rs | 44 - crates/server/src/bootstrap/deps.rs | 4 +- crates/server/src/bootstrap/governance.rs | 339 +- crates/server/src/bootstrap/mcp.rs | 122 +- crates/server/src/bootstrap/mod.rs | 4 +- crates/server/src/bootstrap/plugins.rs | 648 ++- crates/server/src/bootstrap/prompt_facts.rs | 308 -- crates/server/src/bootstrap/providers.rs | 278 +- crates/server/src/bootstrap/runtime.rs | 458 ++- .../src/bootstrap/runtime_coordinator.rs | 33 +- crates/server/src/bootstrap/watch.rs | 92 +- crates/server/src/capability_router.rs | 201 + .../src/config/api_key.rs | 0 .../src/config/constants.rs | 25 +- .../src/config/env_resolver.rs | 1 + .../{application => server}/src/config/mcp.rs | 0 .../{application => server}/src/config/mod.rs | 50 +- .../src/config/selection.rs | 11 +- .../src/config/test_support.rs | 0 .../src/config/validation.rs | 70 +- crates/server/src/config_mode_helpers.rs | 306 ++ crates/server/src/config_service_bridge.rs | 175 + .../src/conversation_read_model.rs} | 695 +++- .../src/conversation_read_model}/facts.rs | 70 +- .../plan_projection.rs | 2 + crates/{application => server}/src/errors.rs | 0 .../src/execution/control.rs | 0 .../src/execution/mod.rs | 2 - .../src/execution/profiles.rs | 1 + .../src/execution/subagent.rs | 20 +- crates/server/src/governance_service.rs | 76 + .../src/governance_surface/assembler.rs | 90 +- .../src/governance_surface/inherited.rs | 5 +- .../src/governance_surface/mod.rs | 12 +- .../src/governance_surface/policy.rs | 1 + .../src/governance_surface/prompt.rs | 0 .../src/governance_surface/tests.rs | 238 +- crates/server/src/http/agent_api.rs | 308 ++ crates/server/src/http/composer_catalog.rs | 181 + crates/server/src/http/mapper.rs | 197 +- crates/server/src/http/routes/agents.rs | 33 +- crates/server/src/http/routes/composer.rs | 29 +- crates/server/src/http/routes/config.rs | 33 +- crates/server/src/http/routes/conversation.rs | 750 +++- crates/server/src/http/routes/mcp.rs | 52 +- crates/server/src/http/routes/model.rs | 7 +- .../src/http/routes/sessions/mutation.rs | 275 +- .../server/src/http/routes/sessions/query.rs | 17 +- .../server/src/http/routes/sessions/stream.rs | 2 +- crates/server/src/http/terminal_projection.rs | 716 +++- .../src/lifecycle/governance.rs | 25 +- .../src/lifecycle/mod.rs | 9 +- crates/server/src/main.rs | 204 +- crates/{application => server}/src/mcp/mod.rs | 0 crates/server/src/mcp_service.rs | 148 + .../src/mode/builtin_prompts.rs | 0 .../src/mode/builtin_prompts/plan_mode.md | 0 .../mode/builtin_prompts/plan_mode_exit.md | 0 .../mode/builtin_prompts/plan_mode_reentry.md | 0 .../src/mode/builtin_prompts/plan_template.md | 0 .../src/mode/catalog.rs | 2 + .../src/mode/compiler.rs | 180 +- .../{application => server}/src/mode/mod.rs | 12 +- .../src/mode/validator.rs | 0 crates/server/src/mode_catalog_service.rs | 140 + .../src/observability/collector.rs | 0 .../src/observability/metrics_snapshot.rs | 3 +- .../src/observability/mod.rs | 216 +- crates/server/src/ports/agent_kernel.rs | 79 + crates/server/src/ports/agent_session.rs | 131 + crates/server/src/ports/app_kernel.rs | 58 + crates/server/src/ports/app_session.rs | 105 + .../src/ports/composer_skill.rs | 0 crates/server/src/ports/kernel_bridge.rs | 287 ++ .../{application => server}/src/ports/mod.rs | 13 +- crates/server/src/ports/session_bridge.rs | 874 ++++ crates/server/src/ports/session_contracts.rs | 89 + .../src/ports/session_submission.rs | 26 +- crates/server/src/profile_service.rs | 64 + crates/server/src/root_execute_service.rs | 407 ++ crates/server/src/runtime_owner_bridge.rs | 158 + crates/server/src/session_identity.rs | 13 + .../src/session_runtime_owner_bridge.rs | 154 + .../src/session_runtime_owner_bridge_impl.rs | 254 ++ crates/server/src/session_runtime_port.rs | 145 + .../src/session_runtime_port_adapter.rs | 1343 +++++++ crates/server/src/session_use_cases.rs | 11 + crates/server/src/tests/agent_routes_tests.rs | 150 +- .../server/src/tests/composer_routes_tests.rs | 10 +- .../server/src/tests/config_routes_tests.rs | 148 +- .../src/tests/session_contract_tests.rs | 79 +- crates/server/src/tests/test_support.rs | 494 ++- crates/server/src/tool_capability_invoker.rs | 215 + crates/server/src/view_projection.rs | 193 + crates/server/src/watch_service.rs | 75 + crates/session-runtime/src/actor/mod.rs | 395 -- crates/session-runtime/src/catalog/mod.rs | 6 - .../src/command/input_queue.rs | 112 - crates/session-runtime/src/command/mod.rs | 233 -- .../src/context_window/compaction/tests.rs | 574 --- .../src/context_window/micro_compact.rs | 422 -- .../session-runtime/src/context_window/mod.rs | 22 - .../src/context_window/prune_pass.rs | 229 -- .../src/context_window/token_usage.rs | 259 -- crates/session-runtime/src/heuristics.rs | 10 - crates/session-runtime/src/identity.rs | 9 - crates/session-runtime/src/lib.rs | 621 --- crates/session-runtime/src/observe/mod.rs | 55 - crates/session-runtime/src/query/agent.rs | 191 - .../query/conversation/projection_support.rs | 473 --- .../src/query/conversation/tests.rs | 1172 ------ .../session-runtime/src/query/input_queue.rs | 167 - crates/session-runtime/src/query/mod.rs | 35 - crates/session-runtime/src/query/replay.rs | 72 - crates/session-runtime/src/query/service.rs | 493 --- crates/session-runtime/src/query/subrun.rs | 298 -- crates/session-runtime/src/query/terminal.rs | 29 - crates/session-runtime/src/query/text.rs | 45 - .../session-runtime/src/query/transcript.rs | 43 - crates/session-runtime/src/query/turn.rs | 238 -- .../src/state/child_sessions.rs | 122 - .../session-runtime/src/state/compaction.rs | 254 -- crates/session-runtime/src/state/execution.rs | 91 - .../session-runtime/src/state/input_queue.rs | 396 -- crates/session-runtime/src/state/mod.rs | 482 --- crates/session-runtime/src/state/paths.rs | 176 - crates/session-runtime/src/state/tasks.rs | 261 -- .../session-runtime/src/state/test_support.rs | 162 - .../src/turn/compact_events.rs | 129 - .../src/turn/compaction_cycle.rs | 265 -- .../src/turn/continuation_cycle.rs | 76 - crates/session-runtime/src/turn/events.rs | 740 ---- crates/session-runtime/src/turn/finalize.rs | 222 -- crates/session-runtime/src/turn/fork.rs | 430 -- crates/session-runtime/src/turn/interrupt.rs | 233 -- crates/session-runtime/src/turn/journal.rs | 39 - crates/session-runtime/src/turn/llm_cycle.rs | 409 -- .../session-runtime/src/turn/loop_control.rs | 58 - .../src/turn/manual_compact.rs | 289 -- crates/session-runtime/src/turn/mod.rs | 65 - .../src/turn/post_llm_policy.rs | 166 - crates/session-runtime/src/turn/projector.rs | 198 - crates/session-runtime/src/turn/request.rs | 949 ----- crates/session-runtime/src/turn/runner.rs | 581 --- .../src/turn/runner/step/driver.rs | 166 - .../src/turn/runner/step/llm_step.rs | 82 - .../src/turn/runner/step/mod.rs | 217 - .../src/turn/runner/step/streaming_tools.rs | 508 --- .../src/turn/runner/step/tests.rs | 1573 -------- .../src/turn/runner/step/tool_execution.rs | 236 -- crates/session-runtime/src/turn/runtime.rs | 524 --- crates/session-runtime/src/turn/submit.rs | 1431 ------- .../session-runtime/src/turn/subrun_events.rs | 218 - crates/session-runtime/src/turn/summary.rs | 246 -- .../session-runtime/src/turn/test_support.rs | 628 --- crates/session-runtime/src/turn/tool_cycle.rs | 1304 ------ crates/session-runtime/src/turn/watcher.rs | 482 --- "docs/ideas/\346\212\275\347\246\273.md" | 2 + examples/example-plugin/Cargo.toml | 15 - examples/example-plugin/src/main.rs | 291 -- examples/plugins/repo-inspector/README.md | 39 - examples/plugins/repo-inspector/plugin.toml | 34 - .../changes/hooks-platform/.openspec.yaml | 2 - openspec/changes/hooks-platform/proposal.md | 93 - .../.openspec.yaml | 2 + .../design.md | 602 +++ .../dto.md | 669 ++++ .../proposal.md | 342 ++ .../research.md | 421 ++ .../specs/agent-runtime-core/spec.md | 64 + .../specs/application-use-cases/spec.md | 19 + .../specs/core-boundary-slimming/spec.md | 78 + .../specs/host-session-runtime/spec.md | 51 + .../specs/lifecycle-hooks-platform/spec.md | 148 + .../specs/plugin-host-runtime/spec.md | 74 + .../specs/plugin-integration/spec.md | 37 + .../specs/session-persistence/spec.md | 19 + .../specs/session-runtime/spec.md | 13 + .../specs/tool-and-skill-discovery/spec.md | 19 + .../specs/turn-orchestration/spec.md | 19 + .../tasks.md | 531 +++ .../.openspec.yaml | 2 - .../design.md | 195 - .../proposal.md | 44 - .../specs/governance-mode-system/spec.md | 89 - .../specs/governance-reload-surface/spec.md | 31 - .../specs/mode-capability-compilation/spec.md | 34 - .../specs/mode-prompt-program/spec.md | 40 - .../workflow-phase-orchestration/spec.md | 56 - .../tasks.md | 47 - openspec/config.yaml | 44 +- openspec/schemas/my-workflow/schema.yaml | 210 + .../schemas/my-workflow/templates/design.md | 48 + openspec/schemas/my-workflow/templates/dto.md | 47 + .../schemas/my-workflow/templates/proposal.md | 33 + .../schemas/my-workflow/templates/research.md | 47 + .../schemas/my-workflow/templates/spec.md | 38 + .../schemas/my-workflow/templates/tasks.md | 14 + scripts/check-crate-boundaries.mjs | 48 +- 408 files changed, 34930 insertions(+), 45451 deletions(-) delete mode 100644 ASTRCODE_EXPLORATION_REPORT.md create mode 100644 CODE_REVIEW_ISSUES.md rename crates/{session-runtime => agent-runtime}/Cargo.toml (70%) create mode 100644 crates/agent-runtime/src/cancel.rs rename crates/{session-runtime => agent-runtime}/src/context_window/compaction.rs (83%) rename crates/{session-runtime => agent-runtime}/src/context_window/compaction/protocol.rs (84%) rename crates/{session-runtime => agent-runtime}/src/context_window/compaction/sanitize.rs (98%) rename crates/{session-runtime => agent-runtime}/src/context_window/compaction/xml_parsing.rs (100%) rename crates/{session-runtime => agent-runtime}/src/context_window/file_access.rs (63%) create mode 100644 crates/agent-runtime/src/context_window/micro_compact.rs create mode 100644 crates/agent-runtime/src/context_window/mod.rs create mode 100644 crates/agent-runtime/src/context_window/prune_pass.rs create mode 100644 crates/agent-runtime/src/context_window/request.rs rename crates/{session-runtime => agent-runtime}/src/context_window/settings.rs (81%) rename crates/{session-runtime => agent-runtime}/src/context_window/templates/compact/base.md (100%) rename crates/{session-runtime => agent-runtime}/src/context_window/templates/compact/incremental.md (100%) create mode 100644 crates/agent-runtime/src/context_window/token_usage.rs rename crates/{session-runtime/src/turn => agent-runtime/src/context_window}/tool_result_budget.rs (53%) rename crates/{session-runtime => agent-runtime}/src/context_window/tool_results.rs (84%) create mode 100644 crates/agent-runtime/src/hook_dispatch.rs create mode 100644 crates/agent-runtime/src/lib.rs create mode 100644 crates/agent-runtime/src/loop.rs create mode 100644 crates/agent-runtime/src/provider.rs create mode 100644 crates/agent-runtime/src/runtime.rs create mode 100644 crates/agent-runtime/src/stream.rs create mode 100644 crates/agent-runtime/src/tool_dispatch.rs create mode 100644 crates/agent-runtime/src/types.rs delete mode 100644 crates/application/src/agent_use_cases.rs delete mode 100644 crates/application/src/composer/mod.rs delete mode 100644 crates/application/src/execution/root.rs delete mode 100644 crates/application/src/lib.rs delete mode 100644 crates/application/src/ports/agent_kernel.rs delete mode 100644 crates/application/src/ports/agent_session.rs delete mode 100644 crates/application/src/ports/app_kernel.rs delete mode 100644 crates/application/src/ports/app_session.rs delete mode 100644 crates/application/src/ports/session_contracts.rs delete mode 100644 crates/application/src/session_identity.rs delete mode 100644 crates/application/src/session_plan.rs delete mode 100644 crates/application/src/session_use_cases.rs delete mode 100644 crates/application/src/terminal/contracts.rs delete mode 100644 crates/application/src/terminal/mod.rs delete mode 100644 crates/application/src/terminal/runtime_mapping.rs delete mode 100644 crates/application/src/terminal/stream_projection.rs delete mode 100644 crates/application/src/terminal_queries/cursor.rs delete mode 100644 crates/application/src/terminal_queries/mod.rs delete mode 100644 crates/application/src/terminal_queries/resume.rs delete mode 100644 crates/application/src/terminal_queries/snapshot.rs delete mode 100644 crates/application/src/terminal_queries/summary.rs delete mode 100644 crates/application/src/terminal_queries/tests.rs delete mode 100644 crates/application/src/test_support.rs delete mode 100644 crates/application/src/watch/mod.rs delete mode 100644 crates/application/src/workflow/bridge.rs delete mode 100644 crates/application/src/workflow/compiler.rs delete mode 100644 crates/application/src/workflow/definition.rs delete mode 100644 crates/application/src/workflow/mod.rs delete mode 100644 crates/application/src/workflow/orchestrator.rs delete mode 100644 crates/application/src/workflow/service.rs delete mode 100644 crates/application/src/workflow/state.rs delete mode 100644 crates/core/src/agent/executor.rs delete mode 100644 crates/core/src/plugin/manifest.rs delete mode 100644 crates/core/src/plugin/mod.rs delete mode 100644 crates/core/src/plugin/registry.rs delete mode 100644 crates/core/src/projection/mod.rs create mode 100644 crates/core/src/prompt.rs rename crates/{application => host-session}/Cargo.toml (56%) rename crates/{session-runtime/src/turn => host-session/src}/branch.rs (65%) create mode 100644 crates/host-session/src/catalog.rs create mode 100644 crates/host-session/src/child_sessions.rs create mode 100644 crates/host-session/src/collaboration.rs create mode 100644 crates/host-session/src/compaction.rs rename crates/{core => host-session}/src/composer.rs (94%) rename crates/{session-runtime/src/state/cache.rs => host-session/src/event_cache.rs} (100%) rename crates/{session-runtime/src/state/writer.rs => host-session/src/event_log.rs} (84%) create mode 100644 crates/host-session/src/execution_surface.rs create mode 100644 crates/host-session/src/fork.rs create mode 100644 crates/host-session/src/input_queue.rs create mode 100644 crates/host-session/src/lib.rs create mode 100644 crates/host-session/src/model_selection.rs create mode 100644 crates/host-session/src/ports.rs rename crates/{core/src/projection/agent_state.rs => host-session/src/projection.rs} (95%) rename crates/{session-runtime/src/state => host-session/src}/projection_registry.rs (93%) create mode 100644 crates/host-session/src/query.rs rename crates/{core => host-session}/src/session_catalog.rs (100%) rename crates/{core => host-session}/src/session_plan.rs (95%) create mode 100644 crates/host-session/src/state.rs create mode 100644 crates/host-session/src/tasks.rs create mode 100644 crates/host-session/src/turn_mutation.rs create mode 100644 crates/host-session/src/turn_projection.rs rename crates/{core => host-session}/src/workflow.rs (99%) delete mode 100644 crates/kernel/Cargo.toml delete mode 100644 crates/kernel/src/agent_surface.rs delete mode 100644 crates/kernel/src/agent_tree/mod.rs delete mode 100644 crates/kernel/src/agent_tree/state.rs delete mode 100644 crates/kernel/src/agent_tree/tests.rs delete mode 100644 crates/kernel/src/error.rs delete mode 100644 crates/kernel/src/events/mod.rs delete mode 100644 crates/kernel/src/gateway/mod.rs delete mode 100644 crates/kernel/src/kernel.rs delete mode 100644 crates/kernel/src/lib.rs delete mode 100644 crates/kernel/src/registry/mod.rs delete mode 100644 crates/kernel/src/registry/router.rs delete mode 100644 crates/kernel/src/registry/tool.rs delete mode 100644 crates/kernel/src/surface/mod.rs rename crates/{plugin => plugin-host}/Cargo.toml (82%) create mode 100644 crates/plugin-host/src/backend.rs create mode 100644 crates/plugin-host/src/descriptor.rs create mode 100644 crates/plugin-host/src/hooks.rs create mode 100644 crates/plugin-host/src/host.rs create mode 100644 crates/plugin-host/src/host_catalog.rs create mode 100644 crates/plugin-host/src/host_dispatch.rs create mode 100644 crates/plugin-host/src/host_reload.rs create mode 100644 crates/plugin-host/src/host_tests.rs create mode 100644 crates/plugin-host/src/lib.rs create mode 100644 crates/plugin-host/src/loader.rs create mode 100644 crates/plugin-host/src/manifest.rs create mode 100644 crates/plugin-host/src/modes.rs create mode 100644 crates/plugin-host/src/protocol.rs create mode 100644 crates/plugin-host/src/providers.rs create mode 100644 crates/plugin-host/src/registry.rs create mode 100644 crates/plugin-host/src/resource_provider.rs create mode 100644 crates/plugin-host/src/resources.rs create mode 100644 crates/plugin-host/src/snapshot.rs create mode 100644 crates/plugin-host/src/tools.rs create mode 100644 crates/plugin-host/src/transport.rs delete mode 100644 crates/plugin/src/bin/fixture_worker.rs delete mode 100644 crates/plugin/src/capability_mapping.rs delete mode 100644 crates/plugin/src/capability_router.rs delete mode 100644 crates/plugin/src/invoker.rs delete mode 100644 crates/plugin/src/lib.rs delete mode 100644 crates/plugin/src/loader.rs delete mode 100644 crates/plugin/src/peer.rs delete mode 100644 crates/plugin/src/process.rs delete mode 100644 crates/plugin/src/streaming.rs delete mode 100644 crates/plugin/src/supervisor.rs delete mode 100644 crates/plugin/src/transport/mod.rs delete mode 100644 crates/plugin/src/transport/stdio.rs delete mode 100644 crates/plugin/src/worker.rs delete mode 100644 crates/plugin/tests/v4_stdio_e2e.rs delete mode 100644 crates/sdk/Cargo.toml delete mode 100644 crates/sdk/src/context.rs delete mode 100644 crates/sdk/src/error.rs delete mode 100644 crates/sdk/src/hook.rs delete mode 100644 crates/sdk/src/lib.rs delete mode 100644 crates/sdk/src/stream.rs delete mode 100644 crates/sdk/src/tests.rs delete mode 100644 crates/sdk/src/tool.rs rename crates/{application => server}/src/agent/context.rs (94%) rename crates/{application => server}/src/agent/mod.rs (98%) rename crates/{application => server}/src/agent/observe.rs (98%) rename crates/{application => server}/src/agent/routing.rs (99%) rename crates/{application => server}/src/agent/routing/child_send.rs (98%) rename crates/{application => server}/src/agent/routing/parent_delivery.rs (100%) rename crates/{application => server}/src/agent/routing/tests.rs (98%) rename crates/{application => server}/src/agent/routing_collaboration_flow.rs (99%) rename crates/{application => server}/src/agent/terminal.rs (98%) rename crates/{application => server}/src/agent/test_support.rs (66%) rename crates/{application => server}/src/agent/wake.rs (98%) create mode 100644 crates/server/src/agent_control_bridge.rs rename crates/{kernel/src/agent_tree => server/src/agent_control_registry}/delivery_queue.rs (61%) create mode 100644 crates/server/src/agent_control_registry/mod.rs create mode 100644 crates/server/src/agent_control_registry/state.rs rename crates/{kernel/src/agent_tree => server/src/agent_control_registry}/tree_ops.rs (67%) create mode 100644 crates/server/src/agent_runtime_bridge.rs create mode 100644 crates/server/src/application_error_bridge.rs delete mode 100644 crates/server/src/bootstrap/composer_skills.rs delete mode 100644 crates/server/src/bootstrap/prompt_facts.rs create mode 100644 crates/server/src/capability_router.rs rename crates/{application => server}/src/config/api_key.rs (100%) rename crates/{application => server}/src/config/constants.rs (88%) rename crates/{application => server}/src/config/env_resolver.rs (99%) rename crates/{application => server}/src/config/mcp.rs (100%) rename crates/{application => server}/src/config/mod.rs (85%) rename crates/{application => server}/src/config/selection.rs (97%) rename crates/{application => server}/src/config/test_support.rs (100%) rename crates/{application => server}/src/config/validation.rs (86%) create mode 100644 crates/server/src/config_mode_helpers.rs create mode 100644 crates/server/src/config_service_bridge.rs rename crates/{session-runtime/src/query/conversation.rs => server/src/conversation_read_model.rs} (61%) rename crates/{session-runtime/src/query/conversation => server/src/conversation_read_model}/facts.rs (80%) rename crates/{session-runtime/src/query/conversation => server/src/conversation_read_model}/plan_projection.rs (99%) rename crates/{application => server}/src/errors.rs (100%) rename crates/{application => server}/src/execution/control.rs (100%) rename crates/{application => server}/src/execution/mod.rs (95%) rename crates/{application => server}/src/execution/profiles.rs (99%) rename crates/{application => server}/src/execution/subagent.rs (94%) create mode 100644 crates/server/src/governance_service.rs rename crates/{application => server}/src/governance_surface/assembler.rs (73%) rename crates/{application => server}/src/governance_surface/inherited.rs (96%) rename crates/{application => server}/src/governance_surface/mod.rs (96%) rename crates/{application => server}/src/governance_surface/policy.rs (99%) rename crates/{application => server}/src/governance_surface/prompt.rs (100%) rename crates/{application => server}/src/governance_surface/tests.rs (54%) create mode 100644 crates/server/src/http/agent_api.rs create mode 100644 crates/server/src/http/composer_catalog.rs rename crates/{application => server}/src/lifecycle/governance.rs (87%) rename crates/{application => server}/src/lifecycle/mod.rs (86%) rename crates/{application => server}/src/mcp/mod.rs (100%) create mode 100644 crates/server/src/mcp_service.rs rename crates/{application => server}/src/mode/builtin_prompts.rs (100%) rename crates/{application => server}/src/mode/builtin_prompts/plan_mode.md (100%) rename crates/{application => server}/src/mode/builtin_prompts/plan_mode_exit.md (100%) rename crates/{application => server}/src/mode/builtin_prompts/plan_mode_reentry.md (100%) rename crates/{application => server}/src/mode/builtin_prompts/plan_template.md (100%) rename crates/{application => server}/src/mode/catalog.rs (99%) rename crates/{application => server}/src/mode/compiler.rs (69%) rename crates/{application => server}/src/mode/mod.rs (66%) rename crates/{application => server}/src/mode/validator.rs (100%) create mode 100644 crates/server/src/mode_catalog_service.rs rename crates/{application => server}/src/observability/collector.rs (100%) rename crates/{application => server}/src/observability/metrics_snapshot.rs (75%) rename crates/{application => server}/src/observability/mod.rs (66%) create mode 100644 crates/server/src/ports/agent_kernel.rs create mode 100644 crates/server/src/ports/agent_session.rs create mode 100644 crates/server/src/ports/app_kernel.rs create mode 100644 crates/server/src/ports/app_session.rs rename crates/{application => server}/src/ports/composer_skill.rs (100%) create mode 100644 crates/server/src/ports/kernel_bridge.rs rename crates/{application => server}/src/ports/mod.rs (67%) create mode 100644 crates/server/src/ports/session_bridge.rs create mode 100644 crates/server/src/ports/session_contracts.rs rename crates/{application => server}/src/ports/session_submission.rs (50%) create mode 100644 crates/server/src/profile_service.rs create mode 100644 crates/server/src/root_execute_service.rs create mode 100644 crates/server/src/runtime_owner_bridge.rs create mode 100644 crates/server/src/session_identity.rs create mode 100644 crates/server/src/session_runtime_owner_bridge.rs create mode 100644 crates/server/src/session_runtime_owner_bridge_impl.rs create mode 100644 crates/server/src/session_runtime_port.rs create mode 100644 crates/server/src/session_runtime_port_adapter.rs create mode 100644 crates/server/src/session_use_cases.rs create mode 100644 crates/server/src/tool_capability_invoker.rs create mode 100644 crates/server/src/view_projection.rs create mode 100644 crates/server/src/watch_service.rs delete mode 100644 crates/session-runtime/src/actor/mod.rs delete mode 100644 crates/session-runtime/src/catalog/mod.rs delete mode 100644 crates/session-runtime/src/command/input_queue.rs delete mode 100644 crates/session-runtime/src/command/mod.rs delete mode 100644 crates/session-runtime/src/context_window/compaction/tests.rs delete mode 100644 crates/session-runtime/src/context_window/micro_compact.rs delete mode 100644 crates/session-runtime/src/context_window/mod.rs delete mode 100644 crates/session-runtime/src/context_window/prune_pass.rs delete mode 100644 crates/session-runtime/src/context_window/token_usage.rs delete mode 100644 crates/session-runtime/src/heuristics.rs delete mode 100644 crates/session-runtime/src/identity.rs delete mode 100644 crates/session-runtime/src/lib.rs delete mode 100644 crates/session-runtime/src/observe/mod.rs delete mode 100644 crates/session-runtime/src/query/agent.rs delete mode 100644 crates/session-runtime/src/query/conversation/projection_support.rs delete mode 100644 crates/session-runtime/src/query/conversation/tests.rs delete mode 100644 crates/session-runtime/src/query/input_queue.rs delete mode 100644 crates/session-runtime/src/query/mod.rs delete mode 100644 crates/session-runtime/src/query/replay.rs delete mode 100644 crates/session-runtime/src/query/service.rs delete mode 100644 crates/session-runtime/src/query/subrun.rs delete mode 100644 crates/session-runtime/src/query/terminal.rs delete mode 100644 crates/session-runtime/src/query/text.rs delete mode 100644 crates/session-runtime/src/query/transcript.rs delete mode 100644 crates/session-runtime/src/query/turn.rs delete mode 100644 crates/session-runtime/src/state/child_sessions.rs delete mode 100644 crates/session-runtime/src/state/compaction.rs delete mode 100644 crates/session-runtime/src/state/execution.rs delete mode 100644 crates/session-runtime/src/state/input_queue.rs delete mode 100644 crates/session-runtime/src/state/mod.rs delete mode 100644 crates/session-runtime/src/state/paths.rs delete mode 100644 crates/session-runtime/src/state/tasks.rs delete mode 100644 crates/session-runtime/src/state/test_support.rs delete mode 100644 crates/session-runtime/src/turn/compact_events.rs delete mode 100644 crates/session-runtime/src/turn/compaction_cycle.rs delete mode 100644 crates/session-runtime/src/turn/continuation_cycle.rs delete mode 100644 crates/session-runtime/src/turn/events.rs delete mode 100644 crates/session-runtime/src/turn/finalize.rs delete mode 100644 crates/session-runtime/src/turn/fork.rs delete mode 100644 crates/session-runtime/src/turn/interrupt.rs delete mode 100644 crates/session-runtime/src/turn/journal.rs delete mode 100644 crates/session-runtime/src/turn/llm_cycle.rs delete mode 100644 crates/session-runtime/src/turn/loop_control.rs delete mode 100644 crates/session-runtime/src/turn/manual_compact.rs delete mode 100644 crates/session-runtime/src/turn/mod.rs delete mode 100644 crates/session-runtime/src/turn/post_llm_policy.rs delete mode 100644 crates/session-runtime/src/turn/projector.rs delete mode 100644 crates/session-runtime/src/turn/request.rs delete mode 100644 crates/session-runtime/src/turn/runner.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/driver.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/llm_step.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/mod.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/streaming_tools.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/tests.rs delete mode 100644 crates/session-runtime/src/turn/runner/step/tool_execution.rs delete mode 100644 crates/session-runtime/src/turn/runtime.rs delete mode 100644 crates/session-runtime/src/turn/submit.rs delete mode 100644 crates/session-runtime/src/turn/subrun_events.rs delete mode 100644 crates/session-runtime/src/turn/summary.rs delete mode 100644 crates/session-runtime/src/turn/test_support.rs delete mode 100644 crates/session-runtime/src/turn/tool_cycle.rs delete mode 100644 crates/session-runtime/src/turn/watcher.rs create mode 100644 "docs/ideas/\346\212\275\347\246\273.md" delete mode 100644 examples/example-plugin/Cargo.toml delete mode 100644 examples/example-plugin/src/main.rs delete mode 100644 examples/plugins/repo-inspector/README.md delete mode 100644 examples/plugins/repo-inspector/plugin.toml delete mode 100644 openspec/changes/hooks-platform/.openspec.yaml delete mode 100644 openspec/changes/hooks-platform/proposal.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/.openspec.yaml create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/design.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/dto.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/proposal.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/research.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/agent-runtime-core/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/application-use-cases/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/core-boundary-slimming/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/host-session-runtime/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/lifecycle-hooks-platform/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-host-runtime/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-integration/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/session-persistence/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/session-runtime/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/tool-and-skill-discovery/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/specs/turn-orchestration/spec.md create mode 100644 openspec/changes/plugin-first-runtime-rearchitecture/tasks.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/.openspec.yaml delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/design.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/proposal.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-mode-system/spec.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-reload-surface/spec.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-capability-compilation/spec.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-prompt-program/spec.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/specs/workflow-phase-orchestration/spec.md delete mode 100644 openspec/changes/unify-declarative-dsl-compiler-architecture/tasks.md create mode 100644 openspec/schemas/my-workflow/schema.yaml create mode 100644 openspec/schemas/my-workflow/templates/design.md create mode 100644 openspec/schemas/my-workflow/templates/dto.md create mode 100644 openspec/schemas/my-workflow/templates/proposal.md create mode 100644 openspec/schemas/my-workflow/templates/research.md create mode 100644 openspec/schemas/my-workflow/templates/spec.md create mode 100644 openspec/schemas/my-workflow/templates/tasks.md diff --git a/AGENTS.md b/AGENTS.md index e1e9ac93..d23ccbb7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,11 +42,39 @@ node scripts/check-crate-boundaries.mjs --strict # 严格模式 - 治理层使用 `AppGovernance`（`astrcode-application`） - 能力语义统一使用 `CapabilitySpec`（`astrcode-core`），传输层使用 `CapabilityWireDescriptor`（`astrcode-protocol`） -## 代码规范 +## Rust 命名与设计要求 -- 用中文注释，且注释尽量表明为什么和做了什么 -- 不需要向后兼容，优先良好架构,期望最佳实践而不是打补丁 -- Git 提交信息使用 emoji + type + scope 风格（如 `✨ feat(module): brief description`） +- 命名必须清晰、直接、可预测，优先让人一眼看懂语义。 +- 类型、Trait、枚举变体使用 `UpperCamelCase`。 +- 模块、函数、方法、变量使用 `snake_case`。 +- 常量使用 `SCREAMING_SNAKE_CASE`。 +- 类型名应为名词，函数名应为动作，布尔变量名应表达判断语义，如 `is_*`、`has_*`、`can_*`。 +- 禁止使用含义模糊的命名，如 `manager`、`helper`、`util`、`common`、`base`，除非语义确实准确且不可替代。 + +## 设计原则 + +- 遵循单一职责：一个模块、类型、Trait、函数只负责一类清晰职责。 +- 遵循关注点分离：领域模型、业务编排、存储/网络/文件等副作用、协议 DTO 必须分层清晰，避免混杂。 +- 优先用类型表达语义：能用 `enum`、新类型、结构体表达的，不要依赖裸 `String`、裸 `u64`、魔法 `bool`。 +- 上层依赖抽象而非具体实现；优先依赖 Trait，而不是直接耦合底层实现。 +- 公共接口保持最小且稳定，非必要不暴露内部细节。 + +## 编码约束 + +- 函数应短小、直接，参数语义必须明确。 +- 参数过多或存在多种可选配置时，优先使用 Builder，禁止堆叠位置参数。 +- 禁止用布尔参数表达模式分支，优先改为具名枚举。 +- 能显式表达语义时，不要引入隐式行为或过度魔法。 +- 优先可读性，避免炫技、过度抽象和无必要设计模式。 + +## 自检标准 + +提交前确认： +- 是否能从命名直接理解职责？ +- 是否一个类型/函数只做一件主要事情？ +- 是否副作用与核心逻辑已分离？ +- 是否减少了调用方的理解成本？ +- 是否让未来修改更容易而不是更困难？ ## Gotchas diff --git a/ASTRCODE_EXPLORATION_REPORT.md b/ASTRCODE_EXPLORATION_REPORT.md deleted file mode 100644 index 63892780..00000000 --- a/ASTRCODE_EXPLORATION_REPORT.md +++ /dev/null @@ -1,334 +0,0 @@ -# Astrcode 项目深度探索报告 - -## 项目概览 - -**Astrcode** 是一个基于 Rust + React 的 AI 编程助手，采用 Tauri 桌面应用架构，支持多模型 LLM 集成、工具调用、插件系统和多会话管理。项目展现了高水平的架构设计，采用严格的分层架构和依赖管理。 - -### 核心定位 -- **AI 编程助手**：类似 GitHub Copilot 的本地化 AI 辅助编程工具 -- **跨平台桌面应用**：基于 Tauri 的桌面客户端，同时支持浏览器模式 -- **可扩展架构**：插件系统、MCP 协议支持、工具调用能力 - -## 技术栈分析 - -### 后端技术栈 -- **核心语言**：Rust (nightly 工具链) -- **异步运行时**：Tokio - 全异步架构，高并发处理 -- **Web 框架**：Axum - HTTP/SSE 服务器 -- **序列化**：serde + serde_json - 类型安全的序列化 -- **并发控制**：DashMap - 高性能并发数据结构 -- **错误处理**：thiserror + anyhow - 结构化错误处理 -- **桌面框架**：Tauri - 轻量级桌面应用壳 - -### 前端技术栈 -- **框架**：React 18 + TypeScript -- **构建工具**：Vite - 快速开发构建 -- **样式**：Tailwind CSS 4.x - 现代化 CSS 框架 -- **桌面桥接**：Tauri API - 前后端通信 -- **Markdown**：react-markdown + remark-gfm - Markdown 渲染 - -### 关键依赖和集成 -- **LLM 集成**：支持 OpenAI、Anthropic、DeepSeek 等多模型 -- **文件系统**：JSONL 事件日志存储 -- **进程管理**：stdio 插件进程通信 -- **配置管理**：TOML 配置文件 + 环境变量 - -## 架构设计亮点 - -### 1. 严格的分层架构 - -项目采用"无兼容层"策略，建立了清晰的架构边界： - -``` -┌─────────────────────────────────────────────────────────┐ -│ Frontend │ -│ (React + TypeScript) │ -└─────────────────────────────────────────────────────────┘ - │ HTTP/SSE - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Server Layer │ -│ (HTTP/SSE 边界 + 组合根) │ -└─────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Application Layer │ -│ (用例编排 + 治理 + 执行控制) │ -└─────────────────────────────────────────────────────────┘ - │ - ▼ -┌──────────────────┬──────────────────┬──────────────────┐ -│ Kernel │ Session-Runtime │ Core │ -│ (全局控制面) │ (单会话真相) │ (领域语义) │ -└──────────────────┴──────────────────┴──────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Adapter Layer │ -│ (存储/LLM/Prompt/工具/MCP/技能/代理适配器) │ -└─────────────────────────────────────────────────────────┘ -``` - -### 2. 核心领域模型 (Core) - -**astrcode-core** 是整个系统的领域根，包含： -- **强类型 ID**：`SessionId`、`AgentId`、`CapabilityName`、`TurnId` -- **端口契约**：定义了 `EventStore`、`LlmProvider`、`PromptProvider` 等核心接口 -- **能力语义**：`CapabilitySpec` - 运行时内部唯一能力模型 -- **配置模型**：稳定的配置结构和解析逻辑 -- **事件模型**：`AgentEvent`、`StorageEvent` 等领域事件 - -与之对应，`CapabilityWireDescriptor` 只存在于 `protocol/plugin` 边界， -用于插件握手和 wire 传输；它不是运行时内部的第二能力模型。 - -**设计亮点**： -- 完全不依赖其他 crate，保证领域模型的纯粹性 -- 使用 `async-trait` 定义异步接口，支持依赖倒置 -- Builder 模式保证复杂对象的类型安全构造 - -### 3. 全局控制面 (Kernel) - -**astrcode-kernel** 提供全局控制能力： -- **CapabilityRouter**：统一的能力路由器 -- **AgentControl**：Agent 树管理，支持父子 Agent 协作 -- **SurfaceManager**：统一能力面管理 -- **EventHub**：全局事件协调 - -**设计亮点**： -- 轻量级寻址层，不做重业务编排 -- 支持能力裁剪和继承 -- 类型化的消息契约 - -### 4. 单会话真相 (Session Runtime) - -**astrcode-session-runtime** 管理单个会话的完整真相： -- **SessionActor**：会话状态机，管理生命周期 -- **Turn 执行**：LLM 对话回合的编排 -- **Context Window**：智能上下文管理和压缩 -- **Event Log**：不可变事件流存储 - -**设计亮点**： -- Event Log 优先架构，所有状态变更都通过事件回放 -- 支持中断、恢复、压缩等高级功能 -- 内置 Token 预算管理 - -### 5. 用例编排层 (Application) - -**astrcode-application** 是业务用例的唯一入口： -- **App**：同步业务用例编排 -- **AppGovernance**：治理、重载、观测入口 -- **AgentOrchestrationService**：Agent 协作服务 - -**设计亮点**： -- 参数校验、权限检查、错误归类 -- 不保存 session shadow state -- 统一的治理策略 - -### 6. 组合根模式 (Server) - -**astrcode-server** 作为唯一的组合根： -- **bootstrap/runtime.rs**：显式组装所有组件 -- **依赖注入**：连接 adapter、kernel、session-runtime、application -- **HTTP 映射**：DTO 转换和状态码映射 - -**设计亮点**： -- 所有依赖在一个地方显式装配 -- 不承载业务逻辑，只做组装和映射 -- 支持测试时的依赖替换 - -## 关键设计模式 - -### 1. 能力系统 (Capability System) - -**CapabilitySpec** 是运行时内部唯一能力语义模型： - -```rust -pub struct CapabilitySpec { - pub name: CapabilityName, - pub kind: CapabilityKind, - pub description: String, - pub input_schema: Value, - pub output_schema: Value, - pub invocation_mode: InvocationMode, - pub permissions: Vec, - // ... 更多元数据 -} -``` - -**特点**： -- 统一的能力描述语言 -- JSON Schema 验证 -- 权限和副作用声明 -- 稳定性标记 - -对应的 `CapabilityWireDescriptor` 只是协议载荷名称： - -- 它在当前实现里复用 `CapabilitySpec` 的结构与校验 -- 但职责上仍然只是 transport DTO -- 运行时内部的 prompt、router、policy、plugin supervisor 决策都应围绕 `CapabilitySpec` - -### 2. 事件溯源架构 - -采用 **Event Sourcing** 模式： -- 所有状态变更记录为不可变事件 -- 状态通过事件回放得到 -- 支持时间旅行调试 - -**事件类型**： -- `StorageEvent`：持久化事件 -- `AgentEvent`：Agent 行为事件 -- `LlmEvent`：LLM 流式事件 - -### 3. Actor 模型 - -**SessionActor** 实现了 Actor 模型： -- 每个会话是一个独立的 Actor -- 通过消息传递进行交互 -- 支持并发和分布式扩展 - -### 4. 依赖倒置原则 - -通过 **端口契约** 实现依赖倒置： -- 接口在 `core` 中定义 -- 实现在 `adapter-*` 中提供 -- 上层模块依赖接口而非实现 - -### 5. Builder 模式 - -广泛使用 Builder 模式： -- `CapabilitySpecBuilder`：能力规格构建 -- `KernelBuilder`：内核构建 -- `ConfigBuilder`：配置构建 - -## 模块依赖关系 - -### 依赖层次结构 - -``` -frontend → server → application → kernel + session-runtime → core → adapter-* -``` - -### 依赖规则 - -**允许的依赖**： -- `protocol → core` -- `kernel → core` -- `session-runtime → core + kernel` -- `application → core + kernel + session-runtime` -- `server → application + protocol` -- `adapter-* → core` - -**禁止的依赖**： -- `core → protocol` -- `application → adapter-*` -- `kernel → adapter-*` -- `session-runtime → adapter-*` - -### 架构守卫 - -项目实现了 `check-crate-boundaries.mjs` 脚本： -- 自动检测依赖边界违反 -- CI 集成的架构守卫 -- 支持严格模式和警告模式 - -## 技术亮点 - -### 1. 类型安全的序列化 - -使用 Rust 的类型系统保证序列化安全： -```rust -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct CapabilitySpec { - // ... -} -``` - -### 2. 异步流式处理 - -支持 LLM 流式输出： -```rust -pub type LlmEventSink = Arc; - -pub enum LlmEvent { - TextDelta(String), - ThinkingDelta(String), - ToolCallDelta { /* ... */ }, -} -``` - -### 3. 智能上下文管理 - -**Context Window 管理**： -- Token 预算分配 -- 自动压缩策略 -- 文件恢复机制 - -### 4. 插件系统 - -基于 **stdio** 的插件架构： -- JSON-RPC 协议通信 -- 能力发现和注册 -- 生命周期管理 - -### 5. 多模型支持 - -统一的多模型接口： -- OpenAI 兼容 API -- Anthropic Claude API -- DeepSeek API -- 运行时模型切换 - -## 项目规模评估 - -### 代码规模 -- **Rust 源文件**：326 个 `.rs` 文件 -- **前端源文件**：90 个 `.ts/.tsx` 文件 -- **测试文件**：多个测试模块，覆盖核心功能 - -### 复杂度评估 -- **架构复杂度**：中高（多层级架构） -- **业务复杂度**：中（AI 编程助手核心功能） -- **技术复杂度**：高（涉及多个技术栈和协议） - -### 团队协作 -- **Git Hooks**：pre-commit 和 pre-push 钩子 -- **CI/CD**：4 个 GitHub Actions workflow -- **代码审查**：有规范的代码审查流程 -- **文档管理**：中文注释，详细的架构文档 - -## 总结 - -Astrcode 是一个架构设计优秀的 AI 编程助手项目，展现了高水平的软件工程实践： - -### 核心优势 -1. **严格的分层架构**：清晰的职责分离和依赖管理 -2. **类型安全的领域建模**：充分利用 Rust 的类型系统 -3. **事件驱动架构**：支持时间旅行和状态回放 -4. **可扩展的插件系统**：基于 stdio 的插件架构 -5. **完善的质量保障**：自动化测试、代码审查、CI/CD - -### 值得学习的设计 -1. **组合根模式**：所有依赖在一个地方装配 -2. **能力系统**：统一的扩展点描述 -3. **事件优先架构**：状态变更通过事件流表达 -4. **依赖倒置原则**：接口与实现分离 -5. **架构守卫**：自动化的架构约束检查 - -### 适用场景 -这个项目非常适合作为学习以下主题的范例： -- Rust 异步编程和 Web 开发 -- 分层架构和依赖管理 -- 事件驱动架构 -- 桌面应用开发（Tauri） -- AI 应用开发 -- 插件系统设计 - -### 推荐资源 -- `PROJECT_ARCHITECTURE.md`：详细的架构设计文档 -- `AGENTS.md`：项目规范和开发指南 -- `README.md`：项目介绍和快速开始 -- `CODE_REVIEW_ISSUES.md`：代码审查示例 - -这个项目展现了如何在实际项目中应用软件工程的最佳实践，是一个高质量的开源项目参考。 diff --git a/CLAUDE.md b/CLAUDE.md index e1e9ac93..d23ccbb7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,11 +42,39 @@ node scripts/check-crate-boundaries.mjs --strict # 严格模式 - 治理层使用 `AppGovernance`（`astrcode-application`） - 能力语义统一使用 `CapabilitySpec`（`astrcode-core`），传输层使用 `CapabilityWireDescriptor`（`astrcode-protocol`） -## 代码规范 +## Rust 命名与设计要求 -- 用中文注释，且注释尽量表明为什么和做了什么 -- 不需要向后兼容，优先良好架构,期望最佳实践而不是打补丁 -- Git 提交信息使用 emoji + type + scope 风格（如 `✨ feat(module): brief description`） +- 命名必须清晰、直接、可预测，优先让人一眼看懂语义。 +- 类型、Trait、枚举变体使用 `UpperCamelCase`。 +- 模块、函数、方法、变量使用 `snake_case`。 +- 常量使用 `SCREAMING_SNAKE_CASE`。 +- 类型名应为名词，函数名应为动作，布尔变量名应表达判断语义，如 `is_*`、`has_*`、`can_*`。 +- 禁止使用含义模糊的命名，如 `manager`、`helper`、`util`、`common`、`base`，除非语义确实准确且不可替代。 + +## 设计原则 + +- 遵循单一职责：一个模块、类型、Trait、函数只负责一类清晰职责。 +- 遵循关注点分离：领域模型、业务编排、存储/网络/文件等副作用、协议 DTO 必须分层清晰，避免混杂。 +- 优先用类型表达语义：能用 `enum`、新类型、结构体表达的，不要依赖裸 `String`、裸 `u64`、魔法 `bool`。 +- 上层依赖抽象而非具体实现；优先依赖 Trait，而不是直接耦合底层实现。 +- 公共接口保持最小且稳定，非必要不暴露内部细节。 + +## 编码约束 + +- 函数应短小、直接，参数语义必须明确。 +- 参数过多或存在多种可选配置时，优先使用 Builder，禁止堆叠位置参数。 +- 禁止用布尔参数表达模式分支，优先改为具名枚举。 +- 能显式表达语义时，不要引入隐式行为或过度魔法。 +- 优先可读性，避免炫技、过度抽象和无必要设计模式。 + +## 自检标准 + +提交前确认： +- 是否能从命名直接理解职责？ +- 是否一个类型/函数只做一件主要事情？ +- 是否副作用与核心逻辑已分离？ +- 是否减少了调用方的理解成本？ +- 是否让未来修改更容易而不是更困难？ ## Gotchas diff --git a/CODE_REVIEW_ISSUES.md b/CODE_REVIEW_ISSUES.md new file mode 100644 index 00000000..0937c52e --- /dev/null +++ b/CODE_REVIEW_ISSUES.md @@ -0,0 +1,94 @@ +# Code Review — dev (未提交变更 + 暂存区大规模重构) + +## Summary +- 审查范围：未提交变更（6 个 Rust 文件）+ 暂存区关键新模块抽样 +- 未提交变更：7 个文件，+164 / -232 行 +- 暂存区：407 文件，+33,468 / -45,009 行（application→server 重构、session-runtime→agent-runtime、新 host-session/plugin-host crate） +- 新问题：3（1 high, 1 medium, 1 low） +- 测试结果：24 passed, 0 failed（agent-runtime 16, core 2, adapter-llm 3, server 3） +- 编译检查：通过（workspace cargo check 无 warning） +- 视角：4/4 + +--- + +## Security + +无安全新问题。 + +- 所有 HTTP 路由（mutation/query/stream/conversation）均调用 `require_auth` +- `validate_session_path_id` 白名单校验（`[a-zA-Z0-9\-_T]`），有效阻止路径注入 +- `delete_project` 使用 `fs::canonicalize` 规范化路径 +- `copy_dir_recursive` 跳过 symlink，防止符号链接穿越 +- `normalize_prompt_request_text` 正确验证 skill invocation 一致性 + +--- + +## Code Quality + +| Sev | Issue | File:Line | Consequence | +|-----|-------|-----------|-------------| +| High | `max_consecutive_failures` 错误用于 output continuation 限制 | session_runtime_port_adapter.rs:255（已修复） | output continuation 次数受失败重试上限控制，语义混淆。此 bug 已在未提交变更中修复。 | +| Medium | `copy_dir_recursive` 无递归深度限制 | mutation.rs:349 | 恶意或损坏的深层目录树可能导致栈溢出（桌面应用风险极低） | + +### 已修复问题确认 + +`session_runtime_port_adapter.rs:255` 的修复是正确的——新增 `max_output_continuation_attempts` 配置项，在 `core/config.rs` 中独立声明（默认 3），带有 `.max(1)` 下限、serde skip_serializing_if、Debug 展示、validation 注册、以及 resolver 测试覆盖。修复将 `with_max_output_continuations(runtime.max_consecutive_failures)` 改为 `with_max_output_continuations(runtime.max_output_continuation_attempts)`。 + +--- + +## Tests + +**Run results**: 24 passed, 0 failed, 0 skipped + +| Test Suite | Result | +|---|---| +| agent-runtime::loop::tests (16) | OK | +| core::config::tests (2) | OK | +| adapter-llm::openai::dto::tests (3) | OK | +| server::mode::compiler::tests (3) | OK | + +| Sev | Issue | Location | +|-----|-------|----------| +| Low | `copy_dir_recursive` 无单元测试 | mutation.rs:349 | + +新增测试覆盖： +- `repeated_max_tokens_stops_at_configured_continuation_limit` — 直接验证 continuation 限制生效，与 bug 修复对应 +- `child_mode_compile_uses_child_fork_mode_for_child_execution_fallback` — 验证 child fork mode 降级逻辑 +- `assistant_message_*` / `user_and_tool_messages_*` (dto) — 验证 OpenAI 消息序列化边界 + +--- + +## Architecture + +| Sev | Inconsistency | Files | +|-----|--------------|-------| +| — | 无新架构不一致 | — | + +暂存区核心变更审查： +- **application → server 迁移**：`ApplicationError` → `ServerRouteError` 映射完整，conversation routes 正确切换 +- **新 crate 边界**：`agent-runtime`（纯 runtime loop）、`host-session`（状态机 + mutation）、`plugin-host`（插件生命周期）职责清晰 +- **AgentControlRegistry**：`spawn_with_storage` 正确校验 depth/concurrent 限制，`prune_finalized_agents_locked` 防止内存泄漏 +- **host-session ports**：`EventStore` trait 提供 `recover_session` 默认实现（全量 replay），`SessionRecoveryCheckpoint` 结构合理 +- **Crate 边界需验证**：`cargo check` 通过，建议合并前跑 `node scripts/check-crate-boundaries.mjs --strict` + +--- + +## Must Fix Before Merge + +*(无 Critical/High 级别阻断项——High 级 bug 已在未提交变更中修复。)* + +确认修复已提交即可。 + +--- + +## Pre-Existing Issues (not blocking) + +- `host-session/src/state.rs` 测试中使用 `unwrap()`（仅限 `#[cfg(test)]`，可接受） +- `plugin-host` reload 逻辑中 `commit_candidate().ok_or_else(...)` 的错误信息 `"candidate commit unexpectedly failed"` 缺少上下文，可考虑补充 snapshot_id + +--- + +## Low-Confidence Observations + +- `create_session(request.working_dir)` 未对 `working_dir` 做 `canonicalize`，与 `delete_project` 行为不一致。桌面应用中风险极低，但建议统一处理方式。 +- `loop.rs` 中 `TurnExecutionContext` 有 15 个字段，构造复杂。当前通过 `new()` 封装，暂可接受，但若继续增长建议引入 builder。 diff --git a/Cargo.lock b/Cargo.lock index 9c2d76ef..e6a09f5e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -160,6 +160,7 @@ name = "astrcode-adapter-llm" version = "0.1.0" dependencies = [ "anyhow", + "astrcode-agent-runtime", "astrcode-core", "async-trait", "futures-util", @@ -176,6 +177,7 @@ version = "0.1.0" dependencies = [ "astrcode-adapter-prompt", "astrcode-core", + "astrcode-plugin-host", "astrcode-support", "async-trait", "base64 0.22.1", @@ -196,7 +198,9 @@ name = "astrcode-adapter-prompt" version = "0.1.0" dependencies = [ "anyhow", + "astrcode-agent-runtime", "astrcode-core", + "astrcode-host-session", "astrcode-support", "async-trait", "chrono", @@ -226,6 +230,7 @@ name = "astrcode-adapter-storage" version = "0.1.0" dependencies = [ "astrcode-core", + "astrcode-host-session", "astrcode-support", "async-trait", "chrono", @@ -244,6 +249,7 @@ name = "astrcode-adapter-tools" version = "0.1.0" dependencies = [ "astrcode-core", + "astrcode-host-session", "astrcode-support", "async-trait", "base64 0.22.1", @@ -261,23 +267,19 @@ dependencies = [ ] [[package]] -name = "astrcode-application" +name = "astrcode-agent-runtime" version = "0.1.0" dependencies = [ "astrcode-core", - "astrcode-kernel", - "astrcode-session-runtime", - "astrcode-support", "async-trait", "chrono", - "dashmap", + "futures-util", "log", + "regex", "serde", "serde_json", "tempfile", - "thiserror 2.0.18", "tokio", - "uuid", ] [[package]] @@ -351,45 +353,35 @@ dependencies = [ ] [[package]] -name = "astrcode-example-plugin" -version = "0.1.0" -dependencies = [ - "astrcode-core", - "astrcode-plugin", - "astrcode-protocol", - "astrcode-sdk", - "async-trait", - "serde_json", - "tokio", -] - -[[package]] -name = "astrcode-kernel" +name = "astrcode-host-session" version = "0.1.0" dependencies = [ + "astrcode-agent-runtime", "astrcode-core", + "astrcode-plugin-host", + "astrcode-support", "async-trait", + "chrono", + "dashmap", "log", "serde", "serde_json", - "thiserror 2.0.18", "tokio", ] [[package]] -name = "astrcode-plugin" +name = "astrcode-plugin-host" version = "0.1.0" dependencies = [ "astrcode-core", "astrcode-protocol", + "astrcode-support", "async-trait", "log", "serde", "serde_json", - "thiserror 2.0.18", "tokio", "toml 1.1.2+spec-1.1.0", - "uuid", ] [[package]] @@ -402,17 +394,6 @@ dependencies = [ "thiserror 2.0.18", ] -[[package]] -name = "astrcode-sdk" -version = "0.1.0" -dependencies = [ - "astrcode-core", - "astrcode-protocol", - "serde", - "serde_json", - "thiserror 2.0.18", -] - [[package]] name = "astrcode-server" version = "0.1.0" @@ -425,12 +406,11 @@ dependencies = [ "astrcode-adapter-skills", "astrcode-adapter-storage", "astrcode-adapter-tools", - "astrcode-application", + "astrcode-agent-runtime", "astrcode-core", - "astrcode-kernel", - "astrcode-plugin", + "astrcode-host-session", + "astrcode-plugin-host", "astrcode-protocol", - "astrcode-session-runtime", "astrcode-support", "async-stream", "async-trait", @@ -451,26 +431,7 @@ dependencies = [ "tokio", "tower", "tower-http", -] - -[[package]] -name = "astrcode-session-runtime" -version = "0.1.0" -dependencies = [ - "astrcode-core", - "astrcode-kernel", - "astrcode-support", - "async-trait", - "chrono", - "dashmap", - "futures-util", - "log", - "regex", - "serde", - "serde_json", - "tempfile", - "thiserror 2.0.18", - "tokio", + "uuid", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index 2fd8b9d4..ac552c7b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,9 +2,9 @@ members = [ "crates/core", "crates/support", - "crates/kernel", - "crates/session-runtime", - "crates/application", + "crates/agent-runtime", + "crates/host-session", + "crates/plugin-host", "crates/eval", "crates/adapter-storage", "crates/adapter-agents", @@ -14,12 +14,9 @@ members = [ "crates/protocol", "crates/client", "crates/cli", - "crates/plugin", - "crates/sdk", "crates/adapter-tools", "crates/adapter-mcp", "crates/server", - "examples/example-plugin", "src-tauri", ] resolver = "2" diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md index 380d227a..3d78590b 100644 --- a/PROJECT_ARCHITECTURE.md +++ b/PROJECT_ARCHITECTURE.md @@ -1,325 +1,169 @@ -# 项目架构总览 +# Astrcode 架构约束 -本文档是仓库级架构的权威说明。`README.md`、`docs/architecture/*` 与各专题文档可以展开局部细节，但不得与本文档的分层边界和依赖方向冲突。 +本文档是当前仓库的权威架构说明。目标不是解释历史，而是约束未来实现。 -## 架构核心原则：三层分离 +## 总原则 -session-runtime 内部存在两种根本不同的关注点，外加面向外部的一致接口。三层的规则各不相同，绝不可混合： +- 不维护向后兼容，优先最终边界和干净代码。 +- `server` 是唯一组合根，只负责装配，不承载长期业务真相。 +- `core` 只保留真正跨 owner 共享的稳定语义，不再充当 DTO/trait 总仓库。 +- runtime、session host、plugin host 分离，避免“大核心 + 补丁式扩展”。 +- 多 agent 协作继续遵循“一个 session 即一个 agent”，durable truth 统一归 `host-session`。 -### 第一层：事件溯源层（发生了什么） +## 目标分层 -**规则**：纯函数、确定性、可回放、无副作用。 +### `astrcode-core` -所有派生事实（phase、mode、turn terminal、active tasks、child session、input queue、conversation snapshot）必须能由事件流重新投影恢复。同一段投影逻辑只存在一个实现，不允许为增量、全量回放、checkpoint 恢复分别写三遍。 +只保留跨 owner 共享的稳定值对象和最小合同： -### 第二层：运行时状态层（正在发生什么） +- `ids` +- LLM / tool / message 基础模型 +- `CapabilitySpec` +- 极少数共享 prompt 语义 +- hooks 的稳定事件键和 effect kind -**规则**：有副作用、有时序依赖、不可回放、不暴露给外部。 +不得继续承载： -CancelToken 触发、running 标志（防止双 turn 并发）、LLM 流式响应累加、工具并发调度——这些是实时并发控制，不是从事件推断出来的投影。运行时状态只存在于 turn 执行期间，turn 结束后销毁，一切真相回归事件流。 +- session recovery / projection / read model +- workflow / mode / session catalog +- plugin registry / active snapshot / plugin manifest +- owner 专属 config / observability / store / composer / ports +- 多 agent 协作 durable truth -### 第三层：外部接口层（外界看到什么） +### `astrcode-agent-runtime` -**规则**：收纯数据、吐纯数据，永远不暴露运行时内脏。 +最小执行内核，只负责单 turn / 单 agent live 执行： -这里的“外部”不仅指 plugin / hook，也包括 `application` 和 `server` -所依赖的稳定 session 合同。只要一个输入输出跨出 `session-runtime` 的内部边界， -它就必须表现为纯数据 snapshot / DTO / decision，而不是 process-local runtime handle。 +- `execute_turn` +- provider stream 调用 +- tool dispatch +- hook dispatch +- 流式状态机 +- 取消 / 超时传播 -所有外部扩展点（plugin、hook、capability、subscription、policy）通过纯数据交互： -- **订阅**：收到 `SessionEventRecord`，观察/记录，无副作用回流 -- **Hook**：收到 `ToolHookContext`，返回 `ToolHookResultContext`（纯数据决策） -- **Capability**：通过 `CapabilitySpec` 声明，执行时收到 `ToolContext`，返回 `ToolExecutionResult` -- **Policy**：收到 `PolicyContext`，返回 `PolicyVerdict` -- **Plugin**：通过 `PluginManifest` 声明，通过 `CapabilitySpec` 注入能力 +不得负责： -外部代码永远不应该看到 `CancelToken`、`AtomicBool`、`StdMutex>` 等运行时类型。 +- session catalog +- 事件日志与恢复 +- branch / fork / compact +- resource discovery +- 多 agent 协作 durable truth -### 三层的交互方向 +### `astrcode-host-session` -``` -运行时层（turn/）──写入事件──→ 事件溯源层（state/projections + query/） - ↓ - 外部接口层（纯数据快照） - ↓ - application / server / plugin / hook -``` - -单向流动，不允许反向：投影层不能调运行时层，外部不能操作运行时状态。 - -## Crate 全览 - -项目包含 18 个 crate + 1 个 Tauri 桌面薄壳。按职责分为六层： - -``` - ┌─────────────┐ - │ src-tauri │ 桌面薄壳 - └──────┬──────┘ - │ - ┌───────────────────┼───────────────────┐ - │ │ │ - ┌─────┴──────┐ ┌─────┴──────┐ ┌──────┴─────┐ - │ cli │ │ server │ │ eval │ - │ (TUI 客户端)│ │ (组合根) │ │ (离线评测) │ - └─────┬──────┘ └─────┬──────┘ └──────┬─────┘ - │ │ │ - ┌─────┴──────┐ │ │ - │ client │ │ │ - │ (HTTP 传输) │ │ │ - └─────┬──────┘ │ │ - │ │ │ - │ ┌─────────────┼────────────┐ │ - │ │ │ │ │ - │ ┌─┴──────────┐ │ ┌─────────┴──┐ │ - │ │ application│ │ │ plugin │ │ - │ │ (业务编排) │ │ │ (插件运行时) │ │ - │ └─────┬──────┘ │ └──────┬──────┘ │ - │ │ │ │ │ - │ ┌─────┴──────┐ │ ┌──────┴───────┐ │ - │ │ kernel │ │ │ sdk │ │ - │ │ (能力聚合) │ │ │ (插件 SDK) │ │ - │ └─────┬──────┘ │ └──────┬───────┘ │ - │ │ │ │ │ - │ ┌─────┴──────────┴────────┴──────┐ │ - │ │ session-runtime │ │ - │ │ (单会话执行引擎) │ │ - │ └──────────────┬──────────────────┘ │ - │ │ │ - │ ┌────────────┼──────────────┐ │ - │ │ │ │ │ - │ ┌─┴──────┐ ┌──┴───────┐ ┌────┴────┐│ - │ │ core │ │ protocol │ │adapter-* ││ - │ │(领域层) │ │(协议层) │ │(7个适配器)││ - │ └────┬───┘ └──────────┘ └─────────┘│ - │ │ │ - │ ┌────┴────────┐ │ - │ │ support │ │ - │ │(共享宿主支持)│ │ - │ └─────────────┘ │ - └─────────────────────────────────────┘ -``` - -### 领域基础层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **core** | 领域协议和跨 crate 共享的纯数据模型。定义所有 port trait（`EventStore`、`LlmProvider`、`Tool`、`PromptProvider` 等）、领域事件（`StorageEventPayload`、`AgentEvent`）、能力模型（`CapabilitySpec`）、配置模型、治理模式 DSL。是整个项目的类型基石。 | 无项目内依赖 | -| **protocol** | 纯数据契约层。定义 HTTP DTO 和插件 JSON-RPC 消息格式，是 server↔client、server↔plugin 之间的序列化协议。不包含业务逻辑。 | core | - -### 共享支持层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **support** | 受限的共享宿主支持层。当前承载 `hostpaths`、`shell`、`tool_results` 三个子域，集中提供跨 crate 共享的宿主路径解析、shell 探测与工具结果持久化等基础设施能力，避免这些 owner 滞留在 `core`。不是泛化 `utils` 桶。 | core | - -### 运行时层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **kernel** | 运行时能力聚合层。组合 LlmProvider + PromptProvider + ResourceProvider + CapabilityRouter + AgentControl 为统一 `Kernel`。`KernelGateway` 收敛四个 provider 为单一门面；`AgentControl` 管理多 agent 生命周期编排、父子树、收件箱、父投递队列；`KernelAgentSurface` 提供面向编排层的稳定视图。 | core | -| **session-runtime** | 单会话执行引擎和事实边界。管理 turn 生命周期、事件投影、compact/恢复、流式对话。内部分为三层：运行时执行层（`turn/`）、事件溯源层（`state/projections`）、读投影层（`query/`）。详见下方"session-runtime 内部架构"章节。需要宿主路径或工具结果持久化时，通过 `support` 消费共享基础设施。 | core, support, kernel | -| **plugin** | 宿主侧插件运行时。管理插件子进程生命周期（supervisor）、JSON-RPC over stdio 通信、能力路由桥接、流式执行。是外部插件接入 Astrcode 的基础设施。 | core, protocol | -| **sdk** | 插件开发 SDK。为插件开发者提供 Rust API：`ToolHandler` 注册工具、`HookRegistry` 注册钩子、`PluginContext` 访问调用上下文、`StreamWriter` 发送流式响应。插件通过 SDK 与宿主交互，不直接依赖 core 或 runtime。 | core, protocol | - -### 编排层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **application** | 业务编排层，唯一的用例入口。通过 port trait 与 session-runtime 和 kernel 解耦。编排根代理执行、子代理 spawn/send/observe/close 四工具、child turn 终态收口、parent delivery 唤醒调度、governance surface 计算、workflow/plan 状态机。需要宿主路径等共享基础设施时，通过 `support` 消费稳定 helper。 | core, support, kernel, session-runtime | - -### 适配器层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **adapter-agents** | Agent Profile 加载：从 builtin/用户级/项目级目录读取 Markdown YAML frontmatter + 纯 YAML，产出 `AgentProfileRegistry` | core | -| **adapter-llm** | 多 LLM 后端统一抽象（Anthropic Claude + OpenAI 兼容 API）：流式 SSE 响应累加、错误分类、指数退避重试 | core | -| **adapter-mcp** | MCP 服务器连接管理：工具/prompt/资源桥接，将外部 MCP 服务器能力注册到 Astrcode 能力路由 | core, support, adapter-prompt | -| **adapter-prompt** | Prompt 组装管线：贡献者模式，每个 `PromptContributor` 生成一段 Block，`PromptComposer` 收集/去重/拓扑排序/渲染，产出最终 `PromptPlan` | core, support | -| **adapter-skills** | Skill 资源发现：Markdown 解析、builtin/用户/项目分层 catalog 合并 | core | -| **adapter-storage** | 本地文件系统 JSONL 事件日志存储、文件锁互斥写入、会话仓库、配置持久化 | core, support | -| **adapter-tools** | 内置工具集（readFile、writeFile、editFile、grep、shell 等）+ Agent 协作工具（spawn、send、observe、close），实现 `Tool` trait | core, support | - -### 接入层 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **server** | 唯一组合根。基于 axum 的 HTTP 服务端，组装 application、session-runtime、kernel 与所有 adapter。负责 bootstrap 装配和 HTTP 协议映射，不承载业务真相。 | 全部 | -| **cli** | TUI 客户端。基于 ratatui 的终端交互界面，通过 `client` crate 与服务端通信。 | client, core | -| **client** | HTTP 传输客户端。基于 reqwest 封装认证交换、会话管理、对话流式传输。 | protocol | -| **eval** | 离线评测框架。包含任务定义、trace 模型、runner、diagnosis 模块，支持 agent 行为的自动化测试与诊断。 | core, protocol | - -### 桌面薄壳 - -| Crate | 职责 | 依赖 | -|-------|------|------| -| **src-tauri** | Tauri 桌面端薄壳。通过 `astrcode-server` 启动后端服务，前端 UI 通过 HTTP 与后端交互。不承载业务逻辑。 | server | +session owner，统一承接 durable truth 和 host use-case： -## Crate 分层（详细边界） +- 事件日志 +- 恢复与回放 +- projection / query / observe +- session catalog +- branch / fork / compact +- 模型选择 +- 输入入口 +- `AgentRuntimeExecutionSurface` 组装 +- 多 agent 协作真相：`SubRunHandle`、`InputQueueProjection`、父子 lineage、结果投递、取消传播 -### `core` — 领域协议和纯数据模型 +### `astrcode-plugin-host` -- 定义跨 crate 共享的类型、trait、port。 -- `CapabilitySpec` 是运行时内部能力语义真相。 -- `WorkflowDef`、`WorkflowPhaseDef` 等协议也属于这一层。 -- **不包含运行时逻辑**：回放算法、文件 I/O、进程检测、home 路径解析不属于 core。Core 定义类型，不实现这些 owner。 -- **不依赖** `application`、`session-runtime` 或任何 adapter。 +统一 builtin / external plugin 宿主： -core 中需要警惕的边界： -- `TurnProjectionSnapshot` 当前仍是 checkpoint 合同的一部分，因此暂留 core 作为共享载体；其业务 owner 仍在 session-runtime。 -- `InputQueueProjection::replay_index()` 包含回放算法，应归入 session-runtime。 -- `tool_result_persist` 执行文件 I/O，应归入 `support` 或 adapter。 -- `RuntimeCoordinator` 包含有状态实现，应归入 server 组合根。 -- `agent/mod.rs`（~60 个公开类型）需要按关注点拆分（types、collaboration、delivery、lineage）。 +- plugin descriptor 校验 +- candidate / active snapshot +- reload commit / rollback +- hooks / providers / resources / commands / prompts / skills / themes 聚合 +- builtin backend 与 external backend 的统一语义 -### `support` — 受限共享宿主能力 +### `astrcode-server` -- 只承载不应继续留在 `core`、又被多个 crate 共同消费的宿主辅助能力。 -- 当前子域包括： - - `hostpaths`：`resolve_home_dir`、`astrcode_dir`、`projects_dir`、`project_dir()` 等。 - - `shell`：默认 shell 选择、shell family 探测、命令存在性检查。 - - `tool_results`：工具结果落盘、截断与 durable 引用生成。 -- 不承载业务语义，不变成 `utils` / `common` 杂项桶。 +唯一组合根： -### `kernel` — 运行时能力聚合层 +- 装配 `agent-runtime`、`host-session`、`plugin-host` +- 装配 `adapter-*` +- 暴露 HTTP / RPC / CLI 所需入口 -- 组合根：通过 `KernelBuilder` 将 LlmProvider + PromptProvider + ResourceProvider + CapabilityRouter + AgentControl 组装为 `Kernel`。 -- 门面：`KernelGateway` 收敛四个 provider 为统一入口，session-runtime 不直接持有各 provider。 -- 控制平面：`AgentControl` 提供多 agent 的生命周期编排、父子树管理、收件箱通信、父投递队列。 -- Anti-corruption layer：`KernelAgentSurface` 将 `AgentControl` 内部 API 整形为编排层友好的稳定接口。 -- 只依赖 `core`。不重新定义 core 的任何 trait。 +不得继续承载： -### `session-runtime` — 单会话执行引擎 +- builtin / plugin / MCP / governance / workflow / mode 的并列事实源 +- provider kind 硬编码选择逻辑 +- 旧运行时协调壳层 -是单 session 执行与恢复的 authoritative truth。内部模块按三层原则划分： +## 迁移中的旧边界 -#### `state/` — 事件溯源基础设施 +以下 crate 已不再是长期权威边界，只允许作为迁移源存在，最终必须删除： -**应该只做**：事件追加、投影计算、最近事件缓存、checkpoint 恢复。 +- `astrcode-application` +- `astrcode-kernel` +- `astrcode-session-runtime` +- 旧 `astrcode-plugin` -- `SessionState` 持有 `ProjectionRegistry` + `SessionWriter` + `broadcaster`。 -- `ProjectionRegistry` 按投影域组织：phase、agent、mode、children、tasks、input_queue、turns、cache。每个域应是独立 struct，`apply()` 委托分发而非一个大 if-else。 -- `SessionWriter` 封装存储后端写入抽象。 -- `RecentSessionEvents` / `RecentStoredEvents` 提供滑动窗口缓存。 +要求： -**不应该做**： -- 不持有 `TurnRuntimeState`（运行时状态机应属于 `turn/` 模块）。 -- 不包含命令处理器（`InputQueueEventAppend`、`append_input_queue_event` 应属于 `command/`）。 -- 不提供绕过事件溯源的命令式写入（如 `upsert_child_session_node`）。 +- 新 crate 不得回头依赖这些旧边界。 +- 新功能不得继续落在这些 crate 中。 +- 组合根不得继续把这些 crate 当成正式装配主链。 -#### `turn/` — 运行时执行层 - -**应该只做**：turn 生命周期管理、LLM 调用、工具执行、流式处理。 - -- `TurnRuntimeState`（prepare/complete/interrupt/cancel）属于此模块，不属于 `state/`。 -- `watcher.rs` 拥有等待 turn 终态的异步监听循环；它可以读取 `SessionState` 的纯投影和广播，但不把等待逻辑留在 `query/`。 -- `runner/` 负责单步循环编排（prompt → LLM → 工具/停止）。 -- `submit.rs` 只做提交入口和协调，终结持久化和 SubRun 事件构造应拆为独立模块。 -- 所有压缩后事件组装（proactive/reactive/manual）应抽取为共享函数，消除三处重复。 - -**不应该做**： -- 不包含只读查询（`replay.rs` 应属于 `query/`）。 -- 不反向调用 `query/` 的方法（`current_turn_messages` 应为 `SessionState` 的投影方法）。 - -#### `query/` — 纯读投影层 - -**应该只做**：从事件流或投影缓存计算只读快照。 - -- `service.rs` 是纯协调器：拿到 state → 调投影函数 → 返回结果。 -- `turn.rs` 是 turn 终态投影的唯一权威位置（合并当前分散在 `state/`、`query/`、`service.rs` 中的逻辑）。 -- `conversation.rs` 承载会话流式投影。 -- `agent.rs`、`terminal.rs`、`transcript.rs` 各自职责单一。 - -**不应该做**： -- 不包含异步事件监听循环（`wait_for_turn_terminal_snapshot` 的等待逻辑应在 `turn/` 内部或独立 watcher）。 -- 不做数据分页或输入标准化（应提取为共享辅助）。 - -#### `command/` — 写入口 - -**应该只做**：接收写操作请求，委托 `state/` 完成事件追加。 - -- `compact_session()` 的立即执行路径应下沉到 `turn/`，command/ 只负责"提交 compact 请求"。 - -#### `context_window/` — 上下文窗口管理 - -- 提供 compact、prune、micro_compact、file_access、token_usage 等能力。 -- 明确不承担最终请求组装（由 `turn/request.rs` 编排）。 -- 对 `turn/` 单向依赖，`turn/` 通过 `request.rs` 汇聚所有 context_window 子模块。 - -#### `actor/` — SessionActor - -- `SessionState` 的轻量容器 + 恢复入口。 -- 直接持有 `TurnRuntimeState`，作为单 session live runtime owner。 -- 不包含 durable 写入逻辑；写入仍通过 `SessionState` / `SessionWriter` 完成。 - -#### `observe/` — 纯数据类型 - -- 只定义 session observe 的数据 shape（filter、scope、source）。 -- 投影算法在 `query/`，类型定义在 `observe/`。 - -### `application` — 业务编排层 - -- 是唯一的业务编排入口。 -- 解释 active workflow、phase signal、phase overlay、artifact bridge 与 mode 切换顺序。 -- 通过 port trait（`AppSessionPort`、`AgentSessionPort`、`AppKernelPort`、`AgentKernelPort`）与 session-runtime 和 kernel 解耦。 -- 只依赖稳定的 runtime 合同；规范化 helper、投影器、执行辅助和运行时控制状态都不属于 `application` 可见表面。 - -**边界纪律**： -- port trait 方法签名中不应暴露 session-runtime / kernel 内部类型（如 `TurnTerminalSnapshot`、`ProjectedTurnOutcome`、`AgentObserveSnapshot`、`PendingParentDelivery`）。编排需要的 session facts 由 `application::ports::session_contracts` 定义 app-owned DTO，并在 port impl 中做映射。 -- `lib.rs` 不应批量 re-export session-runtime 的类型穿透到上层。 -- `CapabilityRouter`（kernel 具体 struct）不应出现在 application 公共 API 中。 -- 不直接操作 session-runtime 的 `append_and_broadcast`、`prepare_execution`、`normalize_session_id` 等内部 helper。 +## 依赖方向 -### `server` — 组合根与 HTTP 路由 +允许的高层方向如下： + +```text +adapter-* ───────────────┐ + ├──> plugin-host ──┐ +storage / protocol ──────┘ │ + │ +core <──────────── agent-runtime <──────────┤ + ^ ^ │ + | | │ + └──────────── host-session <──────────────┘ + ^ + | + server +``` -- 是唯一组合根，组装 `application`、`session-runtime`、`kernel` 与各 adapter。 -- 不承载业务真相，只负责装配和协议映射。 +### 强约束 -**边界纪律**： -- HTTP 路由不应直接 import session-runtime 的 `Conversation*Facts`、`ConversationStreamProjector`、`ForkPoint` 等内部类型。所有业务交互通过 `application` 的用例方法。 -- 不直接调用 `normalize_working_dir` 等 session-runtime 工具函数。 -- 测试不应直接操作 `SessionState::append_and_broadcast`。 +- `core` 不得依赖任何其他工作区 crate。 +- `protocol` 仅允许依赖 `core`。 +- `support` 仅允许依赖 `core`。 +- `agent-runtime` 仅允许依赖 `core`，必要时可依赖极少数纯工具 crate；不得依赖 `application`、`kernel`、`session-runtime`。 +- `plugin-host` 仅允许依赖 `core`、`protocol`、`support`；不得依赖 `application`、`kernel`、`session-runtime`。 +- `host-session` 仅允许依赖 `core`、`support`、`agent-runtime`、`plugin-host`；不得依赖 `application`、`kernel`、`session-runtime`。 +- `server` 是唯一允许同时装配新旧边界的地方，但目标是逐步只装配 `agent-runtime + host-session + plugin-host + adapters`。 -## mode envelope 与 workflow phase 的关系 +## 多 agent 协作约束 -- `mode` 负责治理约束，回答"这一轮允许做什么、如何做"。 -- `workflow phase` 负责业务语义，回答"当前处于正式流程的哪一段、下一步如何迁移"。 -- 同一个 `mode_id` 可以被多个 phase 复用。 -- phase -> mode 绑定由 workflow artifact 的 `phase.mode_id` 持有；mode 不反向拥有 workflow 真相。 -- workflow 迁移必须通过显式 `transition` 与 `bridge` 建模，不能散落在提交入口的 plan-specific if/else 里。 +- 一个 session 就是一个 agent。 +- child agent 必须表现为 child session，而不是同一 session 内的“子人格切换”。 +- `host-session` 是 collaboration durable truth 的唯一 owner。 +- `agent-runtime` 只保留 child session 的最小执行合同。 +- `plugin-host` 只暴露协作 surface，例如 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree`；这些 surface 不得持有 durable truth。 -## 治理 compile / bind / orchestrate 术语 +## hooks 约束 -- `compile`：把声明模型编译成纯数据产物，不读取 session/runtime 实例状态。当前治理链路里的 `ResolvedTurnEnvelope` 虽沿用 envelope 命名，但语义上属于 compile 阶段产物。 -- `bind`：把编译产物与 runtime/session/control/profile 绑定成一次性可执行快照。治理链路里的 owner 是 `ResolvedGovernanceSurface`，工具侧只消费从该快照投影出的纯数据合同。 -- `orchestrate`：基于 workflow state、signal 与 bridge 推进业务 phase，不负责重解释 mode selector 或 capability 语义。 -- compile 结果与 bind 结果不是同一层对象，文档、注释与接口命名不得混称。 -- governance reload 继续遵守 idle-only 合同：存在 running session 时拒绝 reload，不引入 mixed-snapshot 执行模型。 +- hooks 是唯一扩展总线。 +- governance、workflow overlay、tool policy、resource discovery、model selection 必须逐步统一到 hooks catalog。 +- hook effect 只能表达受约束的流程影响，不能直接突变 durable truth。 +- prompt augment 必须继续走 `PromptDeclaration` / `PromptGovernanceContext` 链路，不引入平行 prompt 系统。 -## 依赖方向 +## 实施顺序 -仓库级依赖方向保持如下不变式： +1. 先更新本文档和 crate boundary 守卫。 +2. 新建 `agent-runtime`、`host-session`、`plugin-host` crate 骨架。 +3. 收缩 `core`，先删共享面污染，再迁 owner 专属模型。 +4. 迁移最小 runtime 核心到 `agent-runtime`。 +5. 迁移 session durable truth 和协作真相到 `host-session`。 +6. 迁移 plugin 宿主与统一 snapshot 到 `plugin-host`。 +7. 重写 `server` 组合根。 +8. 删除 `application`、`kernel`、旧 `session-runtime`、旧 `plugin` 边界。 -- `server` 是组合根，只通过 `application` 层消费业务逻辑，仅在 bootstrap 中直接引用 `kernel` 和 adapter。 -- `application` 只依赖 `core`、`support`、`kernel`、`session-runtime`。 -- `support` 只依赖 `core`。 -- 需要共享宿主路径能力的 crate 可以依赖 `support`，但不得因此把业务 owner 重新塞回 `core`。 -- `session-runtime` 只依赖 `core`、`support`、`kernel`。 -- `kernel` 只依赖 `core`。 -- `protocol` 只依赖 `core`。 -- `adapter-*` 只依赖 `core`（互不依赖）。 -- `src-tauri` 是桌面薄壳，不承载业务逻辑。 +## 验证要求 -## 事件与恢复语义 +每次涉及边界变更时，至少验证： -- event log 是执行时间线的 durable truth，append only，不改不删。 -- 所有派生事实必须能由事件投影恢复。 -- display `Phase` 只由 durable event 投影驱动，不允许被运行时代码直接写入。 -- workflow instance state 是独立于 runtime checkpoint 的显式持久化状态；workflow 恢复失败时允许降级到 mode-only 路径。 -- 投影逻辑遵循唯一实现原则：同一段投影（如 turn 终态、compact 后事件组装）只存在一个实现，增量/全量/恢复三种路径共享同一份投影函数。 +- `node scripts/check-crate-boundaries.mjs` +- `cargo check --workspace` -## 文档关系 +进入大规模迁移后，再逐步补齐： -- 本文档：仓库级分层边界与依赖方向的权威约束。 -- `README.md`：项目介绍和对外说明。 -- `docs/architecture/crates-dependency-graph.md`：crate 依赖图和结构快照。 -- `CLAUDE.md`：开发者工作流、常用命令、代码规范。 +- `cargo test --workspace --exclude astrcode --lib` +- 新 crate 的单元测试与集成测试 diff --git a/README.md b/README.md index 88046f83..6883eab7 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,8 @@ cd frontend && npm run build "maxToolConcurrency": 10, "compactKeepRecentTurns": 4, "compactKeepRecentUserMessages": 8, - "compactMaxOutputTokens": 20000 + "compactMaxOutputTokens": 20000, + "maxOutputContinuationAttempts": 3 } } ``` @@ -247,6 +248,7 @@ cd frontend && npm run build | `compactKeepRecentTurns` | 4 | 压缩时保留最近的 turn 数 | | `compactKeepRecentUserMessages` | 8 | 压缩时额外保留最近真实用户消息的数量（原文重新注入） | | `compactMaxOutputTokens` | 20000 | 压缩请求的最大输出 token 上限（自动取模型限制的较小值） | +| `maxOutputContinuationAttempts` | 3 | 单轮 LLM 输出因 max tokens 截断后的最大续写次数 | ### 内建环境变量 @@ -371,7 +373,7 @@ AstrCode/ - 健康状态独立维护：`Unknown / Healthy / Degraded / Unavailable` - 能力路由与权限检查 - 流式执行支持 -- 提供 Rust SDK（`crates/sdk`），包含 `ToolHandler`、`HookRegistry`、`PluginContext`、`StreamWriter` +- 旧 Rust SDK（`crates/sdk`）与 `crates/plugin` 已归档，不再参与 workspace 编译；当前正式宿主边界为 `plugin-host` - 插件握手交换的是 `CapabilityWireDescriptor`；宿主内部消费和决策始终基于 `CapabilitySpec` ### 会话持久化与上下文压缩 diff --git a/crates/adapter-llm/Cargo.toml b/crates/adapter-llm/Cargo.toml index f85da4ec..45b4e9ec 100644 --- a/crates/adapter-llm/Cargo.toml +++ b/crates/adapter-llm/Cargo.toml @@ -6,6 +6,7 @@ license-file.workspace = true authors.workspace = true [dependencies] +astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } anyhow.workspace = true async-trait.workspace = true diff --git a/crates/adapter-llm/src/cache_tracker.rs b/crates/adapter-llm/src/cache_tracker.rs index bf4112ef..e64d646a 100644 --- a/crates/adapter-llm/src/cache_tracker.rs +++ b/crates/adapter-llm/src/cache_tracker.rs @@ -4,7 +4,7 @@ //! - 请求发送前记录一次 prompt/tool/cache 策略快照 //! - 响应返回后根据真实 `cache_read_input_tokens` 跌幅判断是否发生 cache break -use astrcode_core::{ +use astrcode_agent_runtime::{ LlmUsage, PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, }; use serde::Serialize; diff --git a/crates/adapter-llm/src/lib.rs b/crates/adapter-llm/src/lib.rs index 54230c6f..3342a248 100644 --- a/crates/adapter-llm/src/lib.rs +++ b/crates/adapter-llm/src/lib.rs @@ -39,7 +39,8 @@ use std::{collections::HashMap, time::Duration}; -use astrcode_core::{AstrError, CancelToken, LlmEvent, ReasoningContent, Result, ToolCallRequest}; +use astrcode_agent_runtime::LlmEvent; +use astrcode_core::{AstrError, CancelToken, ReasoningContent, Result, ToolCallRequest}; use log::warn; use serde_json::Value; use tokio::{select, time::sleep}; @@ -47,9 +48,10 @@ use tokio::{select, time::sleep}; pub mod cache_tracker; pub mod openai; -pub use astrcode_core::{ +pub use astrcode_agent_runtime::{ LlmEventSink as EventSink, LlmFinishReason as FinishReason, LlmOutput, LlmProvider, LlmRequest, - LlmUsage, ModelLimits, + LlmUsage, ModelLimits, PromptCacheBreakReason, PromptCacheDiagnostics, + PromptCacheGlobalStrategy, PromptCacheHints, PromptLayerFingerprints, }; // --------------------------------------------------------------------------- @@ -443,6 +445,7 @@ impl LlmAccumulator { LlmEvent::ThinkingSignature(signature) => { self.thinking_signature = Some(signature.clone()); }, + LlmEvent::StreamRetryStarted { .. } => {}, LlmEvent::ToolCallDelta { index, id, diff --git a/crates/adapter-llm/src/openai.rs b/crates/adapter-llm/src/openai.rs index f889b386..cfd4d077 100644 --- a/crates/adapter-llm/src/openai.rs +++ b/crates/adapter-llm/src/openai.rs @@ -32,8 +32,7 @@ use std::{ }; use astrcode_core::{ - AstrError, CancelToken, LlmMessage, PromptCacheGlobalStrategy, PromptCacheHints, - ReasoningContent, Result, ToolCallRequest, ToolDefinition, + AstrError, CancelToken, LlmMessage, ReasoningContent, Result, ToolCallRequest, ToolDefinition, }; use async_trait::async_trait; use futures_util::StreamExt; @@ -43,7 +42,8 @@ use tokio::select; use crate::{ EventSink, FinishReason, LlmAccumulator, LlmClientConfig, LlmEvent, LlmOutput, LlmProvider, - LlmRequest, LlmUsage, ModelLimits, Utf8StreamDecoder, build_http_client, + LlmRequest, LlmUsage, ModelLimits, PromptCacheGlobalStrategy, PromptCacheHints, + Utf8StreamDecoder, build_http_client, cache_tracker::{CacheCheckContext, CacheTracker, stable_hash}, emit_event, is_retryable_status, wait_retry_delay, }; @@ -299,80 +299,100 @@ impl OpenAiProvider { output.prompt_cache_diagnostics = tracker.finalize(pending_cache_check, output.usage); } - /// 发送 HTTP 请求并处理响应。 + /// 执行单次 HTTP 请求并处理响应状态。 /// - /// 内置指数退避重试逻辑： - /// - 可重试的 HTTP 状态码（408/429/5xx）和传输层错误会自动重试 - /// - 重试期间监听取消令牌，一旦取消立即中断 - /// - 非重试错误（如 400/401/403）直接返回 - async fn send_request( + /// 调用方在更外层统一管理 attempt 预算，使“建立响应”和“读取流式 body” + /// 属于同一个重试边界。 + async fn send_request_once( &self, req: &T, cancel: CancelToken, ) -> Result { - for attempt in 0..=self.client_config.max_retries { - let send_future = self - .client - .post(&self.api_url) - .bearer_auth(&self.api_key) - .json(req) - .send(); - - let response = select! { - _ = crate::cancelled(cancel.clone()) => { - return Err(AstrError::LlmInterrupted); - } - result = send_future => result - .map_err(|error| AstrError::http_with_source( - "failed to call openai endpoint", - error.is_timeout() || error.is_connect() || error.is_body(), - error, - )) - }; + let send_future = self + .client + .post(&self.api_url) + .bearer_auth(&self.api_key) + .json(req) + .send(); + + let response = select! { + _ = crate::cancelled(cancel.clone()) => { + return Err(AstrError::LlmInterrupted); + } + result = send_future => result + .map_err(|error| AstrError::http_with_source( + "failed to call openai endpoint", + error.is_timeout() || error.is_connect() || error.is_body(), + error, + ))? + }; - match response { - Ok(response) => { - let status = response.status(); - if status.is_success() { - return Ok(response); - } + let status = response.status(); + if status.is_success() { + return Ok(response); + } - let body = response.text().await.unwrap_or_default(); - if is_retryable_status(status) && attempt < self.client_config.max_retries { - wait_retry_delay( - attempt, - cancel.clone(), - self.client_config.retry_base_delay, - ) - .await?; - continue; - } + let body = response.text().await.unwrap_or_default(); + Err(AstrError::LlmRequestFailed { + status: status.as_u16(), + body, + }) + } - return Err(AstrError::LlmRequestFailed { - status: status.as_u16(), - body, - }); - }, - Err(error) => { - if error.is_retryable() && attempt < self.client_config.max_retries { - wait_retry_delay( - attempt, - cancel.clone(), - self.client_config.retry_base_delay, - ) - .await?; - continue; - } - return Err(error); + fn should_retry_generation_error(&self, error: &AstrError) -> bool { + if error.is_cancelled() { + return false; + } + if error.is_retryable() { + return true; + } + match error { + AstrError::LlmRequestFailed { status, .. } => { + reqwest::StatusCode::from_u16(*status).is_ok_and(is_retryable_status) + }, + _ => false, + } + } + + async fn wait_before_generation_retry( + &self, + error: &AstrError, + attempt: u32, + cancel: CancelToken, + sink: Option<&EventSink>, + ) -> Result<()> { + if let Some(sink) = sink { + emit_event( + LlmEvent::StreamRetryStarted { + attempt: attempt.saturating_add(2), + max_attempts: self.client_config.max_retries.saturating_add(1), + reason: error.to_string(), }, - } + &mut LlmAccumulator::default(), + sink, + ); } + wait_retry_delay(attempt, cancel, self.client_config.retry_base_delay).await + } - // 所有路径都会通过 return 退出循环；若到达此处说明逻辑有误， - // 返回 Internal 而非 panic 以保证运行时安全 - Err(AstrError::Internal( - "retry loop should have returned on all paths".into(), - )) + fn annotate_retry_exhausted(&self, error: AstrError, attempts: u32) -> AstrError { + if !self.should_retry_generation_error(&error) || attempts <= 1 { + return error; + } + match error { + AstrError::HttpRequest { + context, + detail, + retryable, + source, + } => AstrError::HttpRequest { + context: format!("{context} after {attempts} attempts"), + detail, + retryable, + source, + }, + other => other, + } } } @@ -664,61 +684,101 @@ impl LlmProvider for OpenAiProvider { .as_ref() .map(|hints| hints.global_cache_strategy) .unwrap_or(PromptCacheGlobalStrategy::SystemPrompt); - let cancel = request.cancel; - let req = self.build_chat_completions_request(OpenAiBuildRequestInput { - messages: &request.messages, - tools: &request.tools, - system_prompt: request.system_prompt.as_deref(), - system_prompt_blocks: &request.system_prompt_blocks, - prompt_cache_hints: prompt_cache_hints.as_ref(), - max_output_tokens_override: request.max_output_tokens_override, - stream: sink.is_some(), - }); - let pending_cache_check = self.cache_tracker.lock().ok().map(|tracker| { - tracker.prepare(&Self::build_cache_check_context( - &req, - global_cache_strategy, - prompt_cache_hints - .as_ref() - .is_some_and(|hints| hints.compacted), - prompt_cache_hints - .as_ref() - .is_some_and(|hints| hints.tool_result_rebudgeted), - )) - }); - let response = self.send_request(&req, cancel.clone()).await?; - - match sink { - None => { - // 非流式路径：解析完整 JSON 响应 - let parsed: OpenAiChatResponse = response.json().await.map_err(|error| { - AstrError::http_with_source( - "failed to parse openai response", - error.is_timeout() || error.is_connect() || error.is_body(), - error, + let cancel = request.cancel.clone(); + let max_retries = self.client_config.max_retries; + + for attempt in 0..=max_retries { + let req = self.build_chat_completions_request(OpenAiBuildRequestInput { + messages: &request.messages, + tools: &request.tools, + system_prompt: request.system_prompt.as_deref(), + system_prompt_blocks: &request.system_prompt_blocks, + prompt_cache_hints: prompt_cache_hints.as_ref(), + max_output_tokens_override: request.max_output_tokens_override, + stream: sink.is_some(), + }); + let pending_cache_check = self.cache_tracker.lock().ok().map(|tracker| { + tracker.prepare(&Self::build_cache_check_context( + &req, + global_cache_strategy, + prompt_cache_hints + .as_ref() + .is_some_and(|hints| hints.compacted), + prompt_cache_hints + .as_ref() + .is_some_and(|hints| hints.tool_result_rebudgeted), + )) + }); + let response = self.send_request_once(&req, cancel.clone()).await; + let result = match (response, sink.as_ref()) { + (Ok(response), None) => { + // 非流式路径：解析完整 JSON 响应 + match response + .json::() + .await + .map_err(|error| { + AstrError::http_with_source( + "failed to parse openai response", + error.is_timeout() || error.is_connect() || error.is_body(), + error, + ) + }) { + Ok(parsed) => { + let OpenAiChatResponse { choices, usage } = parsed; + let usage = usage.map(openai_usage_to_llm_usage); + match choices.into_iter().next() { + Some(first_choice) => { + let mut output = message_to_output( + first_choice.message, + usage, + first_choice.finish_reason, + ); + self.apply_cache_diagnostics(&mut output, pending_cache_check); + Ok(output) + }, + None => Err(AstrError::LlmStreamError( + "openai response did not include choices".to_string(), + )), + } + }, + Err(error) => Err(error), + } + }, + (Ok(response), Some(sink)) => { + self.stream_response( + response, + ChatCompletionsSseProcessor::new(), + cancel.clone(), + Arc::clone(sink), + pending_cache_check, ) - })?; - let OpenAiChatResponse { choices, usage } = parsed; - let usage = usage.map(openai_usage_to_llm_usage); - let first_choice = choices.into_iter().next().ok_or_else(|| { - AstrError::LlmStreamError("openai response did not include choices".to_string()) - })?; - let mut output = - message_to_output(first_choice.message, usage, first_choice.finish_reason); - self.apply_cache_diagnostics(&mut output, pending_cache_check); - Ok(output) - }, - Some(sink) => { - self.stream_response( - response, - ChatCompletionsSseProcessor::new(), - cancel, - sink, - pending_cache_check, - ) - .await - }, + .await + }, + (Err(error), _) => Err(error), + }; + + match result { + Ok(output) => return Ok(output), + Err(error) + if attempt < max_retries && self.should_retry_generation_error(&error) => + { + self.wait_before_generation_retry( + &error, + attempt, + cancel.clone(), + sink.as_ref(), + ) + .await?; + }, + Err(error) => { + return Err(self.annotate_retry_exhausted(error, attempt.saturating_add(1))); + }, + } } + + Err(AstrError::Internal( + "openai generation retry loop should have returned on all paths".into(), + )) } /// 返回当前模型的上下文窗口估算。 @@ -737,22 +797,48 @@ impl OpenAiProvider { sink: Option, ) -> Result { let cancel = request.cancel.clone(); - let req = responses::build_request(self, &request, sink.is_some()); - let response = self.send_request(&req, cancel.clone()).await?; - - match sink { - None => responses::parse_non_streaming_response(response).await, - Some(sink) => { - self.stream_response( - response, - responses::ResponsesSseProcessor::new(), - cancel, - sink, - None, - ) - .await - }, + let max_retries = self.client_config.max_retries; + + for attempt in 0..=max_retries { + let req = responses::build_request(self, &request, sink.is_some()); + let response = self.send_request_once(&req, cancel.clone()).await; + let result = match (response, sink.as_ref()) { + (Ok(response), None) => responses::parse_non_streaming_response(response).await, + (Ok(response), Some(sink)) => { + self.stream_response( + response, + responses::ResponsesSseProcessor::new(), + cancel.clone(), + Arc::clone(sink), + None, + ) + .await + }, + (Err(error), _) => Err(error), + }; + + match result { + Ok(output) => return Ok(output), + Err(error) + if attempt < max_retries && self.should_retry_generation_error(&error) => + { + self.wait_before_generation_retry( + &error, + attempt, + cancel.clone(), + sink.as_ref(), + ) + .await?; + }, + Err(error) => { + return Err(self.annotate_retry_exhausted(error, attempt.saturating_add(1))); + }, + } } + + Err(AstrError::Internal( + "openai responses retry loop should have returned on all paths".into(), + )) } } @@ -1153,6 +1239,7 @@ mod tests { use std::{ net::TcpListener, sync::{Arc, Mutex}, + time::Duration, }; use astrcode_core::{CancelToken, UserMessageOrigin}; @@ -1166,6 +1253,10 @@ mod tests { use crate::sink_collector; fn spawn_server(response: String) -> (String, JoinHandle<()>) { + spawn_server_responses(vec![response]) + } + + fn spawn_server_responses(responses: Vec) -> (String, JoinHandle<()>) { let listener = TcpListener::bind("127.0.0.1:0").expect("listener should bind"); let addr = listener.local_addr().expect("listener should have addr"); listener @@ -1174,16 +1265,18 @@ mod tests { let listener = tokio::net::TcpListener::from_std(listener).expect("tokio listener"); let handle = tokio::spawn(async move { - let (mut socket, _) = listener.accept().await.expect("accept should work"); - let mut buf = [0_u8; 4096]; - // 故意忽略：读取残余数据仅用于清理，失败无影响 - let _ = socket.read(&mut buf).await; - socket - .write_all(response.as_bytes()) - .await - .expect("response should be written"); - // 故意忽略：关闭 socket 时连接可能已断开 - let _ = socket.shutdown().await; + for response in responses { + let (mut socket, _) = listener.accept().await.expect("accept should work"); + let mut buf = [0_u8; 4096]; + // 故意忽略：读取残余数据仅用于清理，失败无影响 + let _ = socket.read(&mut buf).await; + socket + .write_all(response.as_bytes()) + .await + .expect("response should be written"); + // 故意忽略：关闭 socket 时连接可能已断开 + let _ = socket.shutdown().await; + } }); (format!("http://{}", addr), handle) @@ -1820,6 +1913,145 @@ mod tests { ); } + #[tokio::test] + async fn generate_streaming_retries_bad_body_and_resets_live_draft() { + let first_body = format!( + "data: {}\n\n", + json!({ + "choices": [{ + "delta": { "content": "bad" }, + "finish_reason": null + }] + }) + ); + let first_response = format!( + "HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\ncontent-length: \ + {}\r\nconnection: close\r\n\r\n{}", + first_body.len() + 128, + first_body + ); + let second_body = format!( + "data: {}\n\ndata: [DONE]\n\n", + json!({ + "choices": [{ + "delta": { "content": "ok" }, + "finish_reason": "stop" + }] + }) + ); + let second_response = format!( + "HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\ncontent-length: \ + {}\r\nconnection: close\r\n\r\n{}", + second_body.len(), + second_body + ); + let (base_url, handle) = spawn_server_responses(vec![first_response, second_response]); + let provider = OpenAiProvider::new( + base_url, + "sk-test".to_string(), + "model-a".to_string(), + ModelLimits { + context_window: 128_000, + max_output_tokens: 2048, + }, + LlmClientConfig { + max_retries: 1, + retry_base_delay: Duration::from_millis(1), + ..LlmClientConfig::default() + }, + ) + .expect("provider should build"); + let events = Arc::new(Mutex::new(Vec::new())); + + let output = provider + .generate( + LlmRequest::new( + vec![LlmMessage::User { + content: "hi".to_string(), + origin: UserMessageOrigin::User, + }], + vec![], + CancelToken::new(), + ), + Some(sink_collector(events.clone())), + ) + .await + .expect("generate should retry and succeed"); + + handle.await.expect("server should join"); + let events = events.lock().expect("lock").clone(); + + assert_eq!(output.content, "ok"); + assert!(matches!( + events.as_slice(), + [ + LlmEvent::TextDelta(first), + LlmEvent::StreamRetryStarted { + attempt: 2, + max_attempts: 2, + .. + }, + LlmEvent::TextDelta(second), + ] if first == "bad" && second == "ok" + )); + } + + #[tokio::test] + async fn generate_streaming_reports_attempts_after_retry_exhaustion() { + let body = format!( + "data: {}\n\n", + json!({ + "choices": [{ + "delta": { "content": "bad" }, + "finish_reason": null + }] + }) + ); + let bad_response = || { + format!( + "HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\ncontent-length: \ + {}\r\nconnection: close\r\n\r\n{}", + body.len() + 128, + body + ) + }; + let (base_url, handle) = spawn_server_responses(vec![bad_response(), bad_response()]); + let provider = OpenAiProvider::new( + base_url, + "sk-test".to_string(), + "model-a".to_string(), + ModelLimits { + context_window: 128_000, + max_output_tokens: 2048, + }, + LlmClientConfig { + max_retries: 1, + retry_base_delay: Duration::from_millis(1), + ..LlmClientConfig::default() + }, + ) + .expect("provider should build"); + + let error = provider + .generate( + LlmRequest::new( + vec![LlmMessage::User { + content: "hi".to_string(), + origin: UserMessageOrigin::User, + }], + vec![], + CancelToken::new(), + ), + Some(sink_collector(Arc::new(Mutex::new(Vec::new())))), + ) + .await + .expect_err("generate should exhaust retries"); + + handle.await.expect("server should join"); + assert!(error.is_retryable()); + assert!(error.to_string().contains("after 2 attempts")); + } + #[test] fn sse_stream_handles_multibyte_text_split_across_chunks() { let mut accumulator = LlmAccumulator::default(); diff --git a/crates/adapter-llm/src/openai/dto.rs b/crates/adapter-llm/src/openai/dto.rs index 85aa04c0..26d348d8 100644 --- a/crates/adapter-llm/src/openai/dto.rs +++ b/crates/adapter-llm/src/openai/dto.rs @@ -11,7 +11,8 @@ //! - Responses 专有类型继续使用 `serde_json::Value`（在 `responses.rs`） //! - 本模块只存放"两个路径都会用到"的类型和函数 -use astrcode_core::{LlmMessage, LlmUsage, ToolDefinition}; +use astrcode_agent_runtime::LlmUsage; +use astrcode_core::{LlmMessage, ToolDefinition}; use serde::{Deserialize, Serialize}; use serde_json::Value; @@ -212,3 +213,71 @@ pub(super) trait SseProcessor { None } } + +#[cfg(test)] +mod tests { + use astrcode_core::{LlmMessage, ToolCallRequest, UserMessageOrigin}; + + use super::to_openai_message; + + #[test] + fn assistant_message_without_content_or_tool_calls_serializes_empty_fields_as_none() { + let message = LlmMessage::Assistant { + content: String::new(), + tool_calls: Vec::new(), + reasoning: None, + }; + + let converted = to_openai_message(&message); + + assert_eq!(converted.role, "assistant"); + assert!(converted.content.is_none()); + assert!(converted.tool_calls.is_none()); + assert!(converted.tool_call_id.is_none()); + } + + #[test] + fn assistant_tool_calls_serialize_without_empty_content() { + let message = LlmMessage::Assistant { + content: String::new(), + tool_calls: vec![ToolCallRequest { + id: "call-1".to_string(), + name: "readFile".to_string(), + args: serde_json::json!({"path":"README.md"}), + }], + reasoning: None, + }; + + let converted = to_openai_message(&message); + let tool_calls = converted + .tool_calls + .expect("assistant tool calls should be serialized"); + + assert_eq!(converted.role, "assistant"); + assert!(converted.content.is_none()); + assert_eq!(tool_calls.len(), 1); + assert_eq!(tool_calls[0].id, "call-1"); + assert_eq!(tool_calls[0].tool_type, "function"); + assert_eq!(tool_calls[0].function.name, "readFile"); + assert_eq!(tool_calls[0].function.arguments, r#"{"path":"README.md"}"#); + } + + #[test] + fn user_and_tool_messages_keep_required_content_fields() { + let user = to_openai_message(&LlmMessage::User { + content: "hello".to_string(), + origin: UserMessageOrigin::User, + }); + let tool = to_openai_message(&LlmMessage::Tool { + tool_call_id: "call-1".to_string(), + content: "result".to_string(), + }); + + assert_eq!(user.role, "user"); + assert_eq!(user.content.as_deref(), Some("hello")); + assert!(user.tool_call_id.is_none()); + assert_eq!(tool.role, "tool"); + assert_eq!(tool.content.as_deref(), Some("result")); + assert_eq!(tool.tool_call_id.as_deref(), Some("call-1")); + } +} diff --git a/crates/adapter-mcp/Cargo.toml b/crates/adapter-mcp/Cargo.toml index 8c7136a4..3b808c0b 100644 --- a/crates/adapter-mcp/Cargo.toml +++ b/crates/adapter-mcp/Cargo.toml @@ -8,6 +8,7 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } astrcode-adapter-prompt = { path = "../adapter-prompt" } +astrcode-plugin-host = { path = "../plugin-host" } astrcode-support = { path = "../support" } async-trait.workspace = true base64.workspace = true diff --git a/crates/adapter-mcp/src/core_port.rs b/crates/adapter-mcp/src/core_port.rs index 9ed1640d..14385050 100644 --- a/crates/adapter-mcp/src/core_port.rs +++ b/crates/adapter-mcp/src/core_port.rs @@ -1,13 +1,12 @@ -//! 桥接 `adapter-mcp` 与 `core::ports::ResourceProvider`。 +//! 桥接 `adapter-mcp` 与 `plugin-host::ResourceProvider`。 //! //! 让 kernel 通过统一的资源端口读取 MCP 资源。 //! 通过 resource_index 将 URI 反查到所属服务器，再委托给 McpConnectionManager::read_resource。 use std::sync::Arc; -use astrcode_core::{ - AstrError, ResourceProvider, ResourceReadResult, ResourceRequestContext, Result, -}; +use astrcode_core::{AstrError, Result}; +use astrcode_plugin_host::{ResourceProvider, ResourceReadResult, ResourceRequestContext}; use async_trait::async_trait; use log::warn; use serde_json::json; diff --git a/crates/adapter-prompt/Cargo.toml b/crates/adapter-prompt/Cargo.toml index d23d3d0a..f64264fa 100644 --- a/crates/adapter-prompt/Cargo.toml +++ b/crates/adapter-prompt/Cargo.toml @@ -6,7 +6,9 @@ license-file.workspace = true authors.workspace = true [dependencies] +astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } +astrcode-host-session = { path = "../host-session" } astrcode-support = { path = "../support" } anyhow.workspace = true async-trait.workspace = true diff --git a/crates/adapter-prompt/src/composer.rs b/crates/adapter-prompt/src/composer.rs index 41befa93..f65d8b78 100644 --- a/crates/adapter-prompt/src/composer.rs +++ b/crates/adapter-prompt/src/composer.rs @@ -31,7 +31,8 @@ use std::{ }; use anyhow::{Result, anyhow}; -use astrcode_core::{LlmMessage, PromptCacheHints, UserMessageOrigin}; +use astrcode_agent_runtime::PromptCacheHints; +use astrcode_core::{LlmMessage, UserMessageOrigin}; use super::{ BlockCondition, BlockContent, BlockKind, BlockSpec, PromptBlock, PromptContext, diff --git a/crates/adapter-prompt/src/core_port.rs b/crates/adapter-prompt/src/core_port.rs index b80eaeb4..819fb920 100644 --- a/crates/adapter-prompt/src/core_port.rs +++ b/crates/adapter-prompt/src/core_port.rs @@ -3,9 +3,12 @@ //! `core::ports::PromptProvider` 是 kernel 消费的简化端口接口， //! 本模块将其适配到 `LayeredPromptBuilder` 的完整 prompt 构建能力上。 -use astrcode_core::{ - PromptCacheGlobalStrategy, Result, SystemPromptBlock, SystemPromptLayer, - ports::{PromptBuildCacheMetrics, PromptBuildOutput, PromptBuildRequest, PromptProvider}, +use astrcode_agent_runtime::{PromptCacheGlobalStrategy, PromptCacheHints}; +use astrcode_core::{Result, SystemPromptBlock, SystemPromptLayer}; +use astrcode_host_session::{ + PromptAgentProfileSummary as HostPromptAgentProfileSummary, PromptBuildCacheMetrics, + PromptBuildOutput, PromptBuildRequest, PromptProvider, + PromptSkillSummary as HostPromptSkillSummary, }; use async_trait::async_trait; use serde_json::Value; @@ -99,13 +102,11 @@ impl PromptProvider for ComposerPromptProvider { } } -fn convert_agent_profile( - summary: astrcode_core::PromptAgentProfileSummary, -) -> PromptAgentProfileSummary { +fn convert_agent_profile(summary: HostPromptAgentProfileSummary) -> PromptAgentProfileSummary { PromptAgentProfileSummary::new(summary.id, summary.description) } -fn convert_skill(summary: astrcode_core::PromptSkillSummary) -> PromptSkillSummary { +fn convert_skill(summary: HostPromptSkillSummary) -> PromptSkillSummary { PromptSkillSummary::new(summary.id, summary.description) } @@ -176,7 +177,7 @@ fn build_output_metadata( step_index: usize, turn_index: usize, output: &crate::PromptBuildOutput, - prompt_cache_hints: astrcode_core::PromptCacheHints, + prompt_cache_hints: PromptCacheHints, ) -> Value { serde_json::json!({ "extra_tools_count": output.plan.extra_tools.len(), @@ -249,9 +250,9 @@ fn insert_json_string( mod tests { use std::path::PathBuf; - use astrcode_core::{ - CapabilityKind, CapabilitySpec, PromptCacheGlobalStrategy, ports::PromptBuildRequest, - }; + use astrcode_agent_runtime::PromptCacheGlobalStrategy; + use astrcode_core::{CapabilityKind, CapabilitySpec}; + use astrcode_host_session::PromptBuildRequest; use super::{build_output_metadata, build_prompt_vars, select_global_cache_strategy}; use crate::{BlockKind, PromptBlock, PromptDiagnostics, PromptPlan, block::BlockMetadata}; diff --git a/crates/adapter-prompt/src/layered_builder.rs b/crates/adapter-prompt/src/layered_builder.rs index a769bd70..bbbc266a 100644 --- a/crates/adapter-prompt/src/layered_builder.rs +++ b/crates/adapter-prompt/src/layered_builder.rs @@ -11,7 +11,7 @@ use std::{ }; use anyhow::Result; -use astrcode_core::{PromptCacheHints, PromptLayerFingerprints}; +use astrcode_agent_runtime::{PromptCacheHints, PromptLayerFingerprints}; use super::{ PromptBuildOutput, PromptComposer, PromptComposerOptions, PromptContext, PromptContributor, diff --git a/crates/adapter-storage/Cargo.toml b/crates/adapter-storage/Cargo.toml index cc0c4e48..4345d5aa 100644 --- a/crates/adapter-storage/Cargo.toml +++ b/crates/adapter-storage/Cargo.toml @@ -7,6 +7,7 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-host-session = { path = "../host-session" } astrcode-support = { path = "../support" } async-trait.workspace = true chrono.workspace = true diff --git a/crates/adapter-storage/src/session/batch_appender.rs b/crates/adapter-storage/src/session/batch_appender.rs index fa51a386..13da2435 100644 --- a/crates/adapter-storage/src/session/batch_appender.rs +++ b/crates/adapter-storage/src/session/batch_appender.rs @@ -5,7 +5,8 @@ use std::{ time::Duration, }; -use astrcode_core::{SessionRecoveryCheckpoint, StorageEvent, StoredEvent, store::StoreResult}; +use astrcode_core::{StorageEvent, StoredEvent, store::StoreResult}; +use astrcode_host_session::SessionRecoveryCheckpoint; use tokio::sync::{Mutex, Notify, oneshot}; use super::{event_log::EventLog, paths::resolve_existing_session_path_from_projects_root}; diff --git a/crates/adapter-storage/src/session/checkpoint.rs b/crates/adapter-storage/src/session/checkpoint.rs index 4028274d..4074d6ac 100644 --- a/crates/adapter-storage/src/session/checkpoint.rs +++ b/crates/adapter-storage/src/session/checkpoint.rs @@ -6,7 +6,8 @@ use std::{ path::{Path, PathBuf}, }; -use astrcode_core::{RecoveredSessionState, SessionRecoveryCheckpoint, StoredEvent}; +use astrcode_core::StoredEvent; +use astrcode_host_session::{RecoveredSessionState, SessionRecoveryCheckpoint}; use serde::{Deserialize, Serialize}; use uuid::Uuid; diff --git a/crates/adapter-storage/src/session/repository.rs b/crates/adapter-storage/src/session/repository.rs index 873726c3..7e202775 100644 --- a/crates/adapter-storage/src/session/repository.rs +++ b/crates/adapter-storage/src/session/repository.rs @@ -4,11 +4,11 @@ use std::{ }; use astrcode_core::{ - DeleteProjectResult, RecoveredSessionState, Result, SessionId, SessionMeta, - SessionRecoveryCheckpoint, SessionTurnAcquireResult, StorageEvent, StoredEvent, - ports::EventStore, + DeleteProjectResult, Result, SessionId, SessionMeta, SessionTurnAcquireResult, StorageEvent, + StoredEvent, store::{EventLogWriter, SessionManager, StoreResult}, }; +use astrcode_host_session::{EventStore, RecoveredSessionState, SessionRecoveryCheckpoint}; use async_trait::async_trait; use tokio::sync::Mutex; @@ -378,8 +378,11 @@ mod tests { use std::time::Instant; use astrcode_core::{ - AgentEventContext, AgentState, EventStore, LlmMessage, ModeId, Phase, - SessionRecoveryCheckpoint, StorageEvent, StorageEventPayload, UserMessageOrigin, + AgentEventContext, LlmMessage, ModeId, Phase, StorageEvent, StorageEventPayload, + UserMessageOrigin, + }; + use astrcode_host_session::{ + AgentState, EventStore, ProjectionRegistrySnapshot, SessionRecoveryCheckpoint, }; use super::*; @@ -471,7 +474,7 @@ mod tests { turn_count: 2, last_assistant_at: None, }, - astrcode_core::ProjectionRegistrySnapshot::default(), + ProjectionRegistrySnapshot::default(), 2, ), ) @@ -531,7 +534,7 @@ mod tests { turn_count: 1, last_assistant_at: None, }, - astrcode_core::ProjectionRegistrySnapshot::default(), + ProjectionRegistrySnapshot::default(), 1, ), ) diff --git a/crates/adapter-tools/Cargo.toml b/crates/adapter-tools/Cargo.toml index c809a6b5..4d9160af 100644 --- a/crates/adapter-tools/Cargo.toml +++ b/crates/adapter-tools/Cargo.toml @@ -7,6 +7,7 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-host-session = { path = "../host-session" } astrcode-support = { path = "../support" } async-trait.workspace = true base64.workspace = true diff --git a/crates/adapter-tools/src/agent_tools/collaboration_executor.rs b/crates/adapter-tools/src/agent_tools/collaboration_executor.rs index 7148f02a..894f2952 100644 --- a/crates/adapter-tools/src/agent_tools/collaboration_executor.rs +++ b/crates/adapter-tools/src/agent_tools/collaboration_executor.rs @@ -1,5 +1,5 @@ -//! 适配层转发：复用 core 中定义的 CollaborationExecutor 端口。 +//! 适配层转发：复用 host-session owner bridge 中定义的协作端口。 //! -//! Why: 执行契约应由 core 统一定义，adapter-tools 仅消费该端口并暴露工具实现。 +//! Why: 协作执行契约属于 session owner，adapter-tools 仅消费该端口并暴露工具实现。 -pub use astrcode_core::CollaborationExecutor; +pub use astrcode_host_session::CollaborationExecutor; diff --git a/crates/adapter-tools/src/agent_tools/spawn_tool.rs b/crates/adapter-tools/src/agent_tools/spawn_tool.rs index 6d148c3f..67e1e763 100644 --- a/crates/adapter-tools/src/agent_tools/spawn_tool.rs +++ b/crates/adapter-tools/src/agent_tools/spawn_tool.rs @@ -1,9 +1,10 @@ use std::sync::Arc; use astrcode_core::{ - Result, SpawnAgentParams, SubAgentExecutor, Tool, ToolCapabilityMetadata, ToolContext, - ToolDefinition, ToolExecutionResult, ToolPromptMetadata, + Result, SpawnAgentParams, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, + ToolExecutionResult, ToolPromptMetadata, }; +use astrcode_host_session::SubAgentExecutor; use async_trait::async_trait; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/agent_tools/tests.rs b/crates/adapter-tools/src/agent_tools/tests.rs index 061832e3..0227ee67 100644 --- a/crates/adapter-tools/src/agent_tools/tests.rs +++ b/crates/adapter-tools/src/agent_tools/tests.rs @@ -7,9 +7,10 @@ use astrcode_core::{ FailedSubRunOutcome, ObserveParams, ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ParentExecutionRef, ProgressParentDeliveryPayload, SendAgentParams, SendToChildParams, SendToParentParams, - SpawnAgentParams, SubAgentExecutor, SubRunFailure, SubRunFailureCode, SubRunHandoff, - SubRunResult, Tool, ToolContext, + SpawnAgentParams, SubRunFailure, SubRunFailureCode, SubRunHandoff, SubRunResult, Tool, + ToolContext, }; +use astrcode_host_session::SubAgentExecutor; use async_trait::async_trait; use serde_json::json; diff --git a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs index fe4f1a80..00dd521e 100644 --- a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs +++ b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs @@ -8,8 +8,9 @@ use std::{fs, path::Path, time::Instant}; use astrcode_core::{ AstrError, BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, ModeId, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, - ToolPromptMetadata, session_plan_content_digest, + ToolPromptMetadata, }; +use astrcode_host_session::session_plan_content_digest; use async_trait::async_trait; use chrono::Utc; use serde_json::json; diff --git a/crates/adapter-tools/src/builtin_tools/session_plan.rs b/crates/adapter-tools/src/builtin_tools/session_plan.rs index 3e26257c..5104d0cb 100644 --- a/crates/adapter-tools/src/builtin_tools/session_plan.rs +++ b/crates/adapter-tools/src/builtin_tools/session_plan.rs @@ -9,11 +9,11 @@ use std::{ path::{Path, PathBuf}, }; -use astrcode_core::{ - AstrError, ModeArtifactDef, Result, ToolContext, WorkflowArtifactRef, WorkflowInstanceState, - session_plan_content_digest, +use astrcode_core::{AstrError, ModeArtifactDef, Result, ToolContext}; +pub use astrcode_host_session::{SessionPlanState, SessionPlanStatus}; +use astrcode_host_session::{ + WorkflowArtifactRef, WorkflowInstanceState, session_plan_content_digest, }; -pub use astrcode_core::{SessionPlanState, SessionPlanStatus}; use chrono::Utc; use crate::builtin_tools::fs_common::session_dir_for_tool_results; diff --git a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs index 7b79e6d9..a28a954e 100644 --- a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs +++ b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs @@ -6,9 +6,10 @@ use std::{fs, time::Instant}; use astrcode_core::{ - AstrError, Result, SessionPlanState, SessionPlanStatus, SideEffect, Tool, - ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, ToolPromptMetadata, + AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, + ToolExecutionResult, ToolPromptMetadata, }; +use astrcode_host_session::{SessionPlanState, SessionPlanStatus}; use async_trait::async_trait; use chrono::Utc; use serde::Deserialize; diff --git a/crates/adapter-tools/src/lib.rs b/crates/adapter-tools/src/lib.rs index 805f9c38..3c5aae0c 100644 --- a/crates/adapter-tools/src/lib.rs +++ b/crates/adapter-tools/src/lib.rs @@ -9,7 +9,7 @@ //! //! ## 架构约束 //! -//! - 本 crate 仅依赖 `astrcode-core`，不依赖 `runtime` 或其他业务 crate +//! - 本 crate 仅依赖 `astrcode-core` 与 `host-session` 的协作 owner bridge，不依赖 runtime 实现 //! - 所有工具通过 `Tool` trait 统一接口暴露，由 `runtime` 层统一调度 //! - 工具执行结果包含结构化 metadata，供前端渲染（如终端视图、diff 视图） diff --git a/crates/session-runtime/Cargo.toml b/crates/agent-runtime/Cargo.toml similarity index 70% rename from crates/session-runtime/Cargo.toml rename to crates/agent-runtime/Cargo.toml index aef399e6..ec7a2b4e 100644 --- a/crates/session-runtime/Cargo.toml +++ b/crates/agent-runtime/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "astrcode-session-runtime" +name = "astrcode-agent-runtime" version = "0.1.0" edition.workspace = true license-file.workspace = true @@ -7,17 +7,13 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } -astrcode-kernel = { path = "../kernel" } -astrcode-support = { path = "../support" } async-trait.workspace = true chrono.workspace = true -dashmap.workspace = true -futures-util.workspace = true log.workspace = true regex.workspace = true serde.workspace = true serde_json.workspace = true -thiserror.workspace = true +futures-util.workspace = true tokio.workspace = true [dev-dependencies] diff --git a/crates/agent-runtime/src/cancel.rs b/crates/agent-runtime/src/cancel.rs new file mode 100644 index 00000000..ce88209d --- /dev/null +++ b/crates/agent-runtime/src/cancel.rs @@ -0,0 +1,3 @@ +/// 取消与超时传播骨架。 +#[derive(Debug, Default)] +pub struct CancelToken; diff --git a/crates/session-runtime/src/context_window/compaction.rs b/crates/agent-runtime/src/context_window/compaction.rs similarity index 83% rename from crates/session-runtime/src/context_window/compaction.rs rename to crates/agent-runtime/src/context_window/compaction.rs index f771b4d8..a28f6775 100644 --- a/crates/session-runtime/src/context_window/compaction.rs +++ b/crates/agent-runtime/src/context_window/compaction.rs @@ -1,31 +1,22 @@ -//! # 上下文压缩 (Context Compaction) -//! -//! 当会话消息接近 LLM 上下文窗口限制时，自动压缩历史消息以释放空间。 -//! -//! ## 压缩策略 -//! -//! 1. 将消息分为前缀（可压缩）和后缀（保留最近安全边界） -//! 2. 调用 LLM 对前缀生成摘要 -//! 3. 用摘要替换前缀，保留后缀不变 -//! -//! ## 重试机制 -//! -//! 如果压缩请求本身超出上下文窗口，会逐步丢弃最旧的 compact unit 并重试， -//! 最多重试 3 次。 - use std::{collections::HashSet, sync::OnceLock}; use astrcode_core::{ - AstrError, CancelToken, CompactAppliedMeta, CompactMode, CompactSummaryEnvelope, LlmMessage, - LlmRequest, ModelLimits, Result, UserMessageOrigin, format_compact_summary, - parse_compact_summary_message, - tool_result_persist::{is_persisted_output, persisted_output_absolute_path}, + AstrError, CancelToken, CompactAppliedMeta, CompactMode, CompactSummaryEnvelope, + CompactTrigger, LlmMessage, Result, StorageEvent, StorageEventPayload, UserMessageOrigin, + format_compact_summary, parse_compact_summary_message, }; -use astrcode_kernel::KernelGateway; use chrono::{DateTime, Utc}; use regex::Regex; -use super::token_usage::{effective_context_window, estimate_request_tokens}; +use super::{ + file_access::FileAccessTracker, + settings::ContextWindowSettings, + token_usage::{effective_context_window, estimate_request_tokens}, +}; +use crate::{ + provider::{LlmProvider, LlmRequest, ModelLimits}, + types::RuntimeTurnEvent, +}; const BASE_COMPACT_PROMPT_TEMPLATE: &str = include_str!("templates/compact/base.md"); const INCREMENTAL_COMPACT_PROMPT_TEMPLATE: &str = include_str!("templates/compact/incremental.md"); @@ -34,62 +25,39 @@ const INCREMENTAL_COMPACT_PROMPT_TEMPLATE: &str = include_str!("templates/compac mod protocol; use protocol::*; -/// 压缩配置。 #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct CompactConfig { - /// 保留最近的用户 turn 数量。 pub keep_recent_turns: usize, - /// 额外保留最近真实用户消息的数量。 pub keep_recent_user_messages: usize, - /// 压缩触发方式。 - pub trigger: astrcode_core::CompactTrigger, - /// compact 请求自身保留的输出预算。 + pub trigger: CompactTrigger, pub summary_reserve_tokens: usize, - /// compact 请求的最大输出 token 上限。 pub max_output_tokens: usize, - /// compact 允许的最大裁剪重试次数。 pub max_retry_attempts: usize, - /// compact 后注入给模型的旧历史 event log 路径提示。 pub history_path: Option, - /// 仅对手动 compact 生效的附加指令。 pub custom_instructions: Option, } -/// 压缩执行结果。 #[derive(Debug, Clone)] pub(crate) struct CompactResult { - /// 压缩后的完整消息列表。 pub messages: Vec, - /// 压缩生成的摘要文本。 pub summary: String, - /// 最近真实用户消息的极短目的摘要。 pub recent_user_context_digest: Option, - /// compact 后重新注入的最近真实用户消息原文。 pub recent_user_context_messages: Vec, - /// 保留的最近 turn 数。 pub preserved_recent_turns: usize, - /// 压缩前估算 token 数。 pub pre_tokens: usize, - /// 压缩后估算 token 数。 pub post_tokens_estimate: usize, - /// 被移除的消息数。 pub messages_removed: usize, - /// 释放的 token 数。 pub tokens_freed: usize, - /// 压缩时间戳。 pub timestamp: DateTime, - /// compact 执行元数据。 pub meta: CompactAppliedMeta, } -/// compact 输入的边界类型。 #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum CompactionBoundary { RealUserTurn, AssistantStep, } -/// 一段可以安全作为 compact 重试裁剪单位的前缀区间。 #[derive(Debug, Clone, Copy, PartialEq, Eq)] struct CompactionUnit { start: usize, @@ -175,15 +143,8 @@ struct CompactExecutionResult { retry_state: CompactRetryState, } -/// 执行自动压缩。 -/// -/// 通过 `gateway` 调用 LLM 对历史前缀生成摘要，替换为压缩后的消息。 -/// 返回 `None` 表示没有可压缩的内容。 -/// -/// 当前系统只有这一套真实 compact 流程。若未来需要按 mode 调整行为，应扩展 -/// `CompactConfig` / `ContextWindowSettings` 这类显式参数，而不是恢复未消费的粗粒度策略枚举。 -pub async fn auto_compact( - gateway: &KernelGateway, +pub(crate) async fn auto_compact( + provider: &dyn LlmProvider, messages: &[LlmMessage], compact_prompt_context: Option<&str>, config: CompactConfig, @@ -202,10 +163,10 @@ pub async fn auto_compact( let pre_tokens = estimate_request_tokens(messages, compact_prompt_context); let effective_max_output_tokens = config .max_output_tokens - .min(gateway.model_limits().max_output_tokens) + .min(provider.model_limits().max_output_tokens) .max(1); let Some(execution) = execute_compact_request_with_retries( - gateway, + provider, &mut split, compact_prompt_context, &config, @@ -241,6 +202,7 @@ pub async fn auto_compact( split.keep_start, split.suffix, ); + Ok(Some(build_compact_result( CompactResultInput { compacted_messages, @@ -257,17 +219,72 @@ pub async fn auto_compact( ))) } -#[derive(Debug, Clone)] +pub(crate) fn build_post_compact_events( + turn_id: Option<&str>, + agent: &astrcode_core::AgentEventContext, + trigger: CompactTrigger, + compaction: &CompactResult, +) -> Vec { + let _ = ( + &compaction.recent_user_context_digest, + &compaction.recent_user_context_messages, + ); + vec![RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: turn_id.map(str::to_string), + agent: agent.clone(), + payload: StorageEventPayload::CompactApplied { + trigger, + summary: compaction.summary.clone(), + meta: compaction.meta.clone(), + preserved_recent_turns: saturating_u32(compaction.preserved_recent_turns), + pre_tokens: saturating_u32(compaction.pre_tokens), + post_tokens_estimate: saturating_u32(compaction.post_tokens_estimate), + messages_removed: saturating_u32(compaction.messages_removed), + tokens_freed: saturating_u32(compaction.tokens_freed), + timestamp: compaction.timestamp, + }, + }), + }] +} + +pub(crate) fn build_post_compact_recovery_messages( + tracker: &FileAccessTracker, + settings: &ContextWindowSettings, +) -> Vec { + tracker.build_recovery_messages(settings.file_recovery_config()) +} + +pub(crate) fn compact_config_from_settings( + settings: &ContextWindowSettings, + trigger: CompactTrigger, + history_path: Option, + custom_instructions: Option, +) -> CompactConfig { + CompactConfig { + keep_recent_turns: settings.compact_keep_recent_turns, + keep_recent_user_messages: settings.compact_keep_recent_user_messages, + trigger, + summary_reserve_tokens: settings.summary_reserve_tokens, + max_output_tokens: settings.compact_max_output_tokens, + max_retry_attempts: settings.compact_max_retry_attempts, + history_path, + custom_instructions, + } +} + +pub(crate) fn is_prompt_too_long_message(message: &str) -> bool { + contains_ascii_case_insensitive(message, "prompt too long") + || contains_ascii_case_insensitive(message, "context length") + || contains_ascii_case_insensitive(message, "maximum context") + || contains_ascii_case_insensitive(message, "too many tokens") +} + struct CompactionSplit { prefix: Vec, suffix: Vec, keep_start: usize, } -/// 检查消息是否可以被压缩。 -#[cfg(test)] -fn can_compact(messages: &[LlmMessage], keep_recent_turns: usize) -> bool { - split_for_compaction(messages, keep_recent_turns).is_some() -} fn split_for_compaction( messages: &[LlmMessage], @@ -284,9 +301,7 @@ fn split_for_compaction( .map(|index| real_user_indices[index]); let keep_start = primary_keep_start .filter(|index| *index > 0) - .or_else(|| fallback_keep_start(messages)); - - let keep_start = keep_start?; + .or_else(|| fallback_keep_start(messages))?; Some(CompactionSplit { prefix: messages[..keep_start].to_vec(), suffix: messages[keep_start..].to_vec(), @@ -404,7 +419,7 @@ fn trim_prefix_until_compact_request_fits( } async fn execute_compact_request_with_retries( - gateway: &KernelGateway, + provider: &dyn LlmProvider, split: &mut CompactionSplit, compact_prompt_context: Option<&str>, config: &CompactConfig, @@ -417,7 +432,7 @@ async fn execute_compact_request_with_retries( if !trim_prefix_until_compact_request_fits( &mut split.prefix, compact_prompt_context, - gateway.model_limits(), + provider.model_limits(), config, recent_user_context_messages, ) { @@ -442,7 +457,7 @@ async fn execute_compact_request_with_retries( )) .with_max_output_tokens_override(effective_max_output_tokens); - match gateway.call_llm(request, None).await { + match provider.generate(request, None).await { Ok(output) => match parse_compact_output(&output.content) { Ok(parsed_output) => { if let Some(violation) = @@ -466,7 +481,7 @@ async fn execute_compact_request_with_retries( Err(error) => return Err(error), }, Err(error) - if is_prompt_too_long(&error) + if is_prompt_too_long_message(&error.to_string()) && retry_state.salvage_attempts < config.max_retry_attempts => { retry_state.note_salvage_attempt(); @@ -493,7 +508,7 @@ struct CompactResultInput { fn build_compact_result( input: CompactResultInput, compact_prompt_context: Option<&str>, - config: &CompactConfig, + _config: &CompactConfig, execution: CompactExecutionResult, ) -> CompactResult { let CompactResultInput { @@ -531,10 +546,7 @@ fn build_compact_result( mode: prepared_input .prompt_mode .compact_mode(retry_state.salvage_attempts), - instructions_present: config - .custom_instructions - .as_deref() - .is_some_and(|value| !value.trim().is_empty()), + instructions_present: false, fallback_used: parsed_output.used_fallback || retry_state.salvage_attempts > 0, retry_count: retry_state.salvage_attempts.min(u32::MAX as usize) as u32, input_units: prepared_input.input_units.min(u32::MAX as usize) as u32, @@ -600,5 +612,6 @@ fn compacted_messages( messages } -#[cfg(test)] -mod tests; +fn saturating_u32(value: usize) -> u32 { + value.min(u32::MAX as usize) as u32 +} diff --git a/crates/session-runtime/src/context_window/compaction/protocol.rs b/crates/agent-runtime/src/context_window/compaction/protocol.rs similarity index 84% rename from crates/session-runtime/src/context_window/compaction/protocol.rs rename to crates/agent-runtime/src/context_window/compaction/protocol.rs index d22b2edc..c2c213c0 100644 --- a/crates/session-runtime/src/context_window/compaction/protocol.rs +++ b/crates/agent-runtime/src/context_window/compaction/protocol.rs @@ -5,32 +5,6 @@ mod xml_parsing; use sanitize as sanitize_impl; use xml_parsing as xml_parsing_impl; -/// 合并 compact 使用的 prompt 上下文。 -#[cfg(test)] -pub(super) fn merge_compact_prompt_context( - runtime_system_prompt: Option<&str>, - additional_system_prompt: Option<&str>, -) -> Option { - let runtime_system_prompt = runtime_system_prompt.filter(|v| !v.trim().is_empty()); - let additional_system_prompt = additional_system_prompt.filter(|v| !v.trim().is_empty()); - - match (runtime_system_prompt, additional_system_prompt) { - (None, None) => None, - (Some(base), None) => Some(base.to_string()), - (None, Some(additional)) => Some(additional.to_string()), - (Some(base), Some(additional)) => Some(format!("{base}\n\n{additional}")), - } -} - -/// 判断错误是否为 prompt too long。 -pub(super) fn is_prompt_too_long(error: &astrcode_kernel::KernelError) -> bool { - let message = error.to_string(); - xml_parsing_impl::contains_ascii_case_insensitive(&message, "prompt too long") - || xml_parsing_impl::contains_ascii_case_insensitive(&message, "context length") - || xml_parsing_impl::contains_ascii_case_insensitive(&message, "maximum context") - || xml_parsing_impl::contains_ascii_case_insensitive(&message, "too many tokens") -} - pub(super) fn render_compact_system_prompt( compact_prompt_context: Option<&str>, mode: CompactPromptMode, @@ -45,8 +19,8 @@ pub(super) fn render_compact_system_prompt( .replace("{{PREVIOUS_SUMMARY}}", previous_summary.trim()), }; let runtime_context = compact_prompt_context - .filter(|v| !v.trim().is_empty()) - .map(|v| format!("\nCurrent runtime system prompt for context:\n{v}")) + .filter(|value| !value.trim().is_empty()) + .map(|value| format!("\nCurrent runtime system prompt for context:\n{value}")) .unwrap_or_default(); let custom_instruction_block = custom_instructions .filter(|value| !value.trim().is_empty()) @@ -246,7 +220,7 @@ pub(super) fn normalize_compaction_tool_content(content: &str) -> String { if collapsed.is_empty() { return String::new(); } - if is_persisted_output(&collapsed) { + if astrcode_core::is_persisted_output(&collapsed) { return summarize_persisted_tool_output(&collapsed); } collapsed @@ -264,9 +238,14 @@ pub(super) fn parse_compact_output(content: &str) -> Result xml_parsing_impl::parse_compact_output(content) } +pub(super) fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool { + xml_parsing_impl::contains_ascii_case_insensitive(haystack, needle) +} + fn summarize_persisted_tool_output(content: &str) -> String { - let persisted_path = persisted_output_absolute_path(content) - .unwrap_or_else(|| "unknown persisted path".to_string()); + let persisted_path = + astrcode_core::tool_result_persist::persisted_output_absolute_path(content) + .unwrap_or_else(|| "unknown persisted path".to_string()); format!( "Large tool output was persisted instead of inlined.\nPersisted path: \ {persisted_path}\nPreserve only the conclusion, referenced path, and any error." diff --git a/crates/session-runtime/src/context_window/compaction/sanitize.rs b/crates/agent-runtime/src/context_window/compaction/sanitize.rs similarity index 98% rename from crates/session-runtime/src/context_window/compaction/sanitize.rs rename to crates/agent-runtime/src/context_window/compaction/sanitize.rs index ab011744..e01377b4 100644 --- a/crates/session-runtime/src/context_window/compaction/sanitize.rs +++ b/crates/agent-runtime/src/context_window/compaction/sanitize.rs @@ -101,7 +101,7 @@ pub(super) fn sanitize_compact_summary(summary: &str) -> String { .replace_all(&sanitized, rule.replacement) .into_owned(); } - sanitized = collapse_compaction_whitespace(&sanitized); + sanitized = super::collapse_compaction_whitespace(&sanitized); if had_route_sensitive_content { ensure_compact_boundary_section(&sanitized) } else { @@ -110,7 +110,7 @@ pub(super) fn sanitize_compact_summary(summary: &str) -> String { } pub(super) fn sanitize_recent_user_context_digest(digest: &str) -> String { - collapse_compaction_whitespace(digest) + super::collapse_compaction_whitespace(digest) } fn ensure_compact_boundary_section(summary: &str) -> String { diff --git a/crates/session-runtime/src/context_window/compaction/xml_parsing.rs b/crates/agent-runtime/src/context_window/compaction/xml_parsing.rs similarity index 100% rename from crates/session-runtime/src/context_window/compaction/xml_parsing.rs rename to crates/agent-runtime/src/context_window/compaction/xml_parsing.rs diff --git a/crates/session-runtime/src/context_window/file_access.rs b/crates/agent-runtime/src/context_window/file_access.rs similarity index 63% rename from crates/session-runtime/src/context_window/file_access.rs rename to crates/agent-runtime/src/context_window/file_access.rs index 36ece671..f23dc7fe 100644 --- a/crates/session-runtime/src/context_window/file_access.rs +++ b/crates/agent-runtime/src/context_window/file_access.rs @@ -1,8 +1,3 @@ -//! # 文件访问跟踪 -//! -//! compaction 之后，仅靠摘要往往不够让模型继续安全地编辑代码。 -//! 这里保留最近 `readFile` 的访问轨迹，并在压缩后回补一小段最新文件内容。 - use std::{ collections::{HashMap, VecDeque}, fs, @@ -216,9 +211,7 @@ fn slice_text(text: String, offset: Option, limit: Option) -> Stri fn format_range(offset: Option, limit: Option) -> String { match (offset, limit) { - (Some(offset), Some(limit)) => { - format!("Line range: {}-{}\n", offset + 1, offset + limit) - }, + (Some(offset), Some(limit)) => format!("Line range: {}-{}\n", offset + 1, offset + limit), (Some(offset), None) => format!("Line start: {}\n", offset + 1), _ => String::new(), } @@ -242,109 +235,3 @@ fn truncate_to_token_budget(text: &str, budget_tokens: usize) -> String { &text[..end] ) } - -#[cfg(test)] -mod tests { - use std::fs; - - use astrcode_core::{LlmMessage, ToolCallRequest}; - use serde_json::json; - use tempfile::tempdir; - - use super::*; - - #[test] - fn tracker_recovers_recent_files_in_reverse_access_order() { - let tempdir = tempdir().expect("tempdir should exist"); - let working_dir = tempdir.path(); - fs::write(working_dir.join("a.rs"), "fn a() {}\n").expect("a.rs should write"); - fs::write(working_dir.join("b.rs"), "fn b() {}\n").expect("b.rs should write"); - - let messages = vec![ - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"a.rs"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "fn a() {}".to_string(), - }, - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-2".to_string(), - name: "readFile".to_string(), - args: json!({"path":"b.rs"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "fn b() {}".to_string(), - }, - ]; - - let tracker = FileAccessTracker::seed_from_messages(&messages, 8, working_dir); - let recovered = tracker.build_recovery_messages(FileRecoveryConfig { - max_tracked_files: 8, - max_recovered_files: 2, - recovery_token_budget: 400, - }); - - assert_eq!(recovered.len(), 2); - assert!(matches!( - &recovered[0], - LlmMessage::User { content, .. } if content.contains("a.rs") - )); - assert!(matches!( - &recovered[1], - LlmMessage::User { content, .. } if content.contains("b.rs") - )); - } - - #[test] - fn tracker_uses_metadata_path_when_tool_returns_absolute_location() { - let tempdir = tempdir().expect("tempdir should exist"); - let working_dir = tempdir.path(); - let absolute = working_dir.join("nested").join("file.rs"); - fs::create_dir_all(absolute.parent().expect("parent should exist")) - .expect("parent dir should exist"); - fs::write(&absolute, "fn nested() {}\n").expect("file should write"); - - let mut tracker = FileAccessTracker::new(4); - let tool_call = ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"file.rs"}), - }; - let result = ToolExecutionResult { - tool_call_id: "call-1".to_string(), - tool_name: "readFile".to_string(), - ok: true, - output: "fn nested() {}".to_string(), - error: None, - metadata: Some(json!({"path": absolute.to_string_lossy()})), - continuation: None, - duration_ms: 1, - truncated: false, - }; - - tracker.record_tool_result(&tool_call, &result, working_dir); - let recovered = tracker.build_recovery_messages(FileRecoveryConfig { - max_tracked_files: 4, - max_recovered_files: 1, - recovery_token_budget: 200, - }); - - assert_eq!(recovered.len(), 1); - assert!(matches!( - &recovered[0], - LlmMessage::User { content, .. } if content.contains("nested") - )); - } -} diff --git a/crates/agent-runtime/src/context_window/micro_compact.rs b/crates/agent-runtime/src/context_window/micro_compact.rs new file mode 100644 index 00000000..0a3eea84 --- /dev/null +++ b/crates/agent-runtime/src/context_window/micro_compact.rs @@ -0,0 +1,187 @@ +use std::{ + collections::{HashSet, VecDeque}, + time::{Duration, Instant}, +}; + +use astrcode_core::LlmMessage; +use chrono::{DateTime, Utc}; + +use super::tool_results::tool_call_name_map; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct MicroCompactConfig { + pub gap_threshold: Duration, + pub keep_recent_results: usize, +} + +#[derive(Debug, Clone)] +pub(crate) struct MicroCompactOutcome { + pub messages: Vec, +} + +#[derive(Debug, Clone)] +struct TrackedToolResult { + tool_call_id: String, + recorded_at: Instant, +} + +#[derive(Debug, Clone, Default)] +pub(crate) struct MicroCompactState { + tracked_results: VecDeque, + last_prompt_activity: Option, +} + +impl MicroCompactState { + pub fn seed_from_messages( + messages: &[LlmMessage], + config: MicroCompactConfig, + now: Instant, + last_assistant_at: Option>, + ) -> Self { + let mut state = Self::default(); + let stale_at = now.checked_sub(config.gap_threshold).unwrap_or(now); + let restored_activity = last_assistant_at + .and_then(|timestamp| instant_from_timestamp(now, timestamp)) + .unwrap_or(stale_at); + + for message in messages { + match message { + LlmMessage::Assistant { .. } | LlmMessage::Tool { .. } => { + state.last_prompt_activity = Some(restored_activity); + }, + _ => {}, + } + + let LlmMessage::Tool { tool_call_id, .. } = message else { + continue; + }; + state.tracked_results.push_back(TrackedToolResult { + tool_call_id: tool_call_id.clone(), + recorded_at: stale_at, + }); + } + + state + } + + pub fn record_tool_result(&mut self, tool_call_id: impl Into, now: Instant) { + let tool_call_id = tool_call_id.into(); + self.tracked_results + .retain(|entry| entry.tool_call_id != tool_call_id); + self.tracked_results.push_back(TrackedToolResult { + tool_call_id, + recorded_at: now, + }); + self.last_prompt_activity = Some(now); + } + + pub fn record_assistant_activity(&mut self, now: Instant) { + self.last_prompt_activity = Some(now); + } + + pub fn apply_if_idle( + &mut self, + messages: &[LlmMessage], + clearable_tools: &HashSet, + config: MicroCompactConfig, + now: Instant, + ) -> MicroCompactOutcome { + self.retain_live_tool_results(messages); + + let Some(last_activity) = self.last_prompt_activity else { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + }; + + if now.duration_since(last_activity) < config.gap_threshold { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let keep_recent_results = config.keep_recent_results.max(1); + if self.tracked_results.len() <= keep_recent_results { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let tool_call_names = tool_call_name_map(messages); + let protected_ids = self + .tracked_results + .iter() + .rev() + .take(keep_recent_results) + .map(|entry| entry.tool_call_id.as_str()) + .collect::>(); + + let stale_ids = self + .tracked_results + .iter() + .filter(|entry| !protected_ids.contains(entry.tool_call_id.as_str())) + .filter(|entry| now.duration_since(entry.recorded_at) >= config.gap_threshold) + .filter_map(|entry| { + tool_call_names + .get(&entry.tool_call_id) + .filter(|tool_name| clearable_tools.contains(*tool_name)) + .map(|_| entry.tool_call_id.clone()) + }) + .collect::>(); + + if stale_ids.is_empty() { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let mut compacted = messages.to_vec(); + for message in &mut compacted { + let LlmMessage::Tool { + tool_call_id, + content, + } = message + else { + continue; + }; + + if !stale_ids.contains(tool_call_id) || is_micro_compacted(content) { + continue; + } + + let tool_name = tool_call_names + .get(tool_call_id) + .map(String::as_str) + .unwrap_or("tool"); + *content = format!( + "[micro-compacted stale tool result from '{tool_name}' after idle gap; rerun the \ + tool if exact output is needed]" + ); + } + + MicroCompactOutcome { + messages: compacted, + } + } + + fn retain_live_tool_results(&mut self, messages: &[LlmMessage]) { + let live_tool_ids = messages + .iter() + .filter_map(|message| match message { + LlmMessage::Tool { tool_call_id, .. } => Some(tool_call_id.as_str()), + _ => None, + }) + .collect::>(); + self.tracked_results + .retain(|entry| live_tool_ids.contains(entry.tool_call_id.as_str())); + } +} + +fn is_micro_compacted(content: &str) -> bool { + content.contains("[micro-compacted stale tool result") +} + +fn instant_from_timestamp(now: Instant, timestamp: DateTime) -> Option { + let elapsed = (Utc::now() - timestamp).to_std().ok()?; + now.checked_sub(elapsed).or(Some(now)) +} diff --git a/crates/agent-runtime/src/context_window/mod.rs b/crates/agent-runtime/src/context_window/mod.rs new file mode 100644 index 00000000..997ba385 --- /dev/null +++ b/crates/agent-runtime/src/context_window/mod.rs @@ -0,0 +1,17 @@ +//! Runtime-owned context window management. +//! +//! This module contains the local prompt-window work that must happen inside +//! the execution loop: token estimation, tool-result pruning, idle cleanup, +//! aggregate tool-result budgeting, file recovery, and LLM-backed compaction. + +pub(crate) mod compaction; +pub(crate) mod file_access; +pub(crate) mod micro_compact; +pub(crate) mod prune_pass; +pub(crate) mod request; +pub(crate) mod settings; +pub(crate) mod token_usage; +pub(crate) mod tool_result_budget; +pub(crate) mod tool_results; + +pub(crate) use settings::ContextWindowSettings; diff --git a/crates/agent-runtime/src/context_window/prune_pass.rs b/crates/agent-runtime/src/context_window/prune_pass.rs new file mode 100644 index 00000000..f58d2feb --- /dev/null +++ b/crates/agent-runtime/src/context_window/prune_pass.rs @@ -0,0 +1,100 @@ +use std::collections::HashSet; + +use astrcode_core::{LlmMessage, UserMessageOrigin}; + +use super::tool_results::tool_call_name_map; + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub(crate) struct PruneStats { + pub truncated_tool_results: usize, + pub cleared_tool_results: usize, +} + +#[derive(Debug, Clone)] +pub(crate) struct PruneOutcome { + pub messages: Vec, + pub stats: PruneStats, +} + +pub(crate) fn apply_prune_pass( + messages: &[LlmMessage], + clearable_tools: &HashSet, + max_tool_result_bytes: usize, + keep_recent_turns: usize, +) -> PruneOutcome { + let tool_call_names = tool_call_name_map(messages); + let keep_start = recent_turn_start_index(messages, keep_recent_turns.max(1)); + let mut truncated_tool_results = 0usize; + let mut cleared_tool_results = 0usize; + let mut compacted = messages.to_vec(); + + for (index, message) in compacted.iter_mut().enumerate() { + let LlmMessage::Tool { + tool_call_id, + content, + } = message + else { + continue; + }; + + if content.len() > max_tool_result_bytes { + *content = truncate_tool_content(content, max_tool_result_bytes); + truncated_tool_results += 1; + } + + if index >= keep_start { + continue; + } + + let Some(tool_name) = tool_call_names.get(tool_call_id) else { + continue; + }; + if clearable_tools.contains(tool_name) { + *content = format!( + "[cleared older tool result from '{tool_name}' to reduce prompt size; reload it \ + if needed]" + ); + cleared_tool_results += 1; + } + } + + PruneOutcome { + messages: compacted, + stats: PruneStats { + truncated_tool_results, + cleared_tool_results, + }, + } +} + +fn truncate_tool_content(content: &str, max_bytes: usize) -> String { + let total_bytes = content.len(); + let mut visible_bytes = max_bytes.saturating_sub(96).max(64).min(total_bytes); + while !content.is_char_boundary(visible_bytes) { + visible_bytes = visible_bytes.saturating_sub(1); + } + let visible = &content[..visible_bytes]; + format!( + "[truncated: original {total_bytes} bytes, showing first {visible_bytes} bytes]\n{visible}" + ) +} + +fn recent_turn_start_index(messages: &[LlmMessage], requested_recent_turns: usize) -> usize { + let user_turn_indices = messages + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } => Some(index), + _ => None, + }) + .collect::>(); + if user_turn_indices.is_empty() { + return messages.len(); + } + + let keep_turns = requested_recent_turns.min(user_turn_indices.len()).max(1); + user_turn_indices[user_turn_indices.len() - keep_turns] +} diff --git a/crates/agent-runtime/src/context_window/request.rs b/crates/agent-runtime/src/context_window/request.rs new file mode 100644 index 00000000..150b4ef1 --- /dev/null +++ b/crates/agent-runtime/src/context_window/request.rs @@ -0,0 +1,277 @@ +use std::{sync::Arc, time::Instant}; + +use astrcode_core::{ + AgentEventContext, CompactTrigger, PromptMetricsPayload, StorageEvent, StorageEventPayload, +}; + +use crate::{ + context_window::{ + compaction::{ + auto_compact, build_post_compact_events, build_post_compact_recovery_messages, + compact_config_from_settings, + }, + prune_pass::apply_prune_pass, + token_usage::{PromptTokenSnapshot, build_prompt_snapshot, should_compact}, + tool_result_budget::{ + ApplyToolResultBudgetRequest, ToolResultBudgetStats, apply_tool_result_budget, + }, + }, + r#loop::{TurnExecutionContext, TurnExecutionResources}, + provider::{LlmProvider, LlmRequest}, + types::RuntimeTurnEvent, +}; + +pub(crate) async fn assemble_runtime_request( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, +) -> astrcode_core::Result { + let budget_outcome = apply_tool_result_budget(ApplyToolResultBudgetRequest { + messages: &execution.messages, + session_id: &resources.session_id, + working_dir: &resources.working_dir, + replacement_state: &mut execution.tool_result_replacement_state, + aggregate_budget_bytes: resources.settings.aggregate_result_bytes_budget, + turn_id: &resources.turn_id, + agent: &resources.agent, + })?; + execution + .pending_events + .extend( + budget_outcome + .events + .into_iter() + .map(|event| RuntimeTurnEvent::StorageEvent { + event: Box::new(event), + }), + ); + accumulate_tool_result_budget_stats( + &mut execution.tool_result_budget_stats, + budget_outcome.stats, + ); + + let micro_outcome = execution.micro_compact_state.apply_if_idle( + &budget_outcome.messages, + &resources.clearable_tools, + resources.settings.micro_compact_config(), + Instant::now(), + ); + + let prune_outcome = apply_prune_pass( + µ_outcome.messages, + &resources.clearable_tools, + resources.settings.tool_result_max_bytes, + resources.settings.compact_keep_recent_turns, + ); + let mut messages = prune_outcome.messages; + + let Some(provider) = &resources.provider else { + execution.messages = messages.clone(); + return Ok(LlmRequest::new( + messages, + Arc::clone(&resources.tools), + resources.cancel.clone(), + )); + }; + + let mut snapshot = build_prompt_snapshot( + &execution.token_tracker, + &messages, + None, + provider.model_limits(), + resources.settings.compact_threshold_percent, + resources.settings.summary_reserve_tokens, + resources.settings.reserved_context_size, + ); + + if should_compact(snapshot) { + if resources.settings.auto_compact_enabled { + if let Some(compaction) = auto_compact( + provider.as_ref(), + &messages, + None, + compact_config_from_settings( + &resources.settings, + CompactTrigger::Auto, + resources.events_history_path.clone(), + None, + ), + resources.cancel.clone(), + ) + .await? + { + messages = compaction.messages.clone(); + messages.extend(build_post_compact_recovery_messages( + &execution.file_access_tracker, + &resources.settings, + )); + execution.pending_events.extend(build_post_compact_events( + Some(&resources.turn_id), + &resources.agent, + CompactTrigger::Auto, + &compaction, + )); + execution.auto_compaction_count = execution.auto_compaction_count.saturating_add(1); + snapshot = build_prompt_snapshot( + &execution.token_tracker, + &messages, + None, + provider.model_limits(), + resources.settings.compact_threshold_percent, + resources.settings.summary_reserve_tokens, + resources.settings.reserved_context_size, + ); + } + } else { + log::warn!( + "turn {} step {}: context tokens ({}) exceed threshold ({}) but auto compact is \ + disabled", + resources.turn_id, + execution.step_index, + snapshot.context_tokens, + snapshot.threshold_tokens, + ); + } + } + + execution.pending_events.push(prompt_metrics_runtime_event( + &resources.turn_id, + &resources.agent, + execution.step_index, + snapshot, + prune_outcome.stats.truncated_tool_results, + provider.supports_cache_metrics(), + )); + execution.messages = messages.clone(); + + Ok(LlmRequest::new( + messages, + Arc::clone(&resources.tools), + resources.cancel.clone(), + )) +} + +pub(crate) async fn recover_from_prompt_too_long( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + provider: &dyn LlmProvider, +) -> astrcode_core::Result { + execution.reactive_compact_attempts = execution.reactive_compact_attempts.saturating_add(1); + let Some(compaction) = auto_compact( + provider, + &execution.messages, + None, + compact_config_from_settings( + &resources.settings, + CompactTrigger::Auto, + resources.events_history_path.clone(), + None, + ), + resources.cancel.clone(), + ) + .await? + else { + return Ok(false); + }; + + let mut messages = compaction.messages.clone(); + messages.extend(build_post_compact_recovery_messages( + &execution.file_access_tracker, + &resources.settings, + )); + execution.messages = messages; + execution.pending_events.extend(build_post_compact_events( + Some(&resources.turn_id), + &resources.agent, + CompactTrigger::Auto, + &compaction, + )); + Ok(true) +} + +pub(crate) fn apply_prompt_metrics_usage( + events: &mut [RuntimeTurnEvent], + step_index: usize, + usage: Option, + diagnostics: Option, +) { + if usage.is_none() && diagnostics.is_none() { + return; + } + + let step_index = saturating_u32(step_index); + let Some(metrics) = events.iter_mut().rev().find_map(|event| { + let RuntimeTurnEvent::StorageEvent { event } = event else { + return None; + }; + let StorageEventPayload::PromptMetrics { metrics } = &mut event.payload else { + return None; + }; + (metrics.step_index == step_index).then_some(metrics) + }) else { + return; + }; + + if let Some(usage) = usage { + metrics.provider_input_tokens = Some(saturating_u32(usage.input_tokens)); + metrics.provider_output_tokens = Some(saturating_u32(usage.output_tokens)); + metrics.cache_creation_input_tokens = + Some(saturating_u32(usage.cache_creation_input_tokens)); + metrics.cache_read_input_tokens = Some(saturating_u32(usage.cache_read_input_tokens)); + } + if let Some(diagnostics) = diagnostics { + metrics.prompt_cache_diagnostics = Some(diagnostics); + } +} + +fn accumulate_tool_result_budget_stats( + total: &mut ToolResultBudgetStats, + next: ToolResultBudgetStats, +) { + total.replacement_count = total + .replacement_count + .saturating_add(next.replacement_count); + total.reapply_count = total.reapply_count.saturating_add(next.reapply_count); + total.bytes_saved = total.bytes_saved.saturating_add(next.bytes_saved); + total.over_budget_message_count = total + .over_budget_message_count + .saturating_add(next.over_budget_message_count); +} + +fn prompt_metrics_runtime_event( + turn_id: &str, + agent: &AgentEventContext, + step_index: usize, + snapshot: PromptTokenSnapshot, + truncated_tool_results: usize, + provider_cache_metrics_supported: bool, +) -> RuntimeTurnEvent { + RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::PromptMetrics { + metrics: PromptMetricsPayload { + step_index: saturating_u32(step_index), + estimated_tokens: saturating_u32(snapshot.context_tokens), + context_window: saturating_u32(snapshot.context_window), + effective_window: saturating_u32(snapshot.effective_window), + threshold_tokens: saturating_u32(snapshot.threshold_tokens), + truncated_tool_results: saturating_u32(truncated_tool_results), + provider_input_tokens: None, + provider_output_tokens: None, + cache_creation_input_tokens: None, + cache_read_input_tokens: None, + provider_cache_metrics_supported, + prompt_cache_reuse_hits: 0, + prompt_cache_reuse_misses: 0, + prompt_cache_unchanged_layers: Vec::new(), + prompt_cache_diagnostics: None, + }, + }, + }), + } +} + +fn saturating_u32(value: usize) -> u32 { + value.min(u32::MAX as usize) as u32 +} diff --git a/crates/session-runtime/src/context_window/settings.rs b/crates/agent-runtime/src/context_window/settings.rs similarity index 81% rename from crates/session-runtime/src/context_window/settings.rs rename to crates/agent-runtime/src/context_window/settings.rs index 13e67d17..d42750a1 100644 --- a/crates/session-runtime/src/context_window/settings.rs +++ b/crates/agent-runtime/src/context_window/settings.rs @@ -2,8 +2,10 @@ use std::time::Duration; use astrcode_core::ResolvedRuntimeConfig; +use super::{file_access::FileRecoveryConfig, micro_compact::MicroCompactConfig}; + #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ContextWindowSettings { +pub(crate) struct ContextWindowSettings { pub auto_compact_enabled: bool, pub compact_threshold_percent: u8, pub reserved_context_size: usize, @@ -22,15 +24,15 @@ pub struct ContextWindowSettings { } impl ContextWindowSettings { - pub fn micro_compact_config(&self) -> crate::context_window::micro_compact::MicroCompactConfig { - crate::context_window::micro_compact::MicroCompactConfig { + pub fn micro_compact_config(&self) -> MicroCompactConfig { + MicroCompactConfig { gap_threshold: self.micro_compact_gap_threshold, keep_recent_results: self.micro_compact_keep_recent_results, } } - pub fn file_recovery_config(&self) -> crate::context_window::file_access::FileRecoveryConfig { - crate::context_window::file_access::FileRecoveryConfig { + pub fn file_recovery_config(&self) -> FileRecoveryConfig { + FileRecoveryConfig { max_tracked_files: self.max_tracked_files, max_recovered_files: self.max_recovered_files, recovery_token_budget: self.recovery_token_budget, @@ -40,8 +42,6 @@ impl ContextWindowSettings { impl From<&ResolvedRuntimeConfig> for ContextWindowSettings { fn from(config: &ResolvedRuntimeConfig) -> Self { - // TODO: 如果未来需要 mode 感知的上下文压缩，请在 compact 参数模型上做显式覆盖， - // 而不是重新引入 summarize/truncate/ignore 这类未落地的策略枚举。 Self { auto_compact_enabled: config.auto_compact_enabled, compact_threshold_percent: config.compact_threshold_percent, diff --git a/crates/session-runtime/src/context_window/templates/compact/base.md b/crates/agent-runtime/src/context_window/templates/compact/base.md similarity index 100% rename from crates/session-runtime/src/context_window/templates/compact/base.md rename to crates/agent-runtime/src/context_window/templates/compact/base.md diff --git a/crates/session-runtime/src/context_window/templates/compact/incremental.md b/crates/agent-runtime/src/context_window/templates/compact/incremental.md similarity index 100% rename from crates/session-runtime/src/context_window/templates/compact/incremental.md rename to crates/agent-runtime/src/context_window/templates/compact/incremental.md diff --git a/crates/agent-runtime/src/context_window/token_usage.rs b/crates/agent-runtime/src/context_window/token_usage.rs new file mode 100644 index 00000000..f27e587a --- /dev/null +++ b/crates/agent-runtime/src/context_window/token_usage.rs @@ -0,0 +1,149 @@ +use astrcode_core::{LlmMessage, UserMessageOrigin}; + +use crate::provider::{LlmUsage, ModelLimits}; + +const MESSAGE_BASE_TOKENS: usize = 6; +const TOOL_CALL_BASE_TOKENS: usize = 12; +const REQUEST_ESTIMATE_PADDING_NUMERATOR: usize = 4; +const REQUEST_ESTIMATE_PADDING_DENOMINATOR: usize = 3; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct PromptTokenSnapshot { + pub context_tokens: usize, + pub budget_tokens: usize, + pub context_window: usize, + pub effective_window: usize, + pub threshold_tokens: usize, + pub remaining_context_tokens: usize, + pub reserved_context_size: usize, +} + +#[derive(Debug, Default, Clone, Copy)] +pub(crate) struct TokenUsageTracker { + anchored_budget_tokens: usize, +} + +impl TokenUsageTracker { + pub fn record_usage(&mut self, usage: Option) { + let Some(usage) = usage else { + return; + }; + self.anchored_budget_tokens = self + .anchored_budget_tokens + .saturating_add(usage.total_tokens()); + } + + pub fn budget_tokens(&self, estimated_context_tokens: usize) -> usize { + if self.anchored_budget_tokens > 0 { + self.anchored_budget_tokens + } else { + estimated_context_tokens + } + } +} + +pub(crate) fn build_prompt_snapshot( + tracker: &TokenUsageTracker, + messages: &[LlmMessage], + system_prompt: Option<&str>, + limits: ModelLimits, + threshold_percent: u8, + summary_reserve_tokens: usize, + reserved_context_size: usize, +) -> PromptTokenSnapshot { + let context_tokens = estimate_request_tokens(messages, system_prompt); + let effective_window = effective_context_window(limits, summary_reserve_tokens); + PromptTokenSnapshot { + context_tokens, + budget_tokens: tracker.budget_tokens(context_tokens), + context_window: limits.context_window, + effective_window, + threshold_tokens: compact_threshold_tokens(effective_window, threshold_percent), + remaining_context_tokens: effective_window.saturating_sub(context_tokens), + reserved_context_size, + } +} + +pub(crate) fn effective_context_window( + limits: ModelLimits, + summary_reserve_tokens: usize, +) -> usize { + limits + .context_window + .saturating_sub(summary_reserve_tokens.min(limits.context_window)) +} + +pub(crate) fn compact_threshold_tokens(effective_window: usize, threshold_percent: u8) -> usize { + effective_window + .saturating_mul(threshold_percent as usize) + .saturating_div(100) +} + +pub(crate) fn should_compact(snapshot: PromptTokenSnapshot) -> bool { + snapshot.context_tokens >= snapshot.threshold_tokens + || snapshot.remaining_context_tokens <= snapshot.reserved_context_size +} + +pub(crate) fn estimate_request_tokens( + messages: &[LlmMessage], + system_prompt: Option<&str>, +) -> usize { + let system_tokens = system_prompt.map_or(0, estimate_text_tokens); + let raw_total = system_tokens + messages.iter().map(estimate_message_tokens).sum::(); + raw_total + .saturating_mul(REQUEST_ESTIMATE_PADDING_NUMERATOR) + .div_ceil(REQUEST_ESTIMATE_PADDING_DENOMINATOR) +} + +pub(crate) fn estimate_message_tokens(message: &LlmMessage) -> usize { + match message { + LlmMessage::User { content, origin } => { + MESSAGE_BASE_TOKENS + + estimate_text_tokens(content) + + match origin { + UserMessageOrigin::User => 0, + UserMessageOrigin::QueuedInput => 8, + UserMessageOrigin::ContinuationPrompt => 10, + UserMessageOrigin::ReactivationPrompt => 8, + UserMessageOrigin::RecentUserContextDigest => 8, + UserMessageOrigin::RecentUserContext => 8, + UserMessageOrigin::CompactSummary => 16, + } + }, + LlmMessage::Assistant { + content, + tool_calls, + reasoning, + } => { + MESSAGE_BASE_TOKENS + + estimate_text_tokens(content) + + reasoning + .as_ref() + .map_or(0, |reasoning| estimate_text_tokens(&reasoning.content)) + + tool_calls + .iter() + .map(|call| { + TOOL_CALL_BASE_TOKENS + + estimate_text_tokens(&call.id) + + estimate_text_tokens(&call.name) + + estimate_json_tokens(&call.args.to_string()) + }) + .sum::() + }, + LlmMessage::Tool { + tool_call_id, + content, + } => { + MESSAGE_BASE_TOKENS + estimate_text_tokens(tool_call_id) + estimate_text_tokens(content) + }, + } +} + +pub(crate) fn estimate_text_tokens(text: &str) -> usize { + let chars = text.chars().count(); + chars.div_ceil(4).max(1) +} + +fn estimate_json_tokens(json: &str) -> usize { + estimate_text_tokens(json) + 4 +} diff --git a/crates/session-runtime/src/turn/tool_result_budget.rs b/crates/agent-runtime/src/context_window/tool_result_budget.rs similarity index 53% rename from crates/session-runtime/src/turn/tool_result_budget.rs rename to crates/agent-runtime/src/context_window/tool_result_budget.rs index 2d7f51c0..3777e64e 100644 --- a/crates/session-runtime/src/turn/tool_result_budget.rs +++ b/crates/agent-runtime/src/context_window/tool_result_budget.rs @@ -1,23 +1,20 @@ -//! request 组装前的 aggregate tool-result budget。 -//! -//! Why: 单个工具自己的 inline limit 只能处理“一个工具太大”的情况， -//! 这里负责把同一批 trailing tool results 当作整体治理，并把 replacement -//! 决策收敛到稳定状态里。 - use std::{ collections::{HashMap, HashSet}, path::{Path, PathBuf}, }; use astrcode_core::{ - LlmMessage, PersistedToolOutput, Result, StorageEventPayload, is_persisted_output, + AgentEventContext, AstrError, LlmMessage, PersistedToolOutput, Result, StorageEvent, + StorageEventPayload, + env::{ASTRCODE_HOME_DIR_ENV, ASTRCODE_TEST_HOME_ENV}, + is_persisted_output, + project::project_dir_name, + tool_result_persist::{PersistedToolResult, TOOL_RESULT_PREVIEW_LIMIT, TOOL_RESULTS_DIR}, }; -use astrcode_support::{hostpaths::project_dir, tool_results::persist_tool_result}; - -use crate::{SessionState, turn::events::tool_result_reference_applied_event}; #[derive(Debug, Clone, PartialEq, Eq)] pub struct ToolResultReplacementRecord { + pub tool_call_id: String, pub persisted_output: PersistedToolOutput, pub replacement: String, pub original_bytes: u64, @@ -30,7 +27,7 @@ pub struct ToolResultReplacementState { } #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] -pub struct ToolResultBudgetStats { +pub(crate) struct ToolResultBudgetStats { pub replacement_count: usize, pub reapply_count: usize, pub bytes_saved: usize, @@ -38,45 +35,31 @@ pub struct ToolResultBudgetStats { } #[derive(Debug, Clone)] -pub struct ToolResultBudgetOutcome { +pub(crate) struct ToolResultBudgetOutcome { pub messages: Vec, - pub events: Vec, + pub events: Vec, pub stats: ToolResultBudgetStats, } -pub struct ApplyToolResultBudgetRequest<'a> { +pub(crate) struct ApplyToolResultBudgetRequest<'a> { pub messages: &'a [LlmMessage], pub session_id: &'a str, pub working_dir: &'a Path, - pub session_state: &'a SessionState, pub replacement_state: &'a mut ToolResultReplacementState, pub aggregate_budget_bytes: usize, pub turn_id: &'a str, - pub agent: &'a astrcode_core::AgentEventContext, + pub agent: &'a AgentEventContext, } impl ToolResultReplacementState { - pub fn seed(session_state: &SessionState) -> Result { + pub fn seed(records: impl IntoIterator) -> Self { let mut state = Self::default(); - for stored in session_state.snapshot_recent_stored_events()? { - if let StorageEventPayload::ToolResultReferenceApplied { - tool_call_id, - persisted_output, - replacement, - original_bytes, - } = stored.event.payload - { - state.replacements.insert( - tool_call_id.clone(), - ToolResultReplacementRecord { - persisted_output, - replacement, - original_bytes, - }, - ); - } + for record in records { + state + .replacements + .insert(record.tool_call_id.clone(), record); } - Ok(state) + state } fn replacement_for(&self, tool_call_id: &str) -> Option<&ToolResultReplacementRecord> { @@ -97,7 +80,7 @@ impl ToolResultReplacementState { } } -pub fn apply_tool_result_budget( +pub(crate) fn apply_tool_result_budget( request: ApplyToolResultBudgetRequest<'_>, ) -> Result { let mut messages = request.messages.to_vec(); @@ -182,6 +165,7 @@ pub fn apply_tool_result_budget( }; let saved_bytes = original_len.saturating_sub(replacement.output.len()); let record = ToolResultReplacementRecord { + tool_call_id: tool_call_id.clone(), persisted_output: persisted_output.clone(), replacement: replacement.output.clone(), original_bytes: original_len as u64, @@ -227,7 +211,6 @@ pub fn apply_tool_result_budget( } } - let _ = request.session_state; Ok(ToolResultBudgetOutcome { messages, events, @@ -252,108 +235,154 @@ fn resolve_session_dir(working_dir: &Path, session_id: &str) -> Result Ok(project_dir(working_dir)?.join("sessions").join(session_id)) } -#[cfg(test)] -mod tests { - use astrcode_core::{AgentEventContext, EventTranslator, StorageEvent, UserMessageOrigin}; - use chrono::Utc; +pub(crate) fn project_dir(working_dir: &Path) -> Result { + Ok(projects_dir()?.join(project_dir_name(working_dir))) +} + +fn projects_dir() -> Result { + Ok(astrcode_dir()?.join("projects")) +} + +fn astrcode_dir() -> Result { + Ok(resolve_home_dir()?.join(".astrcode")) +} + +fn resolve_home_dir() -> Result { + for key in [ + ASTRCODE_TEST_HOME_ENV, + ASTRCODE_HOME_DIR_ENV, + "HOME", + "USERPROFILE", + ] { + if let Some(home) = std::env::var_os(key).filter(|value| !value.is_empty()) { + return Ok(PathBuf::from(home)); + } + } + Err(AstrError::HomeDirectoryNotFound) +} + +fn persist_tool_result( + session_dir: &Path, + tool_call_id: &str, + content: &str, +) -> PersistedToolResult { + let content_bytes = content.len(); + let results_dir = session_dir.join(TOOL_RESULTS_DIR); + + if std::fs::create_dir_all(&results_dir).is_err() { + log::warn!( + "tool-result: failed to create dir '{}', falling back to truncation", + results_dir.display() + ); + return PersistedToolResult { + output: truncate_with_notice(content), + persisted: None, + }; + } + + let safe_id: String = tool_call_id + .chars() + .filter(|ch| ch.is_alphanumeric() || *ch == '-' || *ch == '_') + .take(64) + .collect(); + let path = results_dir.join(format!("{safe_id}.txt")); + + if std::fs::write(&path, content).is_err() { + log::warn!( + "tool-result: failed to write '{}', falling back to truncation", + path.display() + ); + return PersistedToolResult { + output: truncate_with_notice(content), + persisted: None, + }; + } - use super::*; - use crate::{ - state::append_and_broadcast, - turn::{events::user_message_event, test_support::test_session_state}, + let relative_path = path + .strip_prefix(session_dir) + .unwrap_or(&path) + .to_string_lossy() + .replace('\\', "/"); + let persisted = PersistedToolOutput { + storage_kind: "toolResult".to_string(), + absolute_path: normalize_absolute_path(&path), + relative_path, + total_bytes: content_bytes as u64, + preview_text: build_preview_text(content), + preview_bytes: TOOL_RESULT_PREVIEW_LIMIT.min(content.len()) as u64, }; - #[tokio::test] - async fn aggregate_budget_replaces_largest_fresh_tool_results_and_reapplies_durable_decisions() + PersistedToolResult { + output: format_persisted_output(&persisted), + persisted: Some(persisted), + } +} + +fn format_persisted_output(persisted: &PersistedToolOutput) -> String { + format!( + "\nLarge tool output was saved to a file instead of being \ + inlined.\nPath: {}\nBytes: {}\nRead the file with `readFile`.\nIf you only need a \ + section, read a smaller chunk instead of the whole file.\nStart from the first chunk \ + when you do not yet know the right section.\nSuggested first read: {{ path: {:?}, \ + charOffset: 0, maxChars: 20000 }}\n", + persisted.absolute_path, persisted.total_bytes, persisted.absolute_path + ) +} + +fn build_preview_text(content: &str) -> String { + let preview_limit = TOOL_RESULT_PREVIEW_LIMIT.min(content.len()); + let truncated_at = content.floor_char_boundary(preview_limit); + content[..truncated_at].to_string() +} + +fn normalize_absolute_path(path: &Path) -> String { + normalize_verbatim_path(path.to_path_buf()) + .to_string_lossy() + .to_string() +} + +fn normalize_verbatim_path(path: PathBuf) -> PathBuf { + #[cfg(windows)] { - let session_state = test_session_state(); - let tempdir = tempfile::tempdir().expect("tempdir should exist"); - let agent = AgentEventContext::default(); - let mut translator = EventTranslator::new(session_state.current_phase().expect("phase")); - let replacement = "\nLarge tool output was saved to a file instead of \ - being inlined.\nPath: ~/.astrcode/tool-results/call-1.txt\nBytes: \ - 999\nRead the file with `readFile`.\nIf you only need a section, read \ - a smaller chunk instead of the whole file.\nStart from the first chunk \ - when you do not yet know the right section.\nSuggested first read: { \ - path: \"~/.astrcode/tool-results/call-1.txt\", charOffset: 0, \ - maxChars: 20000 }\n"; - append_and_broadcast( - &session_state, - &StorageEvent { - turn_id: Some("turn-prev".to_string()), - agent: agent.clone(), - payload: StorageEventPayload::ToolResultReferenceApplied { - tool_call_id: "call-1".to_string(), - persisted_output: PersistedToolOutput { - storage_kind: "toolResult".to_string(), - absolute_path: "~/.astrcode/tool-results/call-1.txt".to_string(), - relative_path: "tool-results/call-1.txt".to_string(), - total_bytes: 999, - preview_text: "preview".to_string(), - preview_bytes: 7, - }, - replacement: replacement.to_string(), - original_bytes: 999, - }, - }, - &mut translator, - ) - .await - .expect("replacement event should append"); - append_and_broadcast( - &session_state, - &user_message_event( - "turn-1", - &agent, - "hello".to_string(), - UserMessageOrigin::User, - Utc::now(), - ), - &mut translator, - ) - .await - .expect("user event should append"); - - let mut state = ToolResultReplacementState::seed(&session_state).expect("seed"); - let outcome = apply_tool_result_budget(ApplyToolResultBudgetRequest { - messages: &[ - LlmMessage::User { - content: "hello".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "inline should be replaced from durable state".to_string(), - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "x".repeat(2_000), - }, - ], - session_id: "session-test", - working_dir: tempdir.path(), - session_state: &session_state, - replacement_state: &mut state, - aggregate_budget_bytes: 512, - turn_id: "turn-1", - agent: &agent, - }) - .expect("budget application should succeed"); + if let Some(rendered) = path.to_str() { + if let Some(stripped) = rendered.strip_prefix(r"\\?\UNC\") { + return PathBuf::from(format!(r"\\{}", stripped)); + } + if let Some(stripped) = rendered.strip_prefix(r"\\?\") { + return PathBuf::from(stripped); + } + } + } - assert!(matches!( - &outcome.messages[1], - LlmMessage::Tool { content, .. } if content == replacement - )); - assert!(matches!( - &outcome.messages[2], - LlmMessage::Tool { content, .. } if is_persisted_output(content) - )); - assert_eq!(outcome.stats.reapply_count, 1); - assert_eq!(outcome.stats.replacement_count, 1); - assert_eq!(outcome.stats.over_budget_message_count, 1); - assert!(outcome.events.iter().any(|event| matches!( - &event.payload, - StorageEventPayload::ToolResultReferenceApplied { tool_call_id, .. } if tool_call_id == "call-2" - ))); + path +} + +fn truncate_with_notice(content: &str) -> String { + let limit = TOOL_RESULT_PREVIEW_LIMIT.min(content.len()); + let truncated_at = content.floor_char_boundary(limit); + let prefix = &content[..truncated_at]; + format!( + "{prefix}\n\n... [output truncated to {limit} bytes because persisted storage is \ + unavailable; use offset/limit parameters or rerun with a narrower scope for full content]" + ) +} + +fn tool_result_reference_applied_event( + turn_id: &str, + agent: &AgentEventContext, + tool_call_id: &str, + persisted_output: &PersistedToolOutput, + replacement: &str, + original_bytes: u64, +) -> StorageEvent { + StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::ToolResultReferenceApplied { + tool_call_id: tool_call_id.to_string(), + persisted_output: persisted_output.clone(), + replacement: replacement.to_string(), + original_bytes, + }, } } diff --git a/crates/session-runtime/src/context_window/tool_results.rs b/crates/agent-runtime/src/context_window/tool_results.rs similarity index 84% rename from crates/session-runtime/src/context_window/tool_results.rs rename to crates/agent-runtime/src/context_window/tool_results.rs index 225ef99f..66f0eed2 100644 --- a/crates/session-runtime/src/context_window/tool_results.rs +++ b/crates/agent-runtime/src/context_window/tool_results.rs @@ -2,7 +2,6 @@ use std::collections::HashMap; use astrcode_core::LlmMessage; -/// 从历史 assistant tool calls 构建 `tool_call_id -> tool_name` 映射。 pub(crate) fn tool_call_name_map(messages: &[LlmMessage]) -> HashMap { let mut names = HashMap::new(); for message in messages { diff --git a/crates/agent-runtime/src/hook_dispatch.rs b/crates/agent-runtime/src/hook_dispatch.rs new file mode 100644 index 00000000..496ca813 --- /dev/null +++ b/crates/agent-runtime/src/hook_dispatch.rs @@ -0,0 +1,69 @@ +use astrcode_core::{HookEventKey, Result}; +use async_trait::async_trait; +use serde_json::Value; + +#[derive(Debug, Clone, PartialEq)] +pub struct HookDispatchRequest { + pub snapshot_id: String, + pub event: HookEventKey, + pub session_id: String, + pub turn_id: String, + pub agent_id: String, + pub payload: Value, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum HookEffectKind { + Continue, + Block, + CancelTurn, + AugmentPrompt, + Diagnostic, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct HookEffect { + pub kind: HookEffectKind, + pub message: Option, + pub terminal: bool, +} + +impl HookEffect { + pub fn continue_flow() -> Self { + Self { + kind: HookEffectKind::Continue, + message: None, + terminal: false, + } + } + + pub fn cancel_turn(message: impl Into) -> Self { + Self { + kind: HookEffectKind::CancelTurn, + message: Some(message.into()), + terminal: true, + } + } + + pub fn augment_prompt(message: impl Into) -> Self { + Self { + kind: HookEffectKind::AugmentPrompt, + message: Some(message.into()), + terminal: false, + } + } +} + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct HookDispatchOutcome { + pub effects: Vec, +} + +/// runtime 消费的抽象 hooks 调度面。 +/// +/// `agent-runtime` 只知道 snapshot id 和事件点；具体 hook registry、匹配与 +/// builtin/external handler 归 plugin-host。 +#[async_trait] +pub trait HookDispatcher: Send + Sync { + async fn dispatch_hook(&self, request: HookDispatchRequest) -> Result; +} diff --git a/crates/agent-runtime/src/lib.rs b/crates/agent-runtime/src/lib.rs new file mode 100644 index 00000000..e7b12b63 --- /dev/null +++ b/crates/agent-runtime/src/lib.rs @@ -0,0 +1,38 @@ +//! Agent 执行内核。 +//! +//! 负责 turn loop、provider stream、tool dispatch、hook dispatch 和运行时上下文窗口管理。 +//! +//! ## 设计说明 +//! +//! - `execute_tool_calls` 当前采用**串行预检查 → 并行 I/O → 串行结果处理**的策略： 工具调度的实际 +//! I/O (`dispatch_tool`) 使用 `join_all` 并发执行， 但 Hook +//! 事件发射和结果写入保持顺序以维持消息排序确定性。 +//! 如需要更细粒度的"只读并行、写串行"分桶策略，可参考旧版 `session-runtime` 的 `tool_cycle.rs`。 + +mod context_window; +pub mod hook_dispatch; +pub mod r#loop; +pub mod provider; +pub mod runtime; +pub mod stream; +pub mod tool_dispatch; +pub mod types; + +pub use context_window::tool_result_budget::ToolResultReplacementRecord; +pub use hook_dispatch::{ + HookDispatchOutcome, HookDispatchRequest, HookDispatcher, HookEffect, HookEffectKind, +}; +pub use r#loop::{ + StepOutcome, TurnExecutionContext, TurnExecutionResources, TurnLoop, TurnStepRunner, +}; +pub use provider::{ + LlmEvent, LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, LlmUsage, + ModelLimits, PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, + PromptCacheHints, PromptLayerFingerprints, +}; +pub use runtime::AgentRuntime; +pub use tool_dispatch::{ToolDispatchRequest, ToolDispatcher}; +pub use types::{ + AgentRuntimeExecutionSurface, RuntimeEventSink, RuntimeTurnEvent, TurnIdentity, TurnInput, + TurnLoopTransition, TurnOutput, TurnStopCause, +}; diff --git a/crates/agent-runtime/src/loop.rs b/crates/agent-runtime/src/loop.rs new file mode 100644 index 00000000..ffbac3ae --- /dev/null +++ b/crates/agent-runtime/src/loop.rs @@ -0,0 +1,1868 @@ +use std::{ + collections::HashSet, + path::PathBuf, + sync::{Arc, Mutex}, + time::Instant, +}; + +use astrcode_core::{ + AgentEventContext, AstrError, CapabilitySpec, HookEventKey, LlmMessage, ResolvedRuntimeConfig, + StorageEvent, StorageEventPayload, ToolCallRequest, ToolDefinition, ToolExecutionResult, + ToolOutputDelta, UserMessageOrigin, +}; +use async_trait::async_trait; +use chrono::Utc; + +use crate::{ + context_window::{ + ContextWindowSettings, + compaction::is_prompt_too_long_message, + file_access::FileAccessTracker, + micro_compact::MicroCompactState, + request::{ + apply_prompt_metrics_usage, assemble_runtime_request, recover_from_prompt_too_long, + }, + token_usage::TokenUsageTracker, + tool_result_budget::{ToolResultBudgetStats, ToolResultReplacementState}, + }, + hook_dispatch::{HookDispatchRequest, HookDispatcher, HookEffectKind}, + provider::{LlmEventSink, LlmOutput, LlmProvider}, + tool_dispatch::{ToolDispatchRequest, ToolDispatcher}, + types::{ + RuntimeEventSink, RuntimeTurnEvent, StepError, TurnInput, TurnLoopTransition, TurnOutput, + TurnStopCause, + }, +}; + +const OUTPUT_CONTINUATION_PROMPT: &str = "Continue from the exact point where the previous \ + response was cut off. Do not restart, recap, or \ + apologize."; + +/// 单步执行结果。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum StepOutcome { + Continue(TurnLoopTransition), + Completed(TurnStopCause), + Error(StepError), +} + +/// 单 turn 执行所需的无状态资源快照。 +#[derive(Clone)] +pub struct TurnExecutionResources { + pub session_id: String, + pub turn_id: String, + pub agent_id: String, + pub agent: AgentEventContext, + pub model_ref: String, + pub provider_ref: String, + pub hook_snapshot_id: String, + pub tool_count: usize, + pub tools: Arc<[ToolDefinition]>, + pub provider: Option>, + pub tool_dispatcher: Option>, + pub hook_dispatcher: Option>, + pub cancel: astrcode_core::CancelToken, + pub max_output_continuations: usize, + pub working_dir: PathBuf, + pub runtime_config: ResolvedRuntimeConfig, + pub(crate) settings: ContextWindowSettings, + pub(crate) clearable_tools: HashSet, + pub(crate) previous_tool_result_replacements: + Vec, + pub(crate) last_assistant_at: Option>, + /// 由宿主传入的事件历史路径，`None` 表示不保存 compact 历史。 + pub(crate) events_history_path: Option, + pub(crate) event_sink: Arc, +} + +impl std::fmt::Debug for TurnExecutionResources { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + formatter + .debug_struct("TurnExecutionResources") + .field("session_id", &self.session_id) + .field("turn_id", &self.turn_id) + .field("agent_id", &self.agent_id) + .field("agent", &self.agent) + .field("model_ref", &self.model_ref) + .field("provider_ref", &self.provider_ref) + .field("hook_snapshot_id", &self.hook_snapshot_id) + .field("tool_count", &self.tool_count) + .field( + "provider", + &self.provider.as_ref().map(|_| ""), + ) + .field( + "tool_dispatcher", + &self.tool_dispatcher.as_ref().map(|_| ""), + ) + .field( + "hook_dispatcher", + &self.hook_dispatcher.as_ref().map(|_| ""), + ) + .field("cancel", &self.cancel) + .field("max_output_continuations", &self.max_output_continuations) + .field("working_dir", &self.working_dir) + .field("runtime_config", &self.runtime_config) + .field("events_history_path", &self.events_history_path) + .field("event_sink", &"") + .finish() + } +} + +impl TurnExecutionResources { + fn turn_identity(&self) -> crate::types::TurnIdentity { + crate::types::TurnIdentity::new( + self.session_id.clone(), + self.turn_id.clone(), + self.agent_id.clone(), + ) + } + + fn from_input(input: &TurnInput) -> Self { + let surface = &input.surface; + let settings = ContextWindowSettings::from(&input.runtime_config); + let clearable_tools = surface + .tool_specs + .iter() + .filter(|spec| spec.compact_clearable) + .map(|spec| spec.name.to_string()) + .collect(); + Self { + session_id: surface.session_id.clone(), + turn_id: surface.turn_id.clone(), + agent_id: surface.agent_id.clone(), + agent: input.agent.clone(), + model_ref: surface.model_ref.clone(), + provider_ref: surface.provider_ref.clone(), + hook_snapshot_id: surface.hook_snapshot_id.clone(), + tool_count: surface.tool_specs.len(), + tools: tool_definitions_from_specs(&surface.tool_specs), + provider: input.provider.clone(), + tool_dispatcher: input.tool_dispatcher.clone(), + hook_dispatcher: input.hook_dispatcher.clone(), + cancel: input.cancel.clone(), + max_output_continuations: input.max_output_continuations, + working_dir: input.working_dir.clone(), + runtime_config: input.runtime_config.clone(), + settings, + clearable_tools, + previous_tool_result_replacements: input.previous_tool_result_replacements.clone(), + last_assistant_at: input.last_assistant_at, + events_history_path: input.events_history_path.clone(), + event_sink: input.event_sink.clone().unwrap_or_else(|| Arc::new(|_| {})), + } + } +} + +/// 单 turn 执行上下文。 +#[derive(Debug, Clone)] +pub struct TurnExecutionContext { + pub messages: Vec, + pub pending_events: Vec, + pub started_at: Instant, + pub step_index: usize, + pub last_transition: Option, + pub stop_cause: Option, + pub max_output_continuation_count: usize, + pub reactive_compact_attempts: usize, + pub(crate) token_tracker: TokenUsageTracker, + pub(crate) micro_compact_state: MicroCompactState, + pub(crate) file_access_tracker: FileAccessTracker, + pub(crate) tool_result_replacement_state: ToolResultReplacementState, + pub(crate) tool_result_budget_stats: ToolResultBudgetStats, + pub(crate) auto_compaction_count: usize, +} + +impl TurnExecutionContext { + fn new(messages: Vec, resources: &TurnExecutionResources) -> Self { + let now = Instant::now(); + Self { + micro_compact_state: MicroCompactState::seed_from_messages( + &messages, + resources.settings.micro_compact_config(), + now, + resources.last_assistant_at, + ), + file_access_tracker: FileAccessTracker::seed_from_messages( + &messages, + resources.settings.max_tracked_files, + &resources.working_dir, + ), + tool_result_replacement_state: ToolResultReplacementState::seed( + resources.previous_tool_result_replacements.clone(), + ), + messages, + pending_events: Vec::new(), + started_at: now, + step_index: 0, + last_transition: None, + stop_cause: None, + max_output_continuation_count: 0, + reactive_compact_attempts: 0, + token_tracker: TokenUsageTracker::default(), + tool_result_budget_stats: ToolResultBudgetStats::default(), + auto_compaction_count: 0, + } + } + + fn push_event(&mut self, event: RuntimeTurnEvent) { + self.pending_events.push(event); + } + + fn record_transition(&mut self, transition: TurnLoopTransition) { + self.last_transition = Some(transition); + self.step_index = self.step_index.saturating_add(1); + } + + fn record_stop(&mut self, stop_cause: TurnStopCause) { + self.stop_cause = Some(stop_cause); + } +} + +#[async_trait] +pub trait TurnStepRunner { + async fn run_single_step( + &self, + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + ) -> StepOutcome; +} + +#[derive(Debug, Default)] +struct ProviderTurnStepRunner; + +#[async_trait] +impl TurnStepRunner for ProviderTurnStepRunner { + async fn run_single_step( + &self, + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + ) -> StepOutcome { + run_single_step(execution, resources).await + } +} + +/// 单 turn 主循环。 +#[derive(Debug, Default)] +pub struct TurnLoop; + +impl TurnLoop { + pub async fn run(&self, input: TurnInput) -> TurnOutput { + self.run_with_step_runner(input, &ProviderTurnStepRunner) + .await + } + + pub async fn run_with_step_runner( + &self, + input: TurnInput, + runner: &impl TurnStepRunner, + ) -> TurnOutput { + let resources = TurnExecutionResources::from_input(&input); + let event_sink = Arc::clone(&resources.event_sink); + let mut execution = TurnExecutionContext::new(input.messages, &resources); + let mut emitted_events = Vec::new(); + + execution.push_event(RuntimeTurnEvent::TurnStarted { + identity: resources.turn_identity(), + }); + if let Some(outcome) = + dispatch_runtime_hook(&mut execution, &resources, HookEventKey::TurnStart).await + { + flush_pending_events(event_sink.as_ref(), &mut execution, &mut emitted_events); + return match outcome { + StepOutcome::Completed(stop_cause) => finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + stop_cause, + None, + ), + StepOutcome::Error(step_error) => finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + TurnStopCause::Error, + Some(&step_error.message), + ), + StepOutcome::Continue(_) => unreachable!("hooks cannot request loop continuation"), + }; + } + flush_pending_events(event_sink.as_ref(), &mut execution, &mut emitted_events); + + loop { + match runner.run_single_step(&mut execution, &resources).await { + StepOutcome::Continue(transition) => { + execution.push_event(RuntimeTurnEvent::StepContinued { + identity: resources.turn_identity(), + step_index: execution.step_index, + transition, + }); + execution.record_transition(transition); + flush_pending_events(event_sink.as_ref(), &mut execution, &mut emitted_events); + }, + StepOutcome::Completed(stop_cause) => { + execution.record_stop(stop_cause); + if let Some(hook_outcome) = + dispatch_runtime_hook(&mut execution, &resources, HookEventKey::TurnEnd) + .await + { + return match hook_outcome { + StepOutcome::Completed(stop_cause) => finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + stop_cause, + None, + ), + StepOutcome::Error(step_error) => finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + TurnStopCause::Error, + Some(&step_error.message), + ), + StepOutcome::Continue(_) => { + unreachable!("hooks cannot request loop continuation") + }, + }; + } + return finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + stop_cause, + None, + ); + }, + StepOutcome::Error(step_error) => { + return finalize_turn( + event_sink.as_ref(), + &resources.turn_identity(), + &mut execution, + &mut emitted_events, + TurnStopCause::Error, + Some(&step_error.message), + ); + }, + } + } + } +} + +async fn run_single_step( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, +) -> StepOutcome { + for event in [ + HookEventKey::Context, + HookEventKey::BeforeAgentStart, + HookEventKey::BeforeProviderRequest, + ] { + if let Some(outcome) = dispatch_runtime_hook(execution, resources, event).await { + return outcome; + } + } + + let Some(provider) = &resources.provider else { + return StepOutcome::Completed(TurnStopCause::Completed); + }; + + if resources.cancel.is_cancelled() { + return StepOutcome::Completed(TurnStopCause::Cancelled); + } + + let stream_events = Arc::new(Mutex::new(Vec::new())); + let stream_events_sink = Arc::clone(&stream_events); + let stream_event_sink = Arc::clone(&resources.event_sink); + let stream_identity = resources.turn_identity(); + let sink: LlmEventSink = Arc::new(move |event| { + stream_event_sink.emit_event(RuntimeTurnEvent::ProviderStream { + identity: stream_identity.clone(), + event: event.clone(), + }); + stream_events_sink + .lock() + .expect("provider stream event buffer poisoned") + .push(event); + }); + + let request = match assemble_runtime_request(execution, resources).await { + Ok(request) => request, + Err(error) if error.is_cancelled() => { + return StepOutcome::Completed(TurnStopCause::Cancelled); + }, + Err(error) => return StepOutcome::Error(StepError::from(&error)), + }; + + let output = match provider.generate(request, Some(sink)).await { + Ok(output) => output, + Err(error) if error.is_cancelled() => { + return StepOutcome::Completed(TurnStopCause::Cancelled); + }, + Err(error) + if is_prompt_too_long_message(&error.to_string()) + && execution.reactive_compact_attempts + < resources.settings.compact_max_retry_attempts + && resources.settings.auto_compact_enabled => + { + match recover_from_prompt_too_long(execution, resources, provider.as_ref()).await { + Ok(true) => { + return StepOutcome::Continue(TurnLoopTransition::ReactiveCompactRecovered); + }, + Ok(false) => return StepOutcome::Error(StepError::from(&error)), + Err(recovery_error) if recovery_error.is_cancelled() => { + return StepOutcome::Completed(TurnStopCause::Cancelled); + }, + Err(recovery_error) => return StepOutcome::Error(StepError::from(&recovery_error)), + } + }, + Err(error) => return StepOutcome::Error(StepError::from(&error)), + }; + + for event in stream_events + .lock() + .expect("provider stream event buffer poisoned") + .drain(..) + { + execution.push_event(RuntimeTurnEvent::ProviderStream { + identity: resources.turn_identity(), + event, + }); + } + + record_provider_output(execution, resources, &output); + apply_prompt_metrics_usage( + &mut execution.pending_events, + execution.step_index, + output.usage, + output.prompt_cache_diagnostics.clone(), + ); + execution.token_tracker.record_usage(output.usage); + + if !output.tool_calls.is_empty() { + if let Some(dispatcher) = &resources.tool_dispatcher { + match execute_tool_calls( + execution, + resources, + dispatcher.as_ref(), + &output.tool_calls, + ) + .await + { + Ok(()) => return StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted), + Err(error) if error.is_cancelled() => { + return StepOutcome::Completed(TurnStopCause::Cancelled); + }, + Err(error) => return StepOutcome::Error(StepError::from(&error)), + } + } + execution.push_event(RuntimeTurnEvent::ToolUseRequested { + identity: resources.turn_identity(), + tool_call_count: output.tool_calls.len(), + }); + return StepOutcome::Completed(TurnStopCause::Completed); + } + + if output.finish_reason.is_max_tokens() + && execution.max_output_continuation_count < resources.max_output_continuations + { + execution.messages.push(LlmMessage::User { + content: OUTPUT_CONTINUATION_PROMPT.to_string(), + origin: UserMessageOrigin::ContinuationPrompt, + }); + execution.max_output_continuation_count = + execution.max_output_continuation_count.saturating_add(1); + return StepOutcome::Continue(TurnLoopTransition::OutputContinuationRequested); + } + + StepOutcome::Completed(TurnStopCause::Completed) +} + +async fn dispatch_runtime_hook( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + event: HookEventKey, +) -> Option { + let Some(dispatcher) = &resources.hook_dispatcher else { + return None; + }; + + let outcome = match dispatcher + .dispatch_hook(HookDispatchRequest { + snapshot_id: resources.hook_snapshot_id.clone(), + event, + session_id: resources.session_id.clone(), + turn_id: resources.turn_id.clone(), + agent_id: resources.agent_id.clone(), + payload: serde_json::json!({ + "agent": resources.agent.clone(), + "stepIndex": execution.step_index, + "messageCount": execution.messages.len(), + }), + }) + .await + { + Ok(outcome) => outcome, + Err(error) => return Some(StepOutcome::Error(StepError::from(&error))), + }; + + execution.push_event(RuntimeTurnEvent::HookDispatched { + identity: resources.turn_identity(), + event, + effect_count: outcome.effects.len(), + }); + + for effect in outcome.effects { + match effect.kind { + HookEffectKind::Continue | HookEffectKind::Diagnostic => {}, + HookEffectKind::AugmentPrompt => { + let content = effect.message.unwrap_or_default(); + execution.messages.push(LlmMessage::User { + content: content.clone(), + origin: UserMessageOrigin::ReactivationPrompt, + }); + execution.push_event(RuntimeTurnEvent::HookPromptAugmented { + identity: resources.turn_identity(), + event, + content, + }); + }, + HookEffectKind::CancelTurn => { + return Some(StepOutcome::Completed(TurnStopCause::Cancelled)); + }, + HookEffectKind::Block => { + return Some(StepOutcome::Error(StepError::fatal( + effect + .message + .unwrap_or_else(|| "hook blocked execution".to_string()), + ))); + }, + } + } + + None +} + +async fn execute_tool_calls( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + dispatcher: &dyn ToolDispatcher, + tool_calls: &[ToolCallRequest], +) -> astrcode_core::Result<()> { + let (tool_output_sender, mut tool_output_receiver) = + tokio::sync::mpsc::unbounded_channel::(); + + // Phase 1: Pre-dispatch hooks and event emissions (sequential, order-preserving) + let mut futures = Vec::with_capacity(tool_calls.len()); + for tool_call in tool_calls { + if resources.cancel.is_cancelled() { + return Err(AstrError::Cancelled); + } + if let Some(outcome) = + dispatch_runtime_hook(execution, resources, HookEventKey::ToolCall).await + { + return Err(step_outcome_to_error(outcome)); + } + execution.push_event(RuntimeTurnEvent::ToolCallStarted { + identity: resources.turn_identity(), + tool_call_id: tool_call.id.clone(), + tool_name: tool_call.name.clone(), + }); + push_immediate_event( + execution, + resources, + RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some(resources.turn_id.clone()), + agent: resources.agent.clone(), + payload: StorageEventPayload::ToolCall { + tool_call_id: tool_call.id.clone(), + tool_name: tool_call.name.clone(), + args: tool_call.args.clone(), + }, + }), + }, + ); + futures.push(dispatcher.dispatch_tool(ToolDispatchRequest { + session_id: resources.session_id.clone(), + turn_id: resources.turn_id.clone(), + agent_id: resources.agent_id.clone(), + tool_call: tool_call.clone(), + tool_output_sender: Some(tool_output_sender.clone()), + })); + } + drop(tool_output_sender); + + // Phase 2: Execute all tool dispatches concurrently (I/O-bound parallelism) + let mut results_future = Box::pin(futures_util::future::join_all(futures)); + let results = loop { + tokio::select! { + Some(delta) = tool_output_receiver.recv() => { + record_tool_output_delta(execution, resources, delta); + }, + results = &mut results_future => { + while let Ok(delta) = tool_output_receiver.try_recv() { + record_tool_output_delta(execution, resources, delta); + } + break results; + }, + } + }; + + // Phase 3: Process results in order (sequential, preserving message ordering) + for (tool_call, result) in tool_calls.iter().zip(results) { + let result = match result { + Ok(r) => r, + Err(e) if e.is_cancelled() => return Err(AstrError::Cancelled), + Err(e) => return Err(e), + }; + record_tool_result(execution, resources, tool_call, result); + if let Some(outcome) = + dispatch_runtime_hook(execution, resources, HookEventKey::ToolResult).await + { + return Err(step_outcome_to_error(outcome)); + } + } + Ok(()) +} + +fn step_outcome_to_error(outcome: StepOutcome) -> AstrError { + match outcome { + StepOutcome::Error(step_error) => AstrError::Internal(step_error.message), + StepOutcome::Completed(TurnStopCause::Cancelled) => AstrError::Cancelled, + StepOutcome::Completed(stop_cause) => { + AstrError::Internal(format!("hook terminated tool dispatch with {stop_cause:?}")) + }, + StepOutcome::Continue(transition) => { + AstrError::Internal(format!("hook unexpectedly requested {transition:?}")) + }, + } +} + +fn record_tool_result( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + tool_call: &ToolCallRequest, + result: ToolExecutionResult, +) { + execution.push_event(RuntimeTurnEvent::ToolResultReady { + identity: resources.turn_identity(), + tool_call_id: result.tool_call_id.clone(), + tool_name: result.tool_name.clone(), + ok: result.ok, + }); + push_immediate_event( + execution, + resources, + RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some(resources.turn_id.clone()), + agent: resources.agent.clone(), + payload: StorageEventPayload::ToolResult { + tool_call_id: result.tool_call_id.clone(), + tool_name: result.tool_name.clone(), + output: result.output.clone(), + success: result.ok, + error: result.error.clone(), + metadata: result.metadata.clone(), + continuation: result.continuation.clone(), + duration_ms: result.duration_ms, + }, + }), + }, + ); + execution + .file_access_tracker + .record_tool_result(tool_call, &result, &resources.working_dir); + execution + .micro_compact_state + .record_tool_result(result.tool_call_id.clone(), Instant::now()); + execution.messages.push(LlmMessage::Tool { + tool_call_id: result.tool_call_id.clone(), + content: result.model_content(), + }); +} + +fn record_provider_output( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + output: &LlmOutput, +) { + execution + .micro_compact_state + .record_assistant_activity(Instant::now()); + execution.messages.push(LlmMessage::Assistant { + content: output.content.clone(), + tool_calls: output.tool_calls.clone(), + reasoning: output.reasoning.clone(), + }); + execution.push_event(RuntimeTurnEvent::AssistantFinal { + identity: resources.turn_identity(), + content: output.content.clone(), + reasoning: output.reasoning.clone(), + tool_call_count: output.tool_calls.len(), + }); +} + +fn record_tool_output_delta( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + delta: ToolOutputDelta, +) { + push_immediate_event( + execution, + resources, + RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some(resources.turn_id.clone()), + agent: resources.agent.clone(), + payload: StorageEventPayload::ToolCallDelta { + tool_call_id: delta.tool_call_id, + tool_name: delta.tool_name, + stream: delta.stream, + delta: delta.delta, + }, + }), + }, + ); +} + +fn push_immediate_event( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + event: RuntimeTurnEvent, +) { + resources.event_sink.emit_event(event.clone()); + execution.push_event(event); +} + +fn tool_definitions_from_specs(specs: &[CapabilitySpec]) -> Arc<[ToolDefinition]> { + specs + .iter() + .map(|spec| ToolDefinition { + name: spec.name.to_string(), + description: spec.description.clone(), + parameters: spec.input_schema.clone(), + }) + .collect::>() + .into() +} + +fn flush_pending_events( + event_sink: &dyn crate::types::RuntimeEventSink, + execution: &mut TurnExecutionContext, + emitted_events: &mut Vec, +) { + if execution.pending_events.is_empty() { + return; + } + + for event in execution.pending_events.drain(..) { + if !matches!(event, RuntimeTurnEvent::ProviderStream { .. }) + && !is_immediate_tool_storage_event(&event) + { + event_sink.emit_event(event.clone()); + } + emitted_events.push(event); + } +} + +fn is_immediate_tool_storage_event(event: &RuntimeTurnEvent) -> bool { + matches!( + event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + event.payload, + StorageEventPayload::ToolCall { .. } + | StorageEventPayload::ToolCallDelta { .. } + | StorageEventPayload::ToolResult { .. } + ) + ) +} + +fn finalize_turn( + event_sink: &dyn crate::types::RuntimeEventSink, + identity: &crate::types::TurnIdentity, + execution: &mut TurnExecutionContext, + emitted_events: &mut Vec, + stop_cause: TurnStopCause, + error_message: Option<&str>, +) -> TurnOutput { + execution.record_stop(stop_cause); + if let Some(msg) = error_message { + execution.push_event(RuntimeTurnEvent::TurnErrored { + identity: identity.clone(), + message: msg.to_string(), + }); + } + let terminal_kind = stop_cause.terminal_kind(error_message); + execution.push_event(RuntimeTurnEvent::TurnCompleted { + identity: identity.clone(), + stop_cause, + terminal_kind: terminal_kind.clone(), + }); + flush_pending_events(event_sink, execution, emitted_events); + TurnOutput { + identity: identity.clone(), + terminal_kind: Some(terminal_kind), + stop_cause: Some(stop_cause), + step_count: execution.step_index.saturating_add(1), + events: std::mem::take(emitted_events), + error_message: error_message.map(|m| m.to_string()), + } +} + +#[cfg(test)] +mod tests { + use std::{ + sync::{Arc, Mutex}, + time::Duration, + }; + + use astrcode_core::{ + AgentEventContext, AstrError, CancelToken, HookEventKey, Result, SubRunStorageMode, + ToolExecutionResult, TurnTerminalKind, + }; + use async_trait::async_trait; + + use super::{ + StepOutcome, TurnExecutionContext, TurnExecutionResources, TurnLoop, TurnStepRunner, + }; + use crate::{ + hook_dispatch::{HookDispatchOutcome, HookDispatchRequest, HookDispatcher, HookEffect}, + provider::{ + LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, + }, + tool_dispatch::{ToolDispatchRequest, ToolDispatcher}, + types::{ + AgentRuntimeExecutionSurface, RuntimeTurnEvent, StepError, TurnInput, + TurnLoopTransition, TurnStopCause, + }, + }; + + fn input() -> TurnInput { + TurnInput::new(AgentRuntimeExecutionSurface { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-1".to_string(), + model_ref: "model-a".to_string(), + provider_ref: "provider-a".to_string(), + tool_specs: Vec::new(), + hook_snapshot_id: "snapshot-1".to_string(), + }) + } + + fn storage_payload(event: &RuntimeTurnEvent) -> Option<&astrcode_core::StorageEventPayload> { + match event { + RuntimeTurnEvent::StorageEvent { event } => Some(&event.payload), + _ => None, + } + } + + #[tokio::test] + async fn execute_empty_turn_emits_basic_lifecycle() { + let emitted = Arc::new(Mutex::new(Vec::new())); + let sink_events = Arc::clone(&emitted); + let input = input().with_event_sink(Arc::new(move |event| { + sink_events.lock().expect("event sink poisoned").push(event); + })); + + let output = TurnLoop.run(input).await; + + assert_eq!(output.identity.session_id, "session-1"); + assert_eq!(output.identity.turn_id, "turn-1"); + assert_eq!(output.identity.agent_id, "agent-1"); + assert_eq!(output.stop_cause, Some(TurnStopCause::Completed)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Completed)); + assert_eq!(output.step_count, 1); + assert_eq!(output.events.len(), 2); + assert!(matches!( + output.events[0], + RuntimeTurnEvent::TurnStarted { .. } + )); + assert!(matches!( + output.events[1], + RuntimeTurnEvent::TurnCompleted { + stop_cause: TurnStopCause::Completed, + terminal_kind: TurnTerminalKind::Completed, + .. + } + )); + assert_eq!( + emitted.lock().expect("event sink poisoned").len(), + output.events.len() + ); + } + + #[derive(Debug)] + struct ContinueThenComplete { + remaining_continues: Mutex, + } + + #[async_trait] + impl TurnStepRunner for ContinueThenComplete { + async fn run_single_step( + &self, + _execution: &mut TurnExecutionContext, + _resources: &TurnExecutionResources, + ) -> StepOutcome { + let mut remaining = self + .remaining_continues + .lock() + .expect("step runner state poisoned"); + if *remaining > 0 { + *remaining -= 1; + return StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted); + } + StepOutcome::Completed(TurnStopCause::Completed) + } + } + + #[tokio::test] + async fn loop_records_continue_transitions_before_completion() { + let runner = ContinueThenComplete { + remaining_continues: Mutex::new(1), + }; + + let output = TurnLoop.run_with_step_runner(input(), &runner).await; + + assert_eq!(output.step_count, 2); + assert_eq!( + output + .events + .iter() + .filter(|event| matches!(event, RuntimeTurnEvent::StepContinued { .. })) + .count(), + 1 + ); + } + + #[derive(Debug)] + struct FailingRunner; + + #[async_trait] + impl TurnStepRunner for FailingRunner { + async fn run_single_step( + &self, + _execution: &mut TurnExecutionContext, + _resources: &TurnExecutionResources, + ) -> StepOutcome { + StepOutcome::Error(StepError::fatal("provider failed")) + } + } + + #[tokio::test] + async fn loop_maps_step_error_to_terminal_error() { + let output = TurnLoop.run_with_step_runner(input(), &FailingRunner).await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Error)); + assert_eq!( + output.terminal_kind, + Some(TurnTerminalKind::Error { + message: "provider failed".to_string() + }) + ); + assert_eq!(output.error_message.as_deref(), Some("provider failed")); + assert!(matches!( + output.events.last(), + Some(RuntimeTurnEvent::TurnCompleted { + stop_cause: TurnStopCause::Error, + .. + }) + )); + } + + #[test] + fn context_tracks_start_time_without_external_state() { + let input = input(); + let resources = TurnExecutionResources::from_input(&input); + let context = TurnExecutionContext::new(Vec::new(), &resources); + + assert!(context.started_at.elapsed() < Duration::from_secs(1)); + assert!(context.messages.is_empty()); + assert!(context.pending_events.is_empty()); + } + + #[derive(Debug)] + struct StaticProvider { + outputs: Mutex>, + } + + #[derive(Debug)] + struct BlockingStreamingProvider { + release: Mutex>>, + delta_sent: Mutex>>, + } + + #[derive(Debug)] + struct BlockingStreamingToolDispatcher { + release: Mutex>>, + delta_sent: Mutex>>, + } + + #[async_trait] + impl LlmProvider for StaticProvider { + async fn generate( + &self, + _request: LlmRequest, + sink: Option, + ) -> Result { + if let Some(sink) = sink { + sink(crate::provider::LlmEvent::TextDelta("delta".to_string())); + } + Ok(self + .outputs + .lock() + .expect("provider output buffer poisoned") + .remove(0)) + } + + fn model_limits(&self) -> ModelLimits { + ModelLimits { + context_window: 128_000, + max_output_tokens: 8_000, + } + } + } + + #[async_trait] + impl LlmProvider for BlockingStreamingProvider { + async fn generate( + &self, + _request: LlmRequest, + sink: Option, + ) -> Result { + if let Some(sink) = sink { + sink(crate::provider::LlmEvent::TextDelta("live".to_string())); + } + if let Some(sender) = self + .delta_sent + .lock() + .expect("delta signal lock poisoned") + .take() + { + let _ = sender.send(()); + } + let release = self + .release + .lock() + .expect("release lock poisoned") + .take() + .expect("release receiver should be available"); + let _ = release.await; + Ok(LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }) + } + + fn model_limits(&self) -> ModelLimits { + ModelLimits { + context_window: 128_000, + max_output_tokens: 8_000, + } + } + } + + #[derive(Debug)] + struct CancellingProvider; + + #[derive(Debug)] + struct CapturingProvider { + outputs: Mutex>, + requests: Mutex>, + limits: ModelLimits, + } + + #[async_trait] + impl LlmProvider for CapturingProvider { + async fn generate( + &self, + request: LlmRequest, + _sink: Option, + ) -> Result { + self.requests + .lock() + .expect("request capture poisoned") + .push(request); + Ok(self + .outputs + .lock() + .expect("provider output buffer poisoned") + .remove(0)) + } + + fn model_limits(&self) -> ModelLimits { + self.limits + } + } + + #[async_trait] + impl LlmProvider for CancellingProvider { + async fn generate( + &self, + _request: LlmRequest, + _sink: Option, + ) -> Result { + Err(AstrError::Cancelled) + } + + fn model_limits(&self) -> ModelLimits { + ModelLimits { + context_window: 128_000, + max_output_tokens: 8_000, + } + } + } + + #[derive(Debug)] + struct EchoToolDispatcher; + + #[async_trait] + impl ToolDispatcher for EchoToolDispatcher { + async fn dispatch_tool(&self, request: ToolDispatchRequest) -> Result { + Ok(ToolExecutionResult { + tool_call_id: request.tool_call.id, + tool_name: request.tool_call.name, + ok: true, + output: "tool result".to_string(), + error: None, + metadata: None, + continuation: None, + duration_ms: 0, + truncated: false, + }) + } + } + + #[async_trait] + impl ToolDispatcher for BlockingStreamingToolDispatcher { + async fn dispatch_tool(&self, request: ToolDispatchRequest) -> Result { + if let Some(sender) = request.tool_output_sender { + let _ = sender.send(astrcode_core::ToolOutputDelta { + tool_call_id: request.tool_call.id.clone(), + tool_name: request.tool_call.name.clone(), + stream: astrcode_core::ToolOutputStream::Stdout, + delta: "tool-live\n".to_string(), + }); + } + if let Some(sender) = self + .delta_sent + .lock() + .expect("delta signal lock poisoned") + .take() + { + let _ = sender.send(()); + } + let release = self + .release + .lock() + .expect("release lock poisoned") + .take() + .expect("release receiver should be available"); + let _ = release.await; + Ok(ToolExecutionResult { + tool_call_id: request.tool_call.id, + tool_name: request.tool_call.name, + ok: true, + output: "tool result".to_string(), + error: None, + metadata: None, + continuation: None, + duration_ms: 0, + truncated: false, + }) + } + } + + #[derive(Debug)] + struct CancellingToolDispatcher; + + #[async_trait] + impl ToolDispatcher for CancellingToolDispatcher { + async fn dispatch_tool( + &self, + _request: ToolDispatchRequest, + ) -> Result { + Err(AstrError::Cancelled) + } + } + + #[derive(Debug)] + struct RecordingHookDispatcher { + events: Mutex>, + payloads: Mutex>, + cancel_before_provider: bool, + augment_context: bool, + } + + #[async_trait] + impl HookDispatcher for RecordingHookDispatcher { + async fn dispatch_hook(&self, request: HookDispatchRequest) -> Result { + self.events + .lock() + .expect("hook event buffer poisoned") + .push(request.event); + self.payloads + .lock() + .expect("hook payload buffer poisoned") + .push(request.payload); + let effects = match request.event { + HookEventKey::Context if self.augment_context => { + vec![HookEffect::augment_prompt("extra runtime context")] + }, + HookEventKey::BeforeProviderRequest if self.cancel_before_provider => { + vec![HookEffect::cancel_turn("blocked by hook")] + }, + _ => vec![HookEffect::continue_flow()], + }; + Ok(HookDispatchOutcome { effects }) + } + } + + #[tokio::test] + async fn provider_output_drives_turn_completion() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }]), + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_cancel(CancelToken::new()), + ) + .await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Completed)); + assert!( + output + .events + .iter() + .any(|event| matches!(event, RuntimeTurnEvent::ProviderStream { .. })) + ); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::AssistantFinal { content, .. } if content == "done" + ))); + assert!(output.events.iter().any(|event| matches!( + storage_payload(event), + Some(astrcode_core::StorageEventPayload::PromptMetrics { .. }) + ))); + } + + #[tokio::test] + async fn provider_stream_reaches_event_sink_before_provider_returns() { + let (delta_sent_tx, delta_sent_rx) = tokio::sync::oneshot::channel(); + let (release_tx, release_rx) = tokio::sync::oneshot::channel(); + let provider = Arc::new(BlockingStreamingProvider { + release: Mutex::new(Some(release_rx)), + delta_sent: Mutex::new(Some(delta_sent_tx)), + }); + let (event_tx, mut event_rx) = tokio::sync::mpsc::unbounded_channel(); + + let run_task = tokio::spawn(async move { + TurnLoop + .run( + input() + .with_provider(provider) + .with_event_sink(Arc::new(move |event| { + let _ = event_tx.send(event); + })), + ) + .await + }); + + delta_sent_rx.await.expect("provider should emit a delta"); + tokio::time::timeout(Duration::from_secs(1), async { + loop { + let event = event_rx + .recv() + .await + .expect("event channel should stay open"); + if matches!(event, RuntimeTurnEvent::ProviderStream { .. }) { + break; + } + } + }) + .await + .expect("provider stream should be emitted before provider returns"); + + release_tx + .send(()) + .expect("provider release should succeed"); + let output = run_task.await.expect("turn task should join"); + assert!( + output + .events + .iter() + .any(|event| matches!(event, RuntimeTurnEvent::ProviderStream { .. })) + ); + } + + #[tokio::test] + async fn tool_output_delta_reaches_event_sink_before_tool_returns() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![ + LlmOutput { + finish_reason: LlmFinishReason::ToolCalls, + tool_calls: vec![astrcode_core::ToolCallRequest { + id: "call-1".to_string(), + name: "shell_command".to_string(), + args: serde_json::json!({}), + }], + ..LlmOutput::default() + }, + LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }, + ]), + }); + let (delta_sent_tx, delta_sent_rx) = tokio::sync::oneshot::channel(); + let (release_tx, release_rx) = tokio::sync::oneshot::channel(); + let dispatcher = Arc::new(BlockingStreamingToolDispatcher { + release: Mutex::new(Some(release_rx)), + delta_sent: Mutex::new(Some(delta_sent_tx)), + }); + let (event_tx, mut event_rx) = tokio::sync::mpsc::unbounded_channel(); + + let run_task = tokio::spawn(async move { + TurnLoop + .run( + input() + .with_provider(provider) + .with_tool_dispatcher(dispatcher) + .with_event_sink(Arc::new(move |event| { + let _ = event_tx.send(event); + })), + ) + .await + }); + + delta_sent_rx.await.expect("tool should emit a delta"); + tokio::time::timeout(Duration::from_secs(1), async { + loop { + let event = event_rx + .recv() + .await + .expect("event channel should stay open"); + if matches!( + event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + event.payload, + astrcode_core::StorageEventPayload::ToolCallDelta { .. } + ) + ) { + break; + } + } + }) + .await + .expect("tool stream should be emitted before tool returns"); + + release_tx.send(()).expect("tool release should succeed"); + let output = run_task.await.expect("turn task should join"); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + event.payload, + astrcode_core::StorageEventPayload::ToolCallDelta { .. } + ) + ))); + } + + #[tokio::test] + async fn max_tokens_output_requests_one_continuation_before_completion() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![ + LlmOutput { + content: "partial".to_string(), + finish_reason: LlmFinishReason::MaxTokens, + ..LlmOutput::default() + }, + LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }, + ]), + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_max_output_continuations(1), + ) + .await; + + assert_eq!(output.step_count, 2); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::StepContinued { + transition: TurnLoopTransition::OutputContinuationRequested, + .. + } + ))); + } + + #[tokio::test] + async fn repeated_max_tokens_stops_at_configured_continuation_limit() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![ + LlmOutput { + content: "partial 1".to_string(), + finish_reason: LlmFinishReason::MaxTokens, + ..LlmOutput::default() + }, + LlmOutput { + content: "partial 2".to_string(), + finish_reason: LlmFinishReason::MaxTokens, + ..LlmOutput::default() + }, + LlmOutput { + content: "partial 3".to_string(), + finish_reason: LlmFinishReason::MaxTokens, + ..LlmOutput::default() + }, + ]), + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_max_output_continuations(2), + ) + .await; + + let continuation_count = output + .events + .iter() + .filter(|event| { + matches!( + event, + RuntimeTurnEvent::StepContinued { + transition: TurnLoopTransition::OutputContinuationRequested, + .. + } + ) + }) + .count(); + assert_eq!(output.stop_cause, Some(TurnStopCause::Completed)); + assert_eq!(output.step_count, 3); + assert_eq!(continuation_count, 2); + } + + #[tokio::test] + async fn provider_tool_calls_emit_tool_use_decision() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![LlmOutput { + finish_reason: LlmFinishReason::ToolCalls, + tool_calls: vec![astrcode_core::ToolCallRequest { + id: "call-1".to_string(), + name: "readFile".to_string(), + args: serde_json::json!({"path":"README.md"}), + }], + ..LlmOutput::default() + }]), + }); + + let output = TurnLoop.run(input().with_provider(provider)).await; + + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::ToolUseRequested { + tool_call_count: 1, + .. + } + ))); + } + + #[tokio::test] + async fn tool_dispatch_results_continue_back_to_provider() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![ + LlmOutput { + finish_reason: LlmFinishReason::ToolCalls, + tool_calls: vec![astrcode_core::ToolCallRequest { + id: "call-1".to_string(), + name: "readFile".to_string(), + args: serde_json::json!({"path":"README.md"}), + }], + ..LlmOutput::default() + }, + LlmOutput { + content: "done after tool".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }, + ]), + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_tool_dispatcher(Arc::new(EchoToolDispatcher)), + ) + .await; + + assert_eq!(output.step_count, 2); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::ToolCallStarted { + tool_call_id, + tool_name, + .. + } if tool_call_id == "call-1" && tool_name == "readFile" + ))); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::ToolResultReady { + tool_call_id, + ok: true, + .. + } if tool_call_id == "call-1" + ))); + assert!(output.events.iter().any(|event| matches!( + storage_payload(event), + Some(astrcode_core::StorageEventPayload::ToolCall { + tool_call_id, + .. + }) if tool_call_id == "call-1" + ))); + assert!(output.events.iter().any(|event| matches!( + storage_payload(event), + Some(astrcode_core::StorageEventPayload::ToolResult { + tool_call_id, + output, + .. + }) if tool_call_id == "call-1" && output == "tool result" + ))); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::StepContinued { + transition: TurnLoopTransition::ToolCycleCompleted, + .. + } + ))); + } + + #[tokio::test] + async fn aggregate_tool_result_budget_replaces_large_trailing_results_before_request() { + let tempdir = tempfile::tempdir().expect("tempdir should exist"); + let provider = Arc::new(CapturingProvider { + outputs: Mutex::new(vec![LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }]), + requests: Mutex::new(Vec::new()), + limits: ModelLimits { + context_window: 128_000, + max_output_tokens: 8_000, + }, + }); + let runtime = astrcode_core::ResolvedRuntimeConfig { + aggregate_result_bytes_budget: 128, + ..Default::default() + }; + + let output = TurnLoop + .run( + input() + .with_working_dir(tempdir.path()) + .with_runtime_config(runtime) + .with_messages(vec![ + astrcode_core::LlmMessage::Assistant { + content: String::new(), + tool_calls: vec![astrcode_core::ToolCallRequest { + id: "call-large".to_string(), + name: "readFile".to_string(), + args: serde_json::json!({"path":"large.txt"}), + }], + reasoning: None, + }, + astrcode_core::LlmMessage::Tool { + tool_call_id: "call-large".to_string(), + content: "x".repeat(4_096), + }, + ]) + .with_provider(provider.clone()), + ) + .await; + + assert!(output.events.iter().any(|event| matches!( + storage_payload(event), + Some(astrcode_core::StorageEventPayload::ToolResultReferenceApplied { + tool_call_id, + .. + }) if tool_call_id == "call-large" + ))); + let requests = provider.requests.lock().expect("requests should capture"); + assert!(matches!( + &requests[0].messages[1], + astrcode_core::LlmMessage::Tool { content, .. } + if content.contains("") + )); + } + + #[tokio::test] + async fn auto_compact_replaces_history_and_emits_compact_event() { + let provider = Arc::new(CapturingProvider { + outputs: Mutex::new(vec![ + LlmOutput { + content: "okolder work \ + summarizedcontinue current \ + task" + .to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }, + LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }, + ]), + requests: Mutex::new(Vec::new()), + limits: ModelLimits { + context_window: 16_000, + max_output_tokens: 1_024, + }, + }); + let runtime = astrcode_core::ResolvedRuntimeConfig { + compact_threshold_percent: 1, + summary_reserve_tokens: 1, + reserved_context_size: 1, + compact_keep_recent_turns: 1, + compact_keep_recent_user_messages: 1, + ..Default::default() + }; + + let output = TurnLoop + .run( + input() + .with_runtime_config(runtime) + .with_messages(vec![ + astrcode_core::LlmMessage::User { + content: "old request ".repeat(200), + origin: astrcode_core::UserMessageOrigin::User, + }, + astrcode_core::LlmMessage::Assistant { + content: "old answer ".repeat(200), + tool_calls: Vec::new(), + reasoning: None, + }, + astrcode_core::LlmMessage::User { + content: "new request".to_string(), + origin: astrcode_core::UserMessageOrigin::User, + }, + ]) + .with_provider(provider.clone()), + ) + .await; + + assert!(output.events.iter().any(|event| matches!( + storage_payload(event), + Some(astrcode_core::StorageEventPayload::CompactApplied { + summary, + .. + }) if summary.contains("older work summarized") + ))); + let requests = provider.requests.lock().expect("requests should capture"); + assert!(requests.len() >= 2); + assert!(matches!( + &requests[1].messages[0], + astrcode_core::LlmMessage::User { + origin: astrcode_core::UserMessageOrigin::CompactSummary, + .. + } + )); + } + + #[tokio::test] + async fn runtime_hooks_run_in_turn_order() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![LlmOutput { + content: "done".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }]), + }); + let hook_dispatcher = Arc::new(RecordingHookDispatcher { + events: Mutex::new(Vec::new()), + payloads: Mutex::new(Vec::new()), + cancel_before_provider: false, + augment_context: true, + }); + let agent = AgentEventContext::sub_run( + "agent-1", + "parent-turn-1", + "default", + "subrun-1", + None, + SubRunStorageMode::IndependentSession, + Some("child-session-1".to_string().into()), + ); + + let output = TurnLoop + .run( + input() + .with_agent(agent) + .with_provider(provider) + .with_hook_dispatcher(hook_dispatcher.clone()), + ) + .await; + + let events = hook_dispatcher + .events + .lock() + .expect("hook event buffer poisoned") + .clone(); + assert_eq!( + events, + vec![ + HookEventKey::TurnStart, + HookEventKey::Context, + HookEventKey::BeforeAgentStart, + HookEventKey::BeforeProviderRequest, + HookEventKey::TurnEnd, + ] + ); + let payloads = hook_dispatcher + .payloads + .lock() + .expect("hook payload buffer poisoned"); + assert_eq!( + payloads[0]["agent"]["childSessionId"], + serde_json::json!("child-session-1") + ); + assert!(output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::HookPromptAugmented { + event: HookEventKey::Context, + content, + .. + } if content == "extra runtime context" + ))); + } + + #[tokio::test] + async fn hook_cancel_effect_stops_turn_before_provider_request() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![LlmOutput { + content: "should not be used".to_string(), + finish_reason: LlmFinishReason::Stop, + ..LlmOutput::default() + }]), + }); + let hook_dispatcher = Arc::new(RecordingHookDispatcher { + events: Mutex::new(Vec::new()), + payloads: Mutex::new(Vec::new()), + cancel_before_provider: true, + augment_context: false, + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_hook_dispatcher(hook_dispatcher.clone()), + ) + .await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Cancelled)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Cancelled)); + let events = hook_dispatcher + .events + .lock() + .expect("hook event buffer poisoned") + .clone(); + assert_eq!( + events, + vec![ + HookEventKey::TurnStart, + HookEventKey::Context, + HookEventKey::BeforeAgentStart, + HookEventKey::BeforeProviderRequest, + HookEventKey::TurnEnd, + ] + ); + } + + #[tokio::test] + async fn cancelled_token_stops_before_provider_call() { + let cancel = CancelToken::new(); + cancel.cancel(); + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(Vec::new()), + }); + + let output = TurnLoop + .run(input().with_provider(provider).with_cancel(cancel)) + .await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Cancelled)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Cancelled)); + assert!(!output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::ProviderStream { .. } | RuntimeTurnEvent::AssistantFinal { .. } + ))); + } + + #[tokio::test] + async fn cancelled_provider_error_maps_to_cancelled_turn() { + let output = TurnLoop + .run(input().with_provider(Arc::new(CancellingProvider))) + .await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Cancelled)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Cancelled)); + assert!(!output.events.iter().any(|event| matches!( + event, + RuntimeTurnEvent::ProviderStream { .. } | RuntimeTurnEvent::AssistantFinal { .. } + ))); + } + + #[tokio::test] + async fn cancelled_tool_dispatch_maps_to_cancelled_turn() { + let provider = Arc::new(StaticProvider { + outputs: Mutex::new(vec![LlmOutput { + finish_reason: LlmFinishReason::ToolCalls, + tool_calls: vec![astrcode_core::ToolCallRequest { + id: "call-1".to_string(), + name: "readFile".to_string(), + args: serde_json::json!({"path":"README.md"}), + }], + ..LlmOutput::default() + }]), + }); + + let output = TurnLoop + .run( + input() + .with_provider(provider) + .with_tool_dispatcher(Arc::new(CancellingToolDispatcher)), + ) + .await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Cancelled)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Cancelled)); + } +} diff --git a/crates/agent-runtime/src/provider.rs b/crates/agent-runtime/src/provider.rs new file mode 100644 index 00000000..4c86ee4b --- /dev/null +++ b/crates/agent-runtime/src/provider.rs @@ -0,0 +1,189 @@ +use std::sync::Arc; + +use astrcode_core::{ + CancelToken, LlmMessage, ReasoningContent, Result, ToolCallRequest, ToolDefinition, + policy::{ModelRequest, SystemPromptBlock}, +}; +pub use astrcode_core::{ + PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, + PromptLayerFingerprints, +}; +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; + +/// runtime owner 的 provider 能力限制。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct ModelLimits { + pub context_window: usize, + pub max_output_tokens: usize, +} + +/// 模型 token 使用统计。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct LlmUsage { + pub input_tokens: usize, + pub output_tokens: usize, + pub cache_creation_input_tokens: usize, + pub cache_read_input_tokens: usize, +} + +impl LlmUsage { + pub fn total_tokens(self) -> usize { + self.input_tokens.saturating_add(self.output_tokens) + } +} + +/// LLM 输出结束原因。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum LlmFinishReason { + #[default] + Stop, + MaxTokens, + ToolCalls, + Other(String), +} + +impl LlmFinishReason { + pub fn is_max_tokens(&self) -> bool { + matches!(self, Self::MaxTokens) + } + + pub fn from_api_value(value: &str) -> Self { + match value { + "stop" => Self::Stop, + "max_tokens" | "length" => Self::MaxTokens, + "tool_calls" => Self::ToolCalls, + other => Self::Other(other.to_string()), + } + } +} + +/// provider 流式增量事件。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum LlmEvent { + TextDelta(String), + ThinkingDelta(String), + ThinkingSignature(String), + StreamRetryStarted { + attempt: u32, + max_attempts: u32, + reason: String, + }, + ToolCallDelta { + index: usize, + id: Option, + name: Option, + arguments_delta: String, + }, +} + +pub type LlmEventSink = Arc; + +/// 模型调用请求。 +#[derive(Debug, Clone)] +pub struct LlmRequest { + pub messages: Vec, + pub tools: Arc<[ToolDefinition]>, + pub cancel: CancelToken, + pub system_prompt: Option, + pub system_prompt_blocks: Vec, + pub prompt_cache_hints: Option, + pub max_output_tokens_override: Option, + pub skip_cache_write: bool, +} + +impl LlmRequest { + pub fn new( + messages: Vec, + tools: impl Into>, + cancel: CancelToken, + ) -> Self { + Self { + messages, + tools: tools.into(), + cancel, + system_prompt: None, + system_prompt_blocks: Vec::new(), + prompt_cache_hints: None, + max_output_tokens_override: None, + skip_cache_write: false, + } + } + + pub fn with_system(mut self, prompt: impl Into) -> Self { + self.system_prompt = Some(prompt.into()); + self + } + + pub fn with_max_output_tokens_override(mut self, max_output_tokens: usize) -> Self { + self.max_output_tokens_override = Some(max_output_tokens.max(1)); + self + } + + pub fn with_skip_cache_write(mut self, skip_cache_write: bool) -> Self { + self.skip_cache_write = skip_cache_write; + self + } + + pub fn from_model_request(request: ModelRequest, cancel: CancelToken) -> Self { + Self { + messages: request.messages, + tools: request.tools.into(), + cancel, + system_prompt: request.system_prompt, + system_prompt_blocks: request.system_prompt_blocks, + prompt_cache_hints: None, + max_output_tokens_override: None, + skip_cache_write: false, + } + } +} + +/// 模型调用输出。 +#[derive(Debug, Clone, Default)] +pub struct LlmOutput { + pub content: String, + pub tool_calls: Vec, + pub reasoning: Option, + pub usage: Option, + pub finish_reason: LlmFinishReason, + pub prompt_cache_diagnostics: Option, +} + +/// agent-runtime 消费的抽象 provider stream surface。 +#[async_trait] +pub trait LlmProvider: Send + Sync { + async fn generate(&self, request: LlmRequest, sink: Option) -> Result; + fn model_limits(&self) -> ModelLimits; + fn supports_cache_metrics(&self) -> bool { + false + } +} + +#[cfg(test)] +mod tests { + use super::{LlmFinishReason, LlmUsage}; + + #[test] + fn usage_total_saturates() { + let usage = LlmUsage { + input_tokens: usize::MAX, + output_tokens: 1, + cache_creation_input_tokens: 0, + cache_read_input_tokens: 0, + }; + + assert_eq!(usage.total_tokens(), usize::MAX); + } + + #[test] + fn finish_reason_accepts_openai_family_values() { + assert!(LlmFinishReason::from_api_value("length").is_max_tokens()); + assert_eq!( + LlmFinishReason::from_api_value("tool_calls"), + LlmFinishReason::ToolCalls + ); + } +} diff --git a/crates/agent-runtime/src/runtime.rs b/crates/agent-runtime/src/runtime.rs new file mode 100644 index 00000000..71f75cd2 --- /dev/null +++ b/crates/agent-runtime/src/runtime.rs @@ -0,0 +1,46 @@ +use crate::{ + r#loop::TurnLoop, + types::{TurnInput, TurnOutput}, +}; + +/// 最小执行入口。 +#[derive(Debug, Default)] +pub struct AgentRuntime; + +impl AgentRuntime { + pub fn new() -> Self { + Self + } + + pub async fn execute_turn(&self, input: TurnInput) -> TurnOutput { + TurnLoop.run(input).await + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::TurnTerminalKind; + + use super::AgentRuntime; + use crate::types::{AgentRuntimeExecutionSurface, TurnInput, TurnStopCause}; + + #[tokio::test] + async fn execute_turn_drives_empty_lifecycle() { + let input = TurnInput::new(AgentRuntimeExecutionSurface { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-1".to_string(), + model_ref: "model-a".to_string(), + provider_ref: "provider-a".to_string(), + tool_specs: Vec::new(), + hook_snapshot_id: "snapshot-1".to_string(), + }); + + let output = AgentRuntime::new().execute_turn(input).await; + + assert_eq!(output.stop_cause, Some(TurnStopCause::Completed)); + assert_eq!(output.terminal_kind, Some(TurnTerminalKind::Completed)); + assert_eq!(output.step_count, 1); + assert_eq!(output.events.len(), 2); + } +} diff --git a/crates/agent-runtime/src/stream.rs b/crates/agent-runtime/src/stream.rs new file mode 100644 index 00000000..eee95038 --- /dev/null +++ b/crates/agent-runtime/src/stream.rs @@ -0,0 +1,3 @@ +/// provider 流式处理骨架。 +#[derive(Debug, Default)] +pub struct ProviderStream; diff --git a/crates/agent-runtime/src/tool_dispatch.rs b/crates/agent-runtime/src/tool_dispatch.rs new file mode 100644 index 00000000..6e2dcdf8 --- /dev/null +++ b/crates/agent-runtime/src/tool_dispatch.rs @@ -0,0 +1,22 @@ +use astrcode_core::{Result, ToolCallRequest, ToolExecutionResult, ToolOutputDelta}; +use async_trait::async_trait; +use tokio::sync::mpsc::UnboundedSender; + +/// `agent-runtime -> plugin-host` 的工具调度请求。 +#[derive(Debug, Clone)] +pub struct ToolDispatchRequest { + pub session_id: String, + pub turn_id: String, + pub agent_id: String, + pub tool_call: ToolCallRequest, + pub tool_output_sender: Option>, +} + +/// runtime 消费的抽象工具调度面。 +/// +/// 真实工具归属 plugin-host active snapshot；runtime 只提交一次工具调用并接收 +/// 纯数据结果，不持有 plugin registry 或具体 invoker。 +#[async_trait] +pub trait ToolDispatcher: Send + Sync { + async fn dispatch_tool(&self, request: ToolDispatchRequest) -> Result; +} diff --git a/crates/agent-runtime/src/types.rs b/crates/agent-runtime/src/types.rs new file mode 100644 index 00000000..15b36fc3 --- /dev/null +++ b/crates/agent-runtime/src/types.rs @@ -0,0 +1,446 @@ +use std::{fmt, path::PathBuf, sync::Arc}; + +use astrcode_core::{ + AgentEventContext, AstrError, CancelToken, CapabilitySpec, LlmMessage, ReasoningContent, + ResolvedRuntimeConfig, StorageEvent, TurnTerminalKind, +}; +use chrono::{DateTime, Utc}; + +use crate::{ + context_window::tool_result_budget::ToolResultReplacementRecord, + hook_dispatch::HookDispatcher, + provider::{LlmEvent, LlmProvider}, + tool_dispatch::ToolDispatcher, +}; + +/// `host-session -> agent-runtime` 的最小执行面骨架。 +#[derive(Debug, Clone, Default, PartialEq)] +pub struct AgentRuntimeExecutionSurface { + pub session_id: String, + pub turn_id: String, + pub agent_id: String, + pub model_ref: String, + pub provider_ref: String, + pub tool_specs: Vec, + pub hook_snapshot_id: String, +} + +/// runtime 事件发射回调。 +/// +/// `agent-runtime` 只通过这个回调把 turn 生命周期事件交还给宿主，不持有 +/// EventStore、SessionState 或 plugin registry。 +pub trait RuntimeEventSink: Send + Sync { + fn emit_event(&self, event: RuntimeTurnEvent); +} + +impl RuntimeEventSink for F +where + F: Fn(RuntimeTurnEvent) + Send + Sync, +{ + fn emit_event(&self, event: RuntimeTurnEvent) { + self(event); + } +} + +#[derive(Clone, Default)] +pub struct TurnInput { + pub surface: AgentRuntimeExecutionSurface, + /// Stable event metadata supplied by host-session. + /// + /// The runtime forwards this context to hook/tool execution surfaces, but it + /// must not derive collaboration truth, parent/child linkage, or input queue + /// state from it. + pub agent: AgentEventContext, + pub messages: Vec, + pub provider: Option>, + pub tool_dispatcher: Option>, + pub hook_dispatcher: Option>, + pub cancel: CancelToken, + pub event_sink: Option>, + pub max_output_continuations: usize, + pub working_dir: PathBuf, + pub runtime_config: ResolvedRuntimeConfig, + pub last_assistant_at: Option>, + pub previous_tool_result_replacements: Vec, + /// 事件历史 JSONL 文件路径（如 `{project_dir}/sessions/{session_id}/events.jsonl`）。 + /// + /// 由宿主提供，`agent-runtime` 自身不构造路径。`None` 表示不保存 compact 历史。 + pub events_history_path: Option, +} + +impl fmt::Debug for TurnInput { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("TurnInput") + .field("surface", &self.surface) + .field("agent", &self.agent) + .field("messages", &self.messages) + .field( + "provider", + &self.provider.as_ref().map(|_| ""), + ) + .field( + "tool_dispatcher", + &self.tool_dispatcher.as_ref().map(|_| ""), + ) + .field( + "hook_dispatcher", + &self.hook_dispatcher.as_ref().map(|_| ""), + ) + .field("cancel", &self.cancel) + .field( + "event_sink", + &self.event_sink.as_ref().map(|_| ""), + ) + .field("max_output_continuations", &self.max_output_continuations) + .field("working_dir", &self.working_dir) + .field("runtime_config", &self.runtime_config) + .field("last_assistant_at", &self.last_assistant_at) + .field( + "previous_tool_result_replacements", + &self.previous_tool_result_replacements, + ) + .field("events_history_path", &self.events_history_path) + .finish() + } +} + +impl TurnInput { + pub fn new(surface: AgentRuntimeExecutionSurface) -> Self { + Self { + surface, + agent: AgentEventContext::default(), + messages: Vec::new(), + provider: None, + tool_dispatcher: None, + hook_dispatcher: None, + cancel: CancelToken::new(), + event_sink: None, + max_output_continuations: 0, + working_dir: PathBuf::new(), + runtime_config: ResolvedRuntimeConfig::default(), + last_assistant_at: None, + previous_tool_result_replacements: Vec::new(), + events_history_path: None, + } + } + + pub fn with_messages(mut self, messages: Vec) -> Self { + self.messages = messages; + self + } + + pub fn with_agent(mut self, agent: AgentEventContext) -> Self { + self.agent = agent; + self + } + + pub fn with_provider(mut self, provider: Arc) -> Self { + self.provider = Some(provider); + self + } + + pub fn with_tool_dispatcher(mut self, tool_dispatcher: Arc) -> Self { + self.tool_dispatcher = Some(tool_dispatcher); + self + } + + pub fn with_hook_dispatcher(mut self, hook_dispatcher: Arc) -> Self { + self.hook_dispatcher = Some(hook_dispatcher); + self + } + + pub fn with_cancel(mut self, cancel: CancelToken) -> Self { + self.cancel = cancel; + self + } + + pub fn with_event_sink(mut self, event_sink: Arc) -> Self { + self.event_sink = Some(event_sink); + self + } + + pub fn with_max_output_continuations(mut self, max_output_continuations: usize) -> Self { + self.max_output_continuations = max_output_continuations; + self + } + + pub fn with_working_dir(mut self, working_dir: impl Into) -> Self { + self.working_dir = working_dir.into(); + self + } + + pub fn with_runtime_config(mut self, runtime_config: ResolvedRuntimeConfig) -> Self { + self.runtime_config = runtime_config; + self + } + + pub fn with_last_assistant_at(mut self, last_assistant_at: Option>) -> Self { + self.last_assistant_at = last_assistant_at; + self + } + + pub fn with_previous_tool_result_replacements( + mut self, + replacements: Vec, + ) -> Self { + self.previous_tool_result_replacements = replacements; + self + } + + pub fn with_events_history_path(mut self, path: Option) -> Self { + self.events_history_path = path; + self + } +} + +/// 内部 loop 的“继续下一轮”原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum TurnLoopTransition { + ToolCycleCompleted, + ReactiveCompactRecovered, + OutputContinuationRequested, +} + +/// turn 停止的细粒度原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum TurnStopCause { + Completed, + Cancelled, + Error, +} + +impl TurnStopCause { + pub fn terminal_kind(self, error_message: Option<&str>) -> TurnTerminalKind { + match self { + Self::Completed => TurnTerminalKind::Completed, + Self::Cancelled => TurnTerminalKind::Cancelled, + Self::Error => TurnTerminalKind::Error { + message: error_message.unwrap_or("turn failed").to_string(), + }, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct TurnIdentity { + pub session_id: String, + pub turn_id: String, + pub agent_id: String, +} + +impl TurnIdentity { + pub fn new(session_id: String, turn_id: String, agent_id: String) -> Self { + Self { + session_id, + turn_id, + agent_id, + } + } +} + +/// 单步执行中产生的错误，保留可重试/致命区分。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct StepError { + pub message: String, + pub kind: StepErrorKind, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum StepErrorKind { + Fatal, + Retryable, +} + +impl StepError { + pub fn fatal(message: impl Into) -> Self { + Self { + message: message.into(), + kind: StepErrorKind::Fatal, + } + } + + pub fn retryable(message: impl Into) -> Self { + Self { + message: message.into(), + kind: StepErrorKind::Retryable, + } + } +} + +impl From<&AstrError> for StepError { + fn from(error: &AstrError) -> Self { + Self { + message: error.to_string(), + kind: if error.is_retryable() { + StepErrorKind::Retryable + } else { + StepErrorKind::Fatal + }, + } + } +} + +#[derive(Debug, Clone)] +pub enum RuntimeTurnEvent { + TurnStarted { + identity: TurnIdentity, + }, + ProviderStream { + identity: TurnIdentity, + event: LlmEvent, + }, + AssistantFinal { + identity: TurnIdentity, + content: String, + reasoning: Option, + tool_call_count: usize, + }, + ToolUseRequested { + identity: TurnIdentity, + tool_call_count: usize, + }, + ToolCallStarted { + identity: TurnIdentity, + tool_call_id: String, + tool_name: String, + }, + ToolResultReady { + identity: TurnIdentity, + tool_call_id: String, + tool_name: String, + ok: bool, + }, + HookDispatched { + identity: TurnIdentity, + event: astrcode_core::HookEventKey, + effect_count: usize, + }, + HookPromptAugmented { + identity: TurnIdentity, + event: astrcode_core::HookEventKey, + content: String, + }, + StorageEvent { + event: Box, + }, + StepContinued { + identity: TurnIdentity, + step_index: usize, + transition: TurnLoopTransition, + }, + TurnCompleted { + identity: TurnIdentity, + stop_cause: TurnStopCause, + terminal_kind: TurnTerminalKind, + }, + TurnErrored { + identity: TurnIdentity, + message: String, + }, +} + +#[derive(Debug, Clone, Default)] +pub struct TurnOutput { + pub identity: TurnIdentity, + pub terminal_kind: Option, + pub stop_cause: Option, + pub step_count: usize, + pub events: Vec, + pub error_message: Option, +} + +impl TurnOutput { + pub fn empty_for(input: TurnInput) -> Self { + let identity = TurnIdentity::new( + input.surface.session_id, + input.surface.turn_id, + input.surface.agent_id, + ); + Self { + identity, + terminal_kind: None, + stop_cause: None, + step_count: 0, + events: Vec::new(), + error_message: None, + } + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{AgentEventContext, SubRunStorageMode, TurnTerminalKind}; + + use super::{AgentRuntimeExecutionSurface, TurnInput, TurnOutput, TurnStopCause}; + + #[test] + fn empty_output_keeps_turn_identity() { + let input = TurnInput::new(AgentRuntimeExecutionSurface { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-1".to_string(), + model_ref: "model-a".to_string(), + provider_ref: "provider-a".to_string(), + tool_specs: Vec::new(), + hook_snapshot_id: "snapshot-1".to_string(), + }); + + let output = TurnOutput::empty_for(input); + + assert_eq!(output.identity.session_id, "session-1"); + assert_eq!(output.identity.turn_id, "turn-1"); + assert_eq!(output.identity.agent_id, "agent-1"); + } + + #[test] + fn turn_input_carries_agent_event_context_without_collaboration_state() { + let agent = AgentEventContext::sub_run( + "agent-child", + "parent-turn", + "default", + "subrun-1", + None, + SubRunStorageMode::IndependentSession, + Some("child-session-1".to_string().into()), + ); + let input = TurnInput::new(AgentRuntimeExecutionSurface { + session_id: "child-session-1".to_string(), + turn_id: "child-turn-1".to_string(), + agent_id: "agent-child".to_string(), + model_ref: "model-a".to_string(), + provider_ref: "provider-a".to_string(), + tool_specs: Vec::new(), + hook_snapshot_id: "snapshot-1".to_string(), + }) + .with_agent(agent.clone()); + + assert_eq!(input.agent, agent); + assert!(input.agent.is_independent_sub_run()); + assert!(input.agent.belongs_to_child_session("child-session-1")); + } + + #[test] + fn stop_cause_maps_terminal_kind() { + assert_eq!( + TurnStopCause::Completed.terminal_kind(None), + TurnTerminalKind::Completed + ); + assert_eq!( + TurnStopCause::Cancelled.terminal_kind(None), + TurnTerminalKind::Cancelled + ); + assert_eq!( + TurnStopCause::Error.terminal_kind(Some("boom")), + TurnTerminalKind::Error { + message: "boom".to_string() + } + ); + assert_eq!( + TurnStopCause::Error.terminal_kind(None), + TurnTerminalKind::Error { + message: "turn failed".to_string() + } + ); + } +} diff --git a/crates/application/src/agent_use_cases.rs b/crates/application/src/agent_use_cases.rs deleted file mode 100644 index 1250f582..00000000 --- a/crates/application/src/agent_use_cases.rs +++ /dev/null @@ -1,259 +0,0 @@ -//! Agent 控制用例（`App` 的 agent 相关方法）。 -//! -//! 通过 kernel 的稳定控制合同实现 agent 状态查询、子运行生命周期管理等用例。 - -use astrcode_core::{AgentLifecycleStatus, ResolvedExecutionLimitsSnapshot, SubRunStorageMode}; -use astrcode_kernel::SubRunStatusView; - -use crate::{ - AgentExecuteSummary, App, ApplicationError, RootExecutionRequest, SubRunStatusSourceSummary, - SubRunStatusSummary, -}; - -impl App { - // ── Agent 控制用例（通过 kernel 稳定控制合同） ────────── - - /// 查询子运行状态。 - pub async fn get_subrun_status( - &self, - agent_id: &str, - ) -> Result, ApplicationError> { - self.validate_non_empty("agentId", agent_id)?; - Ok(self.kernel.query_subrun_status(agent_id).await) - } - - /// 查询指定 session 的根 agent 状态。 - pub async fn get_root_agent_status( - &self, - session_id: &str, - ) -> Result, ApplicationError> { - self.validate_non_empty("sessionId", session_id)?; - Ok(self.kernel.query_root_status(session_id).await) - } - - /// 列出所有 agent 状态。 - pub async fn list_agent_statuses(&self) -> Vec { - self.kernel.list_statuses().await - } - - /// 执行 root agent 并返回共享摘要输入。 - pub async fn execute_root_agent_summary( - &self, - request: RootExecutionRequest, - ) -> Result { - let accepted = self.execute_root_agent(request).await?; - let session_id = accepted.session_id.to_string(); - Ok(AgentExecuteSummary { - accepted: true, - message: format!( - "agent '{}' execution accepted; subscribe to \ - /api/v1/conversation/sessions/{}/stream for progress", - accepted.agent_id.as_deref().unwrap_or("unknown-agent"), - session_id - ), - session_id: Some(session_id), - turn_id: Some(accepted.turn_id.to_string()), - agent_id: accepted.agent_id.map(|value| value.to_string()), - }) - } - - /// 查询指定 session/sub-run 的共享状态摘要。 - /// - /// 查找策略（按优先级）： - /// 1. Live 状态：从 kernel 获取 sub-run 或 root agent 的实时状态 - /// 2. Durable 状态：从 session-runtime 的只读投影读取 child session 终态 - /// 3. 都找不到：返回默认的 Idle 状态摘要 - pub async fn get_subrun_status_summary( - &self, - session_id: &str, - requested_subrun_id: &str, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - self.validate_non_empty("subRunId", requested_subrun_id)?; - - if let Some(view) = self.get_subrun_status(requested_subrun_id).await? { - return Ok(summarize_live_subrun_status(view, session_id.to_string())); - } - - if let Some(view) = self.get_root_agent_status(session_id).await? { - if view.sub_run_id == requested_subrun_id { - return Ok(summarize_live_subrun_status(view, session_id.to_string())); - } - return Err(ApplicationError::NotFound(format!( - "subrun '{}' not found in session '{}'", - requested_subrun_id, session_id - ))); - } - - if let Some(summary) = self - .durable_subrun_status_summary(session_id, requested_subrun_id) - .await? - { - return Ok(summary); - } - - Ok(default_subrun_status_summary( - session_id.to_string(), - requested_subrun_id.to_string(), - )) - } - - /// 从 session-runtime 的 durable query 读取子运行状态。 - async fn durable_subrun_status_summary( - &self, - parent_session_id: &str, - requested_subrun_id: &str, - ) -> Result, ApplicationError> { - Ok(self - .session_runtime - .durable_subrun_status_snapshot(parent_session_id, requested_subrun_id) - .await? - .map(summarize_durable_subrun_status)) - } - - /// 关闭 agent 及其子树。 - pub async fn close_agent( - &self, - session_id: &str, - agent_id: &str, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - self.validate_non_empty("agentId", agent_id)?; - let Some(handle) = self.kernel.get_handle(agent_id).await else { - return Err(ApplicationError::NotFound(format!( - "agent '{}' not found", - agent_id - ))); - }; - if handle.session_id.as_str() != session_id { - return Err(ApplicationError::NotFound(format!( - "agent '{}' not found in session '{}'", - agent_id, session_id - ))); - } - self.kernel - .close_subtree(agent_id) - .await - .map_err(|error| ApplicationError::Internal(error.to_string())) - } -} - -fn summarize_live_subrun_status(view: SubRunStatusView, session_id: String) -> SubRunStatusSummary { - SubRunStatusSummary { - sub_run_id: view.sub_run_id, - tool_call_id: None, - source: SubRunStatusSourceSummary::Live, - agent_id: view.agent_id, - agent_profile: view.agent_profile, - session_id, - child_session_id: view.child_session_id, - depth: view.depth, - parent_agent_id: view.parent_agent_id, - parent_sub_run_id: None, - storage_mode: SubRunStorageMode::IndependentSession, - lifecycle: view.lifecycle, - last_turn_outcome: view.last_turn_outcome, - result: None, - step_count: None, - estimated_tokens: None, - resolved_overrides: None, - resolved_limits: Some(view.resolved_limits), - } -} - -fn default_subrun_status_summary(session_id: String, sub_run_id: String) -> SubRunStatusSummary { - SubRunStatusSummary { - sub_run_id, - tool_call_id: None, - source: SubRunStatusSourceSummary::Live, - agent_id: "root-agent".to_string(), - agent_profile: "default".to_string(), - session_id, - child_session_id: None, - depth: 0, - parent_agent_id: None, - parent_sub_run_id: None, - storage_mode: SubRunStorageMode::IndependentSession, - lifecycle: AgentLifecycleStatus::Idle, - last_turn_outcome: None, - result: None, - step_count: None, - estimated_tokens: None, - resolved_overrides: None, - resolved_limits: Some(ResolvedExecutionLimitsSnapshot), - } -} - -fn summarize_durable_subrun_status( - snapshot: astrcode_session_runtime::SubRunStatusSnapshot, -) -> SubRunStatusSummary { - let handle = snapshot.handle; - SubRunStatusSummary { - sub_run_id: handle.sub_run_id.to_string(), - tool_call_id: snapshot.tool_call_id, - source: SubRunStatusSourceSummary::Durable, - agent_id: handle.agent_id.to_string(), - agent_profile: handle.agent_profile, - session_id: handle.session_id.to_string(), - child_session_id: handle.child_session_id.map(|id| id.to_string()), - depth: handle.depth, - parent_agent_id: handle.parent_agent_id.map(|id| id.to_string()), - parent_sub_run_id: handle.parent_sub_run_id.map(|id| id.to_string()), - storage_mode: handle.storage_mode, - lifecycle: handle.lifecycle, - last_turn_outcome: handle.last_turn_outcome, - result: snapshot.result, - step_count: snapshot.step_count, - estimated_tokens: snapshot.estimated_tokens, - resolved_overrides: snapshot.resolved_overrides, - resolved_limits: Some(handle.resolved_limits), - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentLifecycleStatus, AgentTurnOutcome, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, SubRunHandle, SubRunStorageMode, - }; - use astrcode_session_runtime::{SubRunStatusSnapshot, SubRunStatusSource}; - - use super::summarize_durable_subrun_status; - use crate::SubRunStatusSourceSummary; - - #[test] - fn summarize_durable_subrun_status_reuses_runtime_projection() { - let summary = summarize_durable_subrun_status(SubRunStatusSnapshot { - handle: SubRunHandle { - sub_run_id: "subrun-child".into(), - agent_id: "agent-child".into(), - session_id: "session-parent".into(), - child_session_id: Some("session-child".into()), - depth: 1, - parent_turn_id: "turn-parent".into(), - parent_agent_id: None, - parent_sub_run_id: Some("subrun-parent".into()), - lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, - agent_profile: "reviewer".to_string(), - storage_mode: SubRunStorageMode::IndependentSession, - lifecycle: AgentLifecycleStatus::Idle, - last_turn_outcome: Some(AgentTurnOutcome::Completed), - resolved_limits: ResolvedExecutionLimitsSnapshot, - delegation: None, - }, - tool_call_id: Some("call-1".to_string()), - source: SubRunStatusSource::Durable, - result: None, - step_count: Some(5), - estimated_tokens: Some(2048), - resolved_overrides: Some(ResolvedSubagentContextOverrides::default()), - }); - - assert_eq!(summary.source, SubRunStatusSourceSummary::Durable); - assert_eq!(summary.session_id, "session-parent"); - assert_eq!(summary.child_session_id.as_deref(), Some("session-child")); - assert_eq!(summary.tool_call_id.as_deref(), Some("call-1")); - assert_eq!(summary.last_turn_outcome, Some(AgentTurnOutcome::Completed)); - assert_eq!(summary.step_count, Some(5)); - } -} diff --git a/crates/application/src/composer/mod.rs b/crates/application/src/composer/mod.rs deleted file mode 100644 index 78256141..00000000 --- a/crates/application/src/composer/mod.rs +++ /dev/null @@ -1,181 +0,0 @@ -//! Composer 输入补全用例。 -//! -//! 提供 composer 输入候选列表的查询和过滤用例。 -//! 候选来源包括：命令、技能、能力（通过 `KernelGateway` 查询）。 - -pub use astrcode_core::{ComposerOption, ComposerOptionActionKind, ComposerOptionKind}; -use astrcode_kernel::KernelGateway; - -// ============================================================ -// 业务模型 -// ============================================================ - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ComposerOptionsRequest { - pub query: Option, - pub kinds: Vec, - pub limit: usize, -} - -impl Default for ComposerOptionsRequest { - fn default() -> Self { - Self { - query: None, - kinds: Vec::new(), - limit: 50, - } - } -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ComposerSkillSummary { - pub id: String, - pub description: String, -} - -impl ComposerSkillSummary { - pub fn new(id: impl Into, description: impl Into) -> Self { - Self { - id: id.into(), - description: description.into(), - } - } -} - -// ============================================================ -// Composer 用例服务 -// ============================================================ - -/// Composer 输入补全用例服务。 -pub struct ComposerService { - builtin_commands: Vec, -} - -impl Default for ComposerService { - fn default() -> Self { - Self::new() - } -} - -impl ComposerService { - pub fn new() -> Self { - Self { - builtin_commands: vec![ComposerOption { - kind: ComposerOptionKind::Command, - id: "compact".to_string(), - title: "压缩上下文".to_string(), - description: "压缩当前会话上下文".to_string(), - insert_text: "/compact".to_string(), - action_kind: ComposerOptionActionKind::ExecuteCommand, - action_value: "/compact".to_string(), - badges: vec!["built-in".to_string()], - keywords: vec!["compact".to_string(), "compress".to_string()], - }], - } - } - - /// 用例：列出可用的 composer 选项。 - /// - /// 合并内置命令和通过 kernel gateway 查询到的能力选项， - /// 然后按 kind 和 query 过滤。 - pub fn list_options( - &self, - request: ComposerOptionsRequest, - skill_summaries: Vec, - gateway: Option<&KernelGateway>, - ) -> Vec { - let mut items = self.builtin_commands.clone(); - items.extend(skill_summaries.into_iter().map(skill_summary_to_option)); - - if let Some(gateway) = gateway { - for spec in gateway.capabilities().capability_specs() { - let name_str = spec.name.to_string(); - items.push(ComposerOption { - kind: ComposerOptionKind::Capability, - id: name_str.clone(), - title: name_str.clone(), - description: spec.description.clone(), - insert_text: name_str.clone(), - action_kind: ComposerOptionActionKind::InsertText, - action_value: name_str.clone(), - badges: vec!["capability".to_string()], - keywords: vec![name_str.to_lowercase()], - }); - } - } - - if !request.kinds.is_empty() { - items.retain(|item| request.kinds.contains(&item.kind)); - } - - if let Some(query) = request.query { - let query = query.to_lowercase(); - items.retain(|item| { - item.id.to_lowercase().contains(&query) - || item.title.to_lowercase().contains(&query) - || item.description.to_lowercase().contains(&query) - || item - .keywords - .iter() - .any(|kw| kw.to_lowercase().contains(&query)) - }); - } - - items.truncate(request.limit); - items - } -} - -fn skill_summary_to_option(skill: ComposerSkillSummary) -> ComposerOption { - let keywords = skill - .id - .split('-') - .filter(|segment| !segment.is_empty()) - .map(str::to_string) - .collect::>(); - ComposerOption { - kind: ComposerOptionKind::Skill, - title: humanize_skill_title(&skill.id), - insert_text: format!("/{}", skill.id), - action_kind: ComposerOptionActionKind::InsertText, - action_value: format!("/{}", skill.id), - badges: vec!["skill".to_string()], - keywords, - id: skill.id, - description: skill.description, - } -} - -fn humanize_skill_title(skill_id: &str) -> String { - let words = skill_id - .split('-') - .filter(|segment| !segment.is_empty()) - .map(title_case_token) - .collect::>(); - if words.is_empty() { - skill_id.to_string() - } else { - words.join(" ") - } -} - -fn title_case_token(token: &str) -> String { - let mut chars = token.chars(); - let Some(first) = chars.next() else { - return String::new(); - }; - let rest = chars.collect::(); - if first.is_ascii_alphabetic() { - format!("{}{}", first.to_ascii_uppercase(), rest) - } else { - format!("{first}{rest}") - } -} - -impl std::fmt::Debug for ComposerService { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("ComposerService") - .field("builtin_commands", &self.builtin_commands.len()) - .finish() - } -} diff --git a/crates/application/src/execution/root.rs b/crates/application/src/execution/root.rs deleted file mode 100644 index ee272d45..00000000 --- a/crates/application/src/execution/root.rs +++ /dev/null @@ -1,293 +0,0 @@ -//! 根代理执行入口。 -//! -//! 实现 `execute_root_agent`：参数校验 → profile 解析 → session 创建 → agent 注册到 -//! 控制树 → 异步提交 prompt。 -//! -//! `application` 只做编排，不持有 session 真相或 turn 执行细节。 - -use std::{path::Path, sync::Arc}; - -use astrcode_core::{ - AgentMode, ExecutionAccepted, ModeId, ResolvedRuntimeConfig, SubagentContextOverrides, -}; - -use crate::{ - AppKernelPort, AppSessionPort, - agent::root_execution_event_context, - errors::ApplicationError, - execution::{ - ExecutionControl, ProfileResolutionService, ensure_profile_mode, merge_task_with_context, - }, - governance_surface::{GovernanceSurfaceAssembler, RootGovernanceInput}, -}; - -/// 根代理执行请求。 -pub struct RootExecutionRequest { - pub agent_id: String, - pub working_dir: String, - pub task: String, - pub context: Option, - pub control: Option, - pub context_overrides: Option, -} - -/// 执行根代理。 -/// -/// 完整流程： -/// 1. 参数校验 -/// 2. 解析 root profile 并校验 mode -/// 3. 创建 session -/// 4. 注册根 agent 到控制树 -/// 5. 合并 task + context -/// 6. 异步提交 prompt -pub async fn execute_root_agent( - kernel: &dyn AppKernelPort, - session_runtime: &dyn AppSessionPort, - profiles: &Arc, - governance: &GovernanceSurfaceAssembler, - request: RootExecutionRequest, - runtime_config: ResolvedRuntimeConfig, -) -> Result { - validate_root_request(&request)?; - validate_root_context_overrides_supported(request.context_overrides.as_ref())?; - - let profile = profiles.find_profile(Path::new(&request.working_dir), &request.agent_id)?; - ensure_root_profile_mode(&profile)?; - let profile_id = profile.id.clone(); - - let session = session_runtime - .create_session(request.working_dir.clone()) - .await - .map_err(ApplicationError::from)?; - - let handle = kernel - .register_root_agent( - request.agent_id.clone(), - session.session_id.clone(), - profile_id.clone(), - ) - .await - .map_err(|e| ApplicationError::Internal(format!("failed to register root agent: {e}")))?; - let surface = governance.root_surface( - kernel, - RootGovernanceInput { - session_id: session.session_id.clone(), - turn_id: astrcode_core::generate_turn_id(), - working_dir: request.working_dir.clone(), - profile: profile_id.clone(), - mode_id: ModeId::default(), - runtime: runtime_config, - control: request.control.clone(), - }, - )?; - let resolved_limits = surface.resolved_limits.clone(); - if kernel - .set_resolved_limits(&handle.agent_id, resolved_limits.clone()) - .await - .is_none() - { - return Err(ApplicationError::Internal(format!( - "failed to persist resolved limits for root agent '{}' because the control handle \ - disappeared before the limits snapshot was recorded", - handle.agent_id - ))); - } - let mut handle = handle; - handle.resolved_limits = resolved_limits; - - let merged_task = merge_task_with_context(&request.task, request.context.as_deref()); - - let mut accepted = session_runtime - .submit_prompt_for_agent( - &session.session_id, - merged_task, - surface.runtime.clone(), - surface.into_submission( - root_execution_event_context(handle.agent_id.clone(), profile_id), - None, - ), - ) - .await - .map_err(ApplicationError::from)?; - accepted.agent_id = Some(request.agent_id.into()); - Ok(accepted) -} - -fn validate_root_request(request: &RootExecutionRequest) -> Result<(), ApplicationError> { - if request.agent_id.trim().is_empty() { - return Err(ApplicationError::InvalidArgument( - "field 'agentId' must not be empty".to_string(), - )); - } - if request.working_dir.trim().is_empty() { - return Err(ApplicationError::InvalidArgument( - "field 'workingDir' must not be empty".to_string(), - )); - } - if request.task.trim().is_empty() { - return Err(ApplicationError::InvalidArgument( - "field 'task' must not be empty".to_string(), - )); - } - if let Some(control) = &request.control { - control.validate()?; - if control.manual_compact.is_some() { - return Err(ApplicationError::InvalidArgument( - "manualCompact is not valid for root execution".to_string(), - )); - } - } - Ok(()) -} - -/// 校验根执行请求不支持 context overrides。 -/// -/// 根执行没有"父上下文"可继承，任何显式 overrides 都不会真正改变执行输入。 -/// 宁可明确拒绝，也不要伪装成"已接受但生效未知"。 -fn validate_root_context_overrides_supported( - overrides: Option<&SubagentContextOverrides>, -) -> Result<(), ApplicationError> { - let Some(overrides) = overrides else { - return Ok(()); - }; - - // 根执行当前没有“父上下文”可继承，任何显式 overrides 都不会真正改变执行输入。 - // 这里宁可明确拒绝，也不要把请求伪装成“已接受但生效未知”。 - if overrides != &SubagentContextOverrides::default() { - return Err(ApplicationError::InvalidArgument( - "contextOverrides is not supported yet for root execution".to_string(), - )); - } - - Ok(()) -} - -fn ensure_root_profile_mode(profile: &astrcode_core::AgentProfile) -> Result<(), ApplicationError> { - ensure_profile_mode( - profile, - &[AgentMode::Primary, AgentMode::All], - "root execution", - ) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn valid_request() -> RootExecutionRequest { - RootExecutionRequest { - agent_id: "root-agent".to_string(), - working_dir: "/tmp/project".to_string(), - task: "do something".to_string(), - context: None, - control: None, - context_overrides: None, - } - } - - #[test] - fn validate_accepts_valid_request() { - assert!(validate_root_request(&valid_request()).is_ok()); - } - - #[test] - fn validate_rejects_empty_agent_id() { - let mut req = valid_request(); - req.agent_id = " ".to_string(); - let err = validate_root_request(&req).unwrap_err(); - assert!( - err.to_string().contains("agentId"), - "should mention agentId: {err}" - ); - } - - #[test] - fn validate_rejects_empty_working_dir() { - let mut req = valid_request(); - req.working_dir = String::new(); - let err = validate_root_request(&req).unwrap_err(); - assert!( - err.to_string().contains("workingDir"), - "should mention workingDir: {err}" - ); - } - - #[test] - fn validate_rejects_empty_task() { - let mut req = valid_request(); - req.task = " ".to_string(); - let err = validate_root_request(&req).unwrap_err(); - assert!( - err.to_string().contains("task"), - "should mention task: {err}" - ); - } - - #[test] - fn validate_accepts_context_but_uses_empty_as_none() { - let req = RootExecutionRequest { - agent_id: "agent".to_string(), - working_dir: "/tmp".to_string(), - task: "task".to_string(), - context: Some("".to_string()), - control: None, - context_overrides: None, - }; - assert!(validate_root_request(&req).is_ok()); - } - - #[test] - fn validate_rejects_manual_compact_control() { - let mut req = valid_request(); - req.control = Some(ExecutionControl { - manual_compact: Some(true), - }); - - let err = validate_root_request(&req).unwrap_err(); - assert!(err.to_string().contains("manualCompact")); - } - - #[test] - fn merge_context_and_task() { - let merged = merge_task_with_context("main task", Some("background info")); - assert_eq!(merged, "background info\n\nmain task"); - } - - #[test] - fn merge_skips_empty_context() { - let merged = merge_task_with_context("main task", Some(" ")); - assert_eq!(merged, "main task"); - } - - #[test] - fn validate_root_context_overrides_accepts_empty_overrides() { - validate_root_context_overrides_supported(Some(&SubagentContextOverrides::default())) - .expect("empty overrides should pass"); - } - - #[test] - fn validate_root_context_overrides_rejects_non_empty_override() { - let error = validate_root_context_overrides_supported(Some(&SubagentContextOverrides { - include_compact_summary: Some(true), - ..SubagentContextOverrides::default() - })) - .expect_err("non-empty overrides should fail"); - - assert!(error.to_string().contains("contextOverrides")); - } - - #[test] - fn root_execution_rejects_subagent_only_profile() { - let err = ensure_root_profile_mode(&astrcode_core::AgentProfile { - id: "explore".to_string(), - name: "Explore".to_string(), - description: "subagent".to_string(), - mode: AgentMode::SubAgent, - system_prompt: None, - model_preference: None, - }) - .expect_err("subagent-only profile should be rejected"); - - assert!(err.to_string().contains("root execution")); - } -} diff --git a/crates/application/src/lib.rs b/crates/application/src/lib.rs deleted file mode 100644 index 81f4c024..00000000 --- a/crates/application/src/lib.rs +++ /dev/null @@ -1,353 +0,0 @@ -//! # Astrcode 应用层 -//! -//! 纯业务编排层，不依赖任何 adapter-* crate，只依赖 core / kernel / session-runtime。 -//! -//! 核心职责： -//! - 通过 `App` 结构体暴露所有业务用例入口 -//! - 持有并编排 governance surface（治理面）、mode catalog（模式目录）等基础设施 -//! - 通过 port trait 与 adapter 层解耦（AppKernelPort / AppSessionPort / ComposerSkillPort） - -use std::{path::Path, sync::Arc}; - -use astrcode_core::AgentProfile; -use tokio::sync::broadcast; - -use crate::config::ConfigService; - -mod agent_use_cases; -mod governance_surface; -mod ports; -mod session_identity; -mod session_plan; -mod session_use_cases; -mod terminal_queries; -#[cfg(test)] -mod test_support; -mod workflow; - -pub mod agent; -pub mod composer; -pub mod config; -pub mod errors; -pub mod execution; -pub mod lifecycle; -pub mod mcp; -pub mod mode; -pub mod observability; -pub mod terminal; -pub mod watch; - -pub use agent::AgentOrchestrationService; -pub use astrcode_core::{ - AgentEvent, AgentEventContext, AgentLifecycleStatus, AgentMode, AgentTurnOutcome, ArtifactRef, - AstrError, CapabilitySpec, ChildAgentRef, ChildSessionLineageKind, - ChildSessionNotificationKind, CompactTrigger, ComposerOption, ComposerOptionActionKind, - ComposerOptionKind, Config, ExecutionAccepted, ForkMode, InvocationKind, InvocationMode, - LocalServerInfo, Phase, PluginHealth, PluginState, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, SessionEventRecord, SessionMeta, StorageEventPayload, - StoredEvent, SubRunFailure, SubRunFailureCode, SubRunHandoff, SubRunResult, SubRunStorageMode, - SubagentContextOverrides, TestConnectionResult, ToolOutputStream, format_local_rfc3339, - plugin::PluginEntry, -}; -pub use astrcode_kernel::SubRunStatusView; -pub use astrcode_session_runtime::{ - SessionCatalogEvent, SessionControlStateSnapshot, SessionEventFilterSpec, SessionReplay, - SessionTranscriptSnapshot, SubRunEventScope, TurnCollaborationSummary, TurnSummary, -}; -pub use composer::{ComposerOptionsRequest, ComposerSkillSummary}; -pub use errors::ApplicationError; -pub use execution::{ExecutionControl, ProfileResolutionService, RootExecutionRequest}; -pub use governance_surface::{ - FreshChildGovernanceInput, GOVERNANCE_APPROVAL_MODE_INHERIT, GOVERNANCE_POLICY_REVISION, - GovernanceBusyPolicy, GovernanceSurfaceAssembler, ResolvedGovernanceSurface, - ResumedChildGovernanceInput, RootGovernanceInput, SessionGovernanceInput, - ToolCollaborationGovernanceContext, build_delegation_metadata, build_fresh_child_contract, - build_resumed_child_contract, collaboration_policy_context, -}; -pub use lifecycle::governance::{ - AppGovernance, ObservabilitySnapshotProvider, RuntimeGovernancePort, RuntimeGovernanceSnapshot, - RuntimeReloader, SessionInfoProvider, -}; -pub use mcp::{ - McpActionSummary, McpConfigScope, McpPort, McpServerStatusSummary, McpServerStatusView, - McpService, RegisterMcpServerInput, -}; -pub use mode::{ - BuiltinModeCatalog, CompiledModeEnvelope, ModeCatalog, ModeSummary, builtin_mode_catalog, - compile_capability_selector, compile_mode_envelope, compile_mode_envelope_for_child, - validate_mode_transition, -}; -pub use observability::{ - AgentCollaborationScorecardSnapshot, ExecutionDiagnosticsSnapshot, GovernanceSnapshot, - OperationMetricsSnapshot, ReloadResult, ReplayMetricsSnapshot, ReplayPath, - ResolvedRuntimeStatusSummary, RuntimeCapabilitySummary, RuntimeObservabilityCollector, - RuntimeObservabilitySnapshot, RuntimePluginSummary, SubRunExecutionMetricsSnapshot, - resolve_runtime_status_summary, -}; -pub use ports::{ - AgentKernelPort, AgentSessionPort, AppAgentPromptSubmission, AppKernelPort, AppSessionPort, - ComposerResolvedSkill, ComposerSkillPort, RecoverableParentDelivery, SessionObserveSnapshot, - SessionTurnOutcomeSummary, SessionTurnTerminalState, -}; -pub use session_plan::{ProjectPlanArchiveDetail, ProjectPlanArchiveSummary}; -pub use session_use_cases::{SessionForkSelector, summarize_session_meta}; -pub use watch::{WatchEvent, WatchPort, WatchService, WatchSource}; -pub use workflow::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, PlanImplementationStep, - PlanToExecuteBridgeState, WorkflowArtifactRef, WorkflowInstanceState, WorkflowOrchestrator, - WorkflowStateService, plan_execute_workflow, -}; - -/// 唯一业务用例入口。 -pub struct App { - kernel: Arc, - session_runtime: Arc, - profiles: Arc, - config_service: Arc, - composer_service: Arc, - composer_skills: Arc, - governance_surface: Arc, - mode_catalog: Arc, - workflow_orchestrator: Arc, - mcp_service: Arc, - agent_service: Arc, -} - -/// 手动压缩请求的返回结果。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct CompactSessionAccepted { - /// true 表示压缩被推迟（当前有 turn 正在执行），待 turn 结束后自动执行。 - pub deferred: bool, -} - -/// prompt 提交成功后的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PromptAcceptedSummary { - pub turn_id: String, - pub session_id: String, - pub branched_from_session_id: Option, - pub accepted_control: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PromptSkillInvocation { - pub skill_id: String, - pub user_prompt: Option, -} - -/// 手动 compact 的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct CompactSessionSummary { - pub accepted: bool, - pub deferred: bool, - pub message: String, -} - -/// session 列表项的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionListSummary { - pub session_id: String, - pub working_dir: String, - pub display_name: String, - pub title: String, - pub created_at: String, - pub updated_at: String, - pub parent_session_id: Option, - pub parent_storage_seq: Option, - pub phase: Phase, -} - -/// root agent 执行接受后的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct AgentExecuteSummary { - pub accepted: bool, - pub message: String, - pub session_id: Option, - pub turn_id: Option, - pub agent_id: Option, -} - -/// sub-run 状态来源。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum SubRunStatusSourceSummary { - Live, - Durable, -} - -/// sub-run 状态的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SubRunStatusSummary { - pub sub_run_id: String, - pub tool_call_id: Option, - pub source: SubRunStatusSourceSummary, - pub agent_id: String, - pub agent_profile: String, - pub session_id: String, - pub child_session_id: Option, - pub depth: usize, - pub parent_agent_id: Option, - pub parent_sub_run_id: Option, - pub storage_mode: SubRunStorageMode, - pub lifecycle: AgentLifecycleStatus, - pub last_turn_outcome: Option, - pub result: Option, - pub step_count: Option, - pub estimated_tokens: Option, - pub resolved_overrides: Option, - pub resolved_limits: Option, -} - -impl App { - #[allow(clippy::too_many_arguments)] - pub fn new( - kernel: Arc, - session_runtime: Arc, - profiles: Arc, - config_service: Arc, - composer_skills: Arc, - governance_surface: Arc, - mode_catalog: Arc, - mcp_service: Arc, - agent_service: Arc, - ) -> Self { - Self { - kernel, - session_runtime, - profiles, - config_service, - composer_service: Arc::new(composer::ComposerService::new()), - composer_skills, - governance_surface, - mode_catalog, - workflow_orchestrator: Arc::new(WorkflowOrchestrator::default()), - mcp_service, - agent_service, - } - } - - pub fn kernel(&self) -> &Arc { - &self.kernel - } - - pub fn session_runtime(&self) -> &Arc { - &self.session_runtime - } - - pub fn config(&self) -> &Arc { - &self.config_service - } - - pub fn profiles(&self) -> &Arc { - &self.profiles - } - - pub fn mcp(&self) -> &Arc { - &self.mcp_service - } - - pub fn composer(&self) -> &Arc { - &self.composer_service - } - - pub fn composer_skills(&self) -> &Arc { - &self.composer_skills - } - - pub fn governance_surface(&self) -> &Arc { - &self.governance_surface - } - - pub fn mode_catalog(&self) -> &Arc { - &self.mode_catalog - } - - pub fn workflow(&self) -> &Arc { - &self.workflow_orchestrator - } - - pub fn agent(&self) -> &Arc { - &self.agent_service - } - - pub fn subscribe_catalog(&self) -> broadcast::Receiver { - self.session_runtime.subscribe_catalog_events() - } - - pub async fn execute_root_agent( - &self, - request: RootExecutionRequest, - ) -> Result { - let runtime = self - .config_service - .load_resolved_runtime_config(Some(Path::new(&request.working_dir)))?; - execution::execute_root_agent( - self.kernel.as_ref(), - self.session_runtime.as_ref(), - &self.profiles, - self.governance_surface.as_ref(), - request, - runtime, - ) - .await - } - - pub fn list_global_agent_profiles(&self) -> Result, ApplicationError> { - Ok(self.profiles.resolve_global()?.as_ref().clone()) - } - - pub fn list_agent_profiles_for_working_dir( - &self, - working_dir: &Path, - ) -> Result, ApplicationError> { - Ok(self.profiles.resolve(working_dir)?.as_ref().clone()) - } - - pub async fn list_composer_options( - &self, - session_id: &str, - request: ComposerOptionsRequest, - ) -> Result, ApplicationError> { - self.validate_non_empty("sessionId", session_id)?; - let gateway = self.kernel.gateway(); - let working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await - .map_err(ApplicationError::from)?; - let skill_summaries = self - .composer_skills - .list_skill_summaries(Path::new(&working_dir)); - Ok(self - .composer_service - .list_options(request, skill_summaries, Some(&gateway))) - } - - pub async fn get_config(&self) -> Config { - self.config_service.get_config().await - } - - pub fn validate_non_empty( - &self, - field: &'static str, - value: &str, - ) -> Result<(), ApplicationError> { - if value.trim().is_empty() { - return Err(ApplicationError::InvalidArgument(format!( - "field '{}' must not be empty", - field - ))); - } - Ok(()) - } - - pub fn require_permission( - &self, - allowed: bool, - reason: impl Into, - ) -> Result<(), ApplicationError> { - if allowed { - return Ok(()); - } - Err(ApplicationError::PermissionDenied(reason.into())) - } -} diff --git a/crates/application/src/ports/agent_kernel.rs b/crates/application/src/ports/agent_kernel.rs deleted file mode 100644 index dfb84d1e..00000000 --- a/crates/application/src/ports/agent_kernel.rs +++ /dev/null @@ -1,235 +0,0 @@ -//! Agent 编排子域依赖的 kernel 稳定端口。 -//! -//! `AgentKernelPort` 继承 `AppKernelPort`，扩展了 agent 编排所需的全部 kernel 操作： -//! lifecycle 管理、子 agent spawn/resume/terminate、inbox 投递、parent delivery 队列。 -//! -//! 为什么单独抽 trait：`AgentOrchestrationService` 需要的控制面明显大于 `App`， -//! 避免 `AppKernelPort` 被动膨胀成新的大而全 façade。 -//! -//! 同时提供 `Kernel` 对 `AgentKernelPort` 的 blanket impl。 - -use astrcode_core::{ - AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, - DelegationMetadata, SubRunHandle, -}; -use astrcode_kernel::{AgentControlError, Kernel}; -use async_trait::async_trait; - -use super::{AppKernelPort, RecoverableParentDelivery}; - -/// Agent 编排子域依赖的 kernel 稳定端口。 -/// -/// Why: `AgentOrchestrationService` 需要的控制面明显大于 `App`， -/// 单独抽 trait 能避免 `AppKernelPort` 被动膨胀成新的大而全 façade。 -#[async_trait] -pub trait AgentKernelPort: AppKernelPort { - async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option; - async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option; - async fn resume(&self, sub_run_or_agent_id: &str, parent_turn_id: &str) - -> Option; - async fn spawn_independent_child( - &self, - profile: &astrcode_core::AgentProfile, - session_id: String, - child_session_id: String, - parent_turn_id: String, - parent_agent_id: String, - ) -> Result; - async fn set_lifecycle( - &self, - sub_run_or_agent_id: &str, - new_status: AgentLifecycleStatus, - ) -> Option<()>; - async fn complete_turn( - &self, - sub_run_or_agent_id: &str, - outcome: AgentTurnOutcome, - ) -> Option; - async fn set_delegation( - &self, - sub_run_or_agent_id: &str, - delegation: Option, - ) -> Option<()>; - async fn count_children_spawned_for_turn( - &self, - parent_agent_id: &str, - parent_turn_id: &str, - ) -> usize; - async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec; - async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option; - async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()>; - async fn drain_inbox(&self, agent_id: &str) -> Option>; - async fn enqueue_child_delivery( - &self, - parent_session_id: String, - parent_turn_id: String, - notification: ChildSessionNotification, - ) -> bool; - async fn checkout_parent_delivery_batch( - &self, - parent_session_id: &str, - ) -> Option>; - async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize; - async fn requeue_parent_delivery_batch(&self, parent_session_id: &str, delivery_ids: &[String]); - async fn consume_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) -> bool; -} - -#[async_trait] -impl AgentKernelPort for Kernel { - async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option { - self.agent().get_lifecycle(sub_run_or_agent_id).await - } - - async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option { - self.agent().get_turn_outcome(sub_run_or_agent_id).await - } - - async fn resume( - &self, - sub_run_or_agent_id: &str, - parent_turn_id: &str, - ) -> Option { - self.agent() - .resume(sub_run_or_agent_id, parent_turn_id) - .await - } - - async fn spawn_independent_child( - &self, - profile: &astrcode_core::AgentProfile, - session_id: String, - child_session_id: String, - parent_turn_id: String, - parent_agent_id: String, - ) -> Result { - self.agent() - .spawn_independent_child( - profile, - session_id, - child_session_id, - parent_turn_id, - parent_agent_id, - ) - .await - } - - async fn set_lifecycle( - &self, - sub_run_or_agent_id: &str, - new_status: AgentLifecycleStatus, - ) -> Option<()> { - self.agent() - .set_lifecycle(sub_run_or_agent_id, new_status) - .await - } - - async fn complete_turn( - &self, - sub_run_or_agent_id: &str, - outcome: AgentTurnOutcome, - ) -> Option { - self.agent_control() - .complete_turn(sub_run_or_agent_id, outcome) - .await - } - - async fn set_delegation( - &self, - sub_run_or_agent_id: &str, - delegation: Option, - ) -> Option<()> { - self.agent() - .set_delegation(sub_run_or_agent_id, delegation) - .await - } - - async fn count_children_spawned_for_turn( - &self, - parent_agent_id: &str, - parent_turn_id: &str, - ) -> usize { - self.agent() - .count_children_spawned_for_turn(parent_agent_id, parent_turn_id) - .await - } - - async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec { - self.agent() - .collect_subtree_handles(sub_run_or_agent_id) - .await - } - - async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option { - self.agent().terminate_subtree(sub_run_or_agent_id).await - } - - async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()> { - self.agent().deliver(agent_id, envelope).await - } - - async fn drain_inbox(&self, agent_id: &str) -> Option> { - self.agent().drain_inbox(agent_id).await - } - - async fn enqueue_child_delivery( - &self, - parent_session_id: String, - parent_turn_id: String, - notification: ChildSessionNotification, - ) -> bool { - self.agent() - .enqueue_child_delivery(parent_session_id, parent_turn_id, notification) - .await - } - - async fn checkout_parent_delivery_batch( - &self, - parent_session_id: &str, - ) -> Option> { - self.agent() - .checkout_parent_delivery_batch(parent_session_id) - .await - .map(|deliveries| { - deliveries - .into_iter() - .map(|value| RecoverableParentDelivery { - delivery_id: value.delivery_id, - parent_session_id: value.parent_session_id, - parent_turn_id: value.parent_turn_id, - queued_at_ms: value.queued_at_ms, - notification: value.notification, - }) - .collect() - }) - } - - async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { - self.agent_control() - .pending_parent_delivery_count(parent_session_id) - .await - } - - async fn requeue_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) { - self.agent() - .requeue_parent_delivery_batch(parent_session_id, delivery_ids) - .await - } - - async fn consume_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) -> bool { - self.agent() - .consume_parent_delivery_batch(parent_session_id, delivery_ids) - .await - } -} diff --git a/crates/application/src/ports/agent_session.rs b/crates/application/src/ports/agent_session.rs deleted file mode 100644 index bd3ce6cf..00000000 --- a/crates/application/src/ports/agent_session.rs +++ /dev/null @@ -1,334 +0,0 @@ -//! Agent 编排子域依赖的 session 稳定端口。 -//! -//! `AgentSessionPort` 继承 `AppSessionPort`，扩展了 agent 协作编排所需的全部 session 操作： -//! child session 建立、prompt 提交（带 turn id）、durable input queue 管理、 -//! collaboration fact 追加、observe 快照、turn 终态等待。 -//! -//! 先按职责分组在一个端口中表达完整协作流程，未来根据演化决定是否继续瘦身。 -//! -//! 同时提供 `SessionRuntime` 对 `AgentSessionPort` 的 blanket impl。 - -use astrcode_core::{ - AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, ExecutionAccepted, - InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, - ResolvedRuntimeConfig, SessionMeta, StoredEvent, TurnId, -}; -use astrcode_session_runtime::SessionRuntime; -use async_trait::async_trait; - -use super::{ - AppAgentPromptSubmission, AppSessionPort, RecoverableParentDelivery, SessionObserveSnapshot, - SessionTurnOutcomeSummary, SessionTurnTerminalState, -}; - -/// Agent 编排子域依赖的 session 稳定端口。 -/// -/// Why: 这里的方法虽然不少，但调用者仍是同一批 agent collaboration use case。 -/// 先按职责分组，保持一个端口表达完整协作流程，再根据未来演化决定是否继续瘦身。 -#[async_trait] -pub trait AgentSessionPort: AppSessionPort { - // 子 agent session 建立与 prompt 提交。 - async fn create_child_session( - &self, - working_dir: &str, - parent_session_id: &str, - ) -> astrcode_core::Result; - async fn submit_prompt_for_agent_with_submission( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result; - async fn try_submit_prompt_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result>; - async fn submit_queued_inputs_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - queued_inputs: Vec, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result>; - - // Durable input queue / collaboration 事件追加。 - async fn append_agent_input_queued( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputQueuedPayload, - ) -> astrcode_core::Result; - async fn append_agent_input_discarded( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputDiscardedPayload, - ) -> astrcode_core::Result; - async fn append_agent_input_batch_started( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchStartedPayload, - ) -> astrcode_core::Result; - async fn append_agent_input_batch_acked( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchAckedPayload, - ) -> astrcode_core::Result; - async fn append_child_session_notification( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - notification: astrcode_core::ChildSessionNotification, - ) -> astrcode_core::Result; - async fn append_agent_collaboration_fact( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - fact: AgentCollaborationFact, - ) -> astrcode_core::Result; - async fn pending_delivery_ids_for_agent( - &self, - session_id: &str, - agent_id: &str, - ) -> astrcode_core::Result>; - async fn recoverable_parent_deliveries( - &self, - parent_session_id: &str, - ) -> astrcode_core::Result>; - - // 观察与投影读取。 - async fn observe_agent_session( - &self, - open_session_id: &str, - target_agent_id: &str, - lifecycle_status: AgentLifecycleStatus, - ) -> astrcode_core::Result; - async fn project_turn_outcome( - &self, - session_id: &str, - turn_id: &str, - ) -> astrcode_core::Result; - - // Turn 终态等待。 - async fn wait_for_turn_terminal_snapshot( - &self, - session_id: &str, - turn_id: &str, - ) -> astrcode_core::Result; -} - -#[async_trait] -impl AgentSessionPort for SessionRuntime { - // 子 agent session 建立与 prompt 提交。 - async fn create_child_session( - &self, - working_dir: &str, - parent_session_id: &str, - ) -> astrcode_core::Result { - self.create_child_session(working_dir, parent_session_id) - .await - } - - async fn submit_prompt_for_agent_with_submission( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result { - self.submit_prompt_for_agent_with_submission(session_id, text, runtime, submission.into()) - .await - } - - async fn try_submit_prompt_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result> { - self.try_submit_prompt_for_agent_with_turn_id( - session_id, - turn_id, - text, - runtime, - submission.into(), - ) - .await - } - - async fn submit_queued_inputs_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - queued_inputs: Vec, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result> { - self.submit_queued_inputs_for_agent_with_turn_id( - session_id, - turn_id, - queued_inputs, - runtime, - submission.into(), - ) - .await - } - - // Durable input queue / collaboration 事件追加。 - async fn append_agent_input_queued( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputQueuedPayload, - ) -> astrcode_core::Result { - self.append_agent_input_queued(session_id, turn_id, agent, payload) - .await - } - - async fn append_agent_input_discarded( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputDiscardedPayload, - ) -> astrcode_core::Result { - self.append_agent_input_discarded(session_id, turn_id, agent, payload) - .await - } - - async fn append_agent_input_batch_started( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchStartedPayload, - ) -> astrcode_core::Result { - self.append_agent_input_batch_started(session_id, turn_id, agent, payload) - .await - } - - async fn append_agent_input_batch_acked( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchAckedPayload, - ) -> astrcode_core::Result { - self.append_agent_input_batch_acked(session_id, turn_id, agent, payload) - .await - } - - async fn append_child_session_notification( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - notification: astrcode_core::ChildSessionNotification, - ) -> astrcode_core::Result { - self.append_child_session_notification(session_id, turn_id, agent, notification) - .await - } - - async fn append_agent_collaboration_fact( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - fact: AgentCollaborationFact, - ) -> astrcode_core::Result { - self.append_agent_collaboration_fact(session_id, turn_id, agent, fact) - .await - } - - async fn pending_delivery_ids_for_agent( - &self, - session_id: &str, - agent_id: &str, - ) -> astrcode_core::Result> { - self.pending_delivery_ids_for_agent(session_id, agent_id) - .await - } - - async fn recoverable_parent_deliveries( - &self, - parent_session_id: &str, - ) -> astrcode_core::Result> { - Ok(self - .recoverable_parent_deliveries(parent_session_id) - .await? - .into_iter() - .map(|value| RecoverableParentDelivery { - delivery_id: value.delivery_id, - parent_session_id: value.parent_session_id, - parent_turn_id: value.parent_turn_id, - queued_at_ms: value.queued_at_ms, - notification: value.notification, - }) - .collect()) - } - - // 观察与投影读取。 - async fn observe_agent_session( - &self, - open_session_id: &str, - target_agent_id: &str, - lifecycle_status: AgentLifecycleStatus, - ) -> astrcode_core::Result { - let value = self - .observe_agent_session(open_session_id, target_agent_id, lifecycle_status) - .await?; - Ok(SessionObserveSnapshot { - phase: value.phase, - turn_count: value.turn_count, - active_task: value.active_task, - last_output_tail: value.last_output_tail, - last_turn_tail: value.last_turn_tail, - }) - } - - async fn project_turn_outcome( - &self, - session_id: &str, - turn_id: &str, - ) -> astrcode_core::Result { - let value = self.project_turn_outcome(session_id, turn_id).await?; - Ok(SessionTurnOutcomeSummary { - outcome: value.outcome, - summary: value.summary, - technical_message: value.technical_message, - }) - } - - // Turn 终态等待。 - async fn wait_for_turn_terminal_snapshot( - &self, - session_id: &str, - turn_id: &str, - ) -> astrcode_core::Result { - let value = self - .wait_for_turn_terminal_snapshot(session_id, turn_id) - .await?; - Ok(SessionTurnTerminalState { - phase: value.phase, - projection: value.projection, - events: value.events, - }) - } -} diff --git a/crates/application/src/ports/app_kernel.rs b/crates/application/src/ports/app_kernel.rs deleted file mode 100644 index 0637c1e7..00000000 --- a/crates/application/src/ports/app_kernel.rs +++ /dev/null @@ -1,93 +0,0 @@ -//! `App` 依赖的 kernel 稳定端口。 -//! -//! 定义 `AppKernelPort` trait，将应用层与 kernel 具体实现解耦。 -//! `App` 只需要一组稳定的 agent 控制与 capability 查询契约， -//! 不直接绑定 `Kernel` 的内部结构。 -//! -//! 同时提供 `Kernel` 对 `AppKernelPort` 的 blanket impl， -//! 组合根在 `bootstrap_server_runtime()` 中只需一次 `Arc` 即可满足两个端口的约束。 - -use astrcode_core::SubRunHandle; -use astrcode_kernel::{ - AgentControlError, CloseSubtreeResult, Kernel, KernelGateway, SubRunStatusView, -}; -use async_trait::async_trait; - -/// `App` 依赖的 kernel 稳定端口。 -/// -/// Why: `App` 是应用层用例入口，不应直接绑定 `Kernel` 具体实现； -/// 它只需要一组稳定的 agent 控制与 capability 查询契约。 -#[async_trait] -pub trait AppKernelPort: Send + Sync { - fn gateway(&self) -> KernelGateway; - - async fn query_subrun_status(&self, agent_id: &str) -> Option; - async fn query_root_status(&self, session_id: &str) -> Option; - async fn list_statuses(&self) -> Vec; - async fn get_handle(&self, agent_id: &str) -> Option; - async fn find_root_handle_for_session(&self, session_id: &str) -> Option; - async fn register_root_agent( - &self, - agent_id: String, - session_id: String, - profile_id: String, - ) -> Result; - async fn set_resolved_limits( - &self, - sub_run_or_agent_id: &str, - resolved_limits: astrcode_core::ResolvedExecutionLimitsSnapshot, - ) -> Option<()>; - async fn close_subtree(&self, agent_id: &str) -> Result; -} - -#[async_trait] -impl AppKernelPort for Kernel { - fn gateway(&self) -> KernelGateway { - self.gateway().clone() - } - - async fn query_subrun_status(&self, agent_id: &str) -> Option { - self.agent().query_subrun_status(agent_id).await - } - - async fn query_root_status(&self, session_id: &str) -> Option { - self.agent().query_root_status(session_id).await - } - - async fn list_statuses(&self) -> Vec { - self.agent().list_statuses().await - } - - async fn get_handle(&self, agent_id: &str) -> Option { - self.agent().get_handle(agent_id).await - } - - async fn find_root_handle_for_session(&self, session_id: &str) -> Option { - self.agent().find_root_handle_for_session(session_id).await - } - - async fn register_root_agent( - &self, - agent_id: String, - session_id: String, - profile_id: String, - ) -> Result { - self.agent() - .register_root_agent(agent_id, session_id, profile_id) - .await - } - - async fn set_resolved_limits( - &self, - sub_run_or_agent_id: &str, - resolved_limits: astrcode_core::ResolvedExecutionLimitsSnapshot, - ) -> Option<()> { - self.agent() - .set_resolved_limits(sub_run_or_agent_id, resolved_limits) - .await - } - - async fn close_subtree(&self, agent_id: &str) -> Result { - self.agent().close_subtree(agent_id).await - } -} diff --git a/crates/application/src/ports/app_session.rs b/crates/application/src/ports/app_session.rs deleted file mode 100644 index 17820b56..00000000 --- a/crates/application/src/ports/app_session.rs +++ /dev/null @@ -1,283 +0,0 @@ -//! `App` 依赖的 session-runtime 稳定端口。 -//! -//! 定义 `AppSessionPort` trait，将应用层与 `SessionRuntime` 具体实现解耦。 -//! `App` 只编排 session 用例（创建、提交、快照、compact 等）， -//! 不直接耦合 `SessionRuntime` 的内部状态管理。 -//! -//! 同时提供 `SessionRuntime` 对 `AppSessionPort` 的 blanket impl。 - -use astrcode_core::{ - ChildSessionNode, DeleteProjectResult, ExecutionAccepted, ResolvedRuntimeConfig, SessionMeta, - StoredEvent, TaskSnapshot, -}; -use astrcode_session_runtime::{ - ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionCatalogEvent, - SessionControlStateSnapshot, SessionModeSnapshot, SessionReplay, SessionRuntime, - SessionTranscriptSnapshot, SubRunStatusSnapshot, -}; -use async_trait::async_trait; -use tokio::sync::broadcast; - -use super::AppAgentPromptSubmission; -use crate::{ - session_identity::normalize_external_session_id, session_use_cases::SessionForkSelector, -}; - -/// `App` 依赖的 session-runtime 稳定端口。 -/// -/// Why: `App` 只编排 session 用例，不应直接耦合 `SessionRuntime` 的具体结构。 -#[async_trait] -pub trait AppSessionPort: Send + Sync { - fn subscribe_catalog_events(&self) -> broadcast::Receiver; - - async fn list_session_metas(&self) -> astrcode_core::Result>; - async fn create_session(&self, working_dir: String) -> astrcode_core::Result; - async fn fork_session( - &self, - session_id: &str, - selector: SessionForkSelector, - ) -> astrcode_core::Result; - async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()>; - async fn delete_project(&self, working_dir: &str) - -> astrcode_core::Result; - async fn get_session_working_dir(&self, session_id: &str) -> astrcode_core::Result; - async fn submit_prompt_for_agent( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result; - async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()>; - async fn compact_session( - &self, - session_id: &str, - runtime: ResolvedRuntimeConfig, - instructions: Option, - ) -> astrcode_core::Result; - async fn session_transcript_snapshot( - &self, - session_id: &str, - ) -> astrcode_core::Result; - async fn conversation_snapshot( - &self, - session_id: &str, - ) -> astrcode_core::Result; - async fn session_control_state( - &self, - session_id: &str, - ) -> astrcode_core::Result; - async fn active_task_snapshot( - &self, - session_id: &str, - owner: &str, - ) -> astrcode_core::Result>; - async fn session_mode_state( - &self, - session_id: &str, - ) -> astrcode_core::Result; - async fn switch_mode( - &self, - session_id: &str, - from: astrcode_core::ModeId, - to: astrcode_core::ModeId, - ) -> astrcode_core::Result; - async fn session_child_nodes( - &self, - session_id: &str, - ) -> astrcode_core::Result>; - async fn session_stored_events( - &self, - session_id: &str, - ) -> astrcode_core::Result>; - async fn durable_subrun_status_snapshot( - &self, - parent_session_id: &str, - requested_subrun_id: &str, - ) -> astrcode_core::Result>; - async fn session_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> astrcode_core::Result; - async fn conversation_stream_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> astrcode_core::Result; -} - -#[async_trait] -impl AppSessionPort for SessionRuntime { - fn subscribe_catalog_events(&self) -> broadcast::Receiver { - self.subscribe_catalog_events() - } - - async fn list_session_metas(&self) -> astrcode_core::Result> { - self.list_session_metas().await - } - - async fn create_session(&self, working_dir: String) -> astrcode_core::Result { - self.create_session(working_dir).await - } - - async fn fork_session( - &self, - session_id: &str, - selector: SessionForkSelector, - ) -> astrcode_core::Result { - let fork_point = match selector { - SessionForkSelector::Latest => astrcode_session_runtime::ForkPoint::Latest, - SessionForkSelector::TurnEnd { turn_id } => { - astrcode_session_runtime::ForkPoint::TurnEnd(turn_id) - }, - SessionForkSelector::StorageSeq { storage_seq } => { - astrcode_session_runtime::ForkPoint::StorageSeq(storage_seq) - }, - }; - let result = self - .fork_session( - &astrcode_core::SessionId::from(normalize_external_session_id(session_id)), - fork_point, - ) - .await?; - self.list_session_metas() - .await? - .into_iter() - .find(|meta| meta.session_id == result.new_session_id.as_str()) - .ok_or_else(|| { - astrcode_core::AstrError::Internal(format!( - "forked session '{}' was created but metadata is unavailable", - result.new_session_id - )) - }) - } - - async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()> { - self.delete_session(session_id).await - } - - async fn delete_project( - &self, - working_dir: &str, - ) -> astrcode_core::Result { - self.delete_project(working_dir).await - } - - async fn get_session_working_dir(&self, session_id: &str) -> astrcode_core::Result { - self.get_session_working_dir(session_id).await - } - - async fn submit_prompt_for_agent( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result { - self.submit_prompt_for_agent(session_id, text, runtime, submission.into()) - .await - } - - async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()> { - self.interrupt_session(session_id).await - } - - async fn compact_session( - &self, - session_id: &str, - runtime: ResolvedRuntimeConfig, - instructions: Option, - ) -> astrcode_core::Result { - self.compact_session(session_id, runtime, instructions) - .await - } - - async fn session_transcript_snapshot( - &self, - session_id: &str, - ) -> astrcode_core::Result { - self.session_transcript_snapshot(session_id).await - } - - async fn conversation_snapshot( - &self, - session_id: &str, - ) -> astrcode_core::Result { - self.conversation_snapshot(session_id).await - } - - async fn session_control_state( - &self, - session_id: &str, - ) -> astrcode_core::Result { - self.session_control_state(session_id).await - } - - async fn active_task_snapshot( - &self, - session_id: &str, - owner: &str, - ) -> astrcode_core::Result> { - self.active_task_snapshot(session_id, owner).await - } - - async fn session_mode_state( - &self, - session_id: &str, - ) -> astrcode_core::Result { - self.session_mode_state(session_id).await - } - - async fn switch_mode( - &self, - session_id: &str, - from: astrcode_core::ModeId, - to: astrcode_core::ModeId, - ) -> astrcode_core::Result { - self.switch_mode(session_id, from, to).await - } - - async fn session_child_nodes( - &self, - session_id: &str, - ) -> astrcode_core::Result> { - self.session_child_nodes(session_id).await - } - - async fn session_stored_events( - &self, - session_id: &str, - ) -> astrcode_core::Result> { - self.replay_stored_events(&astrcode_core::SessionId::from( - normalize_external_session_id(session_id), - )) - .await - } - - async fn durable_subrun_status_snapshot( - &self, - parent_session_id: &str, - requested_subrun_id: &str, - ) -> astrcode_core::Result> { - self.durable_subrun_status_snapshot(parent_session_id, requested_subrun_id) - .await - } - - async fn session_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> astrcode_core::Result { - self.session_replay(session_id, last_event_id).await - } - - async fn conversation_stream_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> astrcode_core::Result { - self.conversation_stream_replay(session_id, last_event_id) - .await - } -} diff --git a/crates/application/src/ports/session_contracts.rs b/crates/application/src/ports/session_contracts.rs deleted file mode 100644 index e28f8b6f..00000000 --- a/crates/application/src/ports/session_contracts.rs +++ /dev/null @@ -1,54 +0,0 @@ -//! application 自有的 session 编排合同。 -//! -//! Why: `application` 只应该消费纯数据的编排摘要， -//! 不应继续把 `session-runtime` / `kernel` 的内部快照类型透传给上层。 - -use astrcode_core::{ - AgentTurnOutcome, ChildSessionNotification, Phase, StoredEvent, TurnProjectionSnapshot, -}; -use serde::{Deserialize, Serialize}; - -/// 应用层使用的 turn outcome 摘要。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct SessionTurnOutcomeSummary { - pub outcome: AgentTurnOutcome, - pub summary: String, - pub technical_message: String, -} - -/// 应用层使用的 turn 终态快照。 -#[derive(Debug, Clone, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct SessionTurnTerminalState { - pub phase: Phase, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub projection: Option, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub events: Vec, -} - -/// 应用层使用的 observe 快照。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct SessionObserveSnapshot { - pub phase: Phase, - pub turn_count: u32, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub active_task: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub last_output_tail: Option, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub last_turn_tail: Vec, -} - -/// 应用层使用的可恢复父级投递摘要。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct RecoverableParentDelivery { - pub delivery_id: String, - pub parent_session_id: String, - pub parent_turn_id: String, - pub queued_at_ms: i64, - pub notification: ChildSessionNotification, -} diff --git a/crates/application/src/session_identity.rs b/crates/application/src/session_identity.rs deleted file mode 100644 index f4d17e9f..00000000 --- a/crates/application/src/session_identity.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! application 层的 session 输入整形辅助。 -//! -//! Why: 用例层仍然只处理原始字符串，但 session key 规范化真相属于 -//! runtime；这里保留一个极窄的桥接函数，避免业务代码各自复制规则。 - -/// 规范化外部传入的 session 标识。 -/// -/// 真正的规范化规则由 `session-runtime` 持有，这里只做转发。 -pub(crate) fn normalize_external_session_id(session_id: &str) -> String { - astrcode_session_runtime::identity::normalize_external_session_id(session_id) -} diff --git a/crates/application/src/session_plan.rs b/crates/application/src/session_plan.rs deleted file mode 100644 index 70cc9716..00000000 --- a/crates/application/src/session_plan.rs +++ /dev/null @@ -1,1058 +0,0 @@ -//! session 级计划工件。 -//! -//! 这里维护 session 下唯一 canonical plan 的路径规则、状态模型、审批归档和 prompt 注入， -//! 保持 plan mode 的流程真相收敛在 application，而不是散落在 handler / tool / UI。 - -use std::{ - fs, - path::{Path, PathBuf}, -}; - -use astrcode_core::{ - GovernanceModeSpec, LlmMessage, ModeId, PromptDeclaration, - SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER, SessionPlanState, SessionPlanStatus, - UserMessageOrigin, WorkflowSignal, session_plan_content_digest, -}; -use astrcode_support::hostpaths::project_dir; -use chrono::{DateTime, Utc}; -use serde::{Deserialize, Serialize}; - -use crate::{ApplicationError, workflow::PlanToExecuteBridgeState}; - -const PLAN_DIR_NAME: &str = "plan"; -const PLAN_ARCHIVE_DIR_NAME: &str = "plan-archives"; -const PLAN_STATE_FILE_NAME: &str = "state.json"; -const PLAN_ARCHIVE_FILE_NAME: &str = "plan.md"; -const PLAN_ARCHIVE_METADATA_FILE_NAME: &str = "metadata.json"; -const PLAN_PATH_TIMESTAMP_FORMAT: &str = "%Y%m%dT%H%M%SZ"; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionPlanSummary { - pub slug: String, - pub path: String, - pub status: String, - pub title: String, - pub updated_at: DateTime, -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct SessionPlanControlSummary { - pub active_plan: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PlanPromptContext { - pub session_id: String, - pub target_plan_path: String, - pub target_plan_exists: bool, - pub target_plan_slug: String, - pub active_plan: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ModeWorkflowPromptFacts { - pub approved_plan: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PlanApprovalParseResult { - pub approved: bool, - pub matched_phrase: Option<&'static str>, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct ProjectPlanArchiveMetadata { - pub archive_id: String, - pub title: String, - pub source_session_id: String, - pub source_plan_slug: String, - pub source_plan_path: String, - pub approved_at: DateTime, - pub archived_at: DateTime, - pub status: String, - pub content_digest: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ProjectPlanArchiveSummary { - pub metadata: ProjectPlanArchiveMetadata, - pub archive_dir: String, - pub plan_path: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ProjectPlanArchiveDetail { - pub summary: ProjectPlanArchiveSummary, - pub content: String, -} - -fn io_error(action: &str, path: &Path, error: std::io::Error) -> ApplicationError { - ApplicationError::Internal(format!("{action} '{}' failed: {error}", path.display())) -} - -pub(crate) fn session_plan_dir( - session_id: &str, - working_dir: &Path, -) -> Result { - Ok(project_dir(working_dir) - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to resolve project directory for '{}': {error}", - working_dir.display() - )) - })? - .join("sessions") - .join(session_id) - .join(PLAN_DIR_NAME)) -} - -fn project_plan_archive_dir(working_dir: &Path) -> Result { - Ok(project_dir(working_dir) - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to resolve project directory for '{}': {error}", - working_dir.display() - )) - })? - .join(PLAN_ARCHIVE_DIR_NAME)) -} - -fn session_plan_state_path( - session_id: &str, - working_dir: &Path, -) -> Result { - Ok(session_plan_dir(session_id, working_dir)?.join(PLAN_STATE_FILE_NAME)) -} - -pub(crate) fn session_plan_markdown_path( - session_id: &str, - working_dir: &Path, - slug: &str, -) -> Result { - Ok(session_plan_dir(session_id, working_dir)?.join(format!("{slug}.md"))) -} - -fn archive_paths( - working_dir: &Path, - archive_id: &str, -) -> Result<(PathBuf, PathBuf, PathBuf), ApplicationError> { - validate_archive_id(archive_id)?; - let archive_dir = project_plan_archive_dir(working_dir)?.join(archive_id); - Ok(( - archive_dir.clone(), - archive_dir.join(PLAN_ARCHIVE_FILE_NAME), - archive_dir.join(PLAN_ARCHIVE_METADATA_FILE_NAME), - )) -} - -pub(crate) fn load_session_plan_state( - session_id: &str, - working_dir: &Path, -) -> Result, ApplicationError> { - let path = session_plan_state_path(session_id, working_dir)?; - if !path.exists() { - return Ok(None); - } - let content = fs::read_to_string(&path).map_err(|error| io_error("reading", &path, error))?; - serde_json::from_str::(&content) - .map(Some) - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to parse session plan state '{}': {error}", - path.display() - )) - }) -} - -pub(crate) fn session_plan_control_summary( - session_id: &str, - working_dir: &Path, -) -> Result { - Ok(SessionPlanControlSummary { - active_plan: active_plan_summary(session_id, working_dir)?, - }) -} - -pub(crate) fn active_plan_summary( - session_id: &str, - working_dir: &Path, -) -> Result, ApplicationError> { - let Some(state) = load_session_plan_state(session_id, working_dir)? else { - return Ok(None); - }; - Ok(Some(plan_summary(session_id, working_dir, &state)?)) -} - -pub(crate) fn build_plan_prompt_context( - session_id: &str, - working_dir: &Path, - user_text: &str, -) -> Result { - if let Some(active_plan) = active_plan_summary(session_id, working_dir)? { - return Ok(PlanPromptContext { - session_id: session_id.to_string(), - target_plan_path: active_plan.path.clone(), - target_plan_exists: Path::new(&active_plan.path).exists(), - target_plan_slug: active_plan.slug.clone(), - active_plan: Some(active_plan), - }); - } - - let suggested_slug = slugify_plan_topic(user_text) - .unwrap_or_else(|| format!("plan-{}", Utc::now().format(PLAN_PATH_TIMESTAMP_FORMAT))); - let path = session_plan_markdown_path(session_id, working_dir, &suggested_slug)?; - Ok(PlanPromptContext { - session_id: session_id.to_string(), - target_plan_path: path.display().to_string(), - target_plan_exists: false, - target_plan_slug: suggested_slug, - active_plan: None, - }) -} - -pub(crate) fn build_mode_prompt_declarations( - spec: &GovernanceModeSpec, - artifact_state: &PlanPromptContext, - workflow_facts: &ModeWorkflowPromptFacts, -) -> Vec { - let Some(hooks) = spec.prompt_hooks.as_ref() else { - return Vec::new(); - }; - - if let Some(summary) = workflow_facts.approved_plan.as_ref() { - return hooks - .exit_prompt - .as_ref() - .map(|template| { - vec![build_hook_declaration( - spec, - artifact_state, - "exit", - "Mode Exit", - format!( - "{}\n\nApproved plan artifact:\n- path: {}\n- slug: {}\n- title: {}\n- \ - status: {}", - render_mode_prompt_hook_template(template, artifact_state), - summary.path, - summary.slug, - summary.title, - summary.status - ), - Some(605), - )] - }) - .unwrap_or_default(); - } - - let mut declarations = Vec::new(); - if let Some(template) = hooks.facts_template.as_ref() { - declarations.push(build_hook_declaration( - spec, - artifact_state, - "facts", - "Mode Artifact Facts", - render_mode_prompt_hook_template(template, artifact_state), - Some(605), - )); - } - - let active_template = if artifact_state.active_plan.is_some() { - hooks.reentry_prompt.as_ref().map(|template| { - ( - "reentry", - "Mode Re-entry", - render_mode_prompt_hook_template(template, artifact_state), - ) - }) - } else { - hooks.initial_template.as_ref().map(|template| { - ( - "template", - "Mode Template", - render_mode_prompt_hook_template(template, artifact_state), - ) - }) - }; - if let Some((suffix, title, content)) = active_template { - declarations.push(build_hook_declaration( - spec, - artifact_state, - suffix, - title, - content, - Some(604), - )); - } - - declarations -} - -pub(crate) fn build_plan_prompt_declarations( - spec: &GovernanceModeSpec, - context: &PlanPromptContext, -) -> Vec { - build_mode_prompt_declarations(spec, context, &ModeWorkflowPromptFacts::default()) -} - -pub(crate) fn build_plan_exit_declaration( - spec: &GovernanceModeSpec, - session_id: &str, - summary: &SessionPlanSummary, -) -> Option { - let context = PlanPromptContext { - session_id: session_id.to_string(), - target_plan_path: summary.path.clone(), - target_plan_exists: Path::new(&summary.path).exists(), - target_plan_slug: summary.slug.clone(), - active_plan: Some(summary.clone()), - }; - build_mode_prompt_declarations( - spec, - &context, - &ModeWorkflowPromptFacts { - approved_plan: Some(summary.clone()), - }, - ) - .into_iter() - .next() -} - -pub(crate) fn build_plan_draft_approval_guard_declaration( - spec: &GovernanceModeSpec, - context: &PlanPromptContext, - matched_phrase: Option<&str>, -) -> PromptDeclaration { - let active_plan = context - .active_plan - .as_ref() - .map(|plan| { - format!( - "title={}, status={}, path={}", - plan.title, plan.status, plan.path - ) - }) - .unwrap_or_else(|| "(none)".to_string()); - let matched_phrase = matched_phrase.unwrap_or("(unknown)"); - build_hook_declaration( - spec, - context, - "draft-approval-guard", - "Draft Approval Guard", - format!( - "用户这条消息命中了批准/开工语义（matchedPhrase: {matched_phrase}），但当前 canonical \ - session plan 仍然是 draft，尚未进入 \ - awaiting_approval，也还没有被正式呈递给用户。\n\n当前 active plan: \ - {active_plan}\ntargetPlanPath: \ - {}\n\n把这条消息解释成：继续把现有计划打磨到可呈递，而不是立即执行计划。\n硬约束：\\ - n- 保持在 plan mode，不要切换到执行语义。\n- \ - 不要声称“开始执行/已经开始做/总结如下/最终摘要如下”等执行态结果。\n- \ - 不要输出计划外的最终产物正文，也不要提前给出任何最终总结内容。\n- \ - 只允许继续审查上下文、修订 canonical plan，并在计划真正可执行后调用 `exitPlanMode` \ - 呈递审批。\n- 在完成修订并真正呈递前，assistant \ - 对用户的自然语言回复最多只能是一句简短确认，例如：“收到，我先把草稿补全为可呈递版本，\ - 再交给你确认。” 不要展开正文，不要重复计划内容。", - context.target_plan_path - ), - Some(606), - ) -} - -pub(crate) fn build_plan_draft_approval_guard_injected_messages( - context: &PlanPromptContext, - matched_phrase: Option<&str>, -) -> Vec { - let matched_phrase = matched_phrase.unwrap_or("(unknown)"); - vec![LlmMessage::User { - content: format!( - "{SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER}\\ - n内部执行约束（不要在对用户可见输出中复述）：当前 canonical session plan 仍是 \ - draft，尚未进入 \ - awaiting_approval，也还没有正式呈递给用户。下一条真实用户消息虽然命中了批准/\ - 开工语义（matchedPhrase: \ - {matched_phrase}），但只能被解释为“继续把草稿修订为可呈递版本”，不能解释为批准执行。\\ - \ - n\n当前 targetPlanPath: {}\n当前 activePlanStatus: {}\n\n硬约束：\n- \ - 不要开始执行计划，不要切换到执行态语义。\n- \ - 不要输出任何最终总结、计划摘要正文或任务结果正文。\n- \ - 如果必须回复自然语言，最多只允许一句简短确认：“收到，我先把草稿补全为可呈递版本，\ - 再交给你确认。”\n- 优先通过修订 canonical plan \ - 让其进入可呈递状态；只有真正可呈递时才调用 `exitPlanMode`。", - context.target_plan_path, - context - .active_plan - .as_ref() - .map(|plan| plan.status.as_str()) - .unwrap_or("draft") - ), - origin: UserMessageOrigin::ReactivationPrompt, - }] -} - -pub(crate) fn build_execute_bridge_declaration( - session_id: &str, - bridge: &PlanToExecuteBridgeState, -) -> PromptDeclaration { - let step_lines = if bridge.implementation_steps.is_empty() { - "- implementationSteps: (none)".to_string() - } else { - bridge - .implementation_steps - .iter() - .map(|step| format!("{}. {}", step.index, step.summary)) - .collect::>() - .join("\n") - }; - PromptDeclaration { - block_id: format!("session.plan.execute-bridge.{session_id}"), - title: "Plan Execute Bridge".to_string(), - content: format!( - "Execute phase bridge:\n- planPath: {}\n- planTitle: {}\n- approvedAt: {}\n- \ - implementationSteps:\n{}", - bridge.plan_artifact.path, - bridge.plan_title, - bridge - .approved_at - .map(|value| value.to_rfc3339()) - .unwrap_or_else(|| "(unknown)".to_string()), - step_lines - ), - render_target: astrcode_core::PromptDeclarationRenderTarget::System, - layer: astrcode_core::SystemPromptLayer::Dynamic, - kind: astrcode_core::PromptDeclarationKind::ExtensionInstruction, - priority_hint: Some(605), - always_include: true, - source: astrcode_core::PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some("session-plan:execute-bridge".to_string()), - } -} - -pub(crate) fn parse_plan_approval(text: &str) -> PlanApprovalParseResult { - let normalized_english = text - .to_ascii_lowercase() - .split_whitespace() - .collect::>() - .join(" "); - for phrase in ["approved", "go ahead", "implement it"] { - if normalized_english == phrase - || (phrase != "implement it" && normalized_english.starts_with(&format!("{phrase} "))) - { - return PlanApprovalParseResult { - approved: true, - matched_phrase: Some(phrase), - }; - } - } - - let normalized_chinese = text - .chars() - .filter(|ch| !ch.is_whitespace() && !is_common_punctuation(*ch)) - .collect::(); - for phrase in ["同意", "可以", "按这个做", "开始实现"] { - let matched = match phrase { - "同意" | "可以" => normalized_chinese == phrase, - _ => normalized_chinese == phrase || normalized_chinese.starts_with(phrase), - }; - if matched { - return PlanApprovalParseResult { - approved: true, - matched_phrase: Some(phrase), - }; - } - } - - PlanApprovalParseResult { - approved: false, - matched_phrase: None, - } -} - -pub(crate) fn parse_plan_workflow_signal( - text: &str, - plan_state: Option<&SessionPlanState>, -) -> Option { - if active_plan_requires_approval(plan_state) && parse_plan_approval(text).approved { - return Some(WorkflowSignal::Approve); - } - - let normalized_english = text - .trim() - .to_ascii_lowercase() - .split_whitespace() - .collect::>() - .join(" "); - for phrase in ["replan", "back to plan", "revise plan", "request changes"] { - if normalized_english == phrase || normalized_english.starts_with(&format!("{phrase} ")) { - return Some(match phrase { - "request changes" => WorkflowSignal::RequestChanges, - _ => WorkflowSignal::Replan, - }); - } - } - - let normalized_chinese = text - .chars() - .filter(|ch| !ch.is_whitespace() && !is_common_punctuation(*ch)) - .collect::(); - for phrase in ["重新规划", "重新计划", "回到计划", "改计划", "需要修改"] { - if normalized_chinese == phrase || normalized_chinese.starts_with(phrase) { - return Some(match phrase { - "需要修改" => WorkflowSignal::RequestChanges, - _ => WorkflowSignal::Replan, - }); - } - } - None -} - -pub(crate) fn active_plan_requires_approval(state: Option<&SessionPlanState>) -> bool { - state.is_some_and(|state| state.status == SessionPlanStatus::AwaitingApproval) -} - -pub(crate) fn planning_phase_allows_review_mode( - mode_id: &ModeId, - plan_state: Option<&SessionPlanState>, -) -> bool { - *mode_id == ModeId::code() && active_plan_requires_approval(plan_state) -} - -pub(crate) fn mark_active_session_plan_approved( - session_id: &str, - working_dir: &Path, -) -> Result, ApplicationError> { - let Some(mut state) = load_session_plan_state(session_id, working_dir)? else { - return Ok(None); - }; - if state.status != SessionPlanStatus::AwaitingApproval { - return Ok(None); - } - - let plan_path = session_plan_markdown_path(session_id, working_dir, &state.active_plan_slug)?; - let plan_content = - fs::read_to_string(&plan_path).map_err(|error| io_error("reading", &plan_path, error))?; - let plan_content = plan_content.trim().to_string(); - let content_digest = session_plan_content_digest(&plan_content); - let now = Utc::now(); - - state.status = SessionPlanStatus::Approved; - state.updated_at = now; - state.approved_at = Some(now); - if state.archived_plan_digest.as_deref() != Some(content_digest.as_str()) { - let archive_summary = write_plan_archive_snapshot( - session_id, - working_dir, - &state, - &plan_path, - &plan_content, - &content_digest, - now, - )?; - state.archived_plan_digest = Some(content_digest); - state.archived_at = Some(archive_summary.metadata.archived_at); - } - persist_plan_state(&session_plan_state_path(session_id, working_dir)?, &state)?; - Ok(Some(plan_summary(session_id, working_dir, &state)?)) -} - -pub(crate) fn copy_session_plan_artifacts( - source_session_id: &str, - target_session_id: &str, - working_dir: &Path, -) -> Result<(), ApplicationError> { - let source_dir = session_plan_dir(source_session_id, working_dir)?; - if !source_dir.exists() { - return Ok(()); - } - let target_dir = session_plan_dir(target_session_id, working_dir)?; - copy_dir_recursive(&source_dir, &target_dir) -} - -pub(crate) fn current_mode_requires_plan_context(mode_id: &ModeId) -> bool { - mode_id == &ModeId::plan() -} - -pub(crate) fn list_project_plan_archives( - working_dir: &Path, -) -> Result, ApplicationError> { - let archive_root = project_plan_archive_dir(working_dir)?; - if !archive_root.exists() { - return Ok(Vec::new()); - } - let mut items = Vec::new(); - for entry in fs::read_dir(&archive_root) - .map_err(|error| io_error("reading directory", &archive_root, error))? - { - let entry = - entry.map_err(|error| io_error("reading directory entry", &archive_root, error))?; - let archive_dir = entry.path(); - if !entry - .file_type() - .map_err(|error| io_error("reading file type", &archive_dir, error))? - .is_dir() - { - continue; - } - let metadata_path = archive_dir.join(PLAN_ARCHIVE_METADATA_FILE_NAME); - let plan_path = archive_dir.join(PLAN_ARCHIVE_FILE_NAME); - if !metadata_path.exists() || !plan_path.exists() { - continue; - } - let metadata = fs::read_to_string(&metadata_path) - .map_err(|error| io_error("reading", &metadata_path, error)) - .and_then(|content| { - serde_json::from_str::(&content).map_err(|error| { - ApplicationError::Internal(format!( - "failed to parse plan archive metadata '{}': {error}", - metadata_path.display() - )) - }) - })?; - items.push(ProjectPlanArchiveSummary { - archive_dir: archive_dir.display().to_string(), - plan_path: plan_path.display().to_string(), - metadata, - }); - } - items.sort_by(|left, right| { - right - .metadata - .archived_at - .cmp(&left.metadata.archived_at) - .then_with(|| left.metadata.archive_id.cmp(&right.metadata.archive_id)) - }); - Ok(items) -} - -pub(crate) fn read_project_plan_archive( - working_dir: &Path, - archive_id: &str, -) -> Result, ApplicationError> { - let (archive_dir, plan_path, metadata_path) = archive_paths(working_dir, archive_id)?; - if !plan_path.exists() || !metadata_path.exists() { - return Ok(None); - } - let metadata = fs::read_to_string(&metadata_path) - .map_err(|error| io_error("reading", &metadata_path, error)) - .and_then(|content| { - serde_json::from_str::(&content).map_err(|error| { - ApplicationError::Internal(format!( - "failed to parse plan archive metadata '{}': {error}", - metadata_path.display() - )) - }) - })?; - let content = - fs::read_to_string(&plan_path).map_err(|error| io_error("reading", &plan_path, error))?; - Ok(Some(ProjectPlanArchiveDetail { - summary: ProjectPlanArchiveSummary { - metadata, - archive_dir: archive_dir.display().to_string(), - plan_path: plan_path.display().to_string(), - }, - content, - })) -} - -fn persist_plan_state(path: &Path, state: &SessionPlanState) -> Result<(), ApplicationError> { - let Some(parent) = path.parent() else { - return Err(ApplicationError::Internal(format!( - "session plan state '{}' has no parent directory", - path.display() - ))); - }; - fs::create_dir_all(parent).map_err(|error| io_error("creating directory", parent, error))?; - let content = serde_json::to_string_pretty(state).map_err(|error| { - ApplicationError::Internal(format!( - "failed to serialize session plan state '{}': {error}", - path.display() - )) - })?; - fs::write(path, content).map_err(|error| io_error("writing", path, error)) -} - -fn plan_summary( - session_id: &str, - working_dir: &Path, - state: &SessionPlanState, -) -> Result { - Ok(SessionPlanSummary { - slug: state.active_plan_slug.clone(), - path: session_plan_markdown_path(session_id, working_dir, &state.active_plan_slug)? - .display() - .to_string(), - status: state.status.to_string(), - title: state.title.clone(), - updated_at: state.updated_at, - }) -} - -fn write_plan_archive_snapshot( - session_id: &str, - working_dir: &Path, - state: &SessionPlanState, - plan_path: &Path, - plan_content: &str, - content_digest: &str, - approved_at: DateTime, -) -> Result { - let archived_at = Utc::now(); - let archive_root = project_plan_archive_dir(working_dir)?; - fs::create_dir_all(&archive_root) - .map_err(|error| io_error("creating directory", &archive_root, error))?; - let archive_id = reserve_archive_id(&archive_root, approved_at, &state.active_plan_slug)?; - let (archive_dir, archive_plan_path, metadata_path) = archive_paths(working_dir, &archive_id)?; - fs::create_dir_all(&archive_dir) - .map_err(|error| io_error("creating directory", &archive_dir, error))?; - fs::write(&archive_plan_path, format!("{plan_content}\n")) - .map_err(|error| io_error("writing", &archive_plan_path, error))?; - let metadata = ProjectPlanArchiveMetadata { - archive_id: archive_id.clone(), - title: state.title.clone(), - source_session_id: session_id.to_string(), - source_plan_slug: state.active_plan_slug.clone(), - source_plan_path: plan_path.display().to_string(), - approved_at, - archived_at, - status: SessionPlanStatus::Approved.to_string(), - content_digest: content_digest.to_string(), - }; - let metadata_content = serde_json::to_string_pretty(&metadata).map_err(|error| { - ApplicationError::Internal(format!( - "failed to serialize plan archive metadata '{}': {error}", - metadata_path.display() - )) - })?; - fs::write(&metadata_path, metadata_content) - .map_err(|error| io_error("writing", &metadata_path, error))?; - Ok(ProjectPlanArchiveSummary { - metadata, - archive_dir: archive_dir.display().to_string(), - plan_path: archive_plan_path.display().to_string(), - }) -} - -fn reserve_archive_id( - archive_root: &Path, - approved_at: DateTime, - slug: &str, -) -> Result { - let base = format!( - "{}-{}", - approved_at.format(PLAN_PATH_TIMESTAMP_FORMAT), - slug - ); - for attempt in 0..=99 { - let candidate = if attempt == 0 { - base.clone() - } else { - format!("{base}-{attempt}") - }; - if !archive_root.join(&candidate).exists() { - return Ok(candidate); - } - } - Err(ApplicationError::Internal(format!( - "failed to reserve a unique plan archive id for slug '{}'", - slug - ))) -} - -fn validate_archive_id(archive_id: &str) -> Result<(), ApplicationError> { - let archive_id = archive_id.trim(); - if archive_id.is_empty() { - return Err(ApplicationError::InvalidArgument( - "archiveId must not be empty".to_string(), - )); - } - if archive_id.contains("..") - || archive_id.contains('/') - || archive_id.contains('\\') - || Path::new(archive_id).is_absolute() - { - return Err(ApplicationError::InvalidArgument(format!( - "archiveId '{}' is invalid", - archive_id - ))); - } - Ok(()) -} - -fn copy_dir_recursive(source: &Path, target: &Path) -> Result<(), ApplicationError> { - fs::create_dir_all(target).map_err(|error| io_error("creating directory", target, error))?; - for entry in - fs::read_dir(source).map_err(|error| io_error("reading directory", source, error))? - { - let entry = entry.map_err(|error| io_error("reading directory entry", source, error))?; - let source_path = entry.path(); - let target_path = target.join(entry.file_name()); - let file_type = entry - .file_type() - .map_err(|error| io_error("reading file type", &source_path, error))?; - if file_type.is_dir() { - copy_dir_recursive(&source_path, &target_path)?; - } else { - fs::copy(&source_path, &target_path) - .map_err(|error| io_error("copying file", &source_path, error))?; - } - } - Ok(()) -} - -fn is_common_punctuation(ch: char) -> bool { - matches!( - ch, - ',' | '.' | ';' | ':' | '!' | '?' | '，' | '。' | '；' | '：' | '！' | '？' | '、' - ) -} - -fn slugify_plan_topic(input: &str) -> Option { - let mut slug = String::new(); - let mut last_dash = false; - for ch in input.chars().map(|ch| ch.to_ascii_lowercase()) { - if ch.is_ascii_alphanumeric() { - slug.push(ch); - last_dash = false; - continue; - } - if !last_dash && !slug.is_empty() { - slug.push('-'); - last_dash = true; - } - if slug.len() >= 48 { - break; - } - } - let slug = slug.trim_matches('-').to_string(); - if slug.is_empty() { None } else { Some(slug) } -} - -fn build_hook_declaration( - spec: &GovernanceModeSpec, - artifact_state: &PlanPromptContext, - suffix: &str, - title: &str, - content: String, - priority_hint: Option, -) -> PromptDeclaration { - PromptDeclaration { - block_id: format!( - "mode.{}.{}.{}", - spec.id.as_str(), - suffix, - artifact_state.session_id - ), - title: format!("{} {}", spec.name, title), - content, - render_target: astrcode_core::PromptDeclarationRenderTarget::System, - layer: astrcode_core::SystemPromptLayer::Dynamic, - kind: astrcode_core::PromptDeclarationKind::ExtensionInstruction, - priority_hint, - always_include: true, - source: astrcode_core::PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some(format!("mode-hook:{}:{}", spec.id, suffix)), - } -} - -fn render_mode_prompt_hook_template(template: &str, artifact_state: &PlanPromptContext) -> String { - template - .replace("{{targetPlanPath}}", &artifact_state.target_plan_path) - .replace( - "{{targetPlanExists}}", - if artifact_state.target_plan_exists { - "true" - } else { - "false" - }, - ) - .replace("{{targetPlanSlug}}", &artifact_state.target_plan_slug) - .replace( - "{{activePlanSummary}}", - &artifact_state - .active_plan - .as_ref() - .map(|plan| { - format!( - "slug={}, title={}, status={}, path={}", - plan.slug, plan.title, plan.status, plan.path - ) - }) - .unwrap_or_else(|| "(none)".to_string()), - ) -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::builtin_mode_catalog; - - #[test] - fn parse_plan_approval_is_conservative() { - assert!(parse_plan_approval("同意").approved); - assert!(parse_plan_approval("按这个做，开始吧").approved); - assert!(parse_plan_approval("approved please continue").approved); - assert!(!parse_plan_approval("可以再想想").approved); - assert!(!parse_plan_approval("don't implement it yet").approved); - } - - #[test] - fn copy_session_plan_artifacts_ignores_missing_source() { - let temp = tempfile::tempdir().expect("tempdir should exist"); - copy_session_plan_artifacts("session-a", "session-b", temp.path()) - .expect("missing source should be ignored"); - } - - #[test] - fn session_plan_state_round_trips_through_json_schema() { - let state = SessionPlanState { - active_plan_slug: "cleanup-crates".to_string(), - title: "Cleanup crates".to_string(), - status: SessionPlanStatus::AwaitingApproval, - created_at: Utc::now(), - updated_at: Utc::now(), - reviewed_plan_digest: Some("abc".to_string()), - approved_at: None, - archived_plan_digest: Some("def".to_string()), - archived_at: None, - }; - - let encoded = serde_json::to_string(&state).expect("state should serialize"); - let decoded = - serde_json::from_str::(&encoded).expect("state should deserialize"); - assert_eq!(decoded.active_plan_slug, "cleanup-crates"); - assert_eq!(decoded.archived_plan_digest.as_deref(), Some("def")); - } - - #[test] - fn build_plan_prompt_declarations_include_single_plan_facts() { - let spec = builtin_mode_catalog() - .expect("builtin catalog should build") - .get(&ModeId::plan()) - .expect("plan mode should exist"); - let declarations = build_plan_prompt_declarations( - &spec, - &PlanPromptContext { - session_id: "session-a".to_string(), - target_plan_path: "/tmp/cleanup-crates.md".to_string(), - target_plan_exists: false, - target_plan_slug: "cleanup-crates".to_string(), - active_plan: None, - }, - ); - - assert_eq!(declarations.len(), 2); - assert!( - declarations[0] - .content - .contains("targetPlanPath: /tmp/cleanup-crates.md") - ); - assert!(declarations[1].content.contains("## Implementation Steps")); - } - - #[test] - fn build_mode_prompt_declarations_emit_exit_prompt_from_mode_hooks() { - let spec = builtin_mode_catalog() - .expect("builtin catalog should build") - .get(&ModeId::plan()) - .expect("plan mode should exist"); - let declarations = build_mode_prompt_declarations( - &spec, - &PlanPromptContext { - session_id: "session-a".to_string(), - target_plan_path: "/tmp/cleanup-crates.md".to_string(), - target_plan_exists: true, - target_plan_slug: "cleanup-crates".to_string(), - active_plan: Some(SessionPlanSummary { - slug: "cleanup-crates".to_string(), - path: "/tmp/cleanup-crates.md".to_string(), - status: "approved".to_string(), - title: "Cleanup crates".to_string(), - updated_at: Utc::now(), - }), - }, - &ModeWorkflowPromptFacts { - approved_plan: Some(SessionPlanSummary { - slug: "cleanup-crates".to_string(), - path: "/tmp/cleanup-crates.md".to_string(), - status: "approved".to_string(), - title: "Cleanup crates".to_string(), - updated_at: Utc::now(), - }), - }, - ); - - assert_eq!(declarations.len(), 1); - assert!(declarations[0].content.contains("Approved plan artifact")); - assert!(declarations[0].content.contains("Cleanup crates")); - } - - #[test] - fn reserve_archive_id_adds_suffix_on_collision() { - let temp = tempfile::tempdir().expect("tempdir should exist"); - let root = temp.path(); - fs::create_dir_all(root.join("20260419T000000Z-cleanup-crates")) - .expect("seed dir should exist"); - let candidate = reserve_archive_id( - root, - DateTime::parse_from_rfc3339("2026-04-19T00:00:00Z") - .expect("datetime should parse") - .with_timezone(&Utc), - "cleanup-crates", - ) - .expect("candidate should be reserved"); - assert_eq!(candidate, "20260419T000000Z-cleanup-crates-1"); - } - - #[test] - fn read_project_plan_archive_returns_saved_content() { - let _guard = astrcode_core::test_support::TestEnvGuard::new(); - let working_dir = _guard.home_dir().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - let archive_root = - project_plan_archive_dir(&working_dir).expect("archive root should resolve"); - fs::create_dir_all(archive_root.join("archive-a")).expect("archive dir should exist"); - fs::write( - archive_root.join("archive-a").join(PLAN_ARCHIVE_FILE_NAME), - "# Plan\n", - ) - .expect("plan should be written"); - fs::write( - archive_root - .join("archive-a") - .join(PLAN_ARCHIVE_METADATA_FILE_NAME), - serde_json::to_string_pretty(&ProjectPlanArchiveMetadata { - archive_id: "archive-a".to_string(), - title: "Cleanup crates".to_string(), - source_session_id: "session-a".to_string(), - source_plan_slug: "cleanup-crates".to_string(), - source_plan_path: "/tmp/cleanup-crates.md".to_string(), - approved_at: Utc::now(), - archived_at: Utc::now(), - status: "approved".to_string(), - content_digest: "abc".to_string(), - }) - .expect("metadata should serialize"), - ) - .expect("metadata should be written"); - - let archive = read_project_plan_archive(&working_dir, "archive-a") - .expect("archive should load") - .expect("archive should exist"); - assert_eq!(archive.summary.metadata.archive_id, "archive-a"); - assert_eq!(archive.content, "# Plan\n"); - } - - #[test] - fn read_project_plan_archive_rejects_path_traversal_archive_id() { - let temp = tempfile::tempdir().expect("tempdir should exist"); - let working_dir = temp.path().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - - let error = read_project_plan_archive(&working_dir, "../secrets") - .expect_err("path traversal archive id should be rejected"); - - assert!(matches!(error, ApplicationError::InvalidArgument(_))); - assert!(error.to_string().contains("archiveId")); - } -} diff --git a/crates/application/src/session_use_cases.rs b/crates/application/src/session_use_cases.rs deleted file mode 100644 index fc5c95b2..00000000 --- a/crates/application/src/session_use_cases.rs +++ /dev/null @@ -1,1353 +0,0 @@ -//! Session 用例（`App` 的 session 相关方法）。 -//! -//! 用户直接发起的 session 操作：prompt 提交、compact、mode 切换、 -//! session 列表查询、快照查询等。这些方法组装治理面并委托到 session-runtime。 - -use std::path::{Path, PathBuf}; - -use astrcode_core::{ - AgentEventContext, ChildSessionNode, DeleteProjectResult, ExecutionAccepted, LlmMessage, - ModeId, PromptDeclaration, SessionMeta, SessionPlanStatus, StoredEvent, -}; - -use crate::{ - App, ApplicationError, CompactSessionAccepted, CompactSessionSummary, ExecutionControl, - ModeSummary, ProjectPlanArchiveDetail, ProjectPlanArchiveSummary, PromptAcceptedSummary, - PromptSkillInvocation, SessionControlStateSnapshot, SessionListSummary, SessionReplay, - SessionTranscriptSnapshot, - agent::{ - IMPLICIT_ROOT_PROFILE_ID, implicit_session_root_agent_id, root_execution_event_context, - }, - format_local_rfc3339, - governance_surface::{GovernanceBusyPolicy, SessionGovernanceInput}, - session_identity::normalize_external_session_id, - session_plan::{ - active_plan_requires_approval, build_plan_draft_approval_guard_declaration, - build_plan_draft_approval_guard_injected_messages, build_plan_exit_declaration, - build_plan_prompt_context, build_plan_prompt_declarations, copy_session_plan_artifacts, - current_mode_requires_plan_context, list_project_plan_archives, load_session_plan_state, - mark_active_session_plan_approved, parse_plan_approval, parse_plan_workflow_signal, - read_project_plan_archive, - }, - workflow::{ - EXECUTING_PHASE_ID, PLANNING_PHASE_ID, WorkflowInstanceState, WorkflowStateService, - advance_plan_workflow_to_execution, bootstrap_plan_workflow_state, - build_execute_phase_prompt_declaration, reconcile_workflow_phase_mode, - revert_execution_to_planning_workflow_state, - }, -}; - -#[derive(Debug, Default)] -struct PreparedSessionSubmission { - current_mode_id: ModeId, - prompt_declarations: Vec, - injected_messages: Vec, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum SessionForkSelector { - Latest, - TurnEnd { turn_id: String }, - StorageSeq { storage_seq: u64 }, -} - -impl App { - fn plan_mode_spec(&self) -> Result { - self.mode_catalog() - .get(&ModeId::plan()) - .ok_or_else(|| ApplicationError::Internal("builtin plan mode is missing".to_string())) - } - - pub async fn list_sessions(&self) -> Result, ApplicationError> { - self.session_runtime - .list_session_metas() - .await - .map_err(ApplicationError::from) - } - - pub async fn create_session( - &self, - working_dir: impl Into, - ) -> Result { - let working_dir = normalize_application_working_dir(working_dir.into())?; - self.session_runtime - .create_session(working_dir) - .await - .map_err(ApplicationError::from) - } - - pub async fn delete_session(&self, session_id: &str) -> Result<(), ApplicationError> { - self.session_runtime - .delete_session(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn fork_session( - &self, - session_id: &str, - selector: SessionForkSelector, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - if let SessionForkSelector::TurnEnd { turn_id } = &selector { - self.validate_non_empty("turnId", turn_id)?; - } - let source_working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await?; - let meta = self - .session_runtime - .fork_session(session_id, selector) - .await - .map_err(ApplicationError::from)?; - copy_session_plan_artifacts( - session_id, - meta.session_id.as_str(), - Path::new(&source_working_dir), - )?; - Ok(meta) - } - - pub async fn delete_project( - &self, - working_dir: &str, - ) -> Result { - let working_dir = normalize_application_working_dir(working_dir.to_string())?; - self.session_runtime - .delete_project(&working_dir) - .await - .map_err(ApplicationError::from) - } - - pub fn list_project_plan_archives( - &self, - working_dir: &Path, - ) -> Result, ApplicationError> { - list_project_plan_archives(working_dir) - } - - pub fn read_project_plan_archive( - &self, - working_dir: &Path, - archive_id: &str, - ) -> Result, ApplicationError> { - self.validate_non_empty("archiveId", archive_id)?; - read_project_plan_archive(working_dir, archive_id) - } - - pub async fn submit_prompt( - &self, - session_id: &str, - text: String, - ) -> Result { - self.submit_prompt_with_options(session_id, text, None, None) - .await - } - - pub async fn submit_prompt_with_control( - &self, - session_id: &str, - text: String, - control: Option, - ) -> Result { - self.submit_prompt_with_options(session_id, text, control, None) - .await - } - - /// 带 skill 调用选项的 prompt 提交。 - /// - /// 完整流程： - /// 1. 规范化文本（处理 skill invocation 与纯文本的交互） - /// 2. 校验 ExecutionControl 参数 - /// 3. 加载 runtime 配置 + 确保 session root agent context - /// 4. 若有 skill invocation，解析 skill 并构建 prompt declaration - /// 5. 构建治理面（工具白名单、审批策略、协作指导等） - /// 6. 委托 session-runtime 提交 prompt - pub async fn submit_prompt_with_options( - &self, - session_id: &str, - text: String, - control: Option, - skill_invocation: Option, - ) -> Result { - let text = normalize_submission_text(text, skill_invocation.as_ref())?; - if let Some(control) = &control { - control.validate()?; - } - let working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await?; - let runtime = self - .config_service - .load_resolved_runtime_config(Some(Path::new(&working_dir)))?; - let root_agent = self.ensure_session_root_agent_context(session_id).await?; - let mut current_mode_id = self - .session_runtime - .session_mode_state(session_id) - .await - .map_err(ApplicationError::from)? - .current_mode_id; - let submission = self - .prepare_session_submission( - session_id, - Path::new(&working_dir), - &text, - current_mode_id.clone(), - ) - .await?; - current_mode_id = submission.current_mode_id; - let mut prompt_declarations = submission.prompt_declarations; - let mut injected_messages = submission.injected_messages; - - if let Some(skill_invocation) = skill_invocation { - prompt_declarations.push( - self.build_submission_skill_declaration( - Path::new(&working_dir), - &skill_invocation, - )?, - ); - } - let mut surface = self.governance_surface.session_surface( - self.kernel.as_ref(), - SessionGovernanceInput { - session_id: session_id.to_string(), - turn_id: astrcode_core::generate_turn_id(), - working_dir: working_dir.clone(), - profile: root_agent - .agent_profile - .clone() - .unwrap_or_else(|| IMPLICIT_ROOT_PROFILE_ID.to_string()), - mode_id: current_mode_id, - runtime, - control, - extra_prompt_declarations: prompt_declarations, - busy_policy: GovernanceBusyPolicy::BranchOnBusy, - }, - )?; - surface.injected_messages.append(&mut injected_messages); - self.session_runtime - .submit_prompt_for_agent( - session_id, - text, - surface.runtime.clone(), - surface.into_submission(root_agent, None), - ) - .await - .map_err(ApplicationError::from) - } - - async fn prepare_session_submission( - &self, - session_id: &str, - working_dir: &Path, - text: &str, - current_mode_id: ModeId, - ) -> Result { - let workflow_state_path = WorkflowStateService::state_path(session_id, working_dir)?; - let workflow_state_exists = workflow_state_path.exists(); - let mut workflow_state = self - .workflow() - .load_active_workflow(session_id, working_dir)?; - if workflow_state.is_none() && !workflow_state_exists { - workflow_state = - bootstrap_plan_workflow_state(session_id, working_dir, ¤t_mode_id)?; - if let Some(state) = workflow_state.as_ref() { - self.workflow() - .persist_active_workflow(session_id, working_dir, state)?; - } - } - - match workflow_state { - Some(workflow_state) => { - self.prepare_active_workflow_submission( - session_id, - working_dir, - text, - current_mode_id, - workflow_state, - ) - .await - }, - None => { - self.prepare_mode_only_submission(session_id, working_dir, text, current_mode_id) - .await - }, - } - } - - async fn prepare_mode_only_submission( - &self, - session_id: &str, - working_dir: &Path, - text: &str, - mut current_mode_id: ModeId, - ) -> Result { - let mut prompt_declarations = Vec::new(); - let mut injected_messages = Vec::new(); - let plan_state = load_session_plan_state(session_id, working_dir)?; - let plan_approval = parse_plan_approval(text); - let plan_mode_spec = self.plan_mode_spec()?; - - if active_plan_requires_approval(plan_state.as_ref()) && plan_approval.approved { - let approved_plan = mark_active_session_plan_approved(session_id, working_dir)?; - if current_mode_id == ModeId::plan() { - self.switch_mode(session_id, ModeId::code()).await?; - current_mode_id = ModeId::code(); - } - if let Some(summary) = approved_plan { - if let Some(declaration) = - build_plan_exit_declaration(&plan_mode_spec, session_id, &summary) - { - prompt_declarations.push(declaration); - } - } - } else if current_mode_id == ModeId::plan() - && current_mode_requires_plan_context(¤t_mode_id) - && (!plan_approval.approved - || plan_state - .as_ref() - .is_some_and(|state| state.status == SessionPlanStatus::Draft)) - { - let context = build_plan_prompt_context(session_id, working_dir, text)?; - if plan_approval.approved - && plan_state - .as_ref() - .is_some_and(|state| state.status == SessionPlanStatus::Draft) - { - injected_messages.extend(build_plan_draft_approval_guard_injected_messages( - &context, - plan_approval.matched_phrase, - )); - prompt_declarations.push(build_plan_draft_approval_guard_declaration( - &plan_mode_spec, - &context, - plan_approval.matched_phrase, - )); - } - prompt_declarations.extend(build_plan_prompt_declarations(&plan_mode_spec, &context)); - } - - Ok(PreparedSessionSubmission { - current_mode_id, - prompt_declarations, - injected_messages, - }) - } - - async fn prepare_active_workflow_submission( - &self, - session_id: &str, - working_dir: &Path, - text: &str, - mut current_mode_id: ModeId, - mut workflow_state: WorkflowInstanceState, - ) -> Result { - let plan_state = load_session_plan_state(session_id, working_dir)?; - let plan_approval = parse_plan_approval(text); - let signal = parse_plan_workflow_signal(text, plan_state.as_ref()); - let mut prompt_declarations = Vec::new(); - let mut injected_messages = Vec::new(); - let plan_mode_spec = self.plan_mode_spec()?; - - if let Some(signal) = signal { - if let Some(transition) = self - .workflow() - .transition_for_signal(&workflow_state, signal)? - { - workflow_state = match ( - transition.source_phase_id.as_str(), - transition.target_phase_id.as_str(), - ) { - (PLANNING_PHASE_ID, EXECUTING_PHASE_ID) => { - advance_plan_workflow_to_execution(session_id, working_dir)? - .map(|(state, declaration)| { - prompt_declarations.push(declaration); - state - }) - .ok_or_else(|| { - ApplicationError::Internal( - "plan approval signal did not produce an executing workflow \ - state" - .to_string(), - ) - })? - }, - (EXECUTING_PHASE_ID, PLANNING_PHASE_ID) => { - revert_execution_to_planning_workflow_state(session_id, working_dir)? - }, - _ => { - return Err(ApplicationError::Internal(format!( - "unsupported workflow transition '{} -> {}'", - transition.source_phase_id, transition.target_phase_id - ))); - }, - }; - self.workflow().persist_active_workflow( - session_id, - working_dir, - &workflow_state, - )?; - } - } - - current_mode_id = reconcile_workflow_phase_mode( - self.workflow(), - session_id, - working_dir, - current_mode_id, - &workflow_state, - plan_state.as_ref(), - |mode_id| { - let session_id = session_id.to_string(); - async move { self.switch_mode(&session_id, mode_id).await } - }, - ) - .await?; - - match workflow_state.current_phase_id.as_str() { - PLANNING_PHASE_ID => { - let context = build_plan_prompt_context(session_id, working_dir, text)?; - if plan_approval.approved - && plan_state - .as_ref() - .is_some_and(|state| state.status == SessionPlanStatus::Draft) - { - injected_messages.extend(build_plan_draft_approval_guard_injected_messages( - &context, - plan_approval.matched_phrase, - )); - prompt_declarations.push(build_plan_draft_approval_guard_declaration( - &plan_mode_spec, - &context, - plan_approval.matched_phrase, - )); - } - prompt_declarations - .extend(build_plan_prompt_declarations(&plan_mode_spec, &context)); - }, - EXECUTING_PHASE_ID => { - if prompt_declarations.is_empty() { - if let Some(declaration) = - build_execute_phase_prompt_declaration(session_id, &workflow_state)? - { - prompt_declarations.push(declaration); - } - } - }, - other => { - return Err(ApplicationError::Internal(format!( - "unsupported workflow phase '{other}'" - ))); - }, - } - - Ok(PreparedSessionSubmission { - current_mode_id, - prompt_declarations, - injected_messages, - }) - } - - pub async fn submit_prompt_summary( - &self, - session_id: &str, - text: String, - control: Option, - skill_invocation: Option, - ) -> Result { - let accepted_control = normalize_prompt_control(control)?; - let accepted = self - .submit_prompt_with_options( - session_id, - text, - accepted_control.clone(), - skill_invocation, - ) - .await?; - Ok(PromptAcceptedSummary { - turn_id: accepted.turn_id.to_string(), - session_id: accepted.session_id.to_string(), - branched_from_session_id: accepted.branched_from_session_id, - accepted_control, - }) - } - - pub async fn interrupt_session(&self, session_id: &str) -> Result<(), ApplicationError> { - self.session_runtime - .interrupt_session(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn compact_session( - &self, - session_id: &str, - ) -> Result { - self.compact_session_with_options(session_id, None, None) - .await - } - - pub async fn compact_session_with_control( - &self, - session_id: &str, - control: Option, - ) -> Result { - self.compact_session_with_options(session_id, control, None) - .await - } - - pub async fn compact_session_with_options( - &self, - session_id: &str, - control: Option, - instructions: Option, - ) -> Result { - if let Some(control) = &control { - control.validate()?; - if matches!(control.manual_compact, Some(false)) { - return Err(ApplicationError::InvalidArgument( - "manualCompact must be true for manual compact requests".to_string(), - )); - } - } - let working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await?; - let runtime = self - .config_service - .load_resolved_runtime_config(Some(Path::new(&working_dir)))?; - let deferred = self - .session_runtime - .compact_session(session_id, runtime, instructions) - .await - .map_err(ApplicationError::from)?; - Ok(CompactSessionAccepted { deferred }) - } - - pub async fn compact_session_summary( - &self, - session_id: &str, - control: Option, - instructions: Option, - ) -> Result { - let accepted = self - .compact_session_with_options( - session_id, - normalize_compact_control(control), - normalize_compact_instructions(instructions), - ) - .await?; - Ok(CompactSessionSummary { - accepted: true, - deferred: accepted.deferred, - message: if accepted.deferred { - "手动 compact 已登记，会在当前 turn 完成后执行。".to_string() - } else { - "手动 compact 已执行。".to_string() - }, - }) - } - - pub async fn session_transcript_snapshot( - &self, - session_id: &str, - ) -> Result { - self.session_runtime - .session_transcript_snapshot(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn session_control_state( - &self, - session_id: &str, - ) -> Result { - self.session_runtime - .session_control_state(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn list_modes(&self) -> Result, ApplicationError> { - Ok(self.mode_catalog.list()) - } - - pub async fn session_mode_state( - &self, - session_id: &str, - ) -> Result { - self.session_runtime - .session_mode_state(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn switch_mode( - &self, - session_id: &str, - target_mode_id: ModeId, - ) -> Result { - let current = self - .session_runtime - .session_mode_state(session_id) - .await - .map_err(ApplicationError::from)?; - if current.current_mode_id == target_mode_id { - return Ok(current); - } - crate::validate_mode_transition( - self.mode_catalog.as_ref(), - ¤t.current_mode_id, - &target_mode_id, - ) - .map_err(ApplicationError::from)?; - self.session_runtime - .switch_mode(session_id, current.current_mode_id, target_mode_id) - .await - .map_err(ApplicationError::from)?; - self.session_runtime - .session_mode_state(session_id) - .await - .map_err(ApplicationError::from) - } - - /// 返回指定 session 的 durable 存储事件。 - /// - /// Debug Workbench 需要基于服务端真相构造 trace， - /// 这里显式暴露只读查询入口，避免上层直接穿透到 event store。 - pub async fn session_stored_events( - &self, - session_id: &str, - ) -> Result, ApplicationError> { - self.session_runtime - .session_stored_events(session_id) - .await - .map_err(ApplicationError::from) - } - - /// 返回指定 session 当前投影出的 child lineage 节点。 - /// - /// Debug Workbench 的 agent tree 依赖这个稳定投影，不能在前端根据事件流二次猜测。 - pub async fn session_child_nodes( - &self, - session_id: &str, - ) -> Result, ApplicationError> { - self.session_runtime - .session_child_nodes(session_id) - .await - .map_err(ApplicationError::from) - } - - pub async fn session_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> Result { - self.session_runtime - .session_replay(session_id, last_event_id) - .await - .map_err(ApplicationError::from) - } - - /// 确保 session 存在一个 root agent context，如果没有则自动注册隐式 root agent。 - /// - /// 查找逻辑：先通过 kernel 查找已有 handle，找不到则注册隐式 root agent - /// （ID 为 `root-agent:{session_id}`，profile 为 `default`）。 - /// 这是 prompt 提交前的前置步骤，保证 session 总有一个可用的 agent context。 - pub(crate) async fn ensure_session_root_agent_context( - &self, - session_id: &str, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - let normalized_session_id = normalize_external_session_id(session_id); - - if let Some(handle) = self - .kernel - .find_root_handle_for_session(&normalized_session_id) - .await - { - return Ok(root_execution_event_context( - handle.agent_id, - handle.agent_profile, - )); - } - - let handle = self - .kernel - .register_root_agent( - implicit_session_root_agent_id(&normalized_session_id), - normalized_session_id, - IMPLICIT_ROOT_PROFILE_ID.to_string(), - ) - .await - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to register implicit root agent for session prompt: {error}" - )) - })?; - Ok(root_execution_event_context( - handle.agent_id, - handle.agent_profile, - )) - } - - fn build_submission_skill_declaration( - &self, - working_dir: &Path, - skill_invocation: &PromptSkillInvocation, - ) -> Result { - let skill = self - .composer_skills - .resolve_skill(working_dir, &skill_invocation.skill_id) - .ok_or_else(|| { - ApplicationError::InvalidArgument(format!( - "unknown skill slash command: /{}", - skill_invocation.skill_id - )) - })?; - Ok(self - .governance_surface - .build_submission_skill_declaration(&skill, skill_invocation.user_prompt.as_deref())) - } -} - -fn normalize_application_working_dir(working_dir: String) -> Result { - let trimmed = working_dir.trim(); - if trimmed.is_empty() { - return Err(ApplicationError::InvalidArgument( - "workingDir must not be empty".to_string(), - )); - } - - let normalized = astrcode_session_runtime::normalize_working_dir(PathBuf::from(trimmed)) - .map_err(ApplicationError::from)?; - Ok(normalized.display().to_string()) -} - -pub fn summarize_session_meta(meta: SessionMeta) -> SessionListSummary { - SessionListSummary { - session_id: meta.session_id, - working_dir: meta.working_dir, - display_name: meta.display_name, - title: meta.title, - created_at: format_local_rfc3339(meta.created_at), - updated_at: format_local_rfc3339(meta.updated_at), - parent_session_id: meta.parent_session_id, - parent_storage_seq: meta.parent_storage_seq, - phase: meta.phase, - } -} - -fn normalize_prompt_control( - control: Option, -) -> Result, ApplicationError> { - if let Some(control) = &control { - control.validate()?; - } - Ok(control) -} - -/// 规范化 prompt 提交文本，处理 skill invocation 与纯文本的交互。 -/// -/// - 纯文本提交：不允许空文本 -/// - Skill invocation：文本可以为空（由 skill prompt 填充）， 但如果同时提供了文本和 skill -/// userPrompt，两者必须一致 -fn normalize_submission_text( - text: String, - skill_invocation: Option<&PromptSkillInvocation>, -) -> Result { - let text = text.trim().to_string(); - let Some(skill_invocation) = skill_invocation else { - if text.is_empty() { - return Err(ApplicationError::InvalidArgument( - "prompt must not be empty".to_string(), - )); - } - return Ok(text); - }; - - let skill_prompt = skill_invocation - .user_prompt - .as_deref() - .map(str::trim) - .unwrap_or_default() - .to_string(); - if !text.is_empty() && !skill_prompt.is_empty() && text != skill_prompt { - return Err(ApplicationError::InvalidArgument( - "skillInvocation.userPrompt must match prompt text".to_string(), - )); - } - - if !text.is_empty() { - Ok(text) - } else { - Ok(skill_prompt) - } -} - -/// 为手动 compact 请求构建 ExecutionControl。 -/// -/// 强制设置 `manual_compact = true`（如果调用方未指定）， -/// 因为 compact 的语义要求这个标志。 -fn normalize_compact_control(control: Option) -> Option { - let mut control = control.unwrap_or(ExecutionControl { - manual_compact: None, - }); - if control.manual_compact.is_none() { - control.manual_compact = Some(true); - } - Some(control) -} - -fn normalize_compact_instructions(instructions: Option) -> Option { - instructions - .map(|value| value.trim().to_string()) - .filter(|value| !value.is_empty()) -} - -#[cfg(test)] -mod tests { - use std::{ - fs, - path::{Path, PathBuf}, - sync::Arc, - }; - - use astrcode_core::{ - ExecutionTaskItem, ExecutionTaskStatus, LlmMessage, ModeId, SessionPlanState, - SessionPlanStatus, TaskSnapshot, UserMessageOrigin, - }; - use async_trait::async_trait; - use chrono::Utc; - - use super::*; - use crate::{ - App, AppKernelPort, AppSessionPort, ComposerResolvedSkill, ComposerSkillPort, - McpConfigScope, McpPort, McpServerStatusView, McpService, - agent::test_support::{AgentTestHarness, TestLlmBehavior, build_agent_test_harness}, - composer::ComposerSkillSummary, - governance_surface::GovernanceSurfaceAssembler, - mcp::RegisterMcpServerInput, - mode::builtin_mode_catalog, - session_plan::session_plan_dir, - test_support::StubSessionPort, - }; - - struct EmptyComposerSkillPort; - - impl ComposerSkillPort for EmptyComposerSkillPort { - fn list_skill_summaries(&self, _working_dir: &Path) -> Vec { - Vec::new() - } - - fn resolve_skill( - &self, - _working_dir: &Path, - _skill_id: &str, - ) -> Option { - None - } - } - - struct NoopMcpPort; - - #[async_trait] - impl McpPort for NoopMcpPort { - async fn list_server_status(&self) -> Vec { - Vec::new() - } - - async fn approve_server(&self, _server_signature: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reject_server(&self, _server_signature: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reconnect_server(&self, _name: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reset_project_choices(&self) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn upsert_server( - &self, - _input: &RegisterMcpServerInput, - ) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn remove_server( - &self, - _scope: McpConfigScope, - _name: &str, - ) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn set_server_enabled( - &self, - _scope: McpConfigScope, - _name: &str, - _enabled: bool, - ) -> Result<(), ApplicationError> { - Ok(()) - } - } - - struct SessionUseCasesHarness { - _agent_harness: AgentTestHarness, - _workspace_root: tempfile::TempDir, - app: App, - session_port: Arc, - session_id: String, - working_dir: PathBuf, - } - - impl SessionUseCasesHarness { - fn new(initial_mode: ModeId) -> Self { - let agent_harness = build_agent_test_harness(TestLlmBehavior::Succeed { - content: "ok".to_string(), - }) - .expect("agent harness should build"); - let workspace_root = tempfile::tempdir().expect("workspace root should exist"); - let working_dir = workspace_root.path().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - let session_port = Arc::new(StubSessionPort { - working_dir: Some(working_dir.display().to_string()), - mode_state: Arc::new(std::sync::Mutex::new(Some( - astrcode_session_runtime::SessionModeSnapshot { - current_mode_id: initial_mode, - last_mode_changed_at: None, - }, - ))), - ..StubSessionPort::default() - }); - let kernel: Arc = agent_harness.kernel.clone(); - let session_runtime: Arc = session_port.clone(); - let app = App::new( - kernel, - session_runtime, - agent_harness.profiles.clone(), - agent_harness.config_service.clone(), - Arc::new(EmptyComposerSkillPort), - Arc::new(GovernanceSurfaceAssembler::default()), - Arc::new(builtin_mode_catalog().expect("mode catalog should build")), - Arc::new(McpService::new(Arc::new(NoopMcpPort))), - Arc::new(agent_harness.service.clone()), - ); - Self { - _agent_harness: agent_harness, - _workspace_root: workspace_root, - app, - session_port, - session_id: "session-a".to_string(), - working_dir, - } - } - - fn write_plan_state( - &self, - status: SessionPlanStatus, - content: &str, - ) -> Result<(), ApplicationError> { - let plan_dir = session_plan_dir(&self.session_id, &self.working_dir)?; - fs::create_dir_all(&plan_dir).expect("plan dir should exist"); - fs::write(plan_dir.join("plan.md"), content).expect("plan content should be written"); - let now = Utc::now(); - let state = SessionPlanState { - active_plan_slug: "plan".to_string(), - title: "Plan".to_string(), - status, - created_at: now, - updated_at: now, - reviewed_plan_digest: None, - approved_at: None, - archived_plan_digest: None, - archived_at: None, - }; - fs::write( - plan_dir.join("state.json"), - serde_json::to_string_pretty(&state).expect("plan state should serialize"), - ) - .expect("plan state should be written"); - Ok(()) - } - } - - #[tokio::test] - async fn corrupted_workflow_state_downgrades_to_mode_only_submission() { - let harness = SessionUseCasesHarness::new(ModeId::plan()); - harness - .write_plan_state( - SessionPlanStatus::AwaitingApproval, - "# Plan\n\n## Implementation Steps\n- Keep refining\n", - ) - .expect("plan state should be seeded"); - let workflow_path = - WorkflowStateService::state_path(&harness.session_id, &harness.working_dir) - .expect("workflow path should resolve"); - fs::create_dir_all( - workflow_path - .parent() - .expect("workflow parent should exist"), - ) - .expect("workflow parent should exist"); - fs::write(&workflow_path, "{not-json").expect("invalid workflow should be written"); - - harness - .app - .submit_prompt(&harness.session_id, "继续完善计划".to_string()) - .await - .expect("submission should degrade to mode-only path"); - - let submissions = harness - .session_port - .recorded_submissions - .lock() - .expect("submission record lock should work") - .clone(); - assert_eq!(submissions.len(), 1); - assert!( - submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() == Some("mode-hook:plan:facts")) - ); - assert!( - !submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("session-plan:execute-bridge")) - ); - } - - #[tokio::test] - async fn semantically_invalid_workflow_state_downgrades_to_mode_only_submission() { - let harness = SessionUseCasesHarness::new(ModeId::code()); - harness - .write_plan_state( - SessionPlanStatus::Approved, - "# Plan\n\n## Implementation Steps\n- Keep executing through mode-only fallback\n", - ) - .expect("plan state should be seeded"); - let workflow_path = - WorkflowStateService::state_path(&harness.session_id, &harness.working_dir) - .expect("workflow path should resolve"); - fs::create_dir_all( - workflow_path - .parent() - .expect("workflow parent should exist"), - ) - .expect("workflow parent should exist"); - fs::write( - &workflow_path, - serde_json::json!({ - "workflowId": "plan_execute", - "currentPhaseId": EXECUTING_PHASE_ID, - "artifactRefs": { - "canonical-plan": { - "artifactKind": "canonical-plan", - "path": harness - .working_dir - .join("sessions") - .join(&harness.session_id) - .join("plan") - .join("plan.md") - .display() - .to_string() - } - }, - "bridgeState": { - "bridgeKind": "noop", - "sourcePhaseId": PLANNING_PHASE_ID, - "targetPhaseId": EXECUTING_PHASE_ID, - "schemaVersion": 1, - "payload": {} - }, - "updatedAt": Utc::now().to_rfc3339() - }) - .to_string(), - ) - .expect("invalid semantic workflow should be written"); - - harness - .app - .submit_prompt(&harness.session_id, "开始实现".to_string()) - .await - .expect("submission should degrade to mode-only path"); - - let submissions = harness - .session_port - .recorded_submissions - .lock() - .expect("submission record lock should work") - .clone(); - assert_eq!(submissions.len(), 1); - assert!( - !submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("session-plan:execute-bridge")) - ); - } - - #[tokio::test] - async fn approval_persists_executing_phase_before_mode_switch_and_reconciles_later() { - let harness = SessionUseCasesHarness::new(ModeId::plan()); - harness - .write_plan_state( - SessionPlanStatus::AwaitingApproval, - "# Plan\n\n## Implementation Steps\n1. Implement workflow orchestration\n2. Add \ - tests\n", - ) - .expect("plan state should be seeded"); - let workflow_state = bootstrap_plan_workflow_state( - &harness.session_id, - &harness.working_dir, - &ModeId::plan(), - ) - .expect("bootstrap should succeed") - .expect("planning workflow should bootstrap"); - WorkflowStateService::persist(&harness.session_id, &harness.working_dir, &workflow_state) - .expect("workflow state should persist"); - let existing_snapshot = TaskSnapshot { - owner: astrcode_session_runtime::ROOT_AGENT_ID.to_string(), - items: vec![ExecutionTaskItem { - content: "保持现有 task snapshot".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在保持现有 task snapshot".to_string()), - }], - }; - *harness - .session_port - .active_task_snapshot - .lock() - .expect("active task snapshot lock should work") = Some(existing_snapshot.clone()); - *harness - .session_port - .switch_mode_error - .lock() - .expect("mode switch error lock should work") = - Some("forced mode switch failure".to_string()); - - let error = harness - .app - .submit_prompt(&harness.session_id, "同意".to_string()) - .await - .expect_err("mode reconcile failure should surface"); - assert!( - error.to_string().contains("forced mode switch failure"), - "unexpected error: {error}" - ); - - let persisted = WorkflowStateService::load(&harness.session_id, &harness.working_dir) - .expect("workflow state should load") - .expect("workflow state should exist"); - assert_eq!(persisted.current_phase_id, EXECUTING_PHASE_ID); - - *harness - .session_port - .switch_mode_error - .lock() - .expect("mode switch error lock should work") = None; - - harness - .app - .submit_prompt(&harness.session_id, "开始实现".to_string()) - .await - .expect("second submission should reconcile mode and proceed"); - - let submissions = harness - .session_port - .recorded_submissions - .lock() - .expect("submission record lock should work") - .clone(); - assert_eq!(submissions.len(), 1); - assert!( - submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("session-plan:execute-bridge")) - ); - let mode_switches = harness - .session_port - .recorded_mode_switches - .lock() - .expect("mode switch record lock should work") - .clone(); - assert_eq!(mode_switches.len(), 1); - assert_eq!(mode_switches[0].to, ModeId::code()); - assert_eq!( - harness - .session_port - .active_task_snapshot - .lock() - .expect("active task snapshot lock should work") - .clone(), - Some(existing_snapshot) - ); - } - - #[tokio::test] - async fn executing_replan_signal_returns_to_planning_overlay() { - let harness = SessionUseCasesHarness::new(ModeId::code()); - harness - .write_plan_state( - SessionPlanStatus::Approved, - "# Plan\n\n## Implementation Steps\n- Keep the plan artifact stable\n", - ) - .expect("plan state should be seeded"); - let workflow_state = bootstrap_plan_workflow_state( - &harness.session_id, - &harness.working_dir, - &ModeId::code(), - ) - .expect("bootstrap should succeed") - .expect("executing workflow should bootstrap"); - WorkflowStateService::persist(&harness.session_id, &harness.working_dir, &workflow_state) - .expect("workflow state should persist"); - let existing_snapshot = TaskSnapshot { - owner: astrcode_session_runtime::ROOT_AGENT_ID.to_string(), - items: vec![ExecutionTaskItem { - content: "保留执行 task snapshot".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在保留执行 task snapshot".to_string()), - }], - }; - *harness - .session_port - .active_task_snapshot - .lock() - .expect("active task snapshot lock should work") = Some(existing_snapshot.clone()); - - harness - .app - .submit_prompt(&harness.session_id, "重新计划".to_string()) - .await - .expect("replan should transition back to planning"); - - let persisted = WorkflowStateService::load(&harness.session_id, &harness.working_dir) - .expect("workflow state should load") - .expect("workflow state should exist"); - assert_eq!(persisted.current_phase_id, PLANNING_PHASE_ID); - let submissions = harness - .session_port - .recorded_submissions - .lock() - .expect("submission record lock should work") - .clone(); - assert_eq!(submissions.len(), 1); - assert!( - submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() == Some("mode-hook:plan:facts")) - ); - assert!( - !submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("session-plan:execute-bridge")) - ); - let mode_switches = harness - .session_port - .recorded_mode_switches - .lock() - .expect("mode switch record lock should work") - .clone(); - assert_eq!(mode_switches.len(), 1); - assert_eq!(mode_switches[0].to, ModeId::plan()); - assert_eq!( - harness - .session_port - .active_task_snapshot - .lock() - .expect("active task snapshot lock should work") - .clone(), - Some(existing_snapshot) - ); - } - - #[tokio::test] - async fn draft_plan_approval_phrase_stays_in_planning_and_injects_guard_prompt() { - let harness = SessionUseCasesHarness::new(ModeId::plan()); - harness - .write_plan_state( - SessionPlanStatus::Draft, - "# Plan\n\n## Scope\n- 只读总结\n\n## Non-Goals\n- 不修改文件\n\n## Existing Code \ - To Reuse\n- PROJECT_ARCHITECTURE.md\n\n## Implementation Steps\n1. 提炼约束\n", - ) - .expect("plan state should be seeded"); - - harness - .app - .submit_prompt(&harness.session_id, "按这个做，开始吧".to_string()) - .await - .expect("draft approval phrase should stay in planning"); - - let submissions = harness - .session_port - .recorded_submissions - .lock() - .expect("submission record lock should work") - .clone(); - assert_eq!(submissions.len(), 1); - assert_eq!(submissions[0].text, "按这个做，开始吧"); - assert!( - submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("mode-hook:plan:draft-approval-guard")) - ); - assert!( - submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() == Some("mode-hook:plan:facts")) - ); - assert!( - !submissions[0] - .prompt_declarations - .iter() - .any(|declaration| declaration.origin.as_deref() - == Some("session-plan:execute-bridge")) - ); - assert_eq!(submissions[0].injected_messages.len(), 1); - assert!(matches!( - submissions[0].injected_messages[0], - LlmMessage::User { - ref content, - origin: UserMessageOrigin::ReactivationPrompt, - } if content.contains(astrcode_core::SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER) - && content.contains("当前 canonical session plan 仍是 draft") - && content.contains("不要输出任何最终总结") - && content.contains("收到，我先把草稿补全为可呈递版本，再交给你确认。") - )); - - let persisted = WorkflowStateService::load(&harness.session_id, &harness.working_dir) - .expect("workflow state should load") - .expect("workflow state should exist"); - assert_eq!(persisted.current_phase_id, PLANNING_PHASE_ID); - - let mode_switches = harness - .session_port - .recorded_mode_switches - .lock() - .expect("mode switch record lock should work") - .clone(); - assert!(mode_switches.is_empty()); - } -} diff --git a/crates/application/src/terminal/contracts.rs b/crates/application/src/terminal/contracts.rs deleted file mode 100644 index 6622b7f8..00000000 --- a/crates/application/src/terminal/contracts.rs +++ /dev/null @@ -1,269 +0,0 @@ -use astrcode_core::{ - ChildAgentRef, CompactAppliedMeta, CompactTrigger, Phase, PromptCacheDiagnostics, - SessionEventRecord, SystemPromptLayer, ToolOutputStream, -}; -use serde_json::Value; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationBlockStatus { - Streaming, - Complete, - Failed, - Cancelled, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationSystemNoteKind { - Compact, - SystemNote, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationChildHandoffKind { - Delegated, - Progress, - Returned, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationTranscriptErrorKind { - ProviderError, - ContextWindowExceeded, - ToolFatal, - RateLimit, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationPlanEventKind { - Saved, - ReviewPending, - Presented, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationPlanReviewKind { - RevisePlan, - FinalReview, -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ToolCallStreamsFacts { - pub stdout: String, - pub stderr: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationUserBlockFacts { - pub id: String, - pub turn_id: Option, - pub markdown: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationAssistantBlockFacts { - pub id: String, - pub turn_id: Option, - pub status: ConversationBlockStatus, - pub markdown: String, - pub step_index: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationThinkingBlockFacts { - pub id: String, - pub turn_id: Option, - pub status: ConversationBlockStatus, - pub markdown: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPromptMetricsBlockFacts { - pub id: String, - pub turn_id: Option, - pub step_index: u32, - pub estimated_tokens: u32, - pub context_window: u32, - pub effective_window: u32, - pub threshold_tokens: u32, - pub truncated_tool_results: u32, - pub provider_input_tokens: Option, - pub provider_output_tokens: Option, - pub cache_creation_input_tokens: Option, - pub cache_read_input_tokens: Option, - pub provider_cache_metrics_supported: bool, - pub prompt_cache_reuse_hits: u32, - pub prompt_cache_reuse_misses: u32, - pub prompt_cache_unchanged_layers: Vec, - pub prompt_cache_diagnostics: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPlanReviewFacts { - pub kind: ConversationPlanReviewKind, - pub checklist: Vec, -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ConversationPlanBlockersFacts { - pub missing_headings: Vec, - pub invalid_sections: Vec, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPlanBlockFacts { - pub id: String, - pub turn_id: Option, - pub tool_call_id: String, - pub event_kind: ConversationPlanEventKind, - pub title: String, - pub plan_path: String, - pub summary: Option, - pub status: Option, - pub slug: Option, - pub updated_at: Option, - pub content: Option, - pub review: Option, - pub blockers: ConversationPlanBlockersFacts, -} - -#[derive(Debug, Clone, PartialEq)] -pub struct ToolCallBlockFacts { - pub id: String, - pub turn_id: Option, - pub tool_call_id: String, - pub tool_name: String, - pub status: ConversationBlockStatus, - pub input: Option, - pub summary: Option, - pub error: Option, - pub duration_ms: Option, - pub truncated: bool, - pub metadata: Option, - pub child_ref: Option, - pub streams: ToolCallStreamsFacts, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationErrorBlockFacts { - pub id: String, - pub turn_id: Option, - pub code: ConversationTranscriptErrorKind, - pub message: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationSystemNoteBlockFacts { - pub id: String, - pub note_kind: ConversationSystemNoteKind, - pub markdown: String, - pub compact_trigger: Option, - pub compact_meta: Option, - pub compact_preserved_recent_turns: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationChildHandoffBlockFacts { - pub id: String, - pub handoff_kind: ConversationChildHandoffKind, - pub child_ref: ChildAgentRef, - pub message: Option, -} - -#[derive(Debug, Clone, PartialEq)] -pub enum ConversationBlockFacts { - User(ConversationUserBlockFacts), - Assistant(ConversationAssistantBlockFacts), - Thinking(ConversationThinkingBlockFacts), - PromptMetrics(ConversationPromptMetricsBlockFacts), - Plan(Box), - ToolCall(Box), - Error(ConversationErrorBlockFacts), - SystemNote(ConversationSystemNoteBlockFacts), - ChildHandoff(ConversationChildHandoffBlockFacts), -} - -#[derive(Debug, Clone, PartialEq)] -pub enum ConversationBlockPatchFacts { - AppendMarkdown { - markdown: String, - }, - ReplaceMarkdown { - markdown: String, - }, - AppendToolStream { - stream: ToolOutputStream, - chunk: String, - }, - ReplaceSummary { - summary: String, - }, - ReplaceMetadata { - metadata: Value, - }, - ReplaceError { - error: Option, - }, - ReplaceDuration { - duration_ms: u64, - }, - ReplaceChildRef { - child_ref: ChildAgentRef, - }, - SetTruncated { - truncated: bool, - }, - SetStatus { - status: ConversationBlockStatus, - }, -} - -#[derive(Debug, Clone, PartialEq)] -pub enum ConversationDeltaFacts { - AppendBlock { - block: Box, - }, - PatchBlock { - block_id: String, - patch: ConversationBlockPatchFacts, - }, - CompleteBlock { - block_id: String, - status: ConversationBlockStatus, - }, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationStepCursorFacts { - pub turn_id: String, - pub step_index: u32, -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ConversationStepProgressFacts { - pub durable: Option, - pub live: Option, -} - -#[derive(Debug, Clone, PartialEq)] -pub struct ConversationDeltaFrameFacts { - pub cursor: String, - pub step_progress: ConversationStepProgressFacts, - pub delta: ConversationDeltaFacts, -} - -#[derive(Debug, Clone, PartialEq)] -pub struct ConversationSnapshotFacts { - pub cursor: Option, - pub phase: Phase, - pub step_progress: ConversationStepProgressFacts, - pub blocks: Vec, -} - -#[derive(Debug, Clone)] -pub struct ConversationStreamReplayFacts { - pub cursor: Option, - pub phase: Phase, - pub seed_records: Vec, - pub replay_frames: Vec, - pub history: Vec, -} diff --git a/crates/application/src/terminal/mod.rs b/crates/application/src/terminal/mod.rs deleted file mode 100644 index 2be7e958..00000000 --- a/crates/application/src/terminal/mod.rs +++ /dev/null @@ -1,328 +0,0 @@ -//! 终端层数据模型与投影辅助。 -//! -//! 定义面向前端的事件流数据模型（`TerminalFacts`、`ConversationSlashCandidateFacts` 等） -//! 以及从 session-runtime 快照到终端视图的投影辅助函数。 - -mod contracts; -pub(crate) mod runtime_mapping; -mod stream_projection; - -use astrcode_core::{ - ChildAgentRef, ChildSessionNode, CompactAppliedMeta, CompactTrigger, ExecutionTaskStatus, Phase, -}; -use chrono::{DateTime, Utc}; -pub use contracts::{ - ConversationAssistantBlockFacts, ConversationBlockFacts, ConversationBlockPatchFacts, - ConversationBlockStatus, ConversationChildHandoffBlockFacts, ConversationChildHandoffKind, - ConversationDeltaFacts, ConversationDeltaFrameFacts, ConversationErrorBlockFacts, - ConversationPlanBlockFacts, ConversationPlanBlockersFacts, ConversationPlanEventKind, - ConversationPlanReviewFacts, ConversationPlanReviewKind, ConversationSnapshotFacts, - ConversationStepCursorFacts, ConversationStepProgressFacts, ConversationStreamReplayFacts, - ConversationSystemNoteBlockFacts, ConversationSystemNoteKind, ConversationThinkingBlockFacts, - ConversationTranscriptErrorKind, ConversationUserBlockFacts, ToolCallBlockFacts, - ToolCallStreamsFacts, -}; -pub use stream_projection::ConversationStreamProjector; - -use crate::{ComposerOptionKind, SessionReplay}; - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub enum ConversationFocus { - #[default] - Root, - SubRun { - sub_run_id: String, - }, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TerminalLastCompactMetaFacts { - pub trigger: CompactTrigger, - pub meta: CompactAppliedMeta, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PlanReferenceFacts { - pub slug: String, - pub path: String, - pub status: String, - pub title: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TaskItemFacts { - pub content: String, - pub status: ExecutionTaskStatus, - pub active_form: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationControlSummary { - pub phase: Phase, - pub can_submit_prompt: bool, - pub can_request_compact: bool, - pub compact_pending: bool, - pub compacting: bool, - pub active_turn_id: Option, - pub last_compact_meta: Option, - pub current_mode_id: String, - pub active_plan: Option, - pub active_tasks: Option>, -} - -#[derive(Debug, Clone)] -pub struct TerminalControlFacts { - pub phase: Phase, - pub active_turn_id: Option, - pub manual_compact_pending: bool, - pub compacting: bool, - pub last_compact_meta: Option, - pub current_mode_id: String, - pub active_plan: Option, - pub active_tasks: Option>, -} - -pub type ConversationControlFacts = TerminalControlFacts; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TerminalChildSummaryFacts { - pub node: ChildSessionNode, - pub phase: Phase, - pub title: Option, - pub display_name: Option, - pub recent_output: Option, -} - -pub type ConversationChildSummaryFacts = TerminalChildSummaryFacts; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationChildSummarySummary { - pub child_session_id: String, - pub child_agent_id: String, - pub title: String, - pub lifecycle: astrcode_core::AgentLifecycleStatus, - pub latest_output_summary: Option, - pub child_ref: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum TerminalSlashAction { - CreateSession, - OpenResume, - RequestCompact, - InsertText { text: String }, -} - -pub type ConversationSlashAction = TerminalSlashAction; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationSlashActionSummary { - InsertText, - ExecuteCommand, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TerminalSlashCandidateFacts { - pub kind: ComposerOptionKind, - pub id: String, - pub title: String, - pub description: String, - pub keywords: Vec, - pub badges: Vec, - pub action: TerminalSlashAction, -} - -pub type ConversationSlashCandidateFacts = TerminalSlashCandidateFacts; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationSlashCandidateSummary { - pub id: String, - pub title: String, - pub description: String, - pub keywords: Vec, - pub action_kind: ConversationSlashActionSummary, - pub action_value: String, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationAuthoritativeSummary { - pub control: ConversationControlSummary, - pub child_summaries: Vec, - pub slash_candidates: Vec, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TerminalResumeCandidateFacts { - pub session_id: String, - pub title: String, - pub display_name: String, - pub working_dir: String, - pub updated_at: DateTime, - pub created_at: DateTime, - pub phase: Phase, - pub parent_session_id: Option, -} - -pub type ConversationResumeCandidateFacts = TerminalResumeCandidateFacts; - -#[derive(Debug, Clone)] -pub struct TerminalFacts { - pub active_session_id: String, - pub session_title: String, - pub transcript: ConversationSnapshotFacts, - pub control: TerminalControlFacts, - pub child_summaries: Vec, - pub slash_candidates: Vec, -} - -pub type ConversationFacts = TerminalFacts; - -#[derive(Debug)] -pub struct TerminalStreamReplayFacts { - pub active_session_id: String, - pub replay: ConversationStreamReplayFacts, - pub stream: SessionReplay, - pub control: TerminalControlFacts, - pub child_summaries: Vec, - pub slash_candidates: Vec, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TerminalRehydrateReason { - CursorExpired, -} - -pub type ConversationRehydrateReason = TerminalRehydrateReason; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct TerminalRehydrateFacts { - pub session_id: String, - pub requested_cursor: String, - pub latest_cursor: Option, - pub reason: TerminalRehydrateReason, -} - -pub type ConversationRehydrateFacts = TerminalRehydrateFacts; - -#[derive(Debug)] -pub enum TerminalStreamFacts { - Replay(Box), - RehydrateRequired(TerminalRehydrateFacts), -} - -pub type ConversationStreamFacts = TerminalStreamFacts; - -pub(crate) fn latest_transcript_cursor(snapshot: &ConversationSnapshotFacts) -> Option { - snapshot.cursor.clone() -} - -pub fn truncate_terminal_summary(content: &str) -> String { - const MAX_SUMMARY_CHARS: usize = 120; - let normalized = content.split_whitespace().collect::>().join(" "); - let mut chars = normalized.chars(); - let truncated = chars.by_ref().take(MAX_SUMMARY_CHARS).collect::(); - if chars.next().is_some() { - format!("{truncated}…") - } else { - truncated - } -} - -pub fn summarize_conversation_control( - control: &TerminalControlFacts, -) -> ConversationControlSummary { - ConversationControlSummary { - phase: control.phase, - can_submit_prompt: matches!( - control.phase, - Phase::Idle | Phase::Done | Phase::Interrupted - ), - can_request_compact: !control.manual_compact_pending && !control.compacting, - compact_pending: control.manual_compact_pending, - compacting: control.compacting, - active_turn_id: control.active_turn_id.clone(), - last_compact_meta: control.last_compact_meta.clone(), - current_mode_id: control.current_mode_id.clone(), - active_plan: control.active_plan.clone(), - active_tasks: control.active_tasks.clone(), - } -} - -pub fn summarize_conversation_child_summary( - summary: &TerminalChildSummaryFacts, -) -> ConversationChildSummarySummary { - ConversationChildSummarySummary { - child_session_id: summary.node.child_session_id.to_string(), - child_agent_id: summary.node.agent_id().to_string(), - title: summary - .title - .clone() - .or_else(|| summary.display_name.clone()) - .unwrap_or_else(|| summary.node.child_session_id.to_string()), - lifecycle: summary.node.status, - latest_output_summary: summary.recent_output.clone(), - child_ref: Some(summary.node.child_ref()), - } -} - -pub fn summarize_conversation_child_ref( - child_ref: &ChildAgentRef, -) -> ConversationChildSummarySummary { - ConversationChildSummarySummary { - child_session_id: child_ref.open_session_id.to_string(), - child_agent_id: child_ref.agent_id().to_string(), - title: child_ref.agent_id().to_string(), - lifecycle: child_ref.status, - latest_output_summary: None, - child_ref: Some(child_ref.clone()), - } -} - -pub fn summarize_conversation_slash_candidate( - candidate: &TerminalSlashCandidateFacts, -) -> ConversationSlashCandidateSummary { - let (action_kind, action_value) = match &candidate.action { - TerminalSlashAction::CreateSession => ( - ConversationSlashActionSummary::ExecuteCommand, - "/new".to_string(), - ), - TerminalSlashAction::OpenResume => ( - ConversationSlashActionSummary::ExecuteCommand, - "/resume".to_string(), - ), - TerminalSlashAction::RequestCompact => ( - ConversationSlashActionSummary::ExecuteCommand, - "/compact".to_string(), - ), - TerminalSlashAction::InsertText { text } => { - (ConversationSlashActionSummary::InsertText, text.clone()) - }, - }; - - ConversationSlashCandidateSummary { - id: candidate.id.clone(), - title: candidate.title.clone(), - description: candidate.description.clone(), - keywords: candidate.keywords.clone(), - action_kind, - action_value, - } -} - -pub fn summarize_conversation_authoritative( - control: &TerminalControlFacts, - child_summaries: &[TerminalChildSummaryFacts], - slash_candidates: &[TerminalSlashCandidateFacts], -) -> ConversationAuthoritativeSummary { - ConversationAuthoritativeSummary { - control: summarize_conversation_control(control), - child_summaries: child_summaries - .iter() - .map(summarize_conversation_child_summary) - .collect(), - slash_candidates: slash_candidates - .iter() - .map(summarize_conversation_slash_candidate) - .collect(), - } -} diff --git a/crates/application/src/terminal/runtime_mapping.rs b/crates/application/src/terminal/runtime_mapping.rs deleted file mode 100644 index 4a84240d..00000000 --- a/crates/application/src/terminal/runtime_mapping.rs +++ /dev/null @@ -1,621 +0,0 @@ -use astrcode_session_runtime as runtime; -use tokio::sync::broadcast; - -use super::contracts::{ - ConversationAssistantBlockFacts, ConversationBlockFacts, ConversationBlockPatchFacts, - ConversationBlockStatus, ConversationChildHandoffBlockFacts, ConversationChildHandoffKind, - ConversationDeltaFacts, ConversationDeltaFrameFacts, ConversationErrorBlockFacts, - ConversationPlanBlockFacts, ConversationPlanBlockersFacts, ConversationPlanEventKind, - ConversationPlanReviewFacts, ConversationPlanReviewKind, ConversationPromptMetricsBlockFacts, - ConversationSnapshotFacts, ConversationStepCursorFacts, ConversationStepProgressFacts, - ConversationStreamReplayFacts, ConversationSystemNoteBlockFacts, ConversationSystemNoteKind, - ConversationThinkingBlockFacts, ConversationTranscriptErrorKind, ConversationUserBlockFacts, - ToolCallBlockFacts, ToolCallStreamsFacts, -}; -use crate::SessionReplay; - -pub(crate) struct MappedConversationStreamReplay { - pub replay: ConversationStreamReplayFacts, - pub stream: SessionReplay, -} - -pub(crate) fn map_snapshot(facts: runtime::ConversationSnapshotFacts) -> ConversationSnapshotFacts { - ConversationSnapshotFacts { - cursor: facts.cursor, - phase: facts.phase, - step_progress: map_step_progress(facts.step_progress), - blocks: facts.blocks.into_iter().map(map_block).collect(), - } -} - -pub(crate) fn map_stream_replay( - facts: runtime::ConversationStreamReplayFacts, -) -> MappedConversationStreamReplay { - let runtime::ConversationStreamReplayFacts { - cursor, - phase, - seed_records, - replay_frames, - replay, - } = facts; - let history = replay.history.clone(); - - MappedConversationStreamReplay { - replay: ConversationStreamReplayFacts { - cursor, - phase, - seed_records, - replay_frames: replay_frames.into_iter().map(map_frame).collect(), - history, - }, - stream: replay, - } -} - -pub(crate) fn into_runtime_stream_replay( - facts: &ConversationStreamReplayFacts, -) -> runtime::ConversationStreamReplayFacts { - let (_durable_tx, receiver) = broadcast::channel(1); - let (_live_tx, live_receiver) = broadcast::channel(1); - - runtime::ConversationStreamReplayFacts { - cursor: facts.cursor.clone(), - phase: facts.phase, - seed_records: facts.seed_records.clone(), - replay_frames: facts - .replay_frames - .iter() - .cloned() - .map(into_runtime_frame) - .collect(), - replay: runtime::SessionReplay { - history: facts.history.clone(), - receiver, - live_receiver, - }, - } -} - -pub(crate) fn map_frame( - frame: runtime::ConversationDeltaFrameFacts, -) -> ConversationDeltaFrameFacts { - ConversationDeltaFrameFacts { - cursor: frame.cursor, - step_progress: map_step_progress(frame.step_progress), - delta: map_delta(frame.delta), - } -} - -pub(crate) fn map_delta(delta: runtime::ConversationDeltaFacts) -> ConversationDeltaFacts { - match delta { - runtime::ConversationDeltaFacts::AppendBlock { block } => { - ConversationDeltaFacts::AppendBlock { - block: Box::new(map_block(*block)), - } - }, - runtime::ConversationDeltaFacts::PatchBlock { block_id, patch } => { - ConversationDeltaFacts::PatchBlock { - block_id, - patch: map_patch(patch), - } - }, - runtime::ConversationDeltaFacts::CompleteBlock { block_id, status } => { - ConversationDeltaFacts::CompleteBlock { - block_id, - status: map_block_status(status), - } - }, - } -} - -fn map_patch(patch: runtime::ConversationBlockPatchFacts) -> ConversationBlockPatchFacts { - match patch { - runtime::ConversationBlockPatchFacts::AppendMarkdown { markdown } => { - ConversationBlockPatchFacts::AppendMarkdown { markdown } - }, - runtime::ConversationBlockPatchFacts::ReplaceMarkdown { markdown } => { - ConversationBlockPatchFacts::ReplaceMarkdown { markdown } - }, - runtime::ConversationBlockPatchFacts::AppendToolStream { stream, chunk } => { - ConversationBlockPatchFacts::AppendToolStream { stream, chunk } - }, - runtime::ConversationBlockPatchFacts::ReplaceSummary { summary } => { - ConversationBlockPatchFacts::ReplaceSummary { summary } - }, - runtime::ConversationBlockPatchFacts::ReplaceMetadata { metadata } => { - ConversationBlockPatchFacts::ReplaceMetadata { metadata } - }, - runtime::ConversationBlockPatchFacts::ReplaceError { error } => { - ConversationBlockPatchFacts::ReplaceError { error } - }, - runtime::ConversationBlockPatchFacts::ReplaceDuration { duration_ms } => { - ConversationBlockPatchFacts::ReplaceDuration { duration_ms } - }, - runtime::ConversationBlockPatchFacts::ReplaceChildRef { child_ref } => { - ConversationBlockPatchFacts::ReplaceChildRef { child_ref } - }, - runtime::ConversationBlockPatchFacts::SetTruncated { truncated } => { - ConversationBlockPatchFacts::SetTruncated { truncated } - }, - runtime::ConversationBlockPatchFacts::SetStatus { status } => { - ConversationBlockPatchFacts::SetStatus { - status: map_block_status(status), - } - }, - } -} - -fn map_block(block: runtime::ConversationBlockFacts) -> ConversationBlockFacts { - match block { - runtime::ConversationBlockFacts::User(block) => { - ConversationBlockFacts::User(ConversationUserBlockFacts { - id: block.id, - turn_id: block.turn_id, - markdown: block.markdown, - }) - }, - runtime::ConversationBlockFacts::Assistant(block) => { - ConversationBlockFacts::Assistant(ConversationAssistantBlockFacts { - id: block.id, - turn_id: block.turn_id, - status: map_block_status(block.status), - markdown: block.markdown, - step_index: block.step_index, - }) - }, - runtime::ConversationBlockFacts::Thinking(block) => { - ConversationBlockFacts::Thinking(ConversationThinkingBlockFacts { - id: block.id, - turn_id: block.turn_id, - status: map_block_status(block.status), - markdown: block.markdown, - }) - }, - runtime::ConversationBlockFacts::PromptMetrics(block) => { - ConversationBlockFacts::PromptMetrics(ConversationPromptMetricsBlockFacts { - id: block.id, - turn_id: block.turn_id, - step_index: block.step_index, - estimated_tokens: block.estimated_tokens, - context_window: block.context_window, - effective_window: block.effective_window, - threshold_tokens: block.threshold_tokens, - truncated_tool_results: block.truncated_tool_results, - provider_input_tokens: block.provider_input_tokens, - provider_output_tokens: block.provider_output_tokens, - cache_creation_input_tokens: block.cache_creation_input_tokens, - cache_read_input_tokens: block.cache_read_input_tokens, - provider_cache_metrics_supported: block.provider_cache_metrics_supported, - prompt_cache_reuse_hits: block.prompt_cache_reuse_hits, - prompt_cache_reuse_misses: block.prompt_cache_reuse_misses, - prompt_cache_unchanged_layers: block.prompt_cache_unchanged_layers, - prompt_cache_diagnostics: block.prompt_cache_diagnostics, - }) - }, - runtime::ConversationBlockFacts::Plan(block) => { - ConversationBlockFacts::Plan(Box::new(ConversationPlanBlockFacts { - id: block.id, - turn_id: block.turn_id, - tool_call_id: block.tool_call_id, - event_kind: map_plan_event_kind(block.event_kind), - title: block.title, - plan_path: block.plan_path, - summary: block.summary, - status: block.status, - slug: block.slug, - updated_at: block.updated_at, - content: block.content, - review: block.review.map(|review| ConversationPlanReviewFacts { - kind: map_plan_review_kind(review.kind), - checklist: review.checklist, - }), - blockers: ConversationPlanBlockersFacts { - missing_headings: block.blockers.missing_headings, - invalid_sections: block.blockers.invalid_sections, - }, - })) - }, - runtime::ConversationBlockFacts::ToolCall(block) => { - ConversationBlockFacts::ToolCall(Box::new(ToolCallBlockFacts { - id: block.id, - turn_id: block.turn_id, - tool_call_id: block.tool_call_id, - tool_name: block.tool_name, - status: map_block_status(block.status), - input: block.input, - summary: block.summary, - error: block.error, - duration_ms: block.duration_ms, - truncated: block.truncated, - metadata: block.metadata, - child_ref: block.child_ref, - streams: ToolCallStreamsFacts { - stdout: block.streams.stdout, - stderr: block.streams.stderr, - }, - })) - }, - runtime::ConversationBlockFacts::Error(block) => { - ConversationBlockFacts::Error(ConversationErrorBlockFacts { - id: block.id, - turn_id: block.turn_id, - code: map_transcript_error_kind(block.code), - message: block.message, - }) - }, - runtime::ConversationBlockFacts::SystemNote(block) => { - ConversationBlockFacts::SystemNote(ConversationSystemNoteBlockFacts { - id: block.id, - note_kind: map_system_note_kind(block.note_kind), - markdown: block.markdown, - compact_trigger: block.compact_trigger, - compact_meta: block.compact_meta, - compact_preserved_recent_turns: block.compact_preserved_recent_turns, - }) - }, - runtime::ConversationBlockFacts::ChildHandoff(block) => { - ConversationBlockFacts::ChildHandoff(ConversationChildHandoffBlockFacts { - id: block.id, - handoff_kind: map_child_handoff_kind(block.handoff_kind), - child_ref: block.child_ref, - message: block.message, - }) - }, - } -} - -fn into_runtime_frame(frame: ConversationDeltaFrameFacts) -> runtime::ConversationDeltaFrameFacts { - runtime::ConversationDeltaFrameFacts { - cursor: frame.cursor, - step_progress: into_runtime_step_progress(frame.step_progress), - delta: into_runtime_delta(frame.delta), - } -} - -pub(crate) fn map_step_progress( - facts: runtime::ConversationStepProgressFacts, -) -> ConversationStepProgressFacts { - ConversationStepProgressFacts { - durable: facts.durable.map(map_step_cursor), - live: facts.live.map(map_step_cursor), - } -} - -fn map_step_cursor(facts: runtime::ConversationStepCursorFacts) -> ConversationStepCursorFacts { - ConversationStepCursorFacts { - turn_id: facts.turn_id, - step_index: facts.step_index, - } -} - -fn into_runtime_step_progress( - facts: ConversationStepProgressFacts, -) -> runtime::ConversationStepProgressFacts { - runtime::ConversationStepProgressFacts { - durable: facts.durable.map(into_runtime_step_cursor), - live: facts.live.map(into_runtime_step_cursor), - } -} - -fn into_runtime_step_cursor( - facts: ConversationStepCursorFacts, -) -> runtime::ConversationStepCursorFacts { - runtime::ConversationStepCursorFacts { - turn_id: facts.turn_id, - step_index: facts.step_index, - } -} - -fn into_runtime_delta(delta: ConversationDeltaFacts) -> runtime::ConversationDeltaFacts { - match delta { - ConversationDeltaFacts::AppendBlock { block } => { - runtime::ConversationDeltaFacts::AppendBlock { - block: Box::new(into_runtime_block(*block)), - } - }, - ConversationDeltaFacts::PatchBlock { block_id, patch } => { - runtime::ConversationDeltaFacts::PatchBlock { - block_id, - patch: into_runtime_patch(patch), - } - }, - ConversationDeltaFacts::CompleteBlock { block_id, status } => { - runtime::ConversationDeltaFacts::CompleteBlock { - block_id, - status: into_runtime_block_status(status), - } - }, - } -} - -fn into_runtime_patch(patch: ConversationBlockPatchFacts) -> runtime::ConversationBlockPatchFacts { - match patch { - ConversationBlockPatchFacts::AppendMarkdown { markdown } => { - runtime::ConversationBlockPatchFacts::AppendMarkdown { markdown } - }, - ConversationBlockPatchFacts::ReplaceMarkdown { markdown } => { - runtime::ConversationBlockPatchFacts::ReplaceMarkdown { markdown } - }, - ConversationBlockPatchFacts::AppendToolStream { stream, chunk } => { - runtime::ConversationBlockPatchFacts::AppendToolStream { stream, chunk } - }, - ConversationBlockPatchFacts::ReplaceSummary { summary } => { - runtime::ConversationBlockPatchFacts::ReplaceSummary { summary } - }, - ConversationBlockPatchFacts::ReplaceMetadata { metadata } => { - runtime::ConversationBlockPatchFacts::ReplaceMetadata { metadata } - }, - ConversationBlockPatchFacts::ReplaceError { error } => { - runtime::ConversationBlockPatchFacts::ReplaceError { error } - }, - ConversationBlockPatchFacts::ReplaceDuration { duration_ms } => { - runtime::ConversationBlockPatchFacts::ReplaceDuration { duration_ms } - }, - ConversationBlockPatchFacts::ReplaceChildRef { child_ref } => { - runtime::ConversationBlockPatchFacts::ReplaceChildRef { child_ref } - }, - ConversationBlockPatchFacts::SetTruncated { truncated } => { - runtime::ConversationBlockPatchFacts::SetTruncated { truncated } - }, - ConversationBlockPatchFacts::SetStatus { status } => { - runtime::ConversationBlockPatchFacts::SetStatus { - status: into_runtime_block_status(status), - } - }, - } -} - -fn into_runtime_block(block: ConversationBlockFacts) -> runtime::ConversationBlockFacts { - match block { - ConversationBlockFacts::User(block) => { - runtime::ConversationBlockFacts::User(runtime::ConversationUserBlockFacts { - id: block.id, - turn_id: block.turn_id, - markdown: block.markdown, - }) - }, - ConversationBlockFacts::Assistant(block) => { - runtime::ConversationBlockFacts::Assistant(runtime::ConversationAssistantBlockFacts { - id: block.id, - turn_id: block.turn_id, - status: into_runtime_block_status(block.status), - markdown: block.markdown, - step_index: block.step_index, - }) - }, - ConversationBlockFacts::Thinking(block) => { - runtime::ConversationBlockFacts::Thinking(runtime::ConversationThinkingBlockFacts { - id: block.id, - turn_id: block.turn_id, - status: into_runtime_block_status(block.status), - markdown: block.markdown, - }) - }, - ConversationBlockFacts::PromptMetrics(block) => { - runtime::ConversationBlockFacts::PromptMetrics( - runtime::ConversationPromptMetricsBlockFacts { - id: block.id, - turn_id: block.turn_id, - step_index: block.step_index, - estimated_tokens: block.estimated_tokens, - context_window: block.context_window, - effective_window: block.effective_window, - threshold_tokens: block.threshold_tokens, - truncated_tool_results: block.truncated_tool_results, - provider_input_tokens: block.provider_input_tokens, - provider_output_tokens: block.provider_output_tokens, - cache_creation_input_tokens: block.cache_creation_input_tokens, - cache_read_input_tokens: block.cache_read_input_tokens, - provider_cache_metrics_supported: block.provider_cache_metrics_supported, - prompt_cache_reuse_hits: block.prompt_cache_reuse_hits, - prompt_cache_reuse_misses: block.prompt_cache_reuse_misses, - prompt_cache_unchanged_layers: block.prompt_cache_unchanged_layers, - prompt_cache_diagnostics: block.prompt_cache_diagnostics, - }, - ) - }, - ConversationBlockFacts::Plan(block) => { - runtime::ConversationBlockFacts::Plan(Box::new(runtime::ConversationPlanBlockFacts { - id: block.id, - turn_id: block.turn_id, - tool_call_id: block.tool_call_id, - event_kind: into_runtime_plan_event_kind(block.event_kind), - title: block.title, - plan_path: block.plan_path, - summary: block.summary, - status: block.status, - slug: block.slug, - updated_at: block.updated_at, - content: block.content, - review: block - .review - .map(|review| runtime::ConversationPlanReviewFacts { - kind: into_runtime_plan_review_kind(review.kind), - checklist: review.checklist, - }), - blockers: runtime::ConversationPlanBlockersFacts { - missing_headings: block.blockers.missing_headings, - invalid_sections: block.blockers.invalid_sections, - }, - })) - }, - ConversationBlockFacts::ToolCall(block) => { - runtime::ConversationBlockFacts::ToolCall(Box::new(runtime::ToolCallBlockFacts { - id: block.id, - turn_id: block.turn_id, - tool_call_id: block.tool_call_id, - tool_name: block.tool_name, - status: into_runtime_block_status(block.status), - input: block.input, - summary: block.summary, - error: block.error, - duration_ms: block.duration_ms, - truncated: block.truncated, - metadata: block.metadata, - child_ref: block.child_ref, - streams: runtime::ToolCallStreamsFacts { - stdout: block.streams.stdout, - stderr: block.streams.stderr, - }, - })) - }, - ConversationBlockFacts::Error(block) => { - runtime::ConversationBlockFacts::Error(runtime::ConversationErrorBlockFacts { - id: block.id, - turn_id: block.turn_id, - code: into_runtime_transcript_error_kind(block.code), - message: block.message, - }) - }, - ConversationBlockFacts::SystemNote(block) => { - runtime::ConversationBlockFacts::SystemNote(runtime::ConversationSystemNoteBlockFacts { - id: block.id, - note_kind: into_runtime_system_note_kind(block.note_kind), - markdown: block.markdown, - compact_trigger: block.compact_trigger, - compact_meta: block.compact_meta, - compact_preserved_recent_turns: block.compact_preserved_recent_turns, - }) - }, - ConversationBlockFacts::ChildHandoff(block) => { - runtime::ConversationBlockFacts::ChildHandoff( - runtime::ConversationChildHandoffBlockFacts { - id: block.id, - handoff_kind: into_runtime_child_handoff_kind(block.handoff_kind), - child_ref: block.child_ref, - message: block.message, - }, - ) - }, - } -} - -fn map_block_status(status: runtime::ConversationBlockStatus) -> ConversationBlockStatus { - match status { - runtime::ConversationBlockStatus::Streaming => ConversationBlockStatus::Streaming, - runtime::ConversationBlockStatus::Complete => ConversationBlockStatus::Complete, - runtime::ConversationBlockStatus::Failed => ConversationBlockStatus::Failed, - runtime::ConversationBlockStatus::Cancelled => ConversationBlockStatus::Cancelled, - } -} - -fn into_runtime_block_status(status: ConversationBlockStatus) -> runtime::ConversationBlockStatus { - match status { - ConversationBlockStatus::Streaming => runtime::ConversationBlockStatus::Streaming, - ConversationBlockStatus::Complete => runtime::ConversationBlockStatus::Complete, - ConversationBlockStatus::Failed => runtime::ConversationBlockStatus::Failed, - ConversationBlockStatus::Cancelled => runtime::ConversationBlockStatus::Cancelled, - } -} - -fn map_system_note_kind(kind: runtime::ConversationSystemNoteKind) -> ConversationSystemNoteKind { - match kind { - runtime::ConversationSystemNoteKind::Compact => ConversationSystemNoteKind::Compact, - runtime::ConversationSystemNoteKind::SystemNote => ConversationSystemNoteKind::SystemNote, - } -} - -fn into_runtime_system_note_kind( - kind: ConversationSystemNoteKind, -) -> runtime::ConversationSystemNoteKind { - match kind { - ConversationSystemNoteKind::Compact => runtime::ConversationSystemNoteKind::Compact, - ConversationSystemNoteKind::SystemNote => runtime::ConversationSystemNoteKind::SystemNote, - } -} - -fn map_child_handoff_kind( - kind: runtime::ConversationChildHandoffKind, -) -> ConversationChildHandoffKind { - match kind { - runtime::ConversationChildHandoffKind::Delegated => ConversationChildHandoffKind::Delegated, - runtime::ConversationChildHandoffKind::Progress => ConversationChildHandoffKind::Progress, - runtime::ConversationChildHandoffKind::Returned => ConversationChildHandoffKind::Returned, - } -} - -fn into_runtime_child_handoff_kind( - kind: ConversationChildHandoffKind, -) -> runtime::ConversationChildHandoffKind { - match kind { - ConversationChildHandoffKind::Delegated => runtime::ConversationChildHandoffKind::Delegated, - ConversationChildHandoffKind::Progress => runtime::ConversationChildHandoffKind::Progress, - ConversationChildHandoffKind::Returned => runtime::ConversationChildHandoffKind::Returned, - } -} - -fn map_transcript_error_kind( - kind: runtime::ConversationTranscriptErrorKind, -) -> ConversationTranscriptErrorKind { - match kind { - runtime::ConversationTranscriptErrorKind::ProviderError => { - ConversationTranscriptErrorKind::ProviderError - }, - runtime::ConversationTranscriptErrorKind::ContextWindowExceeded => { - ConversationTranscriptErrorKind::ContextWindowExceeded - }, - runtime::ConversationTranscriptErrorKind::ToolFatal => { - ConversationTranscriptErrorKind::ToolFatal - }, - runtime::ConversationTranscriptErrorKind::RateLimit => { - ConversationTranscriptErrorKind::RateLimit - }, - } -} - -fn into_runtime_transcript_error_kind( - kind: ConversationTranscriptErrorKind, -) -> runtime::ConversationTranscriptErrorKind { - match kind { - ConversationTranscriptErrorKind::ProviderError => { - runtime::ConversationTranscriptErrorKind::ProviderError - }, - ConversationTranscriptErrorKind::ContextWindowExceeded => { - runtime::ConversationTranscriptErrorKind::ContextWindowExceeded - }, - ConversationTranscriptErrorKind::ToolFatal => { - runtime::ConversationTranscriptErrorKind::ToolFatal - }, - ConversationTranscriptErrorKind::RateLimit => { - runtime::ConversationTranscriptErrorKind::RateLimit - }, - } -} - -fn map_plan_event_kind(kind: runtime::ConversationPlanEventKind) -> ConversationPlanEventKind { - match kind { - runtime::ConversationPlanEventKind::Saved => ConversationPlanEventKind::Saved, - runtime::ConversationPlanEventKind::ReviewPending => { - ConversationPlanEventKind::ReviewPending - }, - runtime::ConversationPlanEventKind::Presented => ConversationPlanEventKind::Presented, - } -} - -fn into_runtime_plan_event_kind( - kind: ConversationPlanEventKind, -) -> runtime::ConversationPlanEventKind { - match kind { - ConversationPlanEventKind::Saved => runtime::ConversationPlanEventKind::Saved, - ConversationPlanEventKind::ReviewPending => { - runtime::ConversationPlanEventKind::ReviewPending - }, - ConversationPlanEventKind::Presented => runtime::ConversationPlanEventKind::Presented, - } -} - -fn map_plan_review_kind(kind: runtime::ConversationPlanReviewKind) -> ConversationPlanReviewKind { - match kind { - runtime::ConversationPlanReviewKind::RevisePlan => ConversationPlanReviewKind::RevisePlan, - runtime::ConversationPlanReviewKind::FinalReview => ConversationPlanReviewKind::FinalReview, - } -} - -fn into_runtime_plan_review_kind( - kind: ConversationPlanReviewKind, -) -> runtime::ConversationPlanReviewKind { - match kind { - ConversationPlanReviewKind::RevisePlan => runtime::ConversationPlanReviewKind::RevisePlan, - ConversationPlanReviewKind::FinalReview => runtime::ConversationPlanReviewKind::FinalReview, - } -} diff --git a/crates/application/src/terminal/stream_projection.rs b/crates/application/src/terminal/stream_projection.rs deleted file mode 100644 index c3251f4b..00000000 --- a/crates/application/src/terminal/stream_projection.rs +++ /dev/null @@ -1,71 +0,0 @@ -use astrcode_core::{AgentEvent, SessionEventRecord}; -use astrcode_session_runtime::ConversationStreamProjector as RuntimeConversationStreamProjector; - -use super::{ - ConversationDeltaFrameFacts, ConversationStepProgressFacts, ConversationStreamReplayFacts, - runtime_mapping, -}; - -pub struct ConversationStreamProjector { - projector: RuntimeConversationStreamProjector, -} - -impl ConversationStreamProjector { - pub fn new(last_sent_cursor: Option, facts: &ConversationStreamReplayFacts) -> Self { - Self { - projector: RuntimeConversationStreamProjector::new( - last_sent_cursor, - &runtime_mapping::into_runtime_stream_replay(facts), - ), - } - } - - pub fn last_sent_cursor(&self) -> Option<&str> { - self.projector.last_sent_cursor() - } - - pub fn step_progress(&self) -> ConversationStepProgressFacts { - runtime_mapping::map_step_progress(self.projector.step_progress().clone()) - } - - pub fn seed_initial_replay( - &mut self, - facts: &ConversationStreamReplayFacts, - ) -> Vec { - self.projector - .seed_initial_replay(&runtime_mapping::into_runtime_stream_replay(facts)) - .into_iter() - .map(runtime_mapping::map_frame) - .collect() - } - - pub fn project_durable_record( - &mut self, - record: &SessionEventRecord, - ) -> Vec { - self.projector - .project_durable_record(record) - .into_iter() - .map(runtime_mapping::map_frame) - .collect() - } - - pub fn project_live_event(&mut self, event: &AgentEvent) -> Vec { - self.projector - .project_live_event(event) - .into_iter() - .map(runtime_mapping::map_frame) - .collect() - } - - pub fn recover_from( - &mut self, - recovered: &ConversationStreamReplayFacts, - ) -> Vec { - self.projector - .recover_from(&runtime_mapping::into_runtime_stream_replay(recovered)) - .into_iter() - .map(runtime_mapping::map_frame) - .collect() - } -} diff --git a/crates/application/src/terminal_queries/cursor.rs b/crates/application/src/terminal_queries/cursor.rs deleted file mode 100644 index d11727da..00000000 --- a/crates/application/src/terminal_queries/cursor.rs +++ /dev/null @@ -1,43 +0,0 @@ -//! 游标格式校验与比较工具。 -//! -//! 游标格式为 `{storage_seq}.{subindex}`，用于分页查询时标记位置。 -//! `cursor_is_after_head` 判断请求的游标是否已超过最新位置（即客户端是否有未读数据）。 - -use crate::ApplicationError; - -pub(super) fn validate_cursor_format(cursor: &str) -> Result<(), ApplicationError> { - let Some((storage_seq, subindex)) = cursor.split_once('.') else { - return Err(ApplicationError::InvalidArgument(format!( - "invalid cursor '{cursor}'" - ))); - }; - if storage_seq.parse::().is_err() || subindex.parse::().is_err() { - return Err(ApplicationError::InvalidArgument(format!( - "invalid cursor '{cursor}'" - ))); - } - Ok(()) -} - -pub(super) fn cursor_is_after_head( - requested_cursor: &str, - latest_cursor: Option<&str>, -) -> Result { - let Some(latest_cursor) = latest_cursor else { - return Ok(false); - }; - Ok(parse_cursor(requested_cursor)? > parse_cursor(latest_cursor)?) -} - -fn parse_cursor(cursor: &str) -> Result<(u64, u32), ApplicationError> { - let (storage_seq, subindex) = cursor - .split_once('.') - .ok_or_else(|| ApplicationError::InvalidArgument(format!("invalid cursor '{cursor}'")))?; - let storage_seq = storage_seq - .parse::() - .map_err(|_| ApplicationError::InvalidArgument(format!("invalid cursor '{cursor}'")))?; - let subindex = subindex - .parse::() - .map_err(|_| ApplicationError::InvalidArgument(format!("invalid cursor '{cursor}'")))?; - Ok((storage_seq, subindex)) -} diff --git a/crates/application/src/terminal_queries/mod.rs b/crates/application/src/terminal_queries/mod.rs deleted file mode 100644 index 0f347065..00000000 --- a/crates/application/src/terminal_queries/mod.rs +++ /dev/null @@ -1,36 +0,0 @@ -//! # 终端查询子域 -//! -//! 从旧 `terminal_use_cases.rs` 拆分而来，按职责分为四个查询模块： -//! - `cursor`：游标格式校验与比较 -//! - `resume`：会话恢复候选列表 -//! - `snapshot`：会话快照查询（conversation + transcript） -//! - `summary`：会话摘要提取 - -mod cursor; -mod resume; -mod snapshot; -mod summary; -#[cfg(test)] -mod tests; - -use astrcode_session_runtime::SessionControlStateSnapshot; - -use crate::terminal::{PlanReferenceFacts, TerminalControlFacts, TerminalLastCompactMetaFacts}; - -fn map_control_facts(control: SessionControlStateSnapshot) -> TerminalControlFacts { - TerminalControlFacts { - phase: control.phase, - active_turn_id: control.active_turn_id, - manual_compact_pending: control.manual_compact_pending, - compacting: control.compacting, - last_compact_meta: control - .last_compact_meta - .map(|meta| TerminalLastCompactMetaFacts { - trigger: meta.trigger, - meta: meta.meta, - }), - current_mode_id: control.current_mode_id.to_string(), - active_plan: None::, - active_tasks: None, - } -} diff --git a/crates/application/src/terminal_queries/resume.rs b/crates/application/src/terminal_queries/resume.rs deleted file mode 100644 index 581c442a..00000000 --- a/crates/application/src/terminal_queries/resume.rs +++ /dev/null @@ -1,317 +0,0 @@ -//! 会话恢复候选列表查询。 -//! -//! 根据搜索关键词和限制数量，从 session 列表中筛选出可恢复的会话候选项， -//! 按更新时间倒序排列。支持按标题、工作目录、会话 ID 模糊匹配。 - -use std::{cmp::Reverse, collections::HashSet, path::Path}; - -use astrcode_session_runtime::ROOT_AGENT_ID; - -use crate::{ - App, ApplicationError, ComposerOptionKind, ComposerOptionsRequest, SessionMeta, - session_plan::session_plan_control_summary, - terminal::{ - ConversationAuthoritativeSummary, ConversationFocus, TaskItemFacts, - TerminalChildSummaryFacts, TerminalControlFacts, TerminalResumeCandidateFacts, - TerminalSlashAction, TerminalSlashCandidateFacts, runtime_mapping, - summarize_conversation_authoritative, - }, -}; - -impl App { - pub async fn terminal_resume_candidates( - &self, - query: Option<&str>, - limit: usize, - ) -> Result, ApplicationError> { - let metas = self.session_runtime.list_session_metas().await?; - let query = normalize_query(query); - let limit = normalize_limit(limit); - let mut items = metas - .into_iter() - .filter(|meta| resume_candidate_matches(meta, query.as_deref())) - .map(|meta| TerminalResumeCandidateFacts { - session_id: meta.session_id, - title: meta.title, - display_name: meta.display_name, - working_dir: meta.working_dir, - updated_at: meta.updated_at, - created_at: meta.created_at, - phase: meta.phase, - parent_session_id: meta.parent_session_id, - }) - .collect::>(); - - items.sort_by_key(|item| Reverse(item.updated_at)); - items.truncate(limit); - Ok(items) - } - - pub async fn terminal_child_summaries( - &self, - session_id: &str, - ) -> Result, ApplicationError> { - self.conversation_child_summaries(session_id, &ConversationFocus::Root) - .await - } - - pub async fn conversation_child_summaries( - &self, - session_id: &str, - focus: &ConversationFocus, - ) -> Result, ApplicationError> { - self.validate_non_empty("sessionId", session_id)?; - let focus_session_id = self - .resolve_conversation_focus_session_id(session_id, focus) - .await?; - let children = self - .session_runtime - .session_child_nodes(&focus_session_id) - .await?; - let session_metas = self.session_runtime.list_session_metas().await?; - - let summaries = children - .into_iter() - .filter(|node| node.parent_sub_run_id().is_none()) - .map(|node| async { - self.require_permission( - node.parent_session_id.as_str() == focus_session_id, - format!( - "child '{}' is not visible from session '{}'", - node.sub_run_id(), - focus_session_id - ), - )?; - let child_meta = session_metas - .iter() - .find(|meta| meta.session_id == node.child_session_id.as_str()); - let child_transcript = self - .session_runtime - .conversation_snapshot(node.child_session_id.as_str()) - .await - .map(runtime_mapping::map_snapshot)?; - Ok::<_, ApplicationError>(TerminalChildSummaryFacts { - node, - phase: child_transcript.phase, - title: child_meta.map(|meta| meta.title.clone()), - display_name: child_meta.map(|meta| meta.display_name.clone()), - recent_output: super::summary::latest_terminal_summary(&child_transcript), - }) - }) - .collect::>(); - - let mut resolved = Vec::with_capacity(summaries.len()); - for summary in summaries { - resolved.push(summary.await?); - } - resolved.sort_by(|left, right| left.node.sub_run_id().cmp(right.node.sub_run_id())); - Ok(resolved) - } - - pub async fn terminal_slash_candidates( - &self, - session_id: &str, - query: Option<&str>, - ) -> Result, ApplicationError> { - self.validate_non_empty("sessionId", session_id)?; - let working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await?; - let query = normalize_query(query); - let control = self.terminal_control_facts(session_id).await?; - let mut candidates = terminal_builtin_candidates(&control); - candidates.extend( - self.list_composer_options( - session_id, - ComposerOptionsRequest { - query: query.clone(), - kinds: vec![ComposerOptionKind::Skill], - limit: 50, - }, - ) - .await? - .into_iter() - .map(|option| TerminalSlashCandidateFacts { - kind: option.kind, - id: option.id.clone(), - title: option.title, - description: option.description, - keywords: option.keywords, - badges: option.badges, - action: TerminalSlashAction::InsertText { - text: format!("/{}", option.id), - }, - }), - ); - - if let Some(query) = query.as_deref() { - candidates.retain(|candidate| slash_candidate_matches(candidate, query)); - } - - let _ = Path::new(&working_dir); - Ok(candidates) - } - - pub async fn terminal_control_facts( - &self, - session_id: &str, - ) -> Result { - let control = self - .session_runtime - .session_control_state(session_id) - .await?; - let mut facts = super::map_control_facts(control); - let working_dir = self - .session_runtime - .get_session_working_dir(session_id) - .await?; - // TODO(task-panel): 当前 control read model 只读取 root owner 的 task snapshot。 - // 后续若支持多 owner 并行展示，需要把这里扩成 owner 列表查询与聚合映射， - // 而不是继续把 conversation 面板固定到单一 ROOT_AGENT_ID。 - facts.active_tasks = self - .session_runtime - .active_task_snapshot(session_id, ROOT_AGENT_ID) - .await? - .map(|snapshot| { - snapshot - .items - .into_iter() - .map(|item| TaskItemFacts { - content: item.content, - status: item.status, - active_form: item.active_form, - }) - .collect() - }); - let plan_summary = session_plan_control_summary(session_id, Path::new(&working_dir))?; - facts.active_plan = - plan_summary - .active_plan - .map(|plan| crate::terminal::PlanReferenceFacts { - slug: plan.slug, - path: plan.path, - status: plan.status, - title: plan.title, - }); - Ok(facts) - } - - pub async fn conversation_authoritative_summary( - &self, - session_id: &str, - focus: &ConversationFocus, - ) -> Result { - Ok(summarize_conversation_authoritative( - &self.terminal_control_facts(session_id).await?, - &self.conversation_child_summaries(session_id, focus).await?, - &self.terminal_slash_candidates(session_id, None).await?, - )) - } - - pub(super) async fn resolve_conversation_focus_session_id( - &self, - root_session_id: &str, - focus: &ConversationFocus, - ) -> Result { - match focus { - ConversationFocus::Root => Ok(root_session_id.to_string()), - ConversationFocus::SubRun { sub_run_id } => { - let mut pending = vec![root_session_id.to_string()]; - let mut visited = HashSet::new(); - - while let Some(session_id) = pending.pop() { - if !visited.insert(session_id.clone()) { - continue; - } - for node in self - .session_runtime - .session_child_nodes(&session_id) - .await? - { - if node.sub_run_id().as_str() == *sub_run_id { - return Ok(node.child_session_id.to_string()); - } - pending.push(node.child_session_id.to_string()); - } - } - - Err(ApplicationError::NotFound(format!( - "sub-run '{}' not found under session '{}'", - sub_run_id, root_session_id - ))) - }, - } - } -} - -fn normalize_query(query: Option<&str>) -> Option { - query - .map(str::trim) - .filter(|query| !query.is_empty()) - .map(|query| query.to_lowercase()) -} - -fn normalize_limit(limit: usize) -> usize { - if limit == 0 { 20 } else { limit } -} - -fn resume_candidate_matches(meta: &SessionMeta, query: Option<&str>) -> bool { - let Some(query) = query else { - return true; - }; - [ - meta.session_id.as_str(), - meta.title.as_str(), - meta.display_name.as_str(), - meta.working_dir.as_str(), - ] - .iter() - .any(|field| field.to_lowercase().contains(query)) -} - -fn terminal_builtin_candidates(control: &TerminalControlFacts) -> Vec { - let mut candidates = vec![ - TerminalSlashCandidateFacts { - kind: ComposerOptionKind::Command, - id: "new".to_string(), - title: "新建会话".to_string(), - description: "创建新 session 并切换焦点".to_string(), - keywords: vec!["new".to_string(), "session".to_string()], - badges: vec!["built-in".to_string()], - action: TerminalSlashAction::CreateSession, - }, - TerminalSlashCandidateFacts { - kind: ComposerOptionKind::Command, - id: "resume".to_string(), - title: "恢复会话".to_string(), - description: "搜索并切换到已有 session".to_string(), - keywords: vec!["resume".to_string(), "switch".to_string()], - badges: vec!["built-in".to_string()], - action: TerminalSlashAction::OpenResume, - }, - ]; - - if !control.manual_compact_pending && !control.compacting { - candidates.push(TerminalSlashCandidateFacts { - kind: ComposerOptionKind::Command, - id: "compact".to_string(), - title: "压缩上下文".to_string(), - description: "向服务端提交显式 compact 控制请求".to_string(), - keywords: vec!["compact".to_string(), "compress".to_string()], - badges: vec!["built-in".to_string()], - action: TerminalSlashAction::RequestCompact, - }); - } - candidates -} - -fn slash_candidate_matches(candidate: &TerminalSlashCandidateFacts, query: &str) -> bool { - candidate.id.to_lowercase().contains(query) - || candidate.title.to_lowercase().contains(query) - || candidate.description.to_lowercase().contains(query) - || candidate - .keywords - .iter() - .any(|keyword| keyword.to_lowercase().contains(query)) -} diff --git a/crates/application/src/terminal_queries/snapshot.rs b/crates/application/src/terminal_queries/snapshot.rs deleted file mode 100644 index 6841e676..00000000 --- a/crates/application/src/terminal_queries/snapshot.rs +++ /dev/null @@ -1,130 +0,0 @@ -//! 会话快照查询。 -//! -//! 从 session-runtime 获取 conversation/transcript 快照并映射为 -//! terminal 层的事实模型（`TerminalFacts` / `ConversationStreamReplayFacts`）。 - -use crate::{ - App, ApplicationError, - terminal::{ - ConversationFocus, TerminalFacts, TerminalRehydrateFacts, TerminalRehydrateReason, - TerminalStreamFacts, TerminalStreamReplayFacts, runtime_mapping, - }, -}; - -impl App { - pub async fn conversation_snapshot_facts( - &self, - session_id: &str, - focus: ConversationFocus, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - let focus_session_id = self - .resolve_conversation_focus_session_id(session_id, &focus) - .await?; - let transcript = self - .session_runtime - .conversation_snapshot(&focus_session_id) - .await - .map(runtime_mapping::map_snapshot)?; - let session_title = self - .session_runtime - .list_session_metas() - .await? - .into_iter() - .find(|meta| meta.session_id == session_id) - .map(|meta| meta.title) - .ok_or_else(|| { - ApplicationError::NotFound(format!("session '{session_id}' not found")) - })?; - let control = self.terminal_control_facts(session_id).await?; - let child_summaries = self - .conversation_child_summaries(session_id, &focus) - .await?; - let slash_candidates = self.terminal_slash_candidates(session_id, None).await?; - - Ok(TerminalFacts { - active_session_id: session_id.to_string(), - session_title, - transcript, - control, - child_summaries, - slash_candidates, - }) - } - - pub async fn terminal_snapshot_facts( - &self, - session_id: &str, - ) -> Result { - self.conversation_snapshot_facts(session_id, ConversationFocus::Root) - .await - } - - pub async fn conversation_stream_facts( - &self, - session_id: &str, - last_event_id: Option<&str>, - focus: ConversationFocus, - ) -> Result { - self.validate_non_empty("sessionId", session_id)?; - let focus_session_id = self - .resolve_conversation_focus_session_id(session_id, &focus) - .await?; - - if let Some(requested_cursor) = last_event_id { - super::cursor::validate_cursor_format(requested_cursor)?; - let transcript = self - .session_runtime - .session_transcript_snapshot(&focus_session_id) - .await?; - let latest_cursor = transcript.cursor.clone(); - let cursor_missing_from_transcript = !transcript - .records - .iter() - .any(|record| record.event_id == requested_cursor); - if super::cursor::cursor_is_after_head(requested_cursor, latest_cursor.as_deref())? - || cursor_missing_from_transcript - { - return Ok(TerminalStreamFacts::RehydrateRequired( - TerminalRehydrateFacts { - session_id: session_id.to_string(), - requested_cursor: requested_cursor.to_string(), - latest_cursor, - reason: TerminalRehydrateReason::CursorExpired, - }, - )); - } - } - - let mapped = self - .session_runtime - .conversation_stream_replay(&focus_session_id, last_event_id) - .await - .map(runtime_mapping::map_stream_replay)?; - let control = self.terminal_control_facts(session_id).await?; - let child_summaries = self - .conversation_child_summaries(session_id, &focus) - .await?; - let slash_candidates = self.terminal_slash_candidates(session_id, None).await?; - - Ok(TerminalStreamFacts::Replay(Box::new( - TerminalStreamReplayFacts { - active_session_id: session_id.to_string(), - replay: mapped.replay, - stream: mapped.stream, - control, - child_summaries, - slash_candidates, - }, - ))) - } - - pub async fn terminal_stream_facts( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> Result { - self.conversation_stream_facts(session_id, last_event_id, ConversationFocus::Root) - .await - } -} diff --git a/crates/application/src/terminal_queries/summary.rs b/crates/application/src/terminal_queries/summary.rs deleted file mode 100644 index 987eb1c2..00000000 --- a/crates/application/src/terminal_queries/summary.rs +++ /dev/null @@ -1,87 +0,0 @@ -//! 终端摘要提取。 -//! -//! 从 conversation snapshot 中提取最新一条有意义的摘要文本， -//! 按 block 类型降级选择：assistant markdown → tool call summary/error → child handoff → error → -//! system note。 所有候选项都为空时回退到游标位置。 - -use crate::terminal::{ - ConversationBlockFacts, ConversationChildHandoffBlockFacts, ConversationErrorBlockFacts, - ConversationPlanBlockFacts, ConversationSnapshotFacts, ConversationSystemNoteBlockFacts, - ToolCallBlockFacts, latest_transcript_cursor, truncate_terminal_summary, -}; - -pub(super) fn latest_terminal_summary(snapshot: &ConversationSnapshotFacts) -> Option { - snapshot - .blocks - .iter() - .rev() - .find_map(summary_from_block) - .or_else(|| latest_transcript_cursor(snapshot).map(|cursor| format!("cursor:{cursor}"))) -} - -fn summary_from_block(block: &ConversationBlockFacts) -> Option { - match block { - ConversationBlockFacts::Assistant(block) => summary_from_markdown(&block.markdown), - ConversationBlockFacts::Plan(block) => summary_from_plan_block(block), - ConversationBlockFacts::ToolCall(block) => summary_from_tool_call(block), - ConversationBlockFacts::ChildHandoff(block) => summary_from_child_handoff(block), - ConversationBlockFacts::Error(block) => summary_from_error_block(block), - ConversationBlockFacts::SystemNote(block) => summary_from_system_note(block), - ConversationBlockFacts::User(_) - | ConversationBlockFacts::Thinking(_) - | ConversationBlockFacts::PromptMetrics(_) => None, - } -} - -fn summary_from_markdown(markdown: &str) -> Option { - (!markdown.trim().is_empty()).then(|| truncate_terminal_summary(markdown)) -} - -fn summary_from_tool_call(block: &ToolCallBlockFacts) -> Option { - block - .summary - .as_deref() - .filter(|summary| !summary.trim().is_empty()) - .map(truncate_terminal_summary) - .or_else(|| { - block - .error - .as_deref() - .filter(|error| !error.trim().is_empty()) - .map(truncate_terminal_summary) - }) - .or_else(|| summary_from_markdown(&block.streams.stderr)) - .or_else(|| summary_from_markdown(&block.streams.stdout)) -} - -fn summary_from_plan_block(block: &ConversationPlanBlockFacts) -> Option { - block - .summary - .as_deref() - .filter(|summary| !summary.trim().is_empty()) - .map(truncate_terminal_summary) - .or_else(|| { - block - .content - .as_deref() - .filter(|content| !content.trim().is_empty()) - .map(truncate_terminal_summary) - }) - .or_else(|| summary_from_markdown(&block.title)) -} - -fn summary_from_child_handoff(block: &ConversationChildHandoffBlockFacts) -> Option { - block - .message - .as_deref() - .filter(|message| !message.trim().is_empty()) - .map(truncate_terminal_summary) -} - -fn summary_from_error_block(block: &ConversationErrorBlockFacts) -> Option { - summary_from_markdown(&block.message) -} - -fn summary_from_system_note(block: &ConversationSystemNoteBlockFacts) -> Option { - summary_from_markdown(&block.markdown) -} diff --git a/crates/application/src/terminal_queries/tests.rs b/crates/application/src/terminal_queries/tests.rs deleted file mode 100644 index 2ad0c7e7..00000000 --- a/crates/application/src/terminal_queries/tests.rs +++ /dev/null @@ -1,756 +0,0 @@ -//! 终端查询子域集成测试。 -//! -//! 验证终端查询在完整应用栈上的端到端行为，使用真实的 `App` 组装 -//! （而非 mock），覆盖： -//! - 会话恢复候选列表过滤 -//! - 快照查询与游标比较 -//! - 终端摘要提取 - -use std::{path::Path, sync::Arc, time::Duration}; - -use astrcode_core::{AgentEvent, ExecutionTaskItem, ExecutionTaskStatus, TaskSnapshot}; -use astrcode_session_runtime::{SessionControlStateSnapshot, SessionRuntime}; -use async_trait::async_trait; -use tokio::time::timeout; - -use crate::{ - App, AppKernelPort, AppSessionPort, ApplicationError, ComposerResolvedSkill, ComposerSkillPort, - ConfigService, McpConfigScope, McpPort, McpServerStatusView, McpService, - ProfileResolutionService, - agent::{ - AgentOrchestrationService, - test_support::{TestLlmBehavior, build_agent_test_harness}, - }, - composer::ComposerSkillSummary, - mcp::RegisterMcpServerInput, - terminal::{ - ConversationBlockFacts, ConversationFocus, TerminalRehydrateReason, TerminalStreamFacts, - }, - test_support::StubSessionPort, -}; - -struct StaticComposerSkillPort { - summaries: Vec, -} - -impl ComposerSkillPort for StaticComposerSkillPort { - fn list_skill_summaries(&self, _working_dir: &Path) -> Vec { - self.summaries.clone() - } - - fn resolve_skill(&self, _working_dir: &Path, skill_id: &str) -> Option { - self.summaries - .iter() - .find(|summary| summary.id == skill_id) - .map(|summary| ComposerResolvedSkill { - id: summary.id.clone(), - description: summary.description.clone(), - guide: format!("guide for {}", summary.id), - }) - } -} - -struct NoopMcpPort; - -#[async_trait] -impl McpPort for NoopMcpPort { - async fn list_server_status(&self) -> Vec { - Vec::new() - } - - async fn approve_server(&self, _server_signature: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reject_server(&self, _server_signature: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reconnect_server(&self, _name: &str) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn reset_project_choices(&self) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn upsert_server(&self, _input: &RegisterMcpServerInput) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn remove_server( - &self, - _scope: McpConfigScope, - _name: &str, - ) -> Result<(), ApplicationError> { - Ok(()) - } - - async fn set_server_enabled( - &self, - _scope: McpConfigScope, - _name: &str, - _enabled: bool, - ) -> Result<(), ApplicationError> { - Ok(()) - } -} - -struct TerminalAppHarness { - app: App, - session_runtime: Arc, -} - -fn build_terminal_app_harness(skill_ids: &[&str]) -> TerminalAppHarness { - build_terminal_app_harness_with_behavior( - skill_ids, - TestLlmBehavior::Succeed { - content: "子代理已完成。".to_string(), - }, - ) -} - -fn build_terminal_app_harness_with_behavior( - skill_ids: &[&str], - llm_behavior: TestLlmBehavior, -) -> TerminalAppHarness { - let harness = build_agent_test_harness(llm_behavior).expect("agent test harness should build"); - let kernel: Arc = harness.kernel.clone(); - let session_runtime = harness.session_runtime.clone(); - let session_port: Arc = session_runtime.clone(); - let app = build_terminal_app( - kernel, - session_port, - harness.config_service.clone(), - harness.profiles.clone(), - Arc::new(StaticComposerSkillPort { - summaries: skill_ids - .iter() - .map(|id| ComposerSkillSummary::new(*id, format!("{id} description"))) - .collect(), - }), - Arc::new(harness.service.clone()), - ); - TerminalAppHarness { - app, - session_runtime, - } -} - -fn build_terminal_app( - kernel: Arc, - session_port: Arc, - config: Arc, - profiles: Arc, - composer_skills: Arc, - agent_service: Arc, -) -> App { - let mcp_service = Arc::new(McpService::new(Arc::new(NoopMcpPort))); - App::new( - kernel, - session_port, - profiles, - config, - composer_skills, - Arc::new(crate::governance_surface::GovernanceSurfaceAssembler::default()), - Arc::new(crate::mode::builtin_mode_catalog().expect("builtin mode catalog should build")), - mcp_service, - agent_service, - ) -} - -#[tokio::test] -async fn terminal_stream_facts_expose_live_llm_deltas_before_durable_completion() { - let harness = build_terminal_app_harness_with_behavior( - &[], - TestLlmBehavior::Stream { - reasoning_chunks: vec!["先".to_string(), "整理".to_string()], - text_chunks: vec!["流".to_string(), "式".to_string()], - final_content: "流式完成".to_string(), - final_reasoning: Some("先整理".to_string()), - }, - ); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session = harness - .app - .create_session(project.path().display().to_string()) - .await - .expect("session should be created"); - - let TerminalStreamFacts::Replay(replay) = harness - .app - .terminal_stream_facts(&session.session_id, None) - .await - .expect("stream facts should build") - else { - panic!("fresh stream should start from replay facts"); - }; - let mut live_receiver = replay.stream.live_receiver; - - let accepted = harness - .app - .submit_prompt(&session.session_id, "请流式回答".to_string()) - .await - .expect("prompt should submit"); - - let mut live_events = Vec::new(); - for _ in 0..4 { - live_events.push( - timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live delta should arrive in time") - .expect("live receiver should stay open"), - ); - } - - assert!(matches!( - &live_events[0], - AgentEvent::ThinkingDelta { delta, .. } if delta == "先" - )); - assert!(matches!( - &live_events[1], - AgentEvent::ThinkingDelta { delta, .. } if delta == "整理" - )); - assert!(matches!( - &live_events[2], - AgentEvent::ModelDelta { delta, .. } if delta == "流" - )); - assert!(matches!( - &live_events[3], - AgentEvent::ModelDelta { delta, .. } if delta == "式" - )); - - harness - .session_runtime - .wait_for_turn_terminal_snapshot(&session.session_id, accepted.turn_id.as_str()) - .await - .expect("turn should settle"); - - let snapshot = harness - .app - .terminal_snapshot_facts(&session.session_id) - .await - .expect("terminal snapshot should build"); - assert!(snapshot.transcript.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::Assistant(block) if block.markdown == "流式完成" - ))); - assert!(snapshot.transcript.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::Thinking(block) if block.markdown == "先整理" - ))); -} - -#[tokio::test] -async fn terminal_snapshot_facts_hydrate_history_control_and_slash_candidates() { - let harness = build_terminal_app_harness(&["openspec-apply-change"]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session = harness - .app - .create_session(project.path().display().to_string()) - .await - .expect("session should be created"); - harness - .app - .submit_prompt(&session.session_id, "请总结当前仓库".to_string()) - .await - .expect("prompt should submit"); - - let facts = harness - .app - .terminal_snapshot_facts(&session.session_id) - .await - .expect("terminal snapshot should build"); - - assert_eq!(facts.active_session_id, session.session_id); - assert!(!facts.transcript.blocks.is_empty()); - assert!(facts.transcript.cursor.is_some()); - assert!( - facts - .slash_candidates - .iter() - .any(|candidate| candidate.id == "new") - ); - assert!( - facts - .slash_candidates - .iter() - .any(|candidate| candidate.id == "resume") - ); - assert!( - facts - .slash_candidates - .iter() - .any(|candidate| candidate.id == "compact") - ); - assert!( - facts - .slash_candidates - .iter() - .any(|candidate| candidate.id == "openspec-apply-change") - ); - assert!( - facts - .slash_candidates - .iter() - .all(|candidate| candidate.id != "skill") - ); -} - -#[tokio::test] -async fn terminal_stream_facts_returns_replay_for_valid_cursor() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session = harness - .app - .create_session(project.path().display().to_string()) - .await - .expect("session should be created"); - harness - .app - .submit_prompt(&session.session_id, "hello".to_string()) - .await - .expect("prompt should submit"); - let snapshot = harness - .app - .terminal_snapshot_facts(&session.session_id) - .await - .expect("snapshot should build"); - let cursor = snapshot.transcript.cursor.clone(); - - let facts = harness - .app - .terminal_stream_facts(&session.session_id, cursor.as_deref()) - .await - .expect("stream facts should build"); - - match facts { - TerminalStreamFacts::Replay(replay) => { - assert_eq!(replay.active_session_id, session.session_id); - assert!(replay.replay.history.is_empty()); - assert!(replay.replay.replay_frames.is_empty()); - assert_eq!( - replay - .replay - .seed_records - .last() - .map(|record| record.event_id.as_str()), - snapshot.transcript.cursor.as_deref() - ); - }, - TerminalStreamFacts::RehydrateRequired(_) => { - panic!("valid cursor should not require rehydrate"); - }, - } -} - -#[tokio::test] -async fn terminal_stream_facts_falls_back_to_rehydrate_for_future_cursor() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session = harness - .app - .create_session(project.path().display().to_string()) - .await - .expect("session should be created"); - harness - .app - .submit_prompt(&session.session_id, "hello".to_string()) - .await - .expect("prompt should submit"); - - let facts = harness - .app - .terminal_stream_facts(&session.session_id, Some("999999.9")) - .await - .expect("stream facts should build"); - - match facts { - TerminalStreamFacts::Replay(_) => { - panic!("future cursor should require rehydrate"); - }, - TerminalStreamFacts::RehydrateRequired(rehydrate) => { - assert_eq!(rehydrate.reason, TerminalRehydrateReason::CursorExpired); - assert_eq!(rehydrate.requested_cursor, "999999.9"); - assert!(rehydrate.latest_cursor.is_some()); - }, - } -} - -#[tokio::test] -async fn terminal_stream_facts_rehydrates_when_cursor_is_missing_from_transcript() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session = harness - .app - .create_session(project.path().display().to_string()) - .await - .expect("session should be created"); - harness - .app - .submit_prompt(&session.session_id, "hello".to_string()) - .await - .expect("prompt should submit"); - - let transcript = harness - .session_runtime - .session_transcript_snapshot(&session.session_id) - .await - .expect("transcript snapshot should build"); - let candidate = transcript - .records - .iter() - .find_map(|record| { - let (storage_seq, subindex) = record.event_id.split_once('.')?; - let subindex = subindex.parse::().ok()?; - Some(format!("{storage_seq}.{}", subindex.saturating_add(1))) - }) - .expect("session should produce at least one durable cursor"); - - let facts = harness - .app - .terminal_stream_facts(&session.session_id, Some(candidate.as_str())) - .await - .expect("stream facts should build"); - - match facts { - TerminalStreamFacts::Replay(_) => { - panic!("missing transcript cursor should require rehydrate"); - }, - TerminalStreamFacts::RehydrateRequired(rehydrate) => { - assert_eq!(rehydrate.reason, TerminalRehydrateReason::CursorExpired); - assert_eq!(rehydrate.requested_cursor, candidate); - assert_eq!(rehydrate.latest_cursor, transcript.cursor); - }, - } -} - -#[tokio::test] -async fn terminal_resume_candidates_use_server_fact_and_recent_sorting() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let older_dir = project.path().join("older"); - let newer_dir = project.path().join("newer"); - std::fs::create_dir_all(&older_dir).expect("older dir should exist"); - std::fs::create_dir_all(&newer_dir).expect("newer dir should exist"); - let older = harness - .app - .create_session(older_dir.display().to_string()) - .await - .expect("older session should be created"); - tokio::time::sleep(std::time::Duration::from_millis(5)).await; - let newer = harness - .app - .create_session(newer_dir.display().to_string()) - .await - .expect("newer session should be created"); - - let candidates = harness - .app - .terminal_resume_candidates(Some("newer"), 20) - .await - .expect("resume candidates should build"); - - assert_eq!(candidates.len(), 1); - assert_eq!(candidates[0].session_id, newer.session_id); - let all_candidates = harness - .app - .terminal_resume_candidates(None, 20) - .await - .expect("resume candidates should build"); - assert_eq!(all_candidates[0].session_id, newer.session_id); - assert_eq!(all_candidates[1].session_id, older.session_id); -} - -#[tokio::test] -async fn terminal_child_summaries_only_return_direct_visible_children() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let parent_dir = project.path().join("parent"); - let child_dir = project.path().join("child"); - let unrelated_dir = project.path().join("unrelated"); - std::fs::create_dir_all(&parent_dir).expect("parent dir should exist"); - std::fs::create_dir_all(&child_dir).expect("child dir should exist"); - std::fs::create_dir_all(&unrelated_dir).expect("unrelated dir should exist"); - let parent = harness - .session_runtime - .create_session(parent_dir.display().to_string()) - .await - .expect("parent session should be created"); - let child = harness - .session_runtime - .create_session(child_dir.display().to_string()) - .await - .expect("child session should be created"); - let unrelated = harness - .session_runtime - .create_session(unrelated_dir.display().to_string()) - .await - .expect("unrelated session should be created"); - - let root = harness - .app - .ensure_session_root_agent_context(&parent.session_id) - .await - .expect("root context should exist"); - - harness - .session_runtime - .append_child_session_notification( - &parent.session_id, - "turn-parent", - root.clone(), - astrcode_core::ChildSessionNotification { - notification_id: "child-1".to_string().into(), - child_ref: astrcode_core::ChildAgentRef { - identity: astrcode_core::ChildExecutionIdentity { - agent_id: "agent-child".to_string().into(), - session_id: parent.session_id.clone().into(), - sub_run_id: "subrun-child".to_string().into(), - }, - parent: astrcode_core::ParentExecutionRef { - parent_agent_id: root.agent_id.clone(), - parent_sub_run_id: None, - }, - lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, - status: astrcode_core::AgentLifecycleStatus::Running, - open_session_id: child.session_id.clone().into(), - }, - kind: astrcode_core::ChildSessionNotificationKind::Started, - source_tool_call_id: Some("tool-call-1".to_string().into()), - delivery: Some(astrcode_core::ParentDelivery { - idempotency_key: "child-1".to_string(), - origin: astrcode_core::ParentDeliveryOrigin::Explicit, - terminal_semantics: astrcode_core::ParentDeliveryTerminalSemantics::NonTerminal, - source_turn_id: Some("turn-child".to_string()), - payload: astrcode_core::ParentDeliveryPayload::Progress( - astrcode_core::ProgressParentDeliveryPayload { - message: "child progress".to_string(), - }, - ), - }), - }, - ) - .await - .expect("child notification should append"); - - let accepted = harness - .app - .submit_prompt(&child.session_id, "child output".to_string()) - .await - .expect("child prompt should submit"); - harness - .session_runtime - .wait_for_turn_terminal_snapshot(&child.session_id, accepted.turn_id.as_str()) - .await - .expect("child turn should settle"); - harness - .app - .submit_prompt(&unrelated.session_id, "ignore me".to_string()) - .await - .expect("unrelated prompt should submit"); - - let children = harness - .app - .terminal_child_summaries(&parent.session_id) - .await - .expect("child summaries should build"); - - assert_eq!(children.len(), 1); - assert_eq!(children[0].node.child_session_id, child.session_id.into()); - assert!( - children[0] - .recent_output - .as_deref() - .is_some_and(|summary| summary.contains("子代理已完成")) - ); -} - -#[tokio::test] -async fn conversation_focus_snapshot_reads_child_session_transcript() { - let harness = build_terminal_app_harness(&[]); - let project = tempfile::tempdir().expect("tempdir should be created"); - let parent_dir = project.path().join("parent"); - let child_dir = project.path().join("child"); - std::fs::create_dir_all(&parent_dir).expect("parent dir should exist"); - std::fs::create_dir_all(&child_dir).expect("child dir should exist"); - let parent = harness - .session_runtime - .create_session(parent_dir.display().to_string()) - .await - .expect("parent session should be created"); - let child = harness - .session_runtime - .create_session(child_dir.display().to_string()) - .await - .expect("child session should be created"); - let root = harness - .app - .ensure_session_root_agent_context(&parent.session_id) - .await - .expect("root context should exist"); - - harness - .session_runtime - .append_child_session_notification( - &parent.session_id, - "turn-parent", - root.clone(), - astrcode_core::ChildSessionNotification { - notification_id: "child-1".to_string().into(), - child_ref: astrcode_core::ChildAgentRef { - identity: astrcode_core::ChildExecutionIdentity { - agent_id: "agent-child".to_string().into(), - session_id: parent.session_id.clone().into(), - sub_run_id: "subrun-child".to_string().into(), - }, - parent: astrcode_core::ParentExecutionRef { - parent_agent_id: root.agent_id.clone(), - parent_sub_run_id: None, - }, - lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, - status: astrcode_core::AgentLifecycleStatus::Running, - open_session_id: child.session_id.clone().into(), - }, - kind: astrcode_core::ChildSessionNotificationKind::Started, - source_tool_call_id: Some("tool-call-1".to_string().into()), - delivery: Some(astrcode_core::ParentDelivery { - idempotency_key: "child-1".to_string(), - origin: astrcode_core::ParentDeliveryOrigin::Explicit, - terminal_semantics: astrcode_core::ParentDeliveryTerminalSemantics::NonTerminal, - source_turn_id: Some("turn-child".to_string()), - payload: astrcode_core::ParentDeliveryPayload::Progress( - astrcode_core::ProgressParentDeliveryPayload { - message: "child progress".to_string(), - }, - ), - }), - }, - ) - .await - .expect("child notification should append"); - - harness - .app - .submit_prompt(&parent.session_id, "parent prompt".to_string()) - .await - .expect("parent prompt should submit"); - harness - .app - .submit_prompt(&child.session_id, "child prompt".to_string()) - .await - .expect("child prompt should submit"); - - let facts = harness - .app - .conversation_snapshot_facts( - &parent.session_id, - ConversationFocus::SubRun { - sub_run_id: "subrun-child".to_string(), - }, - ) - .await - .expect("conversation focus snapshot should build"); - - assert_eq!(facts.active_session_id, parent.session_id); - assert!(facts.transcript.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::User(block) if block.markdown == "child prompt" - ))); - assert!(facts.transcript.blocks.iter().all(|block| !matches!( - block, - ConversationBlockFacts::User(block) if block.markdown == "parent prompt" - ))); - assert!(facts.child_summaries.is_empty()); -} - -#[test] -fn cursor_is_after_head_treats_equal_cursor_as_caught_up() { - assert!( - !super::cursor::cursor_is_after_head("12.3", Some("12.3")) - .expect("equal cursor should parse") - ); - assert!( - super::cursor::cursor_is_after_head("12.4", Some("12.3")) - .expect("newer cursor should parse") - ); - assert!( - !super::cursor::cursor_is_after_head("12.2", Some("12.3")) - .expect("older cursor should parse") - ); -} - -#[tokio::test] -async fn terminal_control_facts_include_authoritative_active_tasks() { - let harness = build_agent_test_harness(TestLlmBehavior::Succeed { - content: "unused".to_string(), - }) - .expect("agent test harness should build"); - let project = tempfile::tempdir().expect("tempdir should be created"); - let session_port: Arc = Arc::new(StubSessionPort { - working_dir: Some(project.path().display().to_string()), - control_state: Some(SessionControlStateSnapshot { - phase: astrcode_core::Phase::Idle, - active_turn_id: Some("turn-1".to_string()), - manual_compact_pending: false, - compacting: false, - last_compact_meta: None, - current_mode_id: astrcode_core::ModeId::code(), - last_mode_changed_at: None, - }), - active_task_snapshot: Arc::new(std::sync::Mutex::new(Some(TaskSnapshot { - owner: astrcode_session_runtime::ROOT_AGENT_ID.to_string(), - items: vec![ - ExecutionTaskItem { - content: "实现 authoritative task panel".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在实现 authoritative task panel".to_string()), - }, - ExecutionTaskItem { - content: "补充前端 hydration 测试".to_string(), - status: ExecutionTaskStatus::Pending, - active_form: None, - }, - ], - }))), - ..StubSessionPort::default() - }); - let app = build_terminal_app( - harness.kernel.clone(), - session_port, - harness.config_service.clone(), - harness.profiles.clone(), - Arc::new(StaticComposerSkillPort { - summaries: Vec::new(), - }), - Arc::new(harness.service.clone()), - ); - - let control = app - .terminal_control_facts("session-test") - .await - .expect("terminal control should build"); - - assert_eq!(control.current_mode_id, "code"); - assert_eq!(control.active_turn_id.as_deref(), Some("turn-1")); - assert!(control.active_plan.is_none()); - assert!( - !project.path().join(".astrcode").exists(), - "task facts query must not materialize canonical session plan artifacts" - ); - assert_eq!( - control.active_tasks, - Some(vec![ - crate::terminal::TaskItemFacts { - content: "实现 authoritative task panel".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在实现 authoritative task panel".to_string()), - }, - crate::terminal::TaskItemFacts { - content: "补充前端 hydration 测试".to_string(), - status: ExecutionTaskStatus::Pending, - active_form: None, - }, - ]) - ); -} diff --git a/crates/application/src/test_support.rs b/crates/application/src/test_support.rs deleted file mode 100644 index af1a0056..00000000 --- a/crates/application/src/test_support.rs +++ /dev/null @@ -1,430 +0,0 @@ -//! 应用层测试桩。 -//! -//! 提供 `StubSessionPort`，实现 `AppSessionPort` + `AgentSessionPort` 两个 trait， -//! 用于 `application` 内部单元测试，避免依赖真实 `SessionRuntime`。 - -use std::sync::{Arc, Mutex}; - -use astrcode_core::{ - AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, - DeleteProjectResult, ExecutionAccepted, InputBatchAckedPayload, InputBatchStartedPayload, - InputDiscardedPayload, InputQueuedPayload, LlmMessage, ModeId, PromptDeclaration, - ResolvedRuntimeConfig, SessionId, SessionMeta, StorageEvent, StorageEventPayload, StoredEvent, - TaskSnapshot, TurnId, -}; -use astrcode_session_runtime::{ - ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionCatalogEvent, - SessionControlStateSnapshot, SessionModeSnapshot, SessionReplay, SessionTranscriptSnapshot, - SubRunStatusSnapshot, -}; -use async_trait::async_trait; -use chrono::Utc; -use tokio::sync::broadcast; - -use crate::{ - AgentSessionPort, AppAgentPromptSubmission, AppSessionPort, RecoverableParentDelivery, - SessionForkSelector, SessionObserveSnapshot, SessionTurnOutcomeSummary, - SessionTurnTerminalState, -}; - -fn unimplemented_for_test(area: &str) -> ! { - panic!("not used in {area}") -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) struct RecordedPromptSubmission { - pub(crate) session_id: String, - pub(crate) text: String, - pub(crate) prompt_declarations: Vec, - pub(crate) injected_messages: Vec, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) struct RecordedModeSwitch { - pub(crate) session_id: String, - pub(crate) from: ModeId, - pub(crate) to: ModeId, -} - -#[derive(Debug)] -pub(crate) struct StubSessionPort { - pub(crate) stored_events: Vec, - pub(crate) working_dir: Option, - pub(crate) control_state: Option, - pub(crate) active_task_snapshot: Arc>>, - pub(crate) mode_state: Arc>>, - pub(crate) switch_mode_error: Arc>>, - pub(crate) recorded_submissions: Arc>>, - pub(crate) recorded_mode_switches: Arc>>, -} - -impl Default for StubSessionPort { - fn default() -> Self { - Self { - stored_events: Vec::new(), - working_dir: None, - control_state: None, - active_task_snapshot: Arc::new(Mutex::new(None)), - mode_state: Arc::new(Mutex::new(None)), - switch_mode_error: Arc::new(Mutex::new(None)), - recorded_submissions: Arc::new(Mutex::new(Vec::new())), - recorded_mode_switches: Arc::new(Mutex::new(Vec::new())), - } - } -} - -#[async_trait] -impl AppSessionPort for StubSessionPort { - fn subscribe_catalog_events(&self) -> broadcast::Receiver { - let (_tx, rx) = broadcast::channel(1); - rx - } - - async fn list_session_metas(&self) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn create_session(&self, _working_dir: String) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn fork_session( - &self, - _session_id: &str, - _selector: SessionForkSelector, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn delete_session(&self, _session_id: &str) -> astrcode_core::Result<()> { - unimplemented_for_test("application test stub") - } - - async fn delete_project( - &self, - _working_dir: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn get_session_working_dir(&self, _session_id: &str) -> astrcode_core::Result { - Ok(self.working_dir.clone().unwrap_or_else(|| ".".to_string())) - } - - async fn submit_prompt_for_agent( - &self, - session_id: &str, - text: String, - _runtime: ResolvedRuntimeConfig, - submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result { - self.recorded_submissions - .lock() - .expect("submission record lock should work") - .push(RecordedPromptSubmission { - session_id: session_id.to_string(), - text, - prompt_declarations: submission.prompt_declarations, - injected_messages: submission.injected_messages, - }); - Ok(ExecutionAccepted { - session_id: SessionId::from(session_id.to_string()), - turn_id: TurnId::from("turn-stub".to_string()), - agent_id: None, - branched_from_session_id: None, - }) - } - - async fn interrupt_session(&self, _session_id: &str) -> astrcode_core::Result<()> { - unimplemented_for_test("application test stub") - } - - async fn compact_session( - &self, - _session_id: &str, - _runtime: ResolvedRuntimeConfig, - _instructions: Option, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn session_transcript_snapshot( - &self, - _session_id: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn conversation_snapshot( - &self, - _session_id: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn session_control_state( - &self, - _session_id: &str, - ) -> astrcode_core::Result { - Ok(self - .control_state - .clone() - .unwrap_or(SessionControlStateSnapshot { - phase: astrcode_core::Phase::Idle, - active_turn_id: None, - manual_compact_pending: false, - compacting: false, - last_compact_meta: None, - current_mode_id: ModeId::code(), - last_mode_changed_at: None, - })) - } - - async fn active_task_snapshot( - &self, - _session_id: &str, - _owner: &str, - ) -> astrcode_core::Result> { - Ok(self - .active_task_snapshot - .lock() - .expect("active task snapshot lock should work") - .clone()) - } - - async fn session_mode_state( - &self, - _session_id: &str, - ) -> astrcode_core::Result { - Ok(self - .mode_state - .lock() - .expect("mode state lock should work") - .clone() - .unwrap_or(SessionModeSnapshot { - current_mode_id: ModeId::code(), - last_mode_changed_at: None, - })) - } - - async fn switch_mode( - &self, - session_id: &str, - from: ModeId, - to: ModeId, - ) -> astrcode_core::Result { - if let Some(message) = self - .switch_mode_error - .lock() - .expect("mode switch error lock should work") - .clone() - { - return Err(AstrError::Internal(message)); - } - self.recorded_mode_switches - .lock() - .expect("mode switch record lock should work") - .push(RecordedModeSwitch { - session_id: session_id.to_string(), - from: from.clone(), - to: to.clone(), - }); - *self.mode_state.lock().expect("mode state lock should work") = Some(SessionModeSnapshot { - current_mode_id: to.clone(), - last_mode_changed_at: None, - }); - Ok(StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: None, - agent: AgentEventContext::default(), - payload: StorageEventPayload::ModeChanged { - from, - to, - timestamp: Utc::now(), - }, - }, - }) - } - - async fn session_child_nodes( - &self, - _session_id: &str, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn session_stored_events( - &self, - _session_id: &str, - ) -> astrcode_core::Result> { - Ok(self.stored_events.clone()) - } - - async fn durable_subrun_status_snapshot( - &self, - _parent_session_id: &str, - _requested_subrun_id: &str, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn session_replay( - &self, - _session_id: &str, - _last_event_id: Option<&str>, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn conversation_stream_replay( - &self, - _session_id: &str, - _last_event_id: Option<&str>, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } -} - -#[async_trait] -impl AgentSessionPort for StubSessionPort { - async fn create_child_session( - &self, - _working_dir: &str, - _parent_session_id: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn submit_prompt_for_agent_with_submission( - &self, - _session_id: &str, - _text: String, - _runtime: ResolvedRuntimeConfig, - _submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn try_submit_prompt_for_agent_with_turn_id( - &self, - _session_id: &str, - _turn_id: TurnId, - _text: String, - _runtime: ResolvedRuntimeConfig, - _submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn submit_queued_inputs_for_agent_with_turn_id( - &self, - _session_id: &str, - _turn_id: TurnId, - _queued_inputs: Vec, - _runtime: ResolvedRuntimeConfig, - _submission: AppAgentPromptSubmission, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn append_agent_input_queued( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _payload: InputQueuedPayload, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn append_agent_input_discarded( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _payload: InputDiscardedPayload, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn append_agent_input_batch_started( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _payload: InputBatchStartedPayload, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn append_agent_input_batch_acked( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _payload: InputBatchAckedPayload, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn append_child_session_notification( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _notification: astrcode_core::ChildSessionNotification, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn append_agent_collaboration_fact( - &self, - _session_id: &str, - _turn_id: &str, - _agent: AgentEventContext, - _fact: AgentCollaborationFact, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn pending_delivery_ids_for_agent( - &self, - _session_id: &str, - _agent_id: &str, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn recoverable_parent_deliveries( - &self, - _parent_session_id: &str, - ) -> astrcode_core::Result> { - unimplemented_for_test("application test stub") - } - - async fn observe_agent_session( - &self, - _open_session_id: &str, - _target_agent_id: &str, - _lifecycle_status: AgentLifecycleStatus, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn project_turn_outcome( - &self, - _session_id: &str, - _turn_id: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } - - async fn wait_for_turn_terminal_snapshot( - &self, - _session_id: &str, - _turn_id: &str, - ) -> astrcode_core::Result { - unimplemented_for_test("application test stub") - } -} diff --git a/crates/application/src/watch/mod.rs b/crates/application/src/watch/mod.rs deleted file mode 100644 index 8a306d44..00000000 --- a/crates/application/src/watch/mod.rs +++ /dev/null @@ -1,122 +0,0 @@ -//! 文件变更监听用例。 -//! -//! 负责： -//! - **订阅**：注册对配置文件、agent 定义文件的变更兴趣 -//! - **监听**：通过端口接收底层文件系统事件 -//! - **推送**：将变更事件广播给订阅者（config 热重载、agent 热更新等） -//! -//! IO 和文件系统轮询通过 `WatchPort` 端口委托给适配器层。 - -use std::sync::Arc; - -use tokio::sync::broadcast; - -use crate::ApplicationError; - -// ============================================================ -// 业务模型 -// ============================================================ - -/// 变更事件的来源。 -#[derive(Debug, Clone, PartialEq, Eq, Hash)] -pub enum WatchSource { - /// 全局配置文件变更（`~/.astrcode/config.json`）。 - GlobalConfig, - /// 全局 agent 定义目录变更（`~/.claude/agents` / `~/.astrcode/agents`）。 - GlobalAgentDefinitions, - /// 项目级配置覆盖变更（`/.astrcode/config.json`）。 - ProjectConfig { working_dir: String }, - /// Agent 定义文件变更（`/.astrcode/agents/`）。 - AgentDefinitions { working_dir: String }, -} - -/// 文件变更通知。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct WatchEvent { - /// 变更来源。 - pub source: WatchSource, - /// 受影响的文件路径（相对于项目根目录）。 - pub affected_paths: Vec, -} - -// ============================================================ -// Watch 用例端口 -// ============================================================ - -/// 文件系统监听端口，由适配器层实现。 -/// -/// 适配器负责： -/// - 实际的文件系统监听（inotify、FSEvents、ReadDirectoryChangesW） -/// - 防抖（合并短时间内的多次变更） -/// - 动态添加/移除监听路径 -pub trait WatchPort: Send + Sync { - /// 启动对指定来源的监听，变更事件发送到 tx。 - fn start_watch( - &self, - sources: Vec, - tx: broadcast::Sender, - ) -> Result<(), ApplicationError>; - - /// 停止所有监听。 - fn stop_all(&self) -> Result<(), ApplicationError>; - - /// 动态添加新的监听来源。 - fn add_source(&self, source: WatchSource) -> Result<(), ApplicationError>; - - /// 移除指定来源的监听。 - fn remove_source(&self, source: &WatchSource) -> Result<(), ApplicationError>; -} - -// ============================================================ -// Watch 用例服务 -// ============================================================ - -const WATCH_EVENT_CAPACITY: usize = 256; - -/// 文件变更监听用例服务。 -/// -/// 通过 `WatchPort` 订阅文件变更，通过 broadcast channel 推送给订阅者。 -pub struct WatchService { - port: Arc, - tx: broadcast::Sender, -} - -impl WatchService { - pub fn new(port: Arc) -> Self { - let (tx, _) = broadcast::channel(WATCH_EVENT_CAPACITY); - Self { port, tx } - } - - /// 用例：订阅变更通知。 - /// - /// 返回一个 broadcast receiver，调用方通过 `.recv()` 接收推送。 - pub fn subscribe(&self) -> broadcast::Receiver { - self.tx.subscribe() - } - - /// 用例：启动监听指定来源的文件变更。 - pub fn start_watch(&self, sources: Vec) -> Result<(), ApplicationError> { - self.port.start_watch(sources, self.tx.clone()) - } - - /// 用例：停止所有监听。 - pub fn stop_all(&self) -> Result<(), ApplicationError> { - self.port.stop_all() - } - - /// 用例：动态添加新的监听来源。 - pub fn add_source(&self, source: WatchSource) -> Result<(), ApplicationError> { - self.port.add_source(source) - } - - /// 用例：移除指定来源的监听。 - pub fn remove_source(&self, source: &WatchSource) -> Result<(), ApplicationError> { - self.port.remove_source(source) - } -} - -impl std::fmt::Debug for WatchService { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("WatchService").finish_non_exhaustive() - } -} diff --git a/crates/application/src/workflow/bridge.rs b/crates/application/src/workflow/bridge.rs deleted file mode 100644 index cf540726..00000000 --- a/crates/application/src/workflow/bridge.rs +++ /dev/null @@ -1,118 +0,0 @@ -use astrcode_core::{WorkflowArtifactRef, WorkflowBridgeState}; -use chrono::{DateTime, Utc}; -use serde::{Deserialize, Serialize}; - -use crate::ApplicationError; - -pub(crate) const PLAN_TO_EXECUTE_BRIDGE_KIND: &str = "plan_to_execute"; -pub(crate) const PLAN_TO_EXECUTE_SCHEMA_VERSION: u32 = 1; - -/// planning phase 进入 executing phase 时交接的 typed bridge。 -/// -/// Why: application 需要一个可测试、可序列化的 handoff 真相，而不是把 approved plan -/// 仅作为自由文本 prompt 暗示传递给 execute phase。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PlanToExecuteBridgeState { - pub plan_artifact: WorkflowArtifactRef, - #[serde(default, skip_serializing_if = "String::is_empty")] - pub plan_title: String, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub implementation_steps: Vec, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub approved_at: Option>, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PlanImplementationStep { - pub index: usize, - #[serde(default, skip_serializing_if = "String::is_empty")] - pub title: String, - #[serde(default, skip_serializing_if = "String::is_empty")] - pub summary: String, -} - -impl PlanToExecuteBridgeState { - pub(crate) fn to_bridge_state( - &self, - source_phase_id: &str, - target_phase_id: &str, - ) -> Result { - Ok(WorkflowBridgeState { - bridge_kind: PLAN_TO_EXECUTE_BRIDGE_KIND.to_string(), - source_phase_id: source_phase_id.to_string(), - target_phase_id: target_phase_id.to_string(), - schema_version: PLAN_TO_EXECUTE_SCHEMA_VERSION, - payload: serde_json::to_value(self).map_err(|error| { - ApplicationError::Internal(format!( - "failed to serialize plan-to-execute bridge payload: {error}" - )) - })?, - }) - } - - pub(crate) fn from_bridge_state( - bridge_state: &WorkflowBridgeState, - ) -> Result { - if bridge_state.bridge_kind != PLAN_TO_EXECUTE_BRIDGE_KIND { - return Err(ApplicationError::InvalidArgument(format!( - "unsupported bridge kind '{}'", - bridge_state.bridge_kind - ))); - } - serde_json::from_value(bridge_state.payload.clone()).map_err(|error| { - ApplicationError::Internal(format!( - "failed to parse plan-to-execute bridge payload: {error}" - )) - }) - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::WorkflowArtifactRef; - use chrono::{TimeZone, Utc}; - - use super::{PlanImplementationStep, PlanToExecuteBridgeState}; - - #[test] - fn plan_to_execute_bridge_round_trips_through_envelope() { - let bridge = PlanToExecuteBridgeState { - plan_artifact: WorkflowArtifactRef { - artifact_kind: "canonical-plan".to_string(), - path: "/tmp/plan.md".to_string(), - content_digest: Some("abc".to_string()), - }, - plan_title: "Cleanup architecture".to_string(), - implementation_steps: vec![ - PlanImplementationStep { - index: 1, - title: "Refactor runtime".to_string(), - summary: "收拢 state 与 query 依赖".to_string(), - }, - PlanImplementationStep { - index: 2, - title: "补测试".to_string(), - summary: "覆盖回归路径".to_string(), - }, - ], - approved_at: Some( - Utc.with_ymd_and_hms(2026, 4, 21, 8, 0, 0) - .single() - .expect("datetime should be valid"), - ), - }; - - let encoded = bridge - .to_bridge_state("planning", "executing") - .expect("bridge should encode"); - let decoded = - PlanToExecuteBridgeState::from_bridge_state(&encoded).expect("bridge should decode"); - - assert_eq!(decoded, bridge); - assert_eq!(encoded.bridge_kind, "plan_to_execute"); - assert_eq!(encoded.source_phase_id, "planning"); - assert_eq!(encoded.target_phase_id, "executing"); - } -} diff --git a/crates/application/src/workflow/compiler.rs b/crates/application/src/workflow/compiler.rs deleted file mode 100644 index 40c37d03..00000000 --- a/crates/application/src/workflow/compiler.rs +++ /dev/null @@ -1,255 +0,0 @@ -use std::collections::BTreeMap; - -use astrcode_core::{ - WorkflowDef, WorkflowPhaseDef, WorkflowSignal, WorkflowTransitionDef, WorkflowTransitionTrigger, -}; - -use crate::ApplicationError; - -/// 经过显式校验的 workflow 定义。 -/// -/// Why: orchestrator 不应再直接消费“未经校验的 DTO”， -/// 否则 phase 图、signal 契约和 phase -> mode 绑定仍会在运行时分散失败。 -/// 当前 phase / transition 数量很小，compile 之后继续保留顺序容器即可； -/// 这里刻意不引入额外索引结构，避免为了理论规模过度设计。 -#[derive(Debug, Clone)] -pub(crate) struct CompiledWorkflowDef { - definition: WorkflowDef, -} - -impl CompiledWorkflowDef { - pub(crate) fn compile(definition: WorkflowDef) -> Result { - validate_workflow_definition(&definition)?; - Ok(Self { definition }) - } - - pub(crate) fn definition(&self) -> &WorkflowDef { - &self.definition - } - - pub(crate) fn phase(&self, phase_id: &str) -> Option<&WorkflowPhaseDef> { - self.definition - .phases - .iter() - .find(|phase| phase.phase_id == phase_id) - } - - pub(crate) fn transition_for_signal( - &self, - source_phase_id: &str, - signal: WorkflowSignal, - ) -> Option<&WorkflowTransitionDef> { - self.definition.transitions.iter().find(|transition| { - transition.source_phase_id == source_phase_id - && matches!( - transition.trigger, - WorkflowTransitionTrigger::Signal { - signal: transition_signal, - } if transition_signal == signal - ) - }) - } -} - -pub(crate) fn compile_workflows( - workflows: Vec, -) -> Result, ApplicationError> { - let mut compiled = BTreeMap::new(); - for workflow in workflows { - let compiled_workflow = CompiledWorkflowDef::compile(workflow)?; - let workflow_id = compiled_workflow.definition().workflow_id.clone(); - if compiled.contains_key(&workflow_id) { - return Err(ApplicationError::Internal(format!( - "duplicate workflow id '{}'", - workflow_id - ))); - } - compiled.insert(workflow_id, compiled_workflow); - } - Ok(compiled) -} - -fn validate_workflow_definition(workflow: &WorkflowDef) -> Result<(), ApplicationError> { - if workflow.workflow_id.trim().is_empty() { - return Err(ApplicationError::Internal( - "workflow id must not be empty".to_string(), - )); - } - if workflow.initial_phase_id.trim().is_empty() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' must declare initial phase id", - workflow.workflow_id - ))); - } - if workflow.phases.is_empty() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' must declare at least one phase", - workflow.workflow_id - ))); - } - - let mut phases = BTreeMap::<&str, &WorkflowPhaseDef>::new(); - for phase in &workflow.phases { - if phase.phase_id.trim().is_empty() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' contains phase with empty id", - workflow.workflow_id - ))); - } - if phase.mode_id.as_str().trim().is_empty() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' phase '{}' must declare mode_id", - workflow.workflow_id, phase.phase_id - ))); - } - if phases.insert(phase.phase_id.as_str(), phase).is_some() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' contains duplicate phase '{}'", - workflow.workflow_id, phase.phase_id - ))); - } - } - - if !phases.contains_key(workflow.initial_phase_id.as_str()) { - return Err(ApplicationError::Internal(format!( - "workflow '{}' initial phase '{}' is not declared", - workflow.workflow_id, workflow.initial_phase_id - ))); - } - - let mut transitions = BTreeMap::<&str, &WorkflowTransitionDef>::new(); - for transition in &workflow.transitions { - if transition.transition_id.trim().is_empty() { - return Err(ApplicationError::Internal(format!( - "workflow '{}' contains transition with empty id", - workflow.workflow_id - ))); - } - if transitions - .insert(transition.transition_id.as_str(), transition) - .is_some() - { - return Err(ApplicationError::Internal(format!( - "workflow '{}' contains duplicate transition '{}'", - workflow.workflow_id, transition.transition_id - ))); - } - let Some(source_phase) = phases.get(transition.source_phase_id.as_str()) else { - return Err(ApplicationError::Internal(format!( - "workflow '{}' transition '{}' references unknown source phase '{}'", - workflow.workflow_id, transition.transition_id, transition.source_phase_id - ))); - }; - if !phases.contains_key(transition.target_phase_id.as_str()) { - return Err(ApplicationError::Internal(format!( - "workflow '{}' transition '{}' references unknown target phase '{}'", - workflow.workflow_id, transition.transition_id, transition.target_phase_id - ))); - } - if let WorkflowTransitionTrigger::Signal { signal } = transition.trigger { - if !source_phase.accepted_signals.contains(&signal) { - return Err(ApplicationError::Internal(format!( - "workflow '{}' transition '{}' uses signal '{signal:?}' not accepted by phase \ - '{}'", - workflow.workflow_id, transition.transition_id, transition.source_phase_id - ))); - } - } - } - - Ok(()) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ModeId, WorkflowSignal, WorkflowTransitionTrigger}; - - use super::{CompiledWorkflowDef, compile_workflows}; - - fn valid_workflow() -> astrcode_core::WorkflowDef { - astrcode_core::WorkflowDef { - workflow_id: "plan_execute".to_string(), - initial_phase_id: "planning".to_string(), - phases: vec![ - astrcode_core::WorkflowPhaseDef { - phase_id: "planning".to_string(), - mode_id: ModeId::plan(), - role: "planning".to_string(), - artifact_kind: Some("canonical-plan".to_string()), - accepted_signals: vec![WorkflowSignal::Approve], - }, - astrcode_core::WorkflowPhaseDef { - phase_id: "executing".to_string(), - mode_id: ModeId::code(), - role: "executing".to_string(), - artifact_kind: Some("execution-bridge".to_string()), - accepted_signals: vec![WorkflowSignal::Replan], - }, - ], - transitions: vec![astrcode_core::WorkflowTransitionDef { - transition_id: "plan-approved".to_string(), - source_phase_id: "planning".to_string(), - target_phase_id: "executing".to_string(), - trigger: WorkflowTransitionTrigger::Signal { - signal: WorkflowSignal::Approve, - }, - }], - } - } - - #[test] - fn compile_workflow_accepts_valid_phase_graph() { - let compiled = CompiledWorkflowDef::compile(valid_workflow()).expect("workflow compiles"); - - assert_eq!(compiled.definition().workflow_id, "plan_execute"); - assert_eq!( - compiled - .phase("planning") - .expect("planning phase should exist") - .mode_id, - ModeId::plan() - ); - } - - #[test] - fn compile_workflow_rejects_unknown_initial_phase() { - let mut workflow = valid_workflow(); - workflow.initial_phase_id = "missing".to_string(); - - let error = - CompiledWorkflowDef::compile(workflow).expect_err("missing initial phase must fail"); - - assert!( - error - .to_string() - .contains("initial phase 'missing' is not declared") - ); - } - - #[test] - fn compile_workflow_rejects_signal_transition_not_accepted_by_phase() { - let mut workflow = valid_workflow(); - workflow.phases[0].accepted_signals.clear(); - - let error = - CompiledWorkflowDef::compile(workflow).expect_err("undeclared phase signal must fail"); - - assert!( - error - .to_string() - .contains("uses signal 'Approve' not accepted by phase 'planning'") - ); - } - - #[test] - fn compile_workflows_rejects_duplicate_workflow_ids() { - let error = compile_workflows(vec![valid_workflow(), valid_workflow()]) - .expect_err("duplicate workflow ids must fail"); - - assert!( - error - .to_string() - .contains("duplicate workflow id 'plan_execute'") - ); - } -} diff --git a/crates/application/src/workflow/definition.rs b/crates/application/src/workflow/definition.rs deleted file mode 100644 index c3681a0d..00000000 --- a/crates/application/src/workflow/definition.rs +++ /dev/null @@ -1,94 +0,0 @@ -use astrcode_core::{ - ModeId, WorkflowDef, WorkflowPhaseDef, WorkflowSignal, WorkflowTransitionDef, - WorkflowTransitionTrigger, -}; - -pub const PLAN_EXECUTE_WORKFLOW_ID: &str = "plan_execute"; -pub const PLANNING_PHASE_ID: &str = "planning"; -pub const EXECUTING_PHASE_ID: &str = "executing"; - -pub(crate) fn builtin_workflows() -> Vec { - vec![plan_execute_workflow()] -} - -pub fn plan_execute_workflow() -> WorkflowDef { - WorkflowDef { - workflow_id: PLAN_EXECUTE_WORKFLOW_ID.to_string(), - initial_phase_id: PLANNING_PHASE_ID.to_string(), - phases: vec![ - WorkflowPhaseDef { - phase_id: PLANNING_PHASE_ID.to_string(), - mode_id: ModeId::plan(), - role: "planning".to_string(), - artifact_kind: Some("canonical-plan".to_string()), - accepted_signals: vec![ - WorkflowSignal::Approve, - WorkflowSignal::RequestChanges, - WorkflowSignal::Cancel, - ], - }, - WorkflowPhaseDef { - phase_id: EXECUTING_PHASE_ID.to_string(), - mode_id: ModeId::code(), - role: "executing".to_string(), - artifact_kind: Some("execution-bridge".to_string()), - accepted_signals: vec![WorkflowSignal::Replan, WorkflowSignal::Cancel], - }, - ], - transitions: vec![ - WorkflowTransitionDef { - transition_id: "plan-approved".to_string(), - source_phase_id: PLANNING_PHASE_ID.to_string(), - target_phase_id: EXECUTING_PHASE_ID.to_string(), - trigger: WorkflowTransitionTrigger::Signal { - signal: WorkflowSignal::Approve, - }, - }, - WorkflowTransitionDef { - transition_id: "execution-replan".to_string(), - source_phase_id: EXECUTING_PHASE_ID.to_string(), - target_phase_id: PLANNING_PHASE_ID.to_string(), - trigger: WorkflowTransitionTrigger::Signal { - signal: WorkflowSignal::Replan, - }, - }, - ], - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ModeId, WorkflowSignal, WorkflowTransitionTrigger}; - - use super::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, plan_execute_workflow, - }; - - #[test] - fn builtin_plan_execute_workflow_declares_expected_phase_graph() { - let workflow = plan_execute_workflow(); - - assert_eq!(workflow.workflow_id, PLAN_EXECUTE_WORKFLOW_ID); - assert_eq!(workflow.initial_phase_id, PLANNING_PHASE_ID); - assert_eq!(workflow.phases.len(), 2); - assert_eq!(workflow.transitions.len(), 2); - assert!(workflow.phases.iter().any(|phase| { - phase.phase_id == PLANNING_PHASE_ID - && phase.mode_id == ModeId::plan() - && phase.accepted_signals.contains(&WorkflowSignal::Approve) - })); - assert!(workflow.phases.iter().any(|phase| { - phase.phase_id == EXECUTING_PHASE_ID - && phase.mode_id == ModeId::code() - && phase.accepted_signals.contains(&WorkflowSignal::Replan) - })); - assert!(workflow.transitions.iter().any(|transition| { - transition.source_phase_id == PLANNING_PHASE_ID - && transition.target_phase_id == EXECUTING_PHASE_ID - && transition.trigger - == WorkflowTransitionTrigger::Signal { - signal: WorkflowSignal::Approve, - } - })); - } -} diff --git a/crates/application/src/workflow/mod.rs b/crates/application/src/workflow/mod.rs deleted file mode 100644 index 7d99c98d..00000000 --- a/crates/application/src/workflow/mod.rs +++ /dev/null @@ -1,19 +0,0 @@ -mod bridge; -mod compiler; -mod definition; -mod orchestrator; -mod service; -mod state; - -pub use astrcode_core::{WorkflowArtifactRef, WorkflowInstanceState}; -pub use bridge::{PlanImplementationStep, PlanToExecuteBridgeState}; -pub use definition::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, plan_execute_workflow, -}; -pub use orchestrator::WorkflowOrchestrator; -pub(crate) use service::{ - advance_plan_workflow_to_execution, bootstrap_plan_workflow_state, - build_execute_phase_prompt_declaration, reconcile_workflow_phase_mode, - revert_execution_to_planning_workflow_state, -}; -pub use state::WorkflowStateService; diff --git a/crates/application/src/workflow/orchestrator.rs b/crates/application/src/workflow/orchestrator.rs deleted file mode 100644 index cd18bd0d..00000000 --- a/crates/application/src/workflow/orchestrator.rs +++ /dev/null @@ -1,329 +0,0 @@ -use std::{collections::BTreeMap, path::Path}; - -use astrcode_core::{ - WorkflowDef, WorkflowInstanceState, WorkflowPhaseDef, WorkflowSignal, WorkflowTransitionDef, -}; - -use crate::{ - ApplicationError, - workflow::{ - bridge::PlanToExecuteBridgeState, - compiler::{CompiledWorkflowDef, compile_workflows}, - definition::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, builtin_workflows, - }, - state::WorkflowStateService, - }, -}; - -/// application 层唯一的 workflow 编排入口。 -/// -/// Why: 正式 workflow 的 phase 图、恢复与迁移查询不应继续散落在 plan-specific if/else 中。 -#[derive(Debug, Clone)] -pub struct WorkflowOrchestrator { - workflows: BTreeMap, -} - -impl Default for WorkflowOrchestrator { - fn default() -> Self { - Self::try_new(builtin_workflows()).expect("builtin workflows should compile") - } -} - -impl WorkflowOrchestrator { - pub fn new(workflows: Vec) -> Self { - Self::try_new(workflows).expect("workflow definitions should compile") - } - - pub fn try_new(workflows: Vec) -> Result { - Ok(Self { - workflows: compile_workflows(workflows)?, - }) - } - - pub fn workflow(&self, workflow_id: &str) -> Option<&WorkflowDef> { - self.workflows - .get(workflow_id) - .map(CompiledWorkflowDef::definition) - } - - pub fn phase<'a>( - &'a self, - state: &WorkflowInstanceState, - ) -> Result<&'a WorkflowPhaseDef, ApplicationError> { - let workflow = self.workflows.get(&state.workflow_id).ok_or_else(|| { - ApplicationError::Internal(format!( - "workflow '{}' is not registered", - state.workflow_id - )) - })?; - workflow.phase(&state.current_phase_id).ok_or_else(|| { - ApplicationError::Internal(format!( - "workflow '{}' does not contain phase '{}'", - state.workflow_id, state.current_phase_id - )) - }) - } - - pub fn transition_for_signal<'a>( - &'a self, - state: &WorkflowInstanceState, - signal: WorkflowSignal, - ) -> Result, ApplicationError> { - let workflow = self.workflows.get(&state.workflow_id).ok_or_else(|| { - ApplicationError::Internal(format!( - "workflow '{}' is not registered", - state.workflow_id - )) - })?; - Ok(workflow.transition_for_signal(&state.current_phase_id, signal)) - } - - pub fn load_active_workflow( - &self, - session_id: &str, - working_dir: &Path, - ) -> Result, ApplicationError> { - let Some(state) = WorkflowStateService::load_recovering(session_id, working_dir)? else { - return Ok(None); - }; - if let Err(error) = self.validate_state(&state) { - let path = WorkflowStateService::state_path(session_id, working_dir)?; - log::warn!( - "workflow state '{}' is invalid and will degrade to mode-only: {}", - path.display(), - error - ); - return Ok(None); - } - Ok(Some(state)) - } - - pub fn persist_active_workflow( - &self, - session_id: &str, - working_dir: &Path, - state: &WorkflowInstanceState, - ) -> Result<(), ApplicationError> { - self.validate_state(state)?; - WorkflowStateService::persist(session_id, working_dir, state) - } - - pub fn clear_active_workflow( - &self, - session_id: &str, - working_dir: &Path, - ) -> Result<(), ApplicationError> { - WorkflowStateService::clear(session_id, working_dir) - } - - fn validate_state(&self, state: &WorkflowInstanceState) -> Result<(), ApplicationError> { - let phase = self.phase(state)?; - match (state.workflow_id.as_str(), phase.phase_id.as_str()) { - (PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID) if state.bridge_state.is_some() => { - return Err(ApplicationError::Internal( - "planning workflow state must not carry execute bridge state".to_string(), - )); - }, - (PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID) => {}, - (PLAN_EXECUTE_WORKFLOW_ID, EXECUTING_PHASE_ID) => { - let bridge_state = state.bridge_state.as_ref().ok_or_else(|| { - ApplicationError::Internal( - "executing workflow state must include plan execute bridge state" - .to_string(), - ) - })?; - if bridge_state.source_phase_id != PLANNING_PHASE_ID - || bridge_state.target_phase_id != EXECUTING_PHASE_ID - { - return Err(ApplicationError::Internal(format!( - "unexpected plan execute bridge transition '{} -> {}'", - bridge_state.source_phase_id, bridge_state.target_phase_id - ))); - } - PlanToExecuteBridgeState::from_bridge_state(bridge_state)?; - }, - _ => {}, - } - Ok(()) - } -} - -#[cfg(test)] -mod tests { - use std::{collections::BTreeMap, fs}; - - use astrcode_core::{ - ModeId, WorkflowArtifactRef, WorkflowInstanceState, WorkflowSignal, - WorkflowTransitionTrigger, - }; - use chrono::{TimeZone, Utc}; - use serde_json::json; - - use super::WorkflowOrchestrator; - use crate::workflow::{ - bridge::{PlanImplementationStep, PlanToExecuteBridgeState}, - definition::{EXECUTING_PHASE_ID, PLANNING_PHASE_ID}, - state::WorkflowStateService, - }; - - fn workflow_state() -> WorkflowInstanceState { - let plan_artifact = WorkflowArtifactRef { - artifact_kind: "canonical-plan".to_string(), - path: "/tmp/plan.md".to_string(), - content_digest: Some("abc".to_string()), - }; - let bridge = PlanToExecuteBridgeState { - plan_artifact: plan_artifact.clone(), - plan_title: "Cleanup runtime".to_string(), - implementation_steps: vec![PlanImplementationStep { - index: 1, - title: "Refactor".to_string(), - summary: "收拢 workflow state".to_string(), - }], - approved_at: Some( - Utc.with_ymd_and_hms(2026, 4, 21, 12, 0, 0) - .single() - .expect("datetime should be valid"), - ), - }; - WorkflowInstanceState { - workflow_id: "plan_execute".to_string(), - current_phase_id: EXECUTING_PHASE_ID.to_string(), - artifact_refs: BTreeMap::from([("canonical-plan".to_string(), plan_artifact)]), - bridge_state: Some( - bridge - .to_bridge_state(PLANNING_PHASE_ID, EXECUTING_PHASE_ID) - .expect("bridge should encode"), - ), - updated_at: Utc - .with_ymd_and_hms(2026, 4, 21, 12, 1, 0) - .single() - .expect("datetime should be valid"), - } - } - - #[test] - fn load_active_workflow_returns_registered_state() { - let guard = astrcode_core::test_support::TestEnvGuard::new(); - let working_dir = guard.home_dir().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - let orchestrator = WorkflowOrchestrator::default(); - let state = workflow_state(); - - orchestrator - .persist_active_workflow("session-a", &working_dir, &state) - .expect("state should persist"); - - let loaded = orchestrator - .load_active_workflow("session-a", &working_dir) - .expect("state should load") - .expect("workflow should exist"); - - assert_eq!(loaded, state); - let transition = orchestrator - .transition_for_signal(&loaded, WorkflowSignal::Replan) - .expect("transition lookup should succeed") - .expect("replan transition should exist"); - assert_eq!(transition.target_phase_id, PLANNING_PHASE_ID); - } - - #[test] - fn load_active_workflow_downgrades_unknown_phase() { - let guard = astrcode_core::test_support::TestEnvGuard::new(); - let working_dir = guard.home_dir().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - let state = WorkflowInstanceState { - current_phase_id: "unknown".to_string(), - ..workflow_state() - }; - WorkflowStateService::persist("session-a", &working_dir, &state) - .expect("state should persist"); - - let loaded = WorkflowOrchestrator::default() - .load_active_workflow("session-a", &working_dir) - .expect("recovery should not fail"); - assert!( - loaded.is_none(), - "unknown phase should downgrade to mode-only" - ); - } - - #[test] - fn load_active_workflow_downgrades_invalid_execute_bridge() { - let guard = astrcode_core::test_support::TestEnvGuard::new(); - let working_dir = guard.home_dir().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - let state = WorkflowInstanceState { - bridge_state: Some(astrcode_core::WorkflowBridgeState { - bridge_kind: "noop".to_string(), - source_phase_id: PLANNING_PHASE_ID.to_string(), - target_phase_id: EXECUTING_PHASE_ID.to_string(), - schema_version: 1, - payload: json!({}), - }), - ..workflow_state() - }; - WorkflowStateService::persist("session-a", &working_dir, &state) - .expect("state should persist"); - - let loaded = WorkflowOrchestrator::default() - .load_active_workflow("session-a", &working_dir) - .expect("recovery should not fail"); - assert!( - loaded.is_none(), - "invalid execute bridge should downgrade to mode-only" - ); - } - - #[test] - fn try_new_rejects_invalid_workflow_phase_graph() { - let error = WorkflowOrchestrator::try_new(vec![astrcode_core::WorkflowDef { - workflow_id: "invalid".to_string(), - initial_phase_id: "planning".to_string(), - phases: vec![astrcode_core::WorkflowPhaseDef { - phase_id: "planning".to_string(), - mode_id: ModeId::plan(), - role: "planning".to_string(), - artifact_kind: None, - accepted_signals: Vec::new(), - }], - transitions: vec![astrcode_core::WorkflowTransitionDef { - transition_id: "invalid-transition".to_string(), - source_phase_id: "planning".to_string(), - target_phase_id: "missing".to_string(), - trigger: WorkflowTransitionTrigger::Signal { - signal: WorkflowSignal::Approve, - }, - }], - }]) - .expect_err("invalid workflow should not compile"); - - assert!( - error - .to_string() - .contains("references unknown target phase 'missing'") - ); - } - - #[test] - fn transition_lookup_returns_none_when_signal_is_not_declared() { - let orchestrator = WorkflowOrchestrator::default(); - let state = WorkflowInstanceState { - current_phase_id: PLANNING_PHASE_ID.to_string(), - bridge_state: Some(astrcode_core::WorkflowBridgeState { - bridge_kind: "noop".to_string(), - source_phase_id: PLANNING_PHASE_ID.to_string(), - target_phase_id: EXECUTING_PHASE_ID.to_string(), - schema_version: 1, - payload: json!({}), - }), - ..workflow_state() - }; - - let transition = orchestrator - .transition_for_signal(&state, WorkflowSignal::Replan) - .expect("transition lookup should succeed"); - assert!(transition.is_none()); - } -} diff --git a/crates/application/src/workflow/service.rs b/crates/application/src/workflow/service.rs deleted file mode 100644 index 5939dc76..00000000 --- a/crates/application/src/workflow/service.rs +++ /dev/null @@ -1,596 +0,0 @@ -use std::{collections::BTreeMap, fs, future::Future, path::Path}; - -use astrcode_core::{ - ModeId, PromptDeclaration, SessionPlanState, SessionPlanStatus, session_plan_content_digest, -}; -use chrono::Utc; - -use crate::{ - ApplicationError, - session_plan::{ - active_plan_requires_approval, build_execute_bridge_declaration, load_session_plan_state, - mark_active_session_plan_approved, planning_phase_allows_review_mode, - session_plan_markdown_path, - }, - workflow::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, PlanImplementationStep, - PlanToExecuteBridgeState, WorkflowArtifactRef, WorkflowInstanceState, WorkflowOrchestrator, - }, -}; - -/// 基于当前 mode / plan 状态推导初始 workflow state。 -pub(crate) fn bootstrap_plan_workflow_state( - session_id: &str, - working_dir: &Path, - current_mode_id: &astrcode_core::ModeId, -) -> Result, ApplicationError> { - let plan_state = load_session_plan_state(session_id, working_dir)?; - if current_mode_id == &astrcode_core::ModeId::plan() - || active_plan_requires_approval(plan_state.as_ref()) - { - return Ok(Some(build_planning_workflow_state( - session_id, - working_dir, - plan_state.as_ref(), - )?)); - } - if plan_state - .as_ref() - .is_some_and(|state| state.status == SessionPlanStatus::Approved) - { - return Ok(Some(build_executing_workflow_state( - session_id, - working_dir, - plan_state - .as_ref() - .expect("approved plan state should exist"), - )?)); - } - Ok(None) -} - -/// 执行 planning -> executing 迁移，并生成 execute bridge prompt。 -pub(crate) fn advance_plan_workflow_to_execution( - session_id: &str, - working_dir: &Path, -) -> Result, ApplicationError> { - let approved_plan = mark_active_session_plan_approved(session_id, working_dir)?; - let Some(plan_state) = load_session_plan_state(session_id, working_dir)? else { - return Ok(None); - }; - if plan_state.status != SessionPlanStatus::Approved { - return Ok(None); - } - - let next_state = build_executing_workflow_state(session_id, working_dir, &plan_state)?; - let bridge = next_state - .bridge_state - .as_ref() - .ok_or_else(|| { - ApplicationError::Internal( - "executing workflow state must include plan bridge state".to_string(), - ) - }) - .and_then(PlanToExecuteBridgeState::from_bridge_state)?; - let mut declaration = build_execute_bridge_declaration(session_id, &bridge); - if let Some(summary) = approved_plan { - declaration.content.push_str(&format!( - "\n- approvedPlanSlug: {}\n- approvedPlanStatus: {}", - summary.slug, summary.status - )); - } - Ok(Some((next_state, declaration))) -} - -pub(crate) fn revert_execution_to_planning_workflow_state( - session_id: &str, - working_dir: &Path, -) -> Result { - let plan_state = load_session_plan_state(session_id, working_dir)?; - build_planning_workflow_state(session_id, working_dir, plan_state.as_ref()) -} - -pub(crate) fn build_execute_phase_prompt_declaration( - session_id: &str, - workflow_state: &WorkflowInstanceState, -) -> Result, ApplicationError> { - let Some(bridge_state) = workflow_state.bridge_state.as_ref() else { - return Ok(None); - }; - let bridge = PlanToExecuteBridgeState::from_bridge_state(bridge_state)?; - Ok(Some(build_execute_bridge_declaration(session_id, &bridge))) -} - -pub(crate) async fn reconcile_workflow_phase_mode( - orchestrator: &WorkflowOrchestrator, - session_id: &str, - working_dir: &Path, - current_mode_id: ModeId, - workflow_state: &WorkflowInstanceState, - plan_state: Option<&SessionPlanState>, - mut switch_mode: F, -) -> Result -where - F: FnMut(ModeId) -> Fut, - Fut: Future>, -{ - let phase = orchestrator.phase(workflow_state)?; - if phase.mode_id == current_mode_id { - return Ok(current_mode_id); - } - if workflow_state.current_phase_id == PLANNING_PHASE_ID - && planning_phase_allows_review_mode(¤t_mode_id, plan_state) - { - return Ok(current_mode_id); - } - - match switch_mode(phase.mode_id.clone()).await { - Ok(astrcode_session_runtime::SessionModeSnapshot { - current_mode_id, .. - }) => Ok(current_mode_id), - Err(error) => { - let state_path = - crate::workflow::WorkflowStateService::state_path(session_id, working_dir)?; - log::warn!( - "workflow phase '{}' persisted in '{}' but mode reconcile to '{}' failed: {}", - workflow_state.current_phase_id, - state_path.display(), - phase.mode_id, - error - ); - Err(error) - }, - } -} - -fn build_planning_workflow_state( - session_id: &str, - working_dir: &Path, - plan_state: Option<&SessionPlanState>, -) -> Result { - let mut artifact_refs = BTreeMap::new(); - if let Some(plan_state) = plan_state { - if let Some(plan_artifact) = current_plan_artifact_ref(session_id, working_dir, plan_state)? - { - artifact_refs.insert("canonical-plan".to_string(), plan_artifact); - } - } - Ok(WorkflowInstanceState { - workflow_id: PLAN_EXECUTE_WORKFLOW_ID.to_string(), - current_phase_id: PLANNING_PHASE_ID.to_string(), - artifact_refs, - bridge_state: None, - updated_at: plan_state - .map(|state| state.updated_at) - .unwrap_or_else(Utc::now), - }) -} - -fn build_executing_workflow_state( - session_id: &str, - working_dir: &Path, - plan_state: &SessionPlanState, -) -> Result { - let bridge = load_plan_to_execute_bridge_state(session_id, working_dir, plan_state)?; - let plan_artifact = bridge.plan_artifact.clone(); - let bridge_state = bridge.to_bridge_state(PLANNING_PHASE_ID, EXECUTING_PHASE_ID)?; - Ok(WorkflowInstanceState { - workflow_id: PLAN_EXECUTE_WORKFLOW_ID.to_string(), - current_phase_id: EXECUTING_PHASE_ID.to_string(), - artifact_refs: BTreeMap::from([("canonical-plan".to_string(), plan_artifact)]), - bridge_state: Some(bridge_state), - updated_at: plan_state.updated_at, - }) -} - -fn current_plan_artifact_ref( - session_id: &str, - working_dir: &Path, - plan_state: &SessionPlanState, -) -> Result, ApplicationError> { - let plan_path = - session_plan_markdown_path(session_id, working_dir, &plan_state.active_plan_slug)?; - let Ok(content) = fs::read_to_string(&plan_path) else { - return Ok(None); - }; - Ok(Some(WorkflowArtifactRef { - artifact_kind: "canonical-plan".to_string(), - path: plan_path.display().to_string(), - content_digest: Some(session_plan_content_digest(content.trim())), - })) -} - -fn load_plan_to_execute_bridge_state( - session_id: &str, - working_dir: &Path, - plan_state: &SessionPlanState, -) -> Result { - let (plan_artifact, plan_content) = - load_required_plan_artifact(session_id, working_dir, plan_state)?; - Ok(PlanToExecuteBridgeState { - plan_artifact, - plan_title: plan_state.title.clone(), - implementation_steps: extract_implementation_steps(&plan_content), - approved_at: plan_state.approved_at, - }) -} - -fn load_required_plan_artifact( - session_id: &str, - working_dir: &Path, - plan_state: &SessionPlanState, -) -> Result<(WorkflowArtifactRef, String), ApplicationError> { - let plan_path = - session_plan_markdown_path(session_id, working_dir, &plan_state.active_plan_slug)?; - let plan_content = match fs::read_to_string(&plan_path) { - Ok(content) => content, - Err(error) if error.kind() == std::io::ErrorKind::NotFound => { - return Err(ApplicationError::Internal(format!( - "approved plan artifact '{}' is missing", - plan_path.display() - ))); - }, - Err(error) => return Err(io_error("reading", &plan_path, error)), - }; - Ok(( - WorkflowArtifactRef { - artifact_kind: "canonical-plan".to_string(), - path: plan_path.display().to_string(), - content_digest: Some(session_plan_content_digest(plan_content.trim())), - }, - plan_content, - )) -} - -fn extract_implementation_steps(content: &str) -> Vec { - let mut in_steps_section = false; - let mut steps = Vec::new(); - - for line in content.lines() { - let trimmed = line.trim(); - if trimmed.starts_with("## ") { - if in_steps_section { - break; - } - in_steps_section = matches!( - trimmed, - "## Implementation Steps" | "## 实现步骤" | "## 实施步骤" - ); - continue; - } - if !in_steps_section { - continue; - } - - let parsed_step = trimmed - .strip_prefix("- ") - .map(|summary| (None, summary)) - .or_else(|| trimmed.strip_prefix("* ").map(|summary| (None, summary))) - .or_else(|| trimmed.strip_prefix("+ ").map(|summary| (None, summary))) - .or_else(|| { - trimmed.split_once(". ").and_then(|(prefix, rest)| { - prefix - .parse::() - .ok() - .map(|parsed_index| (Some(parsed_index), rest)) - }) - }) - .map(|(parsed_index, summary)| (parsed_index, summary.trim())) - .filter(|(_, summary)| !summary.is_empty()); - let Some((parsed_index, summary)) = parsed_step else { - continue; - }; - - let summary = summary.to_string(); - steps.push(PlanImplementationStep { - index: parsed_index.unwrap_or(steps.len() + 1), - title: summary.clone(), - summary, - }); - } - - steps -} - -fn io_error(action: &str, path: &Path, error: std::io::Error) -> ApplicationError { - ApplicationError::Internal(format!("{action} '{}' failed: {error}", path.display())) -} - -#[cfg(test)] -mod tests { - use std::{ - collections::BTreeMap, - fs, - path::{Path, PathBuf}, - sync::{ - Arc, Mutex, - atomic::{AtomicUsize, Ordering}, - }, - }; - - use astrcode_core::{ModeId, SessionPlanState, SessionPlanStatus, WorkflowInstanceState}; - use astrcode_session_runtime::SessionModeSnapshot; - use chrono::{TimeZone, Utc}; - - use super::{ - advance_plan_workflow_to_execution, bootstrap_plan_workflow_state, - extract_implementation_steps, reconcile_workflow_phase_mode, - revert_execution_to_planning_workflow_state, - }; - use crate::{ - ApplicationError, - workflow::{ - EXECUTING_PHASE_ID, PLAN_EXECUTE_WORKFLOW_ID, PLANNING_PHASE_ID, WorkflowOrchestrator, - }, - }; - - fn prepare_working_dir() -> (astrcode_core::test_support::TestEnvGuard, PathBuf) { - let guard = astrcode_core::test_support::TestEnvGuard::new(); - let working_dir = guard.home_dir().join("workspace"); - fs::create_dir_all(&working_dir).expect("workspace should exist"); - (guard, working_dir) - } - - fn sample_plan_state(status: SessionPlanStatus) -> SessionPlanState { - let now = Utc - .with_ymd_and_hms(2026, 4, 21, 9, 0, 0) - .single() - .expect("datetime should be valid"); - SessionPlanState { - active_plan_slug: "cleanup-crates".to_string(), - title: "Cleanup crates".to_string(), - status, - created_at: now, - updated_at: now, - reviewed_plan_digest: None, - approved_at: None, - archived_plan_digest: None, - archived_at: None, - } - } - - fn persist_plan_fixture( - session_id: &str, - working_dir: &Path, - status: SessionPlanStatus, - write_markdown: bool, - ) -> SessionPlanState { - let mut state = sample_plan_state(status.clone()); - if matches!(status, SessionPlanStatus::Approved) { - state.approved_at = Some(state.updated_at); - } - let plan_dir = crate::session_plan::session_plan_dir(session_id, working_dir) - .expect("plan dir should resolve"); - fs::create_dir_all(&plan_dir).expect("plan dir should exist"); - fs::write( - plan_dir.join("state.json"), - serde_json::to_string_pretty(&state).expect("plan state should serialize"), - ) - .expect("plan state should persist"); - if write_markdown { - let plan_path = crate::session_plan::session_plan_markdown_path( - session_id, - working_dir, - &state.active_plan_slug, - ) - .expect("plan path should resolve"); - fs::write( - plan_path, - "# Plan: Cleanup crates\n\n## Implementation Steps\n1. Audit crate boundaries\n- \ - Remove duplicated workflow state\n", - ) - .expect("plan markdown should persist"); - } - state - } - - fn workflow_state(current_phase_id: &str) -> WorkflowInstanceState { - WorkflowInstanceState { - workflow_id: PLAN_EXECUTE_WORKFLOW_ID.to_string(), - current_phase_id: current_phase_id.to_string(), - artifact_refs: BTreeMap::new(), - bridge_state: None, - updated_at: Utc - .with_ymd_and_hms(2026, 4, 21, 9, 0, 0) - .single() - .expect("datetime should be valid"), - } - } - - #[test] - fn planning_workflow_state_skips_missing_plan_artifact() { - let (_guard, working_dir) = prepare_working_dir(); - - let state = bootstrap_plan_workflow_state( - "session-a", - &working_dir, - &astrcode_core::ModeId::plan(), - ) - .expect("bootstrap should succeed") - .unwrap_or_else(|| panic!("plan mode should bootstrap planning state")); - - assert!( - !state.artifact_refs.contains_key("canonical-plan"), - "missing markdown file should not produce phantom artifact ref" - ); - } - - #[test] - fn advance_plan_workflow_to_execution_returns_none_without_plan_state() { - let (_guard, working_dir) = prepare_working_dir(); - - let next = advance_plan_workflow_to_execution("session-a", &working_dir) - .expect("missing plan state should not fail"); - - assert!(next.is_none()); - } - - #[test] - fn advance_plan_workflow_to_execution_returns_none_when_plan_is_not_reviewable() { - let (_guard, working_dir) = prepare_working_dir(); - persist_plan_fixture("session-a", &working_dir, SessionPlanStatus::Draft, true); - - let next = advance_plan_workflow_to_execution("session-a", &working_dir) - .expect("draft plan should not fail"); - - assert!(next.is_none()); - } - - #[test] - fn advance_plan_workflow_to_execution_rejects_missing_approved_plan_artifact() { - let (_guard, working_dir) = prepare_working_dir(); - persist_plan_fixture( - "session-a", - &working_dir, - SessionPlanStatus::Approved, - false, - ); - - let error = advance_plan_workflow_to_execution("session-a", &working_dir) - .expect_err("approved plan without markdown should fail"); - - assert!(matches!(error, ApplicationError::Internal(_))); - assert!(error.to_string().contains("approved plan artifact")); - } - - #[test] - fn revert_execution_to_planning_workflow_state_restores_canonical_plan_reference() { - let (_guard, working_dir) = prepare_working_dir(); - let state = - persist_plan_fixture("session-a", &working_dir, SessionPlanStatus::Approved, true); - - let planning = revert_execution_to_planning_workflow_state("session-a", &working_dir) - .expect("reverting workflow state should succeed"); - - assert_eq!(planning.workflow_id, PLAN_EXECUTE_WORKFLOW_ID); - assert_eq!(planning.current_phase_id, PLANNING_PHASE_ID); - assert!(planning.bridge_state.is_none()); - assert_eq!( - planning - .artifact_refs - .get("canonical-plan") - .expect("canonical plan should exist") - .path, - crate::session_plan::session_plan_markdown_path( - "session-a", - &working_dir, - &state.active_plan_slug - ) - .expect("plan path should resolve") - .display() - .to_string() - ); - } - - #[test] - fn extract_implementation_steps_preserves_explicit_numbering() { - let steps = extract_implementation_steps( - "# Plan\n\n## 实现步骤\n2. 第二步\n4. 第四步\n- 无序补充\n", - ); - - assert_eq!(steps.len(), 3); - assert_eq!(steps[0].index, 2); - assert_eq!(steps[0].summary, "第二步"); - assert_eq!(steps[1].index, 4); - assert_eq!(steps[1].summary, "第四步"); - assert_eq!(steps[2].index, 3); - } - - #[tokio::test] - async fn reconcile_workflow_phase_mode_keeps_current_mode_when_phase_already_matches() { - let (_guard, working_dir) = prepare_working_dir(); - let calls = Arc::new(AtomicUsize::new(0)); - - let mode = reconcile_workflow_phase_mode( - &WorkflowOrchestrator::default(), - "session-a", - &working_dir, - ModeId::plan(), - &workflow_state(PLANNING_PHASE_ID), - None, - |_| { - let calls = Arc::clone(&calls); - async move { - calls.fetch_add(1, Ordering::SeqCst); - Err(ApplicationError::Internal( - "switch_mode should not be called".to_string(), - )) - } - }, - ) - .await - .expect("matching phase mode should succeed"); - - assert_eq!(mode, ModeId::plan()); - assert_eq!(calls.load(Ordering::SeqCst), 0); - } - - #[tokio::test] - async fn reconcile_workflow_phase_mode_allows_reviewing_approved_plan_in_code_mode() { - let (_guard, working_dir) = prepare_working_dir(); - let calls = Arc::new(AtomicUsize::new(0)); - let plan_state = sample_plan_state(SessionPlanStatus::AwaitingApproval); - - let mode = reconcile_workflow_phase_mode( - &WorkflowOrchestrator::default(), - "session-a", - &working_dir, - ModeId::code(), - &workflow_state(PLANNING_PHASE_ID), - Some(&plan_state), - |_| { - let calls = Arc::clone(&calls); - async move { - calls.fetch_add(1, Ordering::SeqCst); - Err(ApplicationError::Internal( - "switch_mode should not be called".to_string(), - )) - } - }, - ) - .await - .expect("planning review mode should stay in code mode"); - - assert_eq!(mode, ModeId::code()); - assert_eq!(calls.load(Ordering::SeqCst), 0); - } - - #[tokio::test] - async fn reconcile_workflow_phase_mode_switches_to_phase_mode_when_needed() { - let (_guard, working_dir) = prepare_working_dir(); - let requested_modes = Arc::new(Mutex::new(Vec::new())); - - let mode = reconcile_workflow_phase_mode( - &WorkflowOrchestrator::default(), - "session-a", - &working_dir, - ModeId::plan(), - &workflow_state(EXECUTING_PHASE_ID), - None, - |target_mode| { - let requested_modes = Arc::clone(&requested_modes); - async move { - requested_modes - .lock() - .expect("requested mode lock should work") - .push(target_mode.clone()); - Ok(SessionModeSnapshot { - current_mode_id: target_mode, - last_mode_changed_at: None, - }) - } - }, - ) - .await - .expect("mode reconcile should switch to executing mode"); - - assert_eq!(mode, ModeId::code()); - assert_eq!( - requested_modes - .lock() - .expect("requested mode lock should work") - .as_slice(), - &[ModeId::code()] - ); - } -} diff --git a/crates/application/src/workflow/state.rs b/crates/application/src/workflow/state.rs deleted file mode 100644 index 4fff86e6..00000000 --- a/crates/application/src/workflow/state.rs +++ /dev/null @@ -1,176 +0,0 @@ -use std::{ - fs, - path::{Path, PathBuf}, -}; - -use astrcode_core::WorkflowInstanceState; -use astrcode_support::hostpaths::project_dir; - -use crate::ApplicationError; - -const WORKFLOW_DIR_NAME: &str = "workflow"; -const WORKFLOW_STATE_FILE_NAME: &str = "state.json"; - -#[derive(Debug, Clone, Default)] -pub struct WorkflowStateService; - -impl WorkflowStateService { - pub fn workflow_dir(session_id: &str, working_dir: &Path) -> Result { - Ok(project_dir(working_dir) - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to resolve project directory for '{}': {error}", - working_dir.display() - )) - })? - .join("sessions") - .join(session_id) - .join(WORKFLOW_DIR_NAME)) - } - - pub fn state_path(session_id: &str, working_dir: &Path) -> Result { - Ok(Self::workflow_dir(session_id, working_dir)?.join(WORKFLOW_STATE_FILE_NAME)) - } - - pub fn load( - session_id: &str, - working_dir: &Path, - ) -> Result, ApplicationError> { - let path = Self::state_path(session_id, working_dir)?; - if !path.exists() { - return Ok(None); - } - let content = - fs::read_to_string(&path).map_err(|error| io_error("reading", &path, error))?; - serde_json::from_str::(&content) - .map(Some) - .map_err(|error| { - ApplicationError::Internal(format!( - "failed to parse workflow state '{}': {error}", - path.display() - )) - }) - } - - pub fn load_recovering( - session_id: &str, - working_dir: &Path, - ) -> Result, ApplicationError> { - let path = Self::state_path(session_id, working_dir)?; - match Self::load(session_id, working_dir) { - Ok(state) => Ok(state), - Err(error) => { - log::warn!( - "failed to recover workflow state '{}', degrading to mode-only: {}", - path.display(), - error - ); - Ok(None) - }, - } - } - - pub fn persist( - session_id: &str, - working_dir: &Path, - state: &WorkflowInstanceState, - ) -> Result<(), ApplicationError> { - let path = Self::state_path(session_id, working_dir)?; - let Some(parent) = path.parent() else { - return Err(ApplicationError::Internal(format!( - "workflow state '{}' has no parent directory", - path.display() - ))); - }; - fs::create_dir_all(parent) - .map_err(|error| io_error("creating directory", parent, error))?; - let content = serde_json::to_string_pretty(state).map_err(|error| { - ApplicationError::Internal(format!( - "failed to serialize workflow state '{}': {error}", - path.display() - )) - })?; - fs::write(&path, content).map_err(|error| io_error("writing", &path, error)) - } - - pub fn clear(session_id: &str, working_dir: &Path) -> Result<(), ApplicationError> { - let path = Self::state_path(session_id, working_dir)?; - if !path.exists() { - return Ok(()); - } - fs::remove_file(&path).map_err(|error| io_error("removing", &path, error)) - } -} - -fn io_error(action: &str, path: &Path, error: std::io::Error) -> ApplicationError { - ApplicationError::Internal(format!("{action} '{}' failed: {error}", path.display())) -} - -#[cfg(test)] -mod tests { - use std::{collections::BTreeMap, fs}; - - use astrcode_core::{WorkflowArtifactRef, WorkflowInstanceState}; - use chrono::{TimeZone, Utc}; - use tempfile::tempdir; - - use super::WorkflowStateService; - - #[test] - fn workflow_state_service_round_trips_state_file() { - let _guard = astrcode_core::test_support::TestEnvGuard::new(); - let temp = tempdir().expect("tempdir should exist"); - let state = WorkflowInstanceState { - workflow_id: "plan_execute".to_string(), - current_phase_id: "planning".to_string(), - artifact_refs: BTreeMap::from([( - "canonical-plan".to_string(), - WorkflowArtifactRef { - artifact_kind: "canonical-plan".to_string(), - path: "/tmp/plan.md".to_string(), - content_digest: Some("abc".to_string()), - }, - )]), - bridge_state: None, - updated_at: Utc - .with_ymd_and_hms(2026, 4, 21, 9, 0, 0) - .single() - .expect("datetime should be valid"), - }; - - WorkflowStateService::persist("session-a", temp.path(), &state) - .expect("state should persist"); - let loaded = WorkflowStateService::load("session-a", temp.path()) - .expect("state should load") - .expect("state should exist"); - - assert_eq!(loaded, state); - assert!( - WorkflowStateService::state_path("session-a", temp.path()) - .expect("path should resolve") - .display() - .to_string() - .ends_with("workflow\\state.json") - || WorkflowStateService::state_path("session-a", temp.path()) - .expect("path should resolve") - .display() - .to_string() - .ends_with("workflow/state.json") - ); - } - - #[test] - fn load_recovering_downgrades_invalid_json_to_none() { - let _guard = astrcode_core::test_support::TestEnvGuard::new(); - let temp = tempdir().expect("tempdir should exist"); - let path = WorkflowStateService::state_path("session-a", temp.path()) - .expect("path should resolve"); - fs::create_dir_all(path.parent().expect("parent should exist")) - .expect("parent dir should exist"); - fs::write(&path, "{not-json").expect("invalid state should be written"); - - let loaded = WorkflowStateService::load_recovering("session-a", temp.path()) - .expect("recovery should not fail"); - assert!(loaded.is_none()); - } -} diff --git a/crates/core/src/action.rs b/crates/core/src/action.rs index 6661545b..7784de94 100644 --- a/crates/core/src/action.rs +++ b/crates/core/src/action.rs @@ -470,9 +470,9 @@ mod tests { } #[test] - fn user_message_origin_accepts_legacy_auto_continue_nudge_alias() { + fn user_message_origin_accepts_previous_auto_continue_nudge_alias() { let parsed: UserMessageOrigin = - serde_json::from_str("\"auto_continue_nudge\"").expect("legacy origin should parse"); + serde_json::from_str("\"auto_continue_nudge\"").expect("previous origin should parse"); assert_eq!(parsed, UserMessageOrigin::ContinuationPrompt); } diff --git a/crates/core/src/agent/executor.rs b/crates/core/src/agent/executor.rs deleted file mode 100644 index 46fc4170..00000000 --- a/crates/core/src/agent/executor.rs +++ /dev/null @@ -1,40 +0,0 @@ -//! # Agent 协作执行端口 -//! -//! Why: `spawn/send/observe/close` 工具属于 adapter 层，但其执行契约属于 -//! 业务编排边界，必须由 core 定义，避免 application 反向依赖 adapter crate。 - -use async_trait::async_trait; - -use crate::{ - CloseAgentParams, CollaborationResult, ObserveParams, Result, SendAgentParams, - SpawnAgentParams, SubRunResult, ToolContext, -}; - -/// 子 Agent 启动执行端口。 -#[async_trait] -pub trait SubAgentExecutor: Send + Sync { - /// 启动子 Agent，返回结构化执行结果。 - async fn launch(&self, params: SpawnAgentParams, ctx: &ToolContext) -> Result; -} - -/// 子 Agent 协作执行端口（send / close / observe）。 -#[async_trait] -pub trait CollaborationExecutor: Send + Sync { - /// 发送追加消息给既有子 Agent。 - async fn send(&self, params: SendAgentParams, ctx: &ToolContext) - -> Result; - - /// 关闭目标子 Agent（级联关闭其子树）。 - async fn close( - &self, - params: CloseAgentParams, - ctx: &ToolContext, - ) -> Result; - - /// 观测目标子 Agent 快照。 - async fn observe( - &self, - params: ObserveParams, - ctx: &ToolContext, - ) -> Result; -} diff --git a/crates/core/src/agent/lifecycle.rs b/crates/core/src/agent/lifecycle.rs index cdcc20da..41a753c2 100644 --- a/crates/core/src/agent/lifecycle.rs +++ b/crates/core/src/agent/lifecycle.rs @@ -1,18 +1,18 @@ //! # Agent 生命周期与轮次结果 //! -//! 将旧 `AgentStatus` 拆分为两层： +//! Agent 状态拆为两层： //! - `AgentLifecycleStatus`：agent 的长期生命周期（Pending → Running → Idle → Terminated） //! - `AgentTurnOutcome`：最近一轮执行的结束原因 //! -//! 拆分理由：旧 `AgentStatus` 同时承担生命周期（Pending/Running）和单轮结果（Completed/Failed）， +//! 拆分理由：单一状态同时承担生命周期（Pending/Running）和单轮结果（Completed/Failed）， //! 无法表达"agent 完成一轮后进入空闲可继续接收指令"这一四工具模型核心状态。 use serde::{Deserialize, Serialize}; /// Agent 的持久生命周期状态。 /// -/// 与旧 `AgentStatus` 不同，该枚举只描述 agent 实例的长期存活阶段， -/// 不包含单轮执行的具体结束原因（后者由 `AgentTurnOutcome` 表达）。 +/// 该枚举只描述 agent 实例的长期存活阶段，不包含单轮执行的具体结束原因 +/// （后者由 `AgentTurnOutcome` 表达）。 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "camelCase")] pub enum AgentLifecycleStatus { diff --git a/crates/core/src/agent/mod.rs b/crates/core/src/agent/mod.rs index d0c7aa11..5076dfb3 100644 --- a/crates/core/src/agent/mod.rs +++ b/crates/core/src/agent/mod.rs @@ -14,7 +14,6 @@ pub mod collaboration; pub mod delivery; -pub mod executor; pub mod input_queue; pub mod lifecycle; pub mod lineage; @@ -36,7 +35,7 @@ pub use lifecycle::{AgentLifecycleStatus, AgentTurnOutcome}; pub use lineage::{ ChildAgentRef, ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNode, ChildSessionNotification, ChildSessionNotificationKind, ChildSessionStatusSource, - LineageSnapshot, ParentExecutionRef, SubRunHandle, + LineageSnapshot, ParentExecutionRef, }; use serde::{Deserialize, Serialize}; pub use spawn::{ diff --git a/crates/core/src/config.rs b/crates/core/src/config.rs index f845afcc..a585750d 100644 --- a/crates/core/src/config.rs +++ b/crates/core/src/config.rs @@ -52,6 +52,7 @@ pub const DEFAULT_FINALIZED_AGENT_RETAIN_LIMIT: usize = 256; pub const DEFAULT_INBOX_CAPACITY: usize = 1024; pub const DEFAULT_PARENT_DELIVERY_CAPACITY: usize = 1024; pub const DEFAULT_MAX_CONSECUTIVE_FAILURES: usize = 3; +pub const DEFAULT_MAX_OUTPUT_CONTINUATION_ATTEMPTS: usize = 3; pub const DEFAULT_RECOVERY_TRUNCATE_BYTES: usize = 30_000; pub const DEFAULT_API_SESSION_TTL_HOURS: i64 = 8; @@ -112,6 +113,8 @@ pub struct RuntimeConfig { #[serde(skip_serializing_if = "Option::is_none")] pub max_consecutive_failures: Option, #[serde(skip_serializing_if = "Option::is_none")] + pub max_output_continuation_attempts: Option, + #[serde(skip_serializing_if = "Option::is_none")] pub recovery_truncate_bytes: Option, #[serde(skip_serializing_if = "Option::is_none")] @@ -206,6 +209,7 @@ pub struct ResolvedRuntimeConfig { pub compact_keep_recent_user_messages: u8, pub agent: ResolvedAgentConfig, pub max_consecutive_failures: usize, + pub max_output_continuation_attempts: usize, pub recovery_truncate_bytes: usize, pub llm_connect_timeout_secs: u64, pub llm_read_timeout_secs: u64, @@ -268,6 +272,7 @@ impl Default for ResolvedRuntimeConfig { compact_keep_recent_user_messages: DEFAULT_COMPACT_KEEP_RECENT_USER_MESSAGES, agent: ResolvedAgentConfig::default(), max_consecutive_failures: DEFAULT_MAX_CONSECUTIVE_FAILURES, + max_output_continuation_attempts: DEFAULT_MAX_OUTPUT_CONTINUATION_ATTEMPTS, recovery_truncate_bytes: DEFAULT_RECOVERY_TRUNCATE_BYTES, llm_connect_timeout_secs: DEFAULT_LLM_CONNECT_TIMEOUT_SECS, llm_read_timeout_secs: DEFAULT_LLM_READ_TIMEOUT_SECS, @@ -459,6 +464,10 @@ impl fmt::Debug for RuntimeConfig { ) .field("agent", &self.agent) .field("max_consecutive_failures", &self.max_consecutive_failures) + .field( + "max_output_continuation_attempts", + &self.max_output_continuation_attempts, + ) .field("recovery_truncate_bytes", &self.recovery_truncate_bytes) .field("llm_connect_timeout_secs", &self.llm_connect_timeout_secs) .field("llm_read_timeout_secs", &self.llm_read_timeout_secs) @@ -697,6 +706,10 @@ pub fn resolve_runtime_config(runtime: &RuntimeConfig) -> ResolvedRuntimeConfig .max_consecutive_failures .unwrap_or(defaults.max_consecutive_failures) .max(1), + max_output_continuation_attempts: runtime + .max_output_continuation_attempts + .unwrap_or(defaults.max_output_continuation_attempts) + .max(1), recovery_truncate_bytes: runtime .recovery_truncate_bytes .unwrap_or(defaults.recovery_truncate_bytes) @@ -811,6 +824,10 @@ mod tests { resolved.compact_max_output_tokens, DEFAULT_COMPACT_MAX_OUTPUT_TOKENS ); + assert_eq!( + resolved.max_output_continuation_attempts, + DEFAULT_MAX_OUTPUT_CONTINUATION_ATTEMPTS + ); } #[test] @@ -818,6 +835,7 @@ mod tests { let resolved = resolve_runtime_config(&RuntimeConfig { max_tool_concurrency: Some(16), llm_read_timeout_secs: Some(120), + max_output_continuation_attempts: Some(5), agent: Some(AgentConfig { max_subrun_depth: Some(5), max_spawn_per_turn: Some(2), @@ -828,6 +846,7 @@ mod tests { assert_eq!(resolved.max_tool_concurrency, 16); assert_eq!(resolved.llm_read_timeout_secs, 120); + assert_eq!(resolved.max_output_continuation_attempts, 5); assert_eq!(resolved.agent.max_subrun_depth, 5); assert_eq!(resolved.agent.max_spawn_per_turn, 2); } diff --git a/crates/core/src/event/domain.rs b/crates/core/src/event/domain.rs index ea28115a..38cf894e 100644 --- a/crates/core/src/event/domain.rs +++ b/crates/core/src/event/domain.rs @@ -70,6 +70,14 @@ pub enum AgentEvent { agent: AgentEventContext, delta: String, }, + /// provider 流式响应坏流后开始重试。 + StreamRetryStarted { + turn_id: String, + agent: AgentEventContext, + attempt: u32, + max_attempts: u32, + reason: String, + }, /// 助手消息（完整内容） AssistantMessage { turn_id: String, diff --git a/crates/core/src/event/types.rs b/crates/core/src/event/types.rs index df530733..d5f99b27 100644 --- a/crates/core/src/event/types.rs +++ b/crates/core/src/event/types.rs @@ -15,9 +15,9 @@ use serde_json::Value; use crate::{ AgentCollaborationFact, AgentEventContext, AstrError, ChildSessionNotification, ExecutionContinuation, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, - InputQueuedPayload, ModeId, PersistedToolOutput, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, Result, SubRunResult, SystemPromptLayer, ToolOutputStream, - UserMessageOrigin, ports::PromptCacheDiagnostics, + InputQueuedPayload, ModeId, PersistedToolOutput, PromptCacheDiagnostics, + ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, Result, SubRunResult, + SystemPromptLayer, ToolOutputStream, UserMessageOrigin, }; /// Prompt/缓存指标共享载荷。 @@ -493,7 +493,7 @@ mod tests { let event: StorageEvent = serde_json::from_str( r#"{"type":"turnDone","turn_id":"turn-1","timestamp":"2026-01-01T00:00:00Z","reason":"custom-free-text"}"#, ) - .expect("legacy turn done should deserialize"); + .expect("previous turn done should deserialize"); match event { StorageEvent { diff --git a/crates/core/src/hook.rs b/crates/core/src/hook.rs index b5414e0a..83f08505 100644 --- a/crates/core/src/hook.rs +++ b/crates/core/src/hook.rs @@ -20,11 +20,10 @@ use std::path::PathBuf; -use async_trait::async_trait; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::{CompactTrigger, LlmMessage, Result, ToolDefinition, ToolExecutionResult}; +use crate::{CompactTrigger, LlmMessage, ToolDefinition, ToolExecutionResult}; /// 可被外部扩展拦截的生命周期事件。 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)] @@ -37,6 +36,26 @@ pub enum HookEvent { PostCompact, } +/// 新 hooks catalog 的稳定事件键。 +/// +/// 这些键是跨 owner 共享的最小语义；具体 payload、effect 解释与调度报告 +/// 归属 `agent-runtime`、`host-session` 或 `plugin-host`。 +#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)] +#[serde(rename_all = "snake_case")] +pub enum HookEventKey { + Input, + Context, + BeforeAgentStart, + BeforeProviderRequest, + ToolCall, + ToolResult, + TurnStart, + TurnEnd, + SessionBeforeCompact, + ResourcesDiscover, + ModelSelect, +} + /// 工具调用的公共上下文。 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[serde(rename_all = "camelCase")] @@ -99,78 +118,3 @@ pub struct CompactionHookResultContext { pub messages_removed: usize, pub tokens_freed: usize, } - -/// Hook 统一输入。 -#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] -#[serde(rename_all = "camelCase")] -pub enum HookInput { - PreToolUse(ToolHookContext), - PostToolUse(ToolHookResultContext), - PostToolUseFailure(ToolHookResultContext), - PreCompact(CompactionHookContext), - PostCompact(CompactionHookResultContext), -} - -impl HookInput { - pub fn event(&self) -> HookEvent { - match self { - Self::PreToolUse(_) => HookEvent::PreToolUse, - Self::PostToolUse(_) => HookEvent::PostToolUse, - Self::PostToolUseFailure(_) => HookEvent::PostToolUseFailure, - Self::PreCompact(_) => HookEvent::PreCompact, - Self::PostCompact(_) => HookEvent::PostCompact, - } - } -} - -/// Hook 对生命周期流程施加的影响。 -#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] -#[serde(rename_all = "camelCase")] -pub enum HookOutcome { - /// 不改变当前流程，继续执行下一个 hook。 - Continue, - /// 明确阻止当前动作继续。 - Block { reason: String }, - /// 仅允许 `PreToolUse` 修改工具参数。 - ReplaceToolArgs { args: Value }, - /// 仅允许 `PreCompact` 修改压缩上下文。 - /// - /// 通过此变体，hook 可以： - /// - 在默认 compact prompt 后追加自定义指令 - /// - 覆盖保留的最近 turn 数量（动态调整保留策略） - /// - 提供自定义摘要（跳过 LLM 调用，完全接管压缩逻辑） - ModifyCompactContext { - /// 在默认 compact prompt 后追加的系统指令。 - /// 如果提供，将以附加段的方式拼接，避免插件直接替换整套默认压缩约束。 - #[serde(default, skip_serializing_if = "Option::is_none")] - additional_system_prompt: Option, - /// 覆盖保留的最近 turn 数量。 - /// 如果提供，将替换 `keep_recent_turns` 配置。 - #[serde(default, skip_serializing_if = "Option::is_none")] - override_keep_recent_turns: Option, - /// 提供自定义摘要内容。 - /// 如果提供，将跳过 LLM 压缩调用，直接使用此摘要。 - /// 这允许插件完全接管压缩逻辑（例如使用外部服务生成摘要）。 - #[serde(default, skip_serializing_if = "Option::is_none")] - custom_summary: Option, - }, -} - -#[async_trait] -pub trait HookHandler: Send + Sync { - /// 稳定的人类可读名称，用于日志和报错。 - fn name(&self) -> &str; - - /// 声明本 handler 关注的生命周期节点。 - fn event(&self) -> HookEvent; - - /// 可选匹配器，用于做 tool name / source 等更细粒度筛选。 - fn matches(&self, input: &HookInput) -> bool { - // 故意忽略：trait 默认实现不使用 input，只是消除未使用变量警告 - let _ = input; - true - } - - /// 执行 hook。 - async fn run(&self, input: &HookInput) -> Result; -} diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 7421d344..3c316b83 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -1,56 +1,15 @@ -//! # Astrcode 核心库 +//! Astrcode 最小共享语义层。 //! -//! 本库定义了 Astrcode 系统的核心领域模型和接口，与具体的运行时实现解耦。 -//! -//! ## 主要模块 -//! -//! ### 领域模型 -//! -//! - [`agent`][]: Agent 协作模型、子运行管理、输入队列 -//! - [`capability`][]: 能力规格定义（CapabilitySpec 等） -//! - [`ids`][]: 核心标识符类型（AgentId, SessionId, TurnId 等） -//! - [`action`][]: LLM 消息与工具调用相关的数据结构 -//! -//! ### 事件与会话 -//! -//! - [`event`][]: 事件存储与回放系统（JSONL append-only 日志） -//! - [`session`][]: 会话元数据 -//! - [`store`][]: 会话存储与事件日志写入 -//! - [`projection`][]: Agent 状态投影（从事件流推导状态） -//! -//! ### 治理与策略 -//! -//! - [`mode`][]: 治理模式（Code/Plan/Review 模式与策略规则） -//! - [`policy`][]: 策略引擎 trait（审批与模型/工具请求检查） -//! -//! ### 扩展点 -//! -//! - [`ports`][]: 核心 port trait 定义（LlmProvider, PromptProvider, EventStore 等） -//! - [`tool`][]: Tool trait 定义（插件系统的基础抽象） -//! - [`plugin`][]: 插件清单与注册表 -//! - [`registry`][]: 能力路由器（将能力调用分派到具体的 invoker） -//! - [`hook`][]: 钩子系统（工具/压缩钩子） -//! -//! ### 运行时与配置 -//! -//! - [`runtime`][]: 运行时协调器接口 -//! - [`config`][]: 配置模型（Agent/Model/Runtime 配置） -//! - [`observability`][]: 运行时可观测性指标 -//! -//! ### 基础设施 -//! -//! - [`env`][]: 环境变量解析 -//! - [`local_server`][]: 本地服务器信息 -//! - [`project`][]: 项目标识与目录名算法 -//! - [`shell`][]: Shell 检测与解析 -//! - [`tool_result_persist`][]: 工具结果持久化 +//! `core` 只作为跨 owner 共享的值对象和稳定语义入口。session durable +//! truth、plugin descriptor、运行时执行面、projection、workflow、mode 等 +//! owner 专属模型不再作为顶层默认导出；仍保留的历史模块路径仅供 owner +//! bridge 内部复用，不应被新调用方继续视为正式入口。 mod action; pub mod agent; mod cancel; pub mod capability; mod compact_summary; -mod composer; pub mod config; pub mod env; mod error; @@ -64,57 +23,71 @@ pub mod local_server; mod mcp; pub mod mode; pub mod observability; -pub mod plugin; pub mod policy; pub mod ports; pub mod project; -pub mod projection; +mod prompt; pub mod registry; pub mod runtime; pub mod session; -mod session_catalog; -mod session_plan; mod shell; mod skill; pub mod store; -mod time; -// test_support 通过 feature gate "test-support" 守卫。 -// 其他 crate 在 dev-dependencies 中启用此 feature：astrcode-core = { features = ["test-support"] -// }。 发布构建默认不启用，tempfile 不会被编译进产物。 pub mod support; #[cfg(feature = "test-support")] pub mod test_support; +mod time; mod tool; pub mod tool_result_persist; -mod workflow; pub use action::{ AssistantContentParts, LlmMessage, ReasoningContent, ToolCallRequest, ToolDefinition, ToolExecutionResult, ToolOutputDelta, ToolOutputStream, UserMessageOrigin, split_assistant_content, }; +#[doc(hidden)] pub use agent::{ - AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, - AgentCollaborationPolicyContext, AgentEventContext, AgentInboxEnvelope, AgentMode, - AgentProfile, AgentProfileCatalog, ArtifactRef, ChildAgentRef, ChildExecutionIdentity, - ChildSessionLineageKind, ChildSessionNode, ChildSessionNotification, - ChildSessionNotificationKind, ChildSessionStatusSource, CloseAgentParams, - CloseRequestParentDeliveryPayload, CollaborationResult, CompletedParentDeliveryPayload, + AgentCollaborationActionKind, AgentCollaborationFact as PreviousAgentCollaborationFact, + AgentCollaborationOutcomeKind, AgentCollaborationPolicyContext, + AgentEventContext as PreviousAgentEventContext, AgentInboxEnvelope, AgentMode, + AgentProfile as PreviousAgentProfile, AgentProfileCatalog, ArtifactRef, ChildAgentRef, + ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNode as PreviousChildSessionNode, + ChildSessionNotification as PreviousChildSessionNotification, + ChildSessionNotificationKind as PreviousChildSessionNotificationKind, ChildSessionStatusSource, + CloseAgentParams as PreviousCloseAgentParams, CloseRequestParentDeliveryPayload, + CollaborationResult as PreviousCollaborationResult, CompletedParentDeliveryPayload, CompletedSubRunOutcome, DelegationMetadata, FailedParentDeliveryPayload, FailedSubRunOutcome, - ForkMode, InboxEnvelopeKind, InvocationKind, LineageSnapshot, ParentDelivery, - ParentDeliveryKind, ParentDeliveryOrigin, ParentDeliveryPayload, - ParentDeliveryTerminalSemantics, ParentExecutionRef, ProgressParentDeliveryPayload, - ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, SendAgentParams, - SendToChildParams, SendToParentParams, SpawnAgentParams, SubRunFailure, SubRunFailureCode, - SubRunHandle, SubRunHandoff, SubRunResult, SubRunStatus, SubRunStorageMode, - SubagentContextOverrides, - executor::{CollaborationExecutor, SubAgentExecutor}, + ForkMode as PreviousForkMode, InboxEnvelopeKind, InvocationKind as PreviousInvocationKind, + LineageSnapshot, ParentDelivery, ParentDeliveryKind, ParentDeliveryOrigin, + ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ParentExecutionRef, + ProgressParentDeliveryPayload, + ResolvedExecutionLimitsSnapshot as PreviousResolvedExecutionLimitsSnapshot, + ResolvedSubagentContextOverrides as PreviousResolvedSubagentContextOverrides, + SendAgentParams as PreviousSendAgentParams, SendToChildParams, SendToParentParams, + SpawnAgentParams as PreviousSpawnAgentParams, SubRunFailure, SubRunFailureCode, SubRunHandoff, + SubRunResult as PreviousSubRunResult, SubRunStatus, + SubRunStorageMode as PreviousSubRunStorageMode, + SubagentContextOverrides as PreviousSubagentContextOverrides, input_queue::{ - BatchId, CloseParams, DeliveryId, InputBatchAckedPayload, InputBatchStartedPayload, - InputDiscardedPayload, InputQueueProjection, InputQueuedPayload, ObserveParams, + BatchId, CloseParams, DeliveryId as PreviousDeliveryId, + InputBatchAckedPayload as PreviousInputBatchAckedPayload, + InputBatchStartedPayload as PreviousInputBatchStartedPayload, + InputDiscardedPayload as PreviousInputDiscardedPayload, + InputQueuedPayload as PreviousInputQueuedPayload, ObserveParams as PreviousObserveParams, ObserveSnapshot, QueuedInputEnvelope, SendParams, }, - lifecycle::{AgentLifecycleStatus, AgentTurnOutcome}, + lifecycle::{AgentLifecycleStatus, AgentTurnOutcome as PreviousAgentTurnOutcome}, +}; +#[doc(hidden)] +pub use agent::{ + AgentCollaborationFact, AgentEventContext, AgentProfile, AgentTurnOutcome, ChildSessionNode, + ChildSessionNotification, ChildSessionNotificationKind, CloseAgentParams, CollaborationResult, + ForkMode, InvocationKind, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, + SendAgentParams, SpawnAgentParams, SubRunResult, SubRunStorageMode, SubagentContextOverrides, + input_queue::{ + DeliveryId, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, + InputQueuedPayload, ObserveParams, + }, normalize_non_empty_unique_string_list, }; pub use cancel::CancelToken; @@ -126,7 +99,7 @@ pub use compact_summary::{ COMPACT_SUMMARY_CONTINUATION, COMPACT_SUMMARY_PREFIX, CompactSummaryEnvelope, format_compact_summary, parse_compact_summary_message, }; -pub use composer::{ComposerOption, ComposerOptionActionKind, ComposerOptionKind}; +#[doc(hidden)] pub use config::{ ActiveSelection, AgentConfig, Config, ConfigOverlay, CurrentModelSelection, ModelConfig, ModelOption, ModelSelection, OpenAiApiMode, Profile, ResolvedAgentConfig, @@ -140,19 +113,24 @@ pub use event::{ generate_session_id, generate_turn_id, normalize_recovered_phase, phase_of_storage_event, replay_records, }; +#[doc(hidden)] pub use execution_control::ExecutionControl; +#[doc(hidden)] pub use execution_result::{ExecutionContinuation, ExecutionResultCommon}; +#[doc(hidden)] pub use execution_task::{ EXECUTION_TASK_SNAPSHOT_SCHEMA, ExecutionTaskItem, ExecutionTaskSnapshotMetadata, ExecutionTaskStatus, TaskSnapshot, }; +#[doc(hidden)] pub use hook::{ - CompactionHookContext, CompactionHookResultContext, HookEvent, HookHandler, HookInput, - HookOutcome, ToolHookContext, ToolHookResultContext, + CompactionHookContext, CompactionHookResultContext, ToolHookContext, ToolHookResultContext, }; +pub use hook::{HookEvent, HookEventKey}; pub use ids::{AgentId, CapabilityName, SessionId, SubRunId, TurnId}; pub use local_server::{LOCAL_SERVER_READY_PREFIX, LocalServerInfo}; pub use mcp::{McpApprovalData, McpApprovalStatus}; +#[doc(hidden)] pub use mode::{ ActionPolicies, ActionPolicyEffect, ActionPolicyRule, BUILTIN_MODE_CODE_ID, BUILTIN_MODE_PLAN_ID, BUILTIN_MODE_REVIEW_ID, BoundModeToolContractSnapshot, @@ -161,46 +139,40 @@ pub use mode::{ PromptProgramEntry, ResolvedChildPolicy, ResolvedTurnEnvelope, SubmitBusyPolicy, TransitionPolicySpec, }; +#[doc(hidden)] pub use observability::{ AgentCollaborationScorecardSnapshot, ExecutionDiagnosticsSnapshot, OperationMetricsSnapshot, ReplayMetricsSnapshot, ReplayPath, RuntimeMetricsRecorder, RuntimeObservabilitySnapshot, SubRunExecutionMetricsSnapshot, }; -pub use plugin::{PluginHealth, PluginManifest, PluginRegistry, PluginState, PluginType}; +#[doc(hidden)] pub use policy::{ AllowAllPolicyEngine, ApprovalDefault, ApprovalPending, ApprovalRequest, ApprovalResolution, CapabilityCall, ModelRequest, PolicyContext, PolicyEngine, PolicyVerdict, SystemPromptBlock, SystemPromptLayer, }; -pub use ports::{ - EventStore, LlmEvent, LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, - LlmUsage, McpSettingsStore, ModelLimits, ProjectionRegistrySnapshot, PromptAgentProfileSummary, - PromptBuildCacheMetrics, PromptBuildOutput, PromptBuildRequest, PromptCacheBreakReason, - PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, PromptDeclaration, - PromptDeclarationKind, PromptDeclarationRenderTarget, PromptDeclarationSource, - PromptEntrySummary, PromptFacts, PromptFactsProvider, PromptFactsRequest, - PromptGovernanceContext, PromptLayerFingerprints, PromptProvider, PromptSkillSummary, - RecoveredSessionState, ResourceProvider, ResourceReadResult, ResourceRequestContext, - SessionRecoveryCheckpoint, SkillCatalog, TurnProjectionSnapshot, -}; -pub use projection::{AgentState, AgentStateProjector, project}; +#[doc(hidden)] +pub use ports::{McpSettingsStore, SkillCatalog}; +pub use prompt::{ + PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, + PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, + PromptDeclarationSource, PromptLayerFingerprints, +}; pub use registry::{CapabilityContext, CapabilityExecutionResult, CapabilityInvoker}; +#[doc(hidden)] pub use runtime::{ ExecutionAccepted, ExecutionOrchestrationBoundary, LiveSubRunControlBoundary, LoopRunnerBoundary, ManagedRuntimeComponent, RuntimeHandle, SessionTruthBoundary, }; pub use session::{DeleteProjectResult, SessionEventRecord, SessionMeta}; -pub use session_catalog::SessionCatalogEvent; -pub use session_plan::{ - SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER, SessionPlanState, SessionPlanStatus, - session_plan_content_digest, -}; pub use shell::{ResolvedShell, ShellFamily}; pub use skill::{SkillSource, SkillSpec, is_valid_skill_name, normalize_skill_name}; +#[doc(hidden)] pub use store::{ EventLogWriter, SessionManager, SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StoreError, StoreResult, }; +#[doc(hidden)] pub use time::{ format_local_rfc3339, format_local_rfc3339_opt, local_rfc3339, local_rfc3339_option, }; @@ -208,12 +180,9 @@ pub use tool::{ DEFAULT_MAX_OUTPUT_SIZE, ExecutionOwner, Tool, ToolCapabilityMetadata, ToolContext, ToolEventSink, ToolPromptMetadata, }; +#[doc(hidden)] pub use tool_result_persist::{ DEFAULT_TOOL_RESULT_INLINE_LIMIT, PersistedToolOutput, PersistedToolResult, TOOL_RESULT_PREVIEW_LIMIT, TOOL_RESULTS_DIR, is_persisted_output, persisted_output_absolute_path, }; -pub use workflow::{ - WorkflowArtifactRef, WorkflowBridgeState, WorkflowDef, WorkflowInstanceState, WorkflowPhaseDef, - WorkflowSignal, WorkflowTransitionDef, WorkflowTransitionTrigger, -}; diff --git a/crates/core/src/plugin/manifest.rs b/crates/core/src/plugin/manifest.rs deleted file mode 100644 index 3fb21498..00000000 --- a/crates/core/src/plugin/manifest.rs +++ /dev/null @@ -1,53 +0,0 @@ -//! # 插件清单 -//! -//! 定义了插件的描述性元数据结构（`PluginManifest`）和类型枚举（`PluginType`）。 -//! -//! 插件清单从 `Plugin.toml` 文件解析而来，描述插件的名称、版本、能力声明和启动方式。 - -use serde::{Deserialize, Serialize}; - -use crate::CapabilitySpec; - -/// 插件类型。 -/// -/// 一个插件可以同时声明多种类型，每种类型对应不同的运行时行为。 -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] -pub enum PluginType { - /// 工具插件：提供可被 LLM 调用的能力 - Tool, - /// 编排器插件：控制 Agent 的执行流程 - Orchestrator, - /// 提供商插件：提供 LLM API 访问 - Provider, - /// 钩子插件：在特定生命周期事件上执行 - Hook, -} - -/// 插件清单。 -/// -/// 从 `Plugin.toml` 解析，描述插件的元数据和能力声明。 -/// `name` 字段必须与插件目录名一致（kebab-case）。 -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -#[serde(deny_unknown_fields)] -pub struct PluginManifest { - /// 插件名称（必须与目录名一致，kebab-case） - pub name: String, - /// 语义化版本号 - pub version: String, - /// 插件描述 - pub description: String, - /// 插件类型列表 - pub plugin_type: Vec, - /// 能力规范列表（声明该插件提供的能力） - pub capabilities: Vec, - /// 可执行文件路径（可选，用于 sidecar 模式启动） - pub executable: Option, - /// 启动参数 - #[serde(default)] - pub args: Vec, - /// 工作目录（可选） - #[serde(default, skip_serializing_if = "Option::is_none")] - pub working_dir: Option, - /// 仓库地址（可选） - pub repository: Option, -} diff --git a/crates/core/src/plugin/mod.rs b/crates/core/src/plugin/mod.rs deleted file mode 100644 index d0b9a1a5..00000000 --- a/crates/core/src/plugin/mod.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! # 插件系统 -//! -//! 定义了插件的元数据（清单）、注册表和生命周期状态。 -//! -//! ## 模块说明 -//! -//! - `manifest`: 插件清单（`PluginManifest`）和类型（`PluginType`） -//! - `registry`: 插件注册表（`PluginRegistry`），管理插件状态和健康检查 - -mod manifest; -mod registry; - -pub use manifest::{PluginManifest, PluginType}; -pub use registry::{PluginEntry, PluginHealth, PluginRegistry, PluginState}; diff --git a/crates/core/src/plugin/registry.rs b/crates/core/src/plugin/registry.rs deleted file mode 100644 index 607e237a..00000000 --- a/crates/core/src/plugin/registry.rs +++ /dev/null @@ -1,409 +0,0 @@ -//! # 插件注册表 -//! -//! 管理已发现插件的生命周期状态、健康检查和能力声明。 -//! -//! ## 设计要点 -//! -//! - 使用 `RwLock` 保证线程安全和有序遍历 -//! - 插件状态机：`Discovered` → `Initialized` / `Failed` -//! - 健康状态独立于生命周期状态（`Healthy` / `Degraded` / `Unavailable`） -//! - 支持运行时快照替换（用于插件热重载场景） - -use std::{collections::BTreeMap, sync::RwLock}; - -use crate::{CapabilitySpec, PluginManifest}; - -/// 插件生命周期状态。 -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] -#[serde(rename_all = "camelCase")] -pub enum PluginState { - /// 已发现（清单已加载，但尚未初始化） - Discovered, - /// 已初始化（能力已注册，可以正常调用） - Initialized, - /// 初始化失败 - Failed, -} - -/// 插件健康状态。 -/// -/// 与 `PluginState` 不同，健康状态反映运行时状况， -/// 一个已初始化的插件可能因网络问题变为 `Degraded`。 -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] -#[serde(rename_all = "camelCase")] -pub enum PluginHealth { - /// 尚未检查 - Unknown, - /// 正常运行 - Healthy, - /// 部分功能异常 - Degraded, - /// 不可用 - Unavailable, -} - -/// 插件注册表条目。 -/// -/// 包含插件的完整运行时状态：清单、生命周期状态、健康状态、失败记录等。 -#[derive(Debug, Clone)] -pub struct PluginEntry { - /// 插件清单 - pub manifest: PluginManifest, - /// 生命周期状态 - pub state: PluginState, - /// 健康状态 - pub health: PluginHealth, - /// 连续失败次数 - pub failure_count: u32, - /// 已注册的能力列表 - pub capabilities: Vec, - /// 失败原因（仅在失败时设置） - pub failure: Option, - /// 非致命诊断信息（如 skill 物化失败、allowed_tools 被降级）。 - /// - /// 这些 warning 不会改变插件主状态；它们用于把“插件已加载但部分能力 - /// 或资源需要人工关注”的事实显式暴露给上层 UI，而不是静默吞掉。 - pub warnings: Vec, - /// 最后一次健康检查时间 - pub last_checked_at: Option, -} - -/// 插件注册表。 -/// -/// 线程安全的插件状态存储，支持并发读写。 -/// 使用 `RwLock` 而非 `Mutex` 因为读操作远多于写操作。 -#[derive(Debug, Default)] -pub struct PluginRegistry { - plugins: RwLock>, -} - -impl PluginRegistry { - /// 记录一个新发现的插件。 - /// - /// 如果同名插件已存在，会被覆盖。 - pub fn record_discovered(&self, manifest: PluginManifest) { - self.upsert(PluginEntry { - manifest, - state: PluginState::Discovered, - health: PluginHealth::Unknown, - failure_count: 0, - capabilities: Vec::new(), - failure: None, - warnings: Vec::new(), - last_checked_at: None, - }); - } - - /// 记录插件初始化成功，将状态推进到 `Initialized`。 - /// - /// 初始化成功后健康状态重置为 `Healthy`，失败计数清零。 - pub fn record_initialized( - &self, - manifest: PluginManifest, - capabilities: Vec, - warnings: Vec, - ) { - self.upsert(PluginEntry { - manifest, - state: PluginState::Initialized, - health: PluginHealth::Healthy, - failure_count: 0, - capabilities, - failure: None, - warnings, - last_checked_at: None, - }); - } - - /// 记录插件初始化失败，将状态标记为 `Failed`。 - /// - /// 失败后健康状态设为 `Unavailable`，并记录失败原因。 - pub fn record_failed( - &self, - manifest: PluginManifest, - failure: impl Into, - capabilities: Vec, - warnings: Vec, - ) { - self.upsert(PluginEntry { - manifest, - state: PluginState::Failed, - health: PluginHealth::Unavailable, - failure_count: 1, - capabilities, - failure: Some(failure.into()), - warnings, - last_checked_at: None, - }); - } - - /// 按名称查询插件条目。 - /// - /// 返回 `None` 表示该插件尚未被发现或已从注册表中移除。 - pub fn get(&self, name: &str) -> Option { - self.plugins - .read() - .expect("plugin registry lock poisoned") - .get(name) - .cloned() - } - - /// 获取所有插件条目的快照。 - /// - /// 返回当前注册表中所有插件的副本，调用方持有快照后 - /// 注册表的后续变更不会影响已返回的快照。 - pub fn snapshot(&self) -> Vec { - self.plugins - .read() - .expect("plugin registry lock poisoned") - .values() - .cloned() - .collect() - } - - /// 原子替换整个插件注册表快照。 - /// - /// 用于插件热重载场景：新插件集合一次性替换旧集合， - /// 避免逐条更新导致中间状态不一致。 - pub fn replace_snapshot(&self, entries: Vec) { - let mut plugins = self.plugins.write().expect("plugin registry lock poisoned"); - plugins.clear(); - for entry in entries { - plugins.insert(entry.manifest.name.clone(), entry); - } - } - - /// 记录插件运行时成功事件。 - /// - /// 将健康状态重置为 `Healthy` 并清零失败计数， - /// 表明插件当前运行正常。 - pub fn record_runtime_success(&self, name: &str, checked_at: String) { - self.mutate(name, |entry| { - if entry.state == PluginState::Initialized { - entry.health = PluginHealth::Healthy; - } - entry.failure_count = 0; - entry.failure = None; - entry.last_checked_at = Some(checked_at); - }); - } - - /// 记录插件运行时失败事件。 - /// - /// 实现渐进式健康度评估： - /// - 1~2 次失败 → `Degraded`（降级但不完全禁用，后续成功可恢复） - /// - 3 次及以上 → `Unavailable`（完全禁用，需要人工或自动恢复机制介入） - /// - 非 Initialized 状态的插件 → 直接 `Unavailable` - pub fn record_runtime_failure( - &self, - name: &str, - failure: impl Into, - checked_at: String, - ) { - let failure = failure.into(); - self.mutate(name, |entry| { - entry.failure_count = entry.failure_count.saturating_add(1); - entry.failure = Some(failure.clone()); - entry.last_checked_at = Some(checked_at); - if entry.state == PluginState::Initialized { - entry.health = if entry.failure_count >= 3 { - PluginHealth::Unavailable - } else { - PluginHealth::Degraded - }; - } else { - entry.health = PluginHealth::Unavailable; - } - }); - } - - /// 记录一次主动健康探测结果。 - /// - /// 与 `record_runtime_success/failure` 不同，此方法允许调用方 - /// 直接指定健康状态，适用于自定义健康检查逻辑。 - pub fn record_health_probe( - &self, - name: &str, - health: PluginHealth, - failure: Option, - checked_at: String, - ) { - self.mutate(name, |entry| { - entry.health = health.clone(); - if matches!(health, PluginHealth::Healthy) { - entry.failure_count = 0; - entry.failure = None; - } else if let Some(message) = failure.clone() { - entry.failure = Some(message); - } - entry.last_checked_at = Some(checked_at.clone()); - }); - } - - fn upsert(&self, entry: PluginEntry) { - self.plugins - .write() - .expect("plugin registry lock poisoned") - .insert(entry.manifest.name.clone(), entry); - } - - fn mutate(&self, name: &str, update: impl FnOnce(&mut PluginEntry)) { - if let Some(entry) = self - .plugins - .write() - .expect("plugin registry lock poisoned") - .get_mut(name) - { - update(entry); - } - } -} - -#[cfg(test)] -mod tests { - use chrono::Utc; - use serde_json::json; - - use super::{PluginHealth, PluginRegistry, PluginState}; - use crate::{ - CapabilityKind, CapabilitySpec, InvocationMode, PluginManifest, PluginType, SideEffect, - Stability, - }; - - fn manifest(name: &str) -> PluginManifest { - PluginManifest { - name: name.to_string(), - version: "0.1.0".to_string(), - description: format!("{name} manifest"), - plugin_type: vec![PluginType::Tool], - capabilities: Vec::new(), - executable: Some("plugin.exe".to_string()), - args: Vec::new(), - working_dir: None, - repository: None, - } - } - - fn capability(name: &str) -> CapabilitySpec { - CapabilitySpec { - name: name.into(), - kind: CapabilityKind::Tool, - description: format!("{name} capability"), - input_schema: json!({ "type": "object" }), - output_schema: json!({ "type": "object" }), - invocation_mode: InvocationMode::Unary, - concurrency_safe: false, - compact_clearable: false, - profiles: vec!["coding".to_string()], - tags: Vec::new(), - permissions: Vec::new(), - side_effect: SideEffect::None, - stability: Stability::Stable, - metadata: json!(null), - max_result_inline_size: None, - } - } - - #[test] - fn records_state_transitions_and_failure_details() { - let registry = PluginRegistry::default(); - let manifest = manifest("repo-inspector"); - - registry.record_discovered(manifest.clone()); - assert_eq!( - registry - .get("repo-inspector") - .expect("entry should exist") - .state, - PluginState::Discovered - ); - - registry.record_initialized( - manifest.clone(), - vec![capability("tool.repo.inspect")], - vec!["skill warning".to_string()], - ); - let initialized = registry - .get("repo-inspector") - .expect("initialized entry should exist"); - assert_eq!(initialized.state, PluginState::Initialized); - assert_eq!(initialized.health, PluginHealth::Healthy); - assert_eq!(initialized.capabilities.len(), 1); - assert!(initialized.failure.is_none()); - assert_eq!(initialized.warnings, vec!["skill warning".to_string()]); - - registry.record_failed( - manifest, - "capability conflict", - vec![capability("tool.repo.inspect")], - vec!["materialize failed".to_string()], - ); - let failed = registry - .get("repo-inspector") - .expect("failed entry should exist"); - assert_eq!(failed.state, PluginState::Failed); - assert_eq!(failed.health, PluginHealth::Unavailable); - assert_eq!(failed.failure.as_deref(), Some("capability conflict")); - assert_eq!(failed.capabilities.len(), 1); - assert_eq!(failed.warnings, vec!["materialize failed".to_string()]); - } - - #[test] - fn snapshot_is_sorted_by_plugin_name() { - let registry = PluginRegistry::default(); - registry.record_discovered(manifest("zeta")); - registry.record_discovered(manifest("alpha")); - - let snapshot = registry.snapshot(); - assert_eq!( - snapshot - .into_iter() - .map(|entry| entry.manifest.name) - .collect::>(), - vec!["alpha".to_string(), "zeta".to_string()] - ); - } - - #[test] - fn replace_snapshot_overwrites_existing_entries() { - let registry = PluginRegistry::default(); - registry.record_discovered(manifest("alpha")); - registry.replace_snapshot(vec![super::PluginEntry { - manifest: manifest("beta"), - state: PluginState::Initialized, - health: PluginHealth::Healthy, - failure_count: 0, - capabilities: vec![capability("tool.beta")], - failure: None, - warnings: Vec::new(), - last_checked_at: None, - }]); - - assert!(registry.get("alpha").is_none()); - assert_eq!( - registry.get("beta").expect("beta should exist").state, - PluginState::Initialized - ); - } - - #[test] - fn runtime_health_transitions_degrade_then_recover() { - let registry = PluginRegistry::default(); - registry.record_initialized( - manifest("alpha"), - vec![capability("tool.alpha")], - Vec::new(), - ); - - registry.record_runtime_failure("alpha", "transport closed", Utc::now().to_rfc3339()); - let degraded = registry.get("alpha").expect("alpha should exist"); - assert_eq!(degraded.health, PluginHealth::Degraded); - assert_eq!(degraded.failure_count, 1); - - registry.record_runtime_success("alpha", Utc::now().to_rfc3339()); - let healthy = registry.get("alpha").expect("alpha should still exist"); - assert_eq!(healthy.health, PluginHealth::Healthy); - assert_eq!(healthy.failure_count, 0); - assert!(healthy.failure.is_none()); - } -} diff --git a/crates/core/src/ports.rs b/crates/core/src/ports.rs index fd5999f1..13f1b92d 100644 --- a/crates/core/src/ports.rs +++ b/crates/core/src/ports.rs @@ -1,26 +1,15 @@ -//! 运行时稳定端口契约。 +//! 剩余共享配置端口。 //! -//! 这些 trait 定义在 `core`，由 adapter 层实现，由 kernel/session-runtime/application -//! 通过依赖倒置消费，避免上层再反向依赖具体实现 crate。 +//! 运行时、会话和插件 owner 专属端口已经迁入各自 crate。这里仅保留仍被 +//! 多个 owner 共享的配置与本地技能目录端口，避免 `core::ports` 继续作为 +//! provider/session/plugin 的 mega 入口。 -use std::{ - collections::HashMap, - path::{Path, PathBuf}, - sync::Arc, -}; +use std::path::PathBuf; -use async_trait::async_trait; -use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::{ - AgentState, CancelToken, CapabilitySpec, ChildSessionNode, Config, ConfigOverlay, - DeleteProjectResult, InputQueueProjection, LlmMessage, McpApprovalData, Phase, - ReasoningContent, Result, SessionId, SessionMeta, SessionTurnAcquireResult, SkillSpec, - StorageEvent, StoredEvent, SystemPromptBlock, SystemPromptLayer, TaskSnapshot, ToolCallRequest, - ToolDefinition, TurnId, TurnTerminalKind, -}; +use crate::{Config, ConfigOverlay, McpApprovalData, Result, SkillSpec}; /// MCP 配置文件作用域。 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] @@ -31,609 +20,6 @@ pub enum McpConfigFileScope { Local, } -/// EventStore 端口。 -#[async_trait] -pub trait EventStore: Send + Sync { - async fn ensure_session(&self, session_id: &SessionId, working_dir: &Path) -> Result<()>; - async fn append(&self, session_id: &SessionId, event: &StorageEvent) -> Result; - async fn replay(&self, session_id: &SessionId) -> Result>; - async fn recover_session(&self, session_id: &SessionId) -> Result { - Ok(RecoveredSessionState { - checkpoint: None, - tail_events: self.replay(session_id).await?, - }) - } - async fn checkpoint_session( - &self, - _session_id: &SessionId, - _checkpoint: &SessionRecoveryCheckpoint, - ) -> Result<()> { - Ok(()) - } - async fn try_acquire_turn( - &self, - session_id: &SessionId, - turn_id: &str, - ) -> Result; - async fn list_sessions(&self) -> Result>; - async fn list_session_metas(&self) -> Result>; - async fn delete_session(&self, session_id: &SessionId) -> Result<()>; - async fn delete_sessions_by_working_dir( - &self, - working_dir: &str, - ) -> Result; -} - -/// durable 恢复基线。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct TurnProjectionSnapshot { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub terminal_kind: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub last_error: Option, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct ProjectionRegistrySnapshot { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub last_mode_changed_at: Option>, - #[serde(default)] - pub child_nodes: HashMap, - #[serde(default)] - pub active_tasks: HashMap, - #[serde(default)] - pub input_queue_projection_index: HashMap, - #[serde(default)] - pub turn_projections: HashMap, -} - -impl ProjectionRegistrySnapshot { - pub fn is_empty(&self) -> bool { - self.last_mode_changed_at.is_none() - && self.child_nodes.is_empty() - && self.active_tasks.is_empty() - && self.input_queue_projection_index.is_empty() - && self.turn_projections.is_empty() - } -} - -#[derive(Debug, Clone, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -struct LegacySessionRecoveryProjection { - #[serde(default, skip_serializing_if = "Option::is_none")] - phase: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - last_mode_changed_at: Option>, - #[serde(default)] - child_nodes: HashMap, - #[serde(default)] - active_tasks: HashMap, - #[serde(default)] - input_queue_projection_index: HashMap, -} - -impl LegacySessionRecoveryProjection { - fn is_empty(&self) -> bool { - self.phase.is_none() - && self.last_mode_changed_at.is_none() - && self.child_nodes.is_empty() - && self.active_tasks.is_empty() - && self.input_queue_projection_index.is_empty() - } -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct SessionRecoveryCheckpoint { - pub agent_state: AgentState, - #[serde(default, skip_serializing_if = "ProjectionRegistrySnapshot::is_empty")] - pub projection_registry: ProjectionRegistrySnapshot, - pub checkpoint_storage_seq: u64, - #[serde( - flatten, - default, - skip_serializing_if = "LegacySessionRecoveryProjection::is_empty" - )] - legacy: LegacySessionRecoveryProjection, -} - -impl SessionRecoveryCheckpoint { - pub fn new( - agent_state: AgentState, - projection_registry: ProjectionRegistrySnapshot, - checkpoint_storage_seq: u64, - ) -> Self { - Self { - agent_state, - projection_registry, - checkpoint_storage_seq, - legacy: LegacySessionRecoveryProjection::default(), - } - } - - pub fn projection_registry_snapshot(&self) -> ProjectionRegistrySnapshot { - if !self.projection_registry.is_empty() { - return self.projection_registry.clone(); - } - - ProjectionRegistrySnapshot { - last_mode_changed_at: self.legacy.last_mode_changed_at, - child_nodes: self.legacy.child_nodes.clone(), - active_tasks: self.legacy.active_tasks.clone(), - input_queue_projection_index: self.legacy.input_queue_projection_index.clone(), - turn_projections: HashMap::new(), - } - } -} - -/// 会话恢复结果：最近 checkpoint + checkpoint 之后的 tail events。 -#[derive(Debug, Clone, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct RecoveredSessionState { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub checkpoint: Option, - #[serde(default)] - pub tail_events: Vec, -} - -/// 模型能力限制。 -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] -pub struct ModelLimits { - pub context_window: usize, - pub max_output_tokens: usize, -} - -/// 模型 token 使用统计。 -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] -pub struct LlmUsage { - pub input_tokens: usize, - pub output_tokens: usize, - pub cache_creation_input_tokens: usize, - pub cache_read_input_tokens: usize, -} - -impl LlmUsage { - pub fn total_tokens(self) -> usize { - self.input_tokens.saturating_add(self.output_tokens) - } -} - -/// LLM 输出结束原因。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum LlmFinishReason { - #[default] - Stop, - MaxTokens, - ToolCalls, - Other(String), -} - -impl LlmFinishReason { - pub fn is_max_tokens(&self) -> bool { - matches!(self, Self::MaxTokens) - } - - /// 从 OpenAI 家族接口返回的 finish reason 字符串解析统一枚举。 - pub fn from_api_value(value: &str) -> Self { - match value { - "stop" => Self::Stop, - "max_tokens" | "length" => Self::MaxTokens, - "tool_calls" => Self::ToolCalls, - other => Self::Other(other.to_string()), - } - } -} - -/// 流式增量事件。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub enum LlmEvent { - TextDelta(String), - ThinkingDelta(String), - ThinkingSignature(String), - ToolCallDelta { - index: usize, - id: Option, - name: Option, - arguments_delta: String, - }, -} - -pub type LlmEventSink = Arc; - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptLayerFingerprints { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub stable: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub semi_stable: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub inherited: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub dynamic: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptCacheHints { - #[serde(default)] - pub layer_fingerprints: PromptLayerFingerprints, - #[serde(default)] - pub global_cache_strategy: PromptCacheGlobalStrategy, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub unchanged_layers: Vec, - #[serde(default, skip_serializing_if = "is_false")] - pub compacted: bool, - #[serde(default, skip_serializing_if = "is_false")] - pub tool_result_rebudgeted: bool, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum PromptCacheGlobalStrategy { - #[default] - SystemPrompt, - ToolBased, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "snake_case")] -pub enum PromptCacheBreakReason { - SystemPromptChanged, - ToolSchemasChanged, - ModelChanged, - GlobalCacheStrategyChanged, - CompactedPrompt, - ToolResultRebudgeted, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptCacheDiagnostics { - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub reasons: Vec, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub previous_cache_read_input_tokens: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub current_cache_read_input_tokens: Option, - #[serde(default, skip_serializing_if = "is_false")] - pub expected_drop: bool, - #[serde(default, skip_serializing_if = "is_false")] - pub cache_break_detected: bool, -} - -/// 模型调用请求。 -#[derive(Debug, Clone)] -pub struct LlmRequest { - pub messages: Vec, - pub tools: Arc<[ToolDefinition]>, - pub cancel: CancelToken, - pub system_prompt: Option, - pub system_prompt_blocks: Vec, - pub prompt_cache_hints: Option, - pub max_output_tokens_override: Option, - pub skip_cache_write: bool, -} - -impl LlmRequest { - pub fn new( - messages: Vec, - tools: impl Into>, - cancel: CancelToken, - ) -> Self { - Self { - messages, - tools: tools.into(), - cancel, - system_prompt: None, - system_prompt_blocks: Vec::new(), - prompt_cache_hints: None, - max_output_tokens_override: None, - skip_cache_write: false, - } - } - - pub fn with_system(mut self, prompt: impl Into) -> Self { - self.system_prompt = Some(prompt.into()); - self - } - - pub fn with_max_output_tokens_override(mut self, max_output_tokens: usize) -> Self { - self.max_output_tokens_override = Some(max_output_tokens.max(1)); - self - } - - pub fn with_skip_cache_write(mut self, skip_cache_write: bool) -> Self { - self.skip_cache_write = skip_cache_write; - self - } - - pub fn from_model_request(request: crate::ModelRequest, cancel: CancelToken) -> Self { - Self { - messages: request.messages, - tools: request.tools.into(), - cancel, - system_prompt: request.system_prompt, - system_prompt_blocks: request.system_prompt_blocks, - prompt_cache_hints: None, - max_output_tokens_override: None, - skip_cache_write: false, - } - } -} - -/// 模型调用输出。 -#[derive(Debug, Clone, Default)] -pub struct LlmOutput { - pub content: String, - pub tool_calls: Vec, - pub reasoning: Option, - pub usage: Option, - pub finish_reason: LlmFinishReason, - pub prompt_cache_diagnostics: Option, -} - -/// LLM provider 端口。 -#[async_trait] -pub trait LlmProvider: Send + Sync { - async fn generate(&self, request: LlmRequest, sink: Option) -> Result; - fn model_limits(&self) -> ModelLimits; - fn supports_cache_metrics(&self) -> bool { - false - } -} - -/// Prompt 组装请求。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptEntrySummary { - pub id: String, - pub description: String, -} - -impl PromptEntrySummary { - pub fn new(id: impl Into, description: impl Into) -> Self { - Self { - id: id.into(), - description: description.into(), - } - } -} - -pub type PromptSkillSummary = PromptEntrySummary; - -/// Prompt 侧的轻量 agent profile 摘要。 -pub type PromptAgentProfileSummary = PromptEntrySummary; - -/// Prompt 声明来源。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum PromptDeclarationSource { - Builtin, - #[default] - Plugin, - Mcp, -} - -/// Prompt 声明语义类型。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum PromptDeclarationKind { - ToolGuide, - #[default] - ExtensionInstruction, -} - -/// Prompt 声明渲染目标。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum PromptDeclarationRenderTarget { - #[default] - System, - PrependUser, - PrependAssistant, - AppendUser, - AppendAssistant, -} - -/// 稳定的 Prompt 声明 DTO。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptDeclaration { - pub block_id: String, - pub title: String, - pub content: String, - #[serde(default)] - pub render_target: PromptDeclarationRenderTarget, - #[serde(default, skip_serializing_if = "is_unspecified_prompt_layer")] - pub layer: SystemPromptLayer, - #[serde(default)] - pub kind: PromptDeclarationKind, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub priority_hint: Option, - #[serde(default)] - pub always_include: bool, - #[serde(default)] - pub source: PromptDeclarationSource, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub capability_name: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub origin: Option, -} - -/// Prompt 事实查询请求。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptGovernanceContext { - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub allowed_capability_names: Vec, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub mode_id: Option, - #[serde(default, skip_serializing_if = "String::is_empty")] - pub approval_mode: String, - #[serde(default, skip_serializing_if = "String::is_empty")] - pub policy_revision: String, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub max_subrun_depth: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub max_spawn_per_turn: Option, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptFactsRequest { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub session_id: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub turn_id: Option, - pub working_dir: PathBuf, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub allowed_capability_names: Vec, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub governance: Option, -} - -/// Prompt 组装前的已解析事实。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PromptFacts { - pub profile: String, - #[serde(default)] - pub profile_context: Value, - #[serde(default)] - pub metadata: Value, - #[serde(default)] - pub skills: Vec, - #[serde(default)] - pub agent_profiles: Vec, - #[serde(default)] - pub prompt_declarations: Vec, -} - -impl Default for PromptFacts { - fn default() -> Self { - Self { - profile: "coding".to_string(), - profile_context: Value::Null, - metadata: Value::Null, - skills: Vec::new(), - agent_profiles: Vec::new(), - prompt_declarations: Vec::new(), - } - } -} - -fn is_unspecified_prompt_layer(layer: &SystemPromptLayer) -> bool { - matches!(layer, SystemPromptLayer::Unspecified) -} - -/// Prompt facts provider 端口。 -#[async_trait] -pub trait PromptFactsProvider: Send + Sync { - async fn resolve_prompt_facts(&self, request: &PromptFactsRequest) -> Result; -} - -/// Prompt 组装请求。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PromptBuildRequest { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub session_id: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub turn_id: Option, - pub working_dir: PathBuf, - pub profile: String, - #[serde(default)] - pub step_index: usize, - #[serde(default)] - pub turn_index: usize, - #[serde(default)] - pub profile_context: Value, - #[serde(default)] - pub capabilities: Vec, - #[serde(default)] - pub skills: Vec, - #[serde(default)] - pub agent_profiles: Vec, - #[serde(default)] - pub prompt_declarations: Vec, - #[serde(default)] - pub metadata: Value, -} - -/// Prompt 组装结果。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptBuildCacheMetrics { - pub reuse_hits: u32, - pub reuse_misses: u32, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub unchanged_layers: Vec, -} - -/// Prompt 组装结果。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PromptBuildOutput { - pub system_prompt: String, - #[serde(default)] - pub system_prompt_blocks: Vec, - #[serde(default)] - pub prompt_cache_hints: PromptCacheHints, - #[serde(default)] - pub cache_metrics: PromptBuildCacheMetrics, - #[serde(default)] - pub metadata: Value, -} - -/// Prompt provider 端口。 -#[async_trait] -pub trait PromptProvider: Send + Sync { - async fn build_prompt(&self, request: PromptBuildRequest) -> Result; -} - -fn is_false(value: &bool) -> bool { - !*value -} - -/// 资源读取请求上下文。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct ResourceRequestContext { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub session_id: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub turn_id: Option, - #[serde(default)] - pub profile: Option, - #[serde(default)] - pub metadata: Value, -} - -/// 资源读取结果。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct ResourceReadResult { - pub uri: String, - pub content: Value, - #[serde(default)] - pub metadata: Value, -} - -/// Resource provider 端口。 -#[async_trait] -pub trait ResourceProvider: Send + Sync { - async fn read_resource( - &self, - uri: &str, - context: &ResourceRequestContext, - ) -> Result; -} - /// Skill 查询端口。 pub trait SkillCatalog: Send + Sync { fn resolve_for_working_dir(&self, working_dir: &str) -> Vec; diff --git a/crates/core/src/projection/mod.rs b/crates/core/src/projection/mod.rs deleted file mode 100644 index 077cbc30..00000000 --- a/crates/core/src/projection/mod.rs +++ /dev/null @@ -1,9 +0,0 @@ -//! # Agent 状态投影 -//! -//! 从事件流（`StorageEvent` 序列）中推导出 Agent 的当前状态。 -//! 该模块提供纯函数式的投影器，将 append-only 的事件日志转换为 -//! 当前可操作的 Agent 状态快照。 - -mod agent_state; - -pub use agent_state::{AgentState, AgentStateProjector, project}; diff --git a/crates/core/src/prompt.rs b/crates/core/src/prompt.rs new file mode 100644 index 00000000..857c62fd --- /dev/null +++ b/crates/core/src/prompt.rs @@ -0,0 +1,125 @@ +use serde::{Deserialize, Serialize}; + +use crate::SystemPromptLayer; + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptLayerFingerprints { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub stable: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub semi_stable: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub inherited: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub dynamic: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptCacheHints { + #[serde(default)] + pub layer_fingerprints: PromptLayerFingerprints, + #[serde(default)] + pub global_cache_strategy: PromptCacheGlobalStrategy, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub unchanged_layers: Vec, + #[serde(default, skip_serializing_if = "is_false")] + pub compacted: bool, + #[serde(default, skip_serializing_if = "is_false")] + pub tool_result_rebudgeted: bool, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptCacheGlobalStrategy { + #[default] + SystemPrompt, + ToolBased, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum PromptCacheBreakReason { + SystemPromptChanged, + ToolSchemasChanged, + ModelChanged, + GlobalCacheStrategyChanged, + CompactedPrompt, + ToolResultRebudgeted, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptCacheDiagnostics { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub reasons: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub previous_cache_read_input_tokens: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub current_cache_read_input_tokens: Option, + #[serde(default, skip_serializing_if = "is_false")] + pub expected_drop: bool, + #[serde(default, skip_serializing_if = "is_false")] + pub cache_break_detected: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationSource { + Builtin, + #[default] + Plugin, + Mcp, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationKind { + ToolGuide, + #[default] + ExtensionInstruction, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationRenderTarget { + #[default] + System, + PrependUser, + PrependAssistant, + AppendUser, + AppendAssistant, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptDeclaration { + pub block_id: String, + pub title: String, + pub content: String, + #[serde(default)] + pub render_target: PromptDeclarationRenderTarget, + #[serde(default, skip_serializing_if = "is_unspecified_prompt_layer")] + pub layer: SystemPromptLayer, + #[serde(default)] + pub kind: PromptDeclarationKind, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub priority_hint: Option, + #[serde(default)] + pub always_include: bool, + #[serde(default)] + pub source: PromptDeclarationSource, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub capability_name: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub origin: Option, +} + +fn is_unspecified_prompt_layer(layer: &SystemPromptLayer) -> bool { + matches!(layer, SystemPromptLayer::Unspecified) +} + +fn is_false(value: &bool) -> bool { + !*value +} diff --git a/crates/core/src/runtime/traits.rs b/crates/core/src/runtime/traits.rs index 80b24e72..1f25272f 100644 --- a/crates/core/src/runtime/traits.rs +++ b/crates/core/src/runtime/traits.rs @@ -10,8 +10,8 @@ use async_trait::async_trait; use crate::{ - AgentId, AgentProfile, AstrError, SessionEventRecord, SessionId, SessionMeta, SubRunHandle, - SubRunResult, SubagentContextOverrides, TurnId, + AgentId, AgentProfile, AstrError, SessionEventRecord, SessionId, SessionMeta, SubRunResult, + SubagentContextOverrides, TurnId, agent::lineage::SubRunHandle, }; /// 运行时主句柄。 diff --git a/crates/application/Cargo.toml b/crates/host-session/Cargo.toml similarity index 56% rename from crates/application/Cargo.toml rename to crates/host-session/Cargo.toml index d473641b..6b4a320e 100644 --- a/crates/application/Cargo.toml +++ b/crates/host-session/Cargo.toml @@ -1,25 +1,19 @@ [package] -name = "astrcode-application" +name = "astrcode-host-session" version = "0.1.0" edition.workspace = true license-file.workspace = true authors.workspace = true [dependencies] +astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } -astrcode-kernel = { path = "../kernel" } -astrcode-session-runtime = { path = "../session-runtime" } +astrcode-plugin-host = { path = "../plugin-host" } astrcode-support = { path = "../support" } async-trait.workspace = true chrono.workspace = true dashmap.workspace = true serde.workspace = true serde_json.workspace = true -thiserror.workspace = true tokio.workspace = true log.workspace = true -uuid.workspace = true - -[dev-dependencies] -astrcode-core = { path = "../core", features = ["test-support"] } -tempfile.workspace = true diff --git a/crates/session-runtime/src/turn/branch.rs b/crates/host-session/src/branch.rs similarity index 65% rename from crates/session-runtime/src/turn/branch.rs rename to crates/host-session/src/branch.rs index ae1a1b73..1283c6cd 100644 --- a/crates/session-runtime/src/turn/branch.rs +++ b/crates/host-session/src/branch.rs @@ -1,25 +1,21 @@ -use std::{path::PathBuf, sync::Arc}; +use std::path::Path; use astrcode_core::{ - AstrError, SessionId, SessionTurnAcquireResult, SessionTurnLease, StorageEventPayload, - StoredEvent, event::generate_session_id, + AstrError, SessionId, SessionTurnAcquireResult, SessionTurnLease, StorageEvent, + StorageEventPayload, StoredEvent, event::generate_session_id, }; use chrono::Utc; -use crate::{ - SessionRuntime, actor::SessionActor, catalog::SessionCatalogEvent, - state::normalize_working_dir, turn::events::session_start_event, -}; +use crate::{SessionCatalog, SessionCatalogEvent}; -pub(crate) struct SubmitTarget { - pub(crate) session_id: SessionId, - pub(crate) branched_from_session_id: Option, - pub(crate) actor: Arc, - pub(crate) turn_lease: Box, +pub struct SubmitTarget { + pub session_id: SessionId, + pub branched_from_session_id: Option, + pub turn_lease: Box, } -impl SessionRuntime { - pub(crate) async fn resolve_submit_target( +impl SessionCatalog { + pub async fn resolve_submit_target( &self, session_id: &SessionId, turn_id: &str, @@ -39,11 +35,10 @@ impl SessionRuntime { .await? { SessionTurnAcquireResult::Acquired(turn_lease) => { - let actor = self.ensure_loaded_session(&target_session_id).await?; + self.ensure_loaded_session(&target_session_id).await?; return Ok(SubmitTarget { session_id: target_session_id, branched_from_session_id, - actor, turn_lease, }); }, @@ -60,7 +55,7 @@ impl SessionRuntime { } } - pub(crate) async fn try_resolve_submit_target_without_branch( + pub async fn try_resolve_submit_target_without_branch( &self, session_id: &SessionId, turn_id: &str, @@ -73,11 +68,10 @@ impl SessionRuntime { .await? { SessionTurnAcquireResult::Acquired(turn_lease) => { - let actor = self.ensure_loaded_session(session_id).await?; + self.ensure_loaded_session(session_id).await?; Ok(Some(SubmitTarget { session_id: session_id.clone(), branched_from_session_id: None, - actor, turn_lease, })) }, @@ -92,23 +86,22 @@ impl SessionRuntime { ) -> astrcode_core::Result { let source_events = self.event_store.replay(source_session_id).await?; let stable_events = stable_events_before_active_turn(&source_events, active_turn_id); - let source_actor = self.ensure_loaded_session(source_session_id).await?; - let working_dir = normalize_working_dir(PathBuf::from(source_actor.working_dir()))?; + let source = self.ensure_loaded_session(source_session_id).await?; let parent_storage_seq = stable_events.last().map(|event| event.storage_seq); self.fork_events_up_to( source_session_id, - &working_dir, + &source.working_dir, &stable_events, parent_storage_seq, ) .await } - pub(super) async fn fork_events_up_to( + pub(crate) async fn fork_events_up_to( &self, source_session_id: &SessionId, - working_dir: &std::path::Path, + working_dir: &Path, source_events: &[StoredEvent], parent_storage_seq: Option, ) -> astrcode_core::Result { @@ -122,14 +115,11 @@ impl SessionRuntime { working_dir.display().to_string(), Some(source_session_id.to_string()), parent_storage_seq, - Utc::now(), ); self.event_store .append(&branched_session_id, &session_start) .await?; - // 为什么只复制稳定历史：活跃 turn 的半截输出不应污染新分支， - // 否则 replay/context window 会同时看到未完成与新分支的事件。 for stored in source_events { if matches!( stored.event.payload, @@ -148,10 +138,30 @@ impl SessionRuntime { session_id: branched_session_id.to_string(), source_session_id: source_session_id.to_string(), }); + let _ = self.ensure_loaded_session(&branched_session_id).await?; Ok(branched_session_id) } } +pub(crate) fn session_start_event( + session_id: String, + working_dir: String, + parent_session_id: Option, + parent_storage_seq: Option, +) -> StorageEvent { + StorageEvent { + turn_id: None, + agent: astrcode_core::AgentEventContext::default(), + payload: StorageEventPayload::SessionStart { + session_id, + timestamp: Utc::now(), + working_dir, + parent_session_id, + parent_storage_seq, + }, + } +} + fn ensure_branch_depth_within_limit( branch_depth: usize, max_branch_depth: usize, @@ -164,7 +174,7 @@ fn ensure_branch_depth_within_limit( Ok(()) } -fn stable_events_before_active_turn( +pub(crate) fn stable_events_before_active_turn( events: &[StoredEvent], active_turn_id: &str, ) -> Vec { @@ -177,16 +187,10 @@ fn stable_events_before_active_turn( #[cfg(test)] mod tests { - use std::sync::Arc; - - use astrcode_core::{AstrError, SessionId, StorageEventPayload, StoredEvent}; + use astrcode_core::{AgentEventContext, StorageEventPayload, StoredEvent}; use chrono::Utc; - use super::stable_events_before_active_turn; - use crate::turn::{ - events::session_start_event, - test_support::{BranchingTestEventStore, root_turn_event, test_runtime}, - }; + use super::{session_start_event, stable_events_before_active_turn}; fn stored( storage_seq: u64, @@ -195,15 +199,20 @@ mod tests { ) -> StoredEvent { StoredEvent { storage_seq, - event: root_turn_event(turn_id, payload), + event: astrcode_core::StorageEvent { + turn_id: turn_id.map(str::to_string), + agent: AgentEventContext::default(), + payload, + }, } } + #[test] fn stable_events_excludes_active_turn_tail() { let events = vec![ StoredEvent { storage_seq: 1, - event: session_start_event("session-1", "/tmp", None, None, Utc::now()), + event: session_start_event("session-1".into(), "/tmp".into(), None, None), }, stored( 2, @@ -231,43 +240,4 @@ mod tests { assert_eq!(stable[0].storage_seq, 1); assert_eq!(stable[1].storage_seq, 2); } - - #[tokio::test] - async fn resolve_submit_target_rejects_when_branch_depth_limit_is_exceeded() { - let event_store = Arc::new(BranchingTestEventStore::default()); - let runtime = test_runtime(event_store.clone()); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - event_store.push_busy("turn-busy-1"); - event_store.push_busy("turn-busy-2"); - - let error = match runtime - .resolve_submit_target(&SessionId::from(session.session_id.clone()), "turn-new", 1) - .await - { - Ok(_) => panic!("branch depth overflow should return validation error"), - Err(error) => error, - }; - - match error { - AstrError::Validation(message) => { - assert!(message.contains("too many concurrent branch attempts")); - assert!(message.contains("limit: 1")); - }, - other => panic!("unexpected error: {other:?}"), - } - - assert_eq!( - runtime - .list_session_metas() - .await - .expect("durable session metas should be readable") - .len(), - 2, - "first busy submit should still create one durable branched session before the depth \ - limit stops recursion" - ); - } } diff --git a/crates/host-session/src/catalog.rs b/crates/host-session/src/catalog.rs new file mode 100644 index 00000000..48470440 --- /dev/null +++ b/crates/host-session/src/catalog.rs @@ -0,0 +1,563 @@ +use std::{ + path::{Path, PathBuf}, + sync::Arc, +}; + +use astrcode_core::{ + AstrError, EventTranslator, ModeId, Phase, Result, SessionId, SessionMeta, + SessionTurnAcquireResult, StorageEvent, StorageEventPayload, StoredEvent, + event::generate_session_id, +}; +use chrono::Utc; +use dashmap::DashMap; +use tokio::sync::broadcast; + +use crate::{ + AgentStateProjector, EventStore, SessionCatalogEvent, SessionState, SessionWriter, + state::{SESSION_BROADCAST_CAPACITY, append_and_broadcast}, + turn_mutation::TurnMutationState, +}; + +#[derive(Debug)] +pub struct LoadedSession { + pub session_id: SessionId, + pub working_dir: PathBuf, + pub state: Arc, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SessionModeState { + pub current_mode_id: ModeId, + pub last_mode_changed_at: Option>, +} + +/// Host-session owned catalog and loaded-session registry. +/// +/// This is the durable-session owner surface that replaces the old +/// `session-runtime` DashMap/catalog responsibilities. It deliberately owns +/// only event-log recovery, loaded `SessionState`, and catalog broadcasts. +pub struct SessionCatalog { + pub(crate) event_store: Arc, + sessions: DashMap>, + pub(crate) turn_mutations: DashMap>, + pub(crate) catalog_events: broadcast::Sender, +} + +impl SessionCatalog { + pub fn new(event_store: Arc) -> Self { + let (catalog_events, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); + Self { + event_store, + sessions: DashMap::new(), + turn_mutations: DashMap::new(), + catalog_events, + } + } + + pub fn subscribe_catalog_events(&self) -> broadcast::Receiver { + self.catalog_events.subscribe() + } + + pub fn list_loaded_sessions(&self) -> Vec { + let mut sessions = self + .sessions + .iter() + .map(|entry| entry.key().clone()) + .collect::>(); + sessions.sort(); + sessions + } + + pub async fn list_session_metas(&self) -> Result> { + let mut metas = self.event_store.list_session_metas().await?; + for meta in &mut metas { + let session_id: SessionId = meta.session_id.clone().into(); + if let Some(entry) = self.sessions.get(&session_id) { + meta.phase = entry.state.current_phase()?; + } + } + metas.sort_by_key(|meta| meta.updated_at); + Ok(metas) + } + + pub async fn create_session(&self, working_dir: impl Into) -> Result { + self.create_session_with_parent(working_dir, None, None) + .await + } + + pub async fn create_child_session( + &self, + working_dir: impl Into, + parent_session_id: impl Into, + parent_storage_seq: Option, + ) -> Result { + self.create_session_with_parent( + working_dir, + Some(parent_session_id.into()), + parent_storage_seq, + ) + .await + } + + async fn create_session_with_parent( + &self, + working_dir: impl Into, + parent_session_id: Option, + parent_storage_seq: Option, + ) -> Result { + let working_dir = normalize_working_dir(PathBuf::from(working_dir.into()))?; + let session_id_raw = generate_session_id(); + let session_id: SessionId = session_id_raw.clone().into(); + if self.sessions.contains_key(&session_id) { + return Err(AstrError::Validation(format!( + "session '{}' already exists", + session_id + ))); + } + + self.event_store + .ensure_session(&session_id, &working_dir) + .await?; + + let writer = Arc::new(SessionWriter::from_event_store( + Arc::clone(&self.event_store), + session_id.clone(), + )); + let state = Arc::new(SessionState::new( + Phase::Idle, + writer, + AgentStateProjector::default(), + Vec::new(), + Vec::new(), + )); + let created_at = Utc::now(); + let start = StorageEvent { + turn_id: None, + agent: astrcode_core::AgentEventContext::default(), + payload: StorageEventPayload::SessionStart { + session_id: session_id.to_string(), + timestamp: created_at, + working_dir: working_dir.display().to_string(), + parent_session_id: parent_session_id.clone(), + parent_storage_seq, + }, + }; + let mut translator = EventTranslator::new(Phase::Idle); + append_and_broadcast(&state, &start, &mut translator).await?; + + let loaded = Arc::new(LoadedSession { + session_id: session_id.clone(), + working_dir: working_dir.clone(), + state: Arc::clone(&state), + }); + self.sessions.insert(session_id.clone(), loaded); + + let meta = SessionMeta { + session_id: session_id.to_string(), + working_dir: working_dir.display().to_string(), + display_name: display_name_from_working_dir(&working_dir), + title: "New Session".to_string(), + created_at, + updated_at: created_at, + parent_session_id, + parent_storage_seq, + phase: Phase::Idle, + }; + let _ = self + .catalog_events + .send(SessionCatalogEvent::SessionCreated { + session_id: session_id.to_string(), + }); + Ok(meta) + } + + pub async fn ensure_loaded_session( + &self, + session_id: &SessionId, + ) -> Result> { + if let Some(entry) = self.sessions.get(session_id) { + return Ok(Arc::clone(entry.value())); + } + + let meta = self.find_meta(session_id).await?; + let recovered = self.event_store.recover_session(session_id).await?; + let writer = Arc::new(SessionWriter::from_event_store( + Arc::clone(&self.event_store), + session_id.clone(), + )); + let state = Arc::new(match recovered.checkpoint { + Some(checkpoint) => { + SessionState::from_recovery(writer, &checkpoint, recovered.tail_events)? + }, + None => { + let events = recovered + .tail_events + .iter() + .map(|stored| stored.event.clone()) + .collect::>(); + SessionState::new( + normalize_recovered_phase_from_events(&recovered.tail_events), + writer, + AgentStateProjector::from_events(&events), + astrcode_core::replay_records(&recovered.tail_events, None), + recovered.tail_events, + ) + }, + }); + + let loaded = Arc::new(LoadedSession { + session_id: session_id.clone(), + working_dir: PathBuf::from(meta.working_dir), + state, + }); + match self.sessions.entry(session_id.clone()) { + dashmap::mapref::entry::Entry::Occupied(entry) => Ok(Arc::clone(entry.get())), + dashmap::mapref::entry::Entry::Vacant(entry) => { + entry.insert(Arc::clone(&loaded)); + Ok(loaded) + }, + } + } + + pub async fn ensure_session_exists(&self, session_id: &SessionId) -> Result<()> { + if self.sessions.contains_key(session_id) { + return Ok(()); + } + self.find_meta(session_id).await.map(|_| ()) + } + + pub async fn try_acquire_turn( + &self, + session_id: &SessionId, + turn_id: &str, + ) -> Result { + self.ensure_session_exists(session_id).await?; + self.event_store.try_acquire_turn(session_id, turn_id).await + } + + pub async fn replay_stored_events(&self, session_id: &SessionId) -> Result> { + self.ensure_session_exists(session_id).await?; + self.event_store.replay(session_id).await + } + + pub async fn session_mode_state(&self, session_id: &SessionId) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + Ok(SessionModeState { + current_mode_id: loaded.state.current_mode_id()?, + last_mode_changed_at: loaded.state.last_mode_changed_at()?, + }) + } + + pub async fn switch_mode( + &self, + session_id: &SessionId, + target_mode_id: ModeId, + ) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let current_mode_id = loaded.state.current_mode_id()?; + if current_mode_id == target_mode_id { + return Ok(SessionModeState { + current_mode_id, + last_mode_changed_at: loaded.state.last_mode_changed_at()?, + }); + } + + let mut translator = EventTranslator::new(loaded.state.current_phase()?); + append_and_broadcast( + &loaded.state, + &StorageEvent { + turn_id: None, + agent: astrcode_core::AgentEventContext::default(), + payload: StorageEventPayload::ModeChanged { + from: current_mode_id, + to: target_mode_id, + timestamp: Utc::now(), + }, + }, + &mut translator, + ) + .await?; + + Ok(SessionModeState { + current_mode_id: loaded.state.current_mode_id()?, + last_mode_changed_at: loaded.state.last_mode_changed_at()?, + }) + } + + pub async fn delete_session(&self, session_id: &SessionId) -> Result<()> { + self.ensure_session_exists(session_id).await?; + self.event_store.delete_session(session_id).await?; + self.sessions.remove(session_id); + let _ = self + .catalog_events + .send(SessionCatalogEvent::SessionDeleted { + session_id: session_id.to_string(), + }); + Ok(()) + } + + pub async fn delete_project( + &self, + working_dir: &str, + ) -> Result { + let deleted = self + .event_store + .delete_sessions_by_working_dir(working_dir) + .await?; + + let target = normalize_path(working_dir); + let to_remove = self + .sessions + .iter() + .filter_map(|entry| { + (normalize_path(&entry.working_dir.display().to_string()) == target) + .then_some(entry.key().clone()) + }) + .collect::>(); + for session_id in to_remove { + self.sessions.remove(&session_id); + } + + let _ = self + .catalog_events + .send(SessionCatalogEvent::ProjectDeleted { + working_dir: working_dir.to_string(), + }); + Ok(deleted) + } + + async fn find_meta(&self, session_id: &SessionId) -> Result { + self.event_store + .list_session_metas() + .await? + .into_iter() + .find(|meta| normalize_session_id(&meta.session_id) == session_id.as_str()) + .ok_or_else(|| AstrError::SessionNotFound(session_id.to_string())) + } +} + +pub fn normalize_session_id(session_id: &str) -> String { + session_id.trim().to_string() +} + +pub fn normalize_working_dir(path: PathBuf) -> Result { + if path.as_os_str().is_empty() { + return std::env::current_dir().map_err(|error| { + AstrError::Internal(format!("resolve current working directory failed: {error}")) + }); + } + Ok(path) +} + +pub fn display_name_from_working_dir(path: &Path) -> String { + path.file_name() + .and_then(|name| name.to_str()) + .filter(|name| !name.trim().is_empty()) + .unwrap_or_else(|| path.to_str().unwrap_or("session")) + .to_string() +} + +fn normalize_path(value: &str) -> String { + value.replace('\\', "/").trim_end_matches('/').to_string() +} + +fn normalize_recovered_phase_from_events(events: &[StoredEvent]) -> Phase { + let phase = events + .last() + .map(|stored| astrcode_core::phase_of_storage_event(&stored.event)) + .unwrap_or(Phase::Idle); + astrcode_core::normalize_recovered_phase(phase) +} + +#[cfg(test)] +mod tests { + use std::{ + collections::HashMap, + path::{Path, PathBuf}, + sync::{Arc, Mutex}, + }; + + use astrcode_core::{ + DeleteProjectResult, ModeId, SessionMeta, SessionTurnAcquireResult, SessionTurnLease, + StoredEvent, + }; + use async_trait::async_trait; + + use super::*; + + #[derive(Debug)] + struct TestLease; + + impl SessionTurnLease for TestLease {} + + #[derive(Default)] + struct MemoryEventStore { + sessions: Mutex)>>, + } + + #[async_trait] + impl EventStore for MemoryEventStore { + async fn ensure_session(&self, session_id: &SessionId, working_dir: &Path) -> Result<()> { + self.sessions + .lock() + .expect("sessions lock poisoned") + .entry(session_id.clone()) + .or_insert_with(|| (working_dir.to_path_buf(), Vec::new())); + Ok(()) + } + + async fn append( + &self, + session_id: &SessionId, + event: &StorageEvent, + ) -> Result { + let mut sessions = self.sessions.lock().expect("sessions lock poisoned"); + let (_, events) = sessions + .get_mut(session_id) + .ok_or_else(|| AstrError::SessionNotFound(session_id.to_string()))?; + let stored = StoredEvent { + storage_seq: events.len() as u64 + 1, + event: event.clone(), + }; + events.push(stored.clone()); + Ok(stored) + } + + async fn replay(&self, session_id: &SessionId) -> Result> { + Ok(self + .sessions + .lock() + .expect("sessions lock poisoned") + .get(session_id) + .map(|(_, events)| events.clone()) + .unwrap_or_default()) + } + + async fn try_acquire_turn( + &self, + _session_id: &SessionId, + _turn_id: &str, + ) -> Result { + Ok(SessionTurnAcquireResult::Acquired(Box::new(TestLease))) + } + + async fn list_sessions(&self) -> Result> { + Ok(self + .sessions + .lock() + .expect("sessions lock poisoned") + .keys() + .cloned() + .collect()) + } + + async fn list_session_metas(&self) -> Result> { + let now = Utc::now(); + Ok(self + .sessions + .lock() + .expect("sessions lock poisoned") + .iter() + .map(|(session_id, (working_dir, _))| SessionMeta { + session_id: session_id.to_string(), + working_dir: working_dir.display().to_string(), + display_name: display_name_from_working_dir(working_dir), + title: "New Session".to_string(), + created_at: now, + updated_at: now, + parent_session_id: None, + parent_storage_seq: None, + phase: Phase::Idle, + }) + .collect()) + } + + async fn delete_session(&self, session_id: &SessionId) -> Result<()> { + self.sessions + .lock() + .expect("sessions lock poisoned") + .remove(session_id); + Ok(()) + } + + async fn delete_sessions_by_working_dir( + &self, + working_dir: &str, + ) -> Result { + let target = normalize_path(working_dir); + let mut sessions = self.sessions.lock().expect("sessions lock poisoned"); + let before = sessions.len(); + sessions.retain(|_, (path, _)| normalize_path(&path.display().to_string()) != target); + Ok(DeleteProjectResult { + success_count: before.saturating_sub(sessions.len()), + failed_session_ids: Vec::new(), + }) + } + } + + #[tokio::test] + async fn catalog_creates_loads_and_deletes_sessions() { + let store = Arc::new(MemoryEventStore::default()); + let catalog = SessionCatalog::new(store); + let mut events = catalog.subscribe_catalog_events(); + + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id.clone()); + + assert_eq!(catalog.list_loaded_sessions(), vec![session_id.clone()]); + assert!(matches!( + events.try_recv(), + Ok(SessionCatalogEvent::SessionCreated { .. }) + )); + assert_eq!( + catalog + .ensure_loaded_session(&session_id) + .await + .expect("session should load") + .state + .snapshot_recent_stored_events() + .expect("events should be cached") + .len(), + 1 + ); + assert!(matches!( + catalog.try_acquire_turn(&session_id, "turn-1").await, + Ok(SessionTurnAcquireResult::Acquired(_)) + )); + + catalog + .delete_session(&session_id) + .await + .expect("session should delete"); + assert!(catalog.list_loaded_sessions().is_empty()); + } + + #[tokio::test] + async fn catalog_switch_mode_updates_projected_mode_state() { + let store = Arc::new(MemoryEventStore::default()); + let catalog = SessionCatalog::new(store); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + + let initial = catalog + .session_mode_state(&session_id) + .await + .expect("mode state should read"); + assert_eq!(initial.current_mode_id, ModeId::code()); + assert!(initial.last_mode_changed_at.is_none()); + + let switched = catalog + .switch_mode(&session_id, ModeId::plan()) + .await + .expect("mode should switch"); + + assert_eq!(switched.current_mode_id, ModeId::plan()); + assert!(switched.last_mode_changed_at.is_some()); + } +} diff --git a/crates/host-session/src/child_sessions.rs b/crates/host-session/src/child_sessions.rs new file mode 100644 index 00000000..f069b6e8 --- /dev/null +++ b/crates/host-session/src/child_sessions.rs @@ -0,0 +1,27 @@ +use std::collections::HashMap; + +use astrcode_core::{ChildSessionNode, StorageEventPayload, StoredEvent}; + +pub(crate) fn rebuild_child_nodes(events: &[StoredEvent]) -> HashMap { + let mut nodes = HashMap::new(); + for stored in events { + if let Some(node) = child_node_from_stored_event(stored) { + nodes.insert(node.sub_run_id().to_string(), node); + } + } + nodes +} + +pub(crate) fn child_node_from_stored_event(stored: &StoredEvent) -> Option { + match &stored.event.payload { + StorageEventPayload::ChildSessionNotification { notification, .. } => { + Some(notification.child_ref.to_child_session_node( + stored.event.turn_id.clone().unwrap_or_default().into(), + astrcode_core::ChildSessionStatusSource::Durable, + notification.source_tool_call_id.clone(), + None, + )) + }, + _ => None, + } +} diff --git a/crates/host-session/src/collaboration.rs b/crates/host-session/src/collaboration.rs new file mode 100644 index 00000000..bb53ffa0 --- /dev/null +++ b/crates/host-session/src/collaboration.rs @@ -0,0 +1,398 @@ +use astrcode_core::{ + AgentCollaborationFact, AgentEventContext, ChildSessionNotification, CloseAgentParams, + CollaborationResult, EventTranslator, InputBatchAckedPayload, InputBatchStartedPayload, + InputDiscardedPayload, InputQueuedPayload, ObserveParams, ResolvedExecutionLimitsSnapshot, + ResolvedSubagentContextOverrides, Result, SendAgentParams, SpawnAgentParams, StorageEvent, + StorageEventPayload, StoredEvent, SubRunResult, ToolContext, +}; +use async_trait::async_trait; +use chrono::Utc; + +use crate::{SessionCatalog, state}; + +/// `host-session` 对外暴露的 sub-run owner bridge。 +/// +/// 新调用方必须从 `host-session` 导入它，避免把协作执行/read-model 合同挂在 core 顶层。 +pub type SubRunHandle = astrcode_core::agent::lineage::SubRunHandle; + +/// 子 Agent 启动执行端口。 +#[async_trait] +pub trait SubAgentExecutor: Send + Sync { + /// 启动子 Agent，返回结构化执行结果。 + async fn launch(&self, params: SpawnAgentParams, ctx: &ToolContext) -> Result; +} + +/// 子 Agent 协作执行端口（send / close / observe）。 +#[async_trait] +pub trait CollaborationExecutor: Send + Sync { + /// 发送追加消息给既有子 Agent。 + async fn send(&self, params: SendAgentParams, ctx: &ToolContext) + -> Result; + + /// 关闭目标子 Agent（级联关闭其子树）。 + async fn close( + &self, + params: CloseAgentParams, + ctx: &ToolContext, + ) -> Result; + + /// 观测目标子 Agent 快照。 + async fn observe( + &self, + params: ObserveParams, + ctx: &ToolContext, + ) -> Result; +} + +pub fn agent_event_context_from_subrun(handle: &SubRunHandle) -> AgentEventContext { + AgentEventContext::from(handle) +} + +impl SessionCatalog { + pub async fn append_subrun_started( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + resolved_limits: Option, + resolved_overrides: Option, + source_tool_call_id: Option, + ) -> Result> { + let Some(event) = subrun_started_event( + turn_id, + &agent, + resolved_limits, + resolved_overrides, + source_tool_call_id, + ) else { + return Ok(None); + }; + self.append_collaboration_event(session_id, event) + .await + .map(Some) + } + + pub async fn append_subrun_finished( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + result: SubRunResult, + stats: SubRunFinishStats, + source_tool_call_id: Option, + ) -> Result> { + let Some(event) = + subrun_finished_event(turn_id, &agent, result, stats, source_tool_call_id) + else { + return Ok(None); + }; + self.append_collaboration_event(session_id, event) + .await + .map(Some) + } + + pub async fn append_child_session_notification( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + notification: ChildSessionNotification, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::ChildSessionNotification { + notification, + timestamp: Some(Utc::now()), + }, + ) + .await + } + + pub async fn append_agent_collaboration_fact( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + fact: AgentCollaborationFact, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::AgentCollaborationFact { + fact, + timestamp: Some(Utc::now()), + }, + ) + .await + } + + pub async fn append_agent_input_queued( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + payload: InputQueuedPayload, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::AgentInputQueued { payload }, + ) + .await + } + + pub async fn append_agent_input_batch_started( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchStartedPayload, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::AgentInputBatchStarted { payload }, + ) + .await + } + + pub async fn append_agent_input_batch_acked( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchAckedPayload, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::AgentInputBatchAcked { payload }, + ) + .await + } + + pub async fn append_agent_input_discarded( + &self, + session_id: &astrcode_core::SessionId, + turn_id: &str, + agent: AgentEventContext, + payload: InputDiscardedPayload, + ) -> Result { + self.append_collaboration_payload( + session_id, + Some(turn_id.to_string()), + agent, + StorageEventPayload::AgentInputDiscarded { payload }, + ) + .await + } + + async fn append_collaboration_payload( + &self, + session_id: &astrcode_core::SessionId, + turn_id: Option, + agent: AgentEventContext, + payload: StorageEventPayload, + ) -> Result { + self.append_collaboration_event( + session_id, + StorageEvent { + turn_id, + agent, + payload, + }, + ) + .await + } + + async fn append_collaboration_event( + &self, + session_id: &astrcode_core::SessionId, + event: StorageEvent, + ) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let phase = loaded.state.current_phase()?; + let mut translator = EventTranslator::new(phase); + state::append_and_broadcast(&loaded.state, &event, &mut translator).await + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct SubRunFinishStats { + pub step_count: u32, + pub estimated_tokens: u64, +} + +pub fn subrun_started_event( + turn_id: &str, + agent: &AgentEventContext, + resolved_limits: Option, + resolved_overrides: Option, + source_tool_call_id: Option, +) -> Option { + if agent.invocation_kind != Some(astrcode_core::InvocationKind::SubRun) { + return None; + } + + Some(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::SubRunStarted { + tool_call_id: source_tool_call_id, + resolved_overrides: resolved_overrides.unwrap_or_default(), + resolved_limits: resolved_limits.unwrap_or_default(), + timestamp: Some(Utc::now()), + }, + }) +} + +pub fn subrun_finished_event( + turn_id: &str, + agent: &AgentEventContext, + result: SubRunResult, + stats: SubRunFinishStats, + source_tool_call_id: Option, +) -> Option { + if agent.invocation_kind != Some(astrcode_core::InvocationKind::SubRun) { + return None; + } + + Some(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::SubRunFinished { + tool_call_id: source_tool_call_id, + result, + step_count: stats.step_count, + estimated_tokens: stats.estimated_tokens, + timestamp: Some(Utc::now()), + }, + }) +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum SubRunStatus { + #[default] + Queued, + Running, + Succeeded, + Failed, + Cancelled, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum DeliveryState { + #[default] + Pending, + Delivered, + Acknowledged, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ResultDeliveryState { + #[default] + Pending, + Delivered, + Dropped, +} + +#[cfg(test)] +mod tests { + use astrcode_core::{ + AgentEventContext, AgentLifecycleStatus, CompletedSubRunOutcome, + ResolvedExecutionLimitsSnapshot, StorageEventPayload, SubRunHandoff, SubRunResult, + SubRunStorageMode, + }; + + use super::{SubRunFinishStats, SubRunHandle, subrun_finished_event, subrun_started_event}; + + #[test] + fn owner_bridge_exposes_subrun_shape() { + let handle = SubRunHandle { + sub_run_id: "subrun-1".into(), + agent_id: "agent-child".into(), + session_id: "session-parent".into(), + child_session_id: Some("session-child".into()), + depth: 1, + parent_turn_id: "turn-parent".into(), + parent_agent_id: None, + parent_sub_run_id: None, + lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, + agent_profile: "default".to_string(), + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: AgentLifecycleStatus::Pending, + last_turn_outcome: None, + resolved_limits: ResolvedExecutionLimitsSnapshot, + delegation: None, + }; + + assert_eq!(handle.sub_run_id.as_str(), "subrun-1"); + assert_eq!(handle.open_session_id().as_str(), "session-child"); + } + + fn subrun_agent() -> AgentEventContext { + AgentEventContext::sub_run( + "agent-child", + "turn-parent", + "reviewer", + "subrun-1", + None, + SubRunStorageMode::IndependentSession, + Some("session-child".into()), + ) + } + + #[test] + fn subrun_lifecycle_events_require_subrun_context() { + assert!( + subrun_started_event("turn-1", &AgentEventContext::default(), None, None, None) + .is_none() + ); + + let started = + subrun_started_event("turn-1", &subrun_agent(), None, None, Some("call-1".into())) + .expect("subrun context should emit started event"); + assert!(matches!( + started.payload, + StorageEventPayload::SubRunStarted { tool_call_id, .. } + if tool_call_id.as_deref() == Some("call-1") + )); + } + + #[test] + fn subrun_finished_event_preserves_result_contract() { + let event = subrun_finished_event( + "turn-1", + &subrun_agent(), + SubRunResult::Completed { + outcome: CompletedSubRunOutcome::Completed, + handoff: SubRunHandoff { + findings: Vec::new(), + artifacts: Vec::new(), + delivery: None, + }, + }, + SubRunFinishStats { + step_count: 3, + estimated_tokens: 99, + }, + None, + ) + .expect("subrun context should emit finish event"); + + assert!(matches!( + event.payload, + StorageEventPayload::SubRunFinished { + step_count: 3, + estimated_tokens: 99, + .. + } + )); + } +} diff --git a/crates/host-session/src/compaction.rs b/crates/host-session/src/compaction.rs new file mode 100644 index 00000000..2648cf33 --- /dev/null +++ b/crates/host-session/src/compaction.rs @@ -0,0 +1,89 @@ +use astrcode_core::{EventTranslator, Result, StorageEvent, StorageEventPayload, StoredEvent}; + +use crate::{SessionCatalog, state}; + +#[derive(Debug, Clone)] +pub struct CompactPersistResult { + pub persisted_events: Vec, + pub compact_applied: bool, +} + +impl SessionCatalog { + /// Persist compact events through the host-session writer/projection path. + /// + /// Summary generation remains outside this owner; host-session owns the + /// durable append, projection update, broadcast, and checkpoint trigger. + pub async fn persist_compact_events( + &self, + session_id: &astrcode_core::SessionId, + events: Vec, + ) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let phase = loaded.state.current_phase()?; + let mut translator = EventTranslator::new(phase); + let mut persisted_events = Vec::with_capacity(events.len()); + + for event in events { + persisted_events + .push(state::append_and_broadcast(&loaded.state, &event, &mut translator).await?); + } + + state::checkpoint_if_compacted( + &self.event_store, + session_id, + &loaded.state, + &persisted_events, + ) + .await; + + let compact_applied = persisted_events.iter().any(|stored| { + matches!( + stored.event.payload, + StorageEventPayload::CompactApplied { .. } + ) + }); + Ok(CompactPersistResult { + persisted_events, + compact_applied, + }) + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{ + AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, StorageEvent, + StorageEventPayload, + }; + + #[test] + fn compact_applied_event_shape_remains_durable() { + let event = StorageEvent { + turn_id: None, + agent: AgentEventContext::default(), + payload: StorageEventPayload::CompactApplied { + trigger: CompactTrigger::Manual, + summary: "summary".to_string(), + meta: CompactAppliedMeta { + mode: CompactMode::Full, + instructions_present: false, + fallback_used: false, + retry_count: 0, + input_units: 10, + output_summary_chars: 7, + }, + preserved_recent_turns: 1, + pre_tokens: 100, + post_tokens_estimate: 20, + messages_removed: 2, + tokens_freed: 80, + timestamp: chrono::Utc::now(), + }, + }; + + assert!(matches!( + event.payload, + StorageEventPayload::CompactApplied { summary, .. } if summary == "summary" + )); + } +} diff --git a/crates/core/src/composer.rs b/crates/host-session/src/composer.rs similarity index 94% rename from crates/core/src/composer.rs rename to crates/host-session/src/composer.rs index 4b95c362..d31f56f1 100644 --- a/crates/core/src/composer.rs +++ b/crates/host-session/src/composer.rs @@ -1,6 +1,6 @@ //! # 输入候选项模型 //! -//! 定义 Composer 输入面板的候选项数据结构。 +//! 定义 host-session 输入面板的候选项数据结构。 //! 候选项可以来自命令、技能或能力声明，用户选择后执行对应的插入或命令动作。 use serde::{Deserialize, Serialize}; diff --git a/crates/session-runtime/src/state/cache.rs b/crates/host-session/src/event_cache.rs similarity index 100% rename from crates/session-runtime/src/state/cache.rs rename to crates/host-session/src/event_cache.rs diff --git a/crates/session-runtime/src/state/writer.rs b/crates/host-session/src/event_log.rs similarity index 84% rename from crates/session-runtime/src/state/writer.rs rename to crates/host-session/src/event_log.rs index 870a8547..23c6dc4d 100644 --- a/crates/session-runtime/src/state/writer.rs +++ b/crates/host-session/src/event_log.rs @@ -4,12 +4,15 @@ use std::sync::Mutex as StdMutex; #[cfg(test)] use astrcode_core::{EventLogWriter, support}; -use astrcode_core::{EventStore, Result, SessionId, StorageEvent, StoredEvent}; +use astrcode_core::{Result, SessionId, StorageEvent, StoredEvent}; -/// 同步 `EventLogWriter` 的 async-safe 包装。 +use crate::EventStore; + +/// Async-safe session event writer owned by host-session. /// -/// 生产路径直接持有异步 `EventStore`，避免在正常 append 流程里做同步/异步桥接。 -/// 仅保留同步 writer 兼容层，用于测试态和遗留同步调用点。 +/// Production appends go through the async `EventStore`. The sync +/// `EventLogWriter` bridge is retained only for tests and event replay +/// fixtures while the old runtime boundary is being deleted. pub struct SessionWriter { inner: SessionWriterInner, } @@ -40,7 +43,6 @@ impl SessionWriter { } } - /// 同步写入：在当前线程直接调用 writer，用于 `spawn_blocking` 内部或测试。 #[cfg(test)] pub fn append_blocking(&self, event: &StorageEvent) -> Result { event.validate()?; @@ -63,7 +65,6 @@ impl SessionWriter { } } - /// 异步写入：生产路径直接走 `EventStore`，同步 writer 则退回 `spawn_blocking` 兼容层。 pub async fn append(self: Arc, event: StorageEvent) -> Result { event.validate()?; match &self.inner { @@ -107,7 +108,6 @@ fn block_on_event_store_append( } } -/// 将同步闭包包装为 `spawn_blocking` 异步调用，统一处理 JoinError。 #[cfg(test)] async fn spawn_blocking_result(label: &'static str, work: F) -> Result where diff --git a/crates/host-session/src/execution_surface.rs b/crates/host-session/src/execution_surface.rs new file mode 100644 index 00000000..6000503b --- /dev/null +++ b/crates/host-session/src/execution_surface.rs @@ -0,0 +1,40 @@ +/// `host-session` 持有的最小快照骨架。 +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct HostSessionSnapshot { + pub session_id: String, + pub working_dir: String, + pub event_log_revision: u64, + pub read_model_revision: u64, + pub lineage_parent_session_id: Option, + pub active_turn_id: Option, + pub mode_id: Option, +} + +impl HostSessionSnapshot { + pub fn new(session_id: impl Into, working_dir: impl Into) -> Self { + Self { + session_id: session_id.into(), + working_dir: working_dir.into(), + event_log_revision: 0, + read_model_revision: 0, + lineage_parent_session_id: None, + active_turn_id: None, + mode_id: None, + } + } +} + +#[cfg(test)] +mod tests { + use super::HostSessionSnapshot; + + #[test] + fn new_snapshot_starts_without_active_turn() { + let snapshot = HostSessionSnapshot::new("session-1", "D:/repo"); + + assert_eq!(snapshot.session_id, "session-1"); + assert_eq!(snapshot.working_dir, "D:/repo"); + assert_eq!(snapshot.event_log_revision, 0); + assert!(snapshot.active_turn_id.is_none()); + } +} diff --git a/crates/host-session/src/fork.rs b/crates/host-session/src/fork.rs new file mode 100644 index 00000000..6fe5eff3 --- /dev/null +++ b/crates/host-session/src/fork.rs @@ -0,0 +1,285 @@ +use astrcode_core::{AstrError, SessionId, StorageEventPayload, StoredEvent}; + +use crate::SessionCatalog; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ForkPoint { + StorageSeq(u64), + TurnEnd(String), + Latest, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ForkResult { + pub new_session_id: SessionId, + pub fork_point_storage_seq: u64, + pub events_copied: usize, +} + +impl SessionCatalog { + pub async fn fork_session( + &self, + source_session_id: &SessionId, + fork_point: ForkPoint, + ) -> astrcode_core::Result { + self.ensure_session_exists(source_session_id).await?; + + let source_events = self.event_store.replay(source_session_id).await?; + let fork_point_storage_seq = + resolve_fork_point_storage_seq(source_session_id, &source_events, &fork_point)?; + let events_to_copy = + stable_events_up_to_storage_seq(&source_events, fork_point_storage_seq)?; + + let source = self.ensure_loaded_session(source_session_id).await?; + let new_session_id = self + .fork_events_up_to( + source_session_id, + &source.working_dir, + &events_to_copy, + Some(fork_point_storage_seq), + ) + .await?; + + Ok(ForkResult { + new_session_id, + fork_point_storage_seq, + events_copied: events_to_copy + .iter() + .filter(|stored| { + !matches!( + stored.event.payload, + StorageEventPayload::SessionStart { .. } + ) + }) + .count(), + }) + } +} + +fn resolve_fork_point_storage_seq( + source_session_id: &SessionId, + events: &[StoredEvent], + fork_point: &ForkPoint, +) -> astrcode_core::Result { + match fork_point { + ForkPoint::Latest => latest_stable_storage_seq(events).ok_or_else(|| { + AstrError::Validation(format!( + "session '{}' has no stable fork point", + source_session_id + )) + }), + ForkPoint::StorageSeq(storage_seq) => { + if !events + .iter() + .any(|stored| stored.storage_seq == *storage_seq) + { + return Err(AstrError::Validation(format!( + "storage_seq {} is out of range for session '{}'", + storage_seq, source_session_id + ))); + } + let _ = stable_events_up_to_storage_seq(events, *storage_seq)?; + Ok(*storage_seq) + }, + ForkPoint::TurnEnd(turn_id) => { + resolve_turn_end_storage_seq(source_session_id, events, turn_id) + }, + } +} + +fn resolve_turn_end_storage_seq( + source_session_id: &SessionId, + events: &[StoredEvent], + turn_id: &str, +) -> astrcode_core::Result { + let turn_exists = events + .iter() + .any(|stored| stored.event.turn_id.as_deref() == Some(turn_id)); + if !turn_exists { + return Err(AstrError::SessionNotFound(format!( + "turn '{}' in session '{}'", + turn_id, source_session_id + ))); + } + + events + .iter() + .find_map(|stored| match &stored.event.payload { + StorageEventPayload::TurnDone { .. } + if stored.event.turn_id.as_deref() == Some(turn_id) => + { + Some(stored.storage_seq) + }, + _ => None, + }) + .ok_or_else(|| { + AstrError::Validation(format!( + "turn '{}' has not completed and cannot be used as a fork point", + turn_id + )) + }) +} + +fn latest_stable_storage_seq(events: &[StoredEvent]) -> Option { + let mut latest = None; + for stored in events { + if matches!( + stored.event.payload, + StorageEventPayload::SessionStart { .. } + ) { + latest = Some(stored.storage_seq); + } + if matches!( + stored.event.payload, + StorageEventPayload::TurnDone { .. } | StorageEventPayload::Error { .. } + ) { + latest = Some(stored.storage_seq); + } + } + latest +} + +fn stable_events_up_to_storage_seq( + events: &[StoredEvent], + storage_seq: u64, +) -> astrcode_core::Result> { + let cutoff = events + .iter() + .position(|stored| stored.storage_seq == storage_seq) + .ok_or_else(|| { + AstrError::Validation(format!("storage_seq {} is out of range", storage_seq)) + })?; + let candidate = events[..=cutoff].to_vec(); + + if is_stable_prefix(&candidate) { + Ok(candidate) + } else { + Err(AstrError::Validation(format!( + "storage_seq {} is inside an unfinished turn and cannot be used as a fork point", + storage_seq + ))) + } +} + +fn is_stable_prefix(events: &[StoredEvent]) -> bool { + let mut active_turn_id: Option<&str> = None; + for stored in events { + let Some(turn_id) = stored.event.turn_id.as_deref() else { + continue; + }; + match &stored.event.payload { + StorageEventPayload::TurnDone { .. } | StorageEventPayload::Error { .. } => { + if active_turn_id == Some(turn_id) { + active_turn_id = None; + } + }, + _ => { + if active_turn_id.is_none() { + active_turn_id = Some(turn_id); + } + }, + } + } + active_turn_id.is_none() +} + +#[cfg(test)] +mod tests { + use astrcode_core::{AgentEventContext, StorageEvent, StorageEventPayload, StoredEvent}; + use chrono::Utc; + + use super::{ForkPoint, latest_stable_storage_seq, resolve_fork_point_storage_seq}; + use crate::branch::session_start_event; + + fn stored( + storage_seq: u64, + turn_id: Option<&str>, + payload: StorageEventPayload, + ) -> StoredEvent { + StoredEvent { + storage_seq, + event: StorageEvent { + turn_id: turn_id.map(str::to_string), + agent: AgentEventContext::default(), + payload, + }, + } + } + + #[test] + fn latest_stable_storage_seq_stops_before_active_turn() { + let events = vec![ + StoredEvent { + storage_seq: 1, + event: session_start_event("source".into(), ".".into(), None, None), + }, + stored( + 2, + Some("turn-1"), + StorageEventPayload::UserMessage { + content: "hello".to_string(), + origin: astrcode_core::UserMessageOrigin::User, + timestamp: Utc::now(), + }, + ), + stored( + 3, + Some("turn-1"), + StorageEventPayload::TurnDone { + timestamp: Utc::now(), + terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), + reason: Some("completed".to_string()), + }, + ), + stored( + 4, + Some("turn-2"), + StorageEventPayload::UserMessage { + content: "still running".to_string(), + origin: astrcode_core::UserMessageOrigin::User, + timestamp: Utc::now(), + }, + ), + ]; + + assert_eq!(latest_stable_storage_seq(&events), Some(3)); + } + + #[test] + fn fork_point_accepts_completed_turn_end() { + let events = vec![ + StoredEvent { + storage_seq: 1, + event: session_start_event("source".into(), ".".into(), None, None), + }, + stored( + 2, + Some("turn-1"), + StorageEventPayload::UserMessage { + content: "hello".to_string(), + origin: astrcode_core::UserMessageOrigin::User, + timestamp: Utc::now(), + }, + ), + stored( + 3, + Some("turn-1"), + StorageEventPayload::TurnDone { + timestamp: Utc::now(), + terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), + reason: None, + }, + ), + ]; + + assert_eq!( + resolve_fork_point_storage_seq( + &"source".to_string().into(), + &events, + &ForkPoint::TurnEnd("turn-1".to_string()), + ) + .expect("completed turn should resolve"), + 3 + ); + } +} diff --git a/crates/host-session/src/input_queue.rs b/crates/host-session/src/input_queue.rs new file mode 100644 index 00000000..12da4acb --- /dev/null +++ b/crates/host-session/src/input_queue.rs @@ -0,0 +1,169 @@ +use std::collections::{HashMap, HashSet}; + +use astrcode_core::{StorageEventPayload, StoredEvent}; +use serde::{Deserialize, Serialize}; + +/// `host-session` 对外暴露的 input queue owner bridge。 +/// +/// 新调用方必须从 `host-session` 导入它，避免把 input queue read-model 合同挂在 core 顶层。 +pub type InputQueueProjection = astrcode_core::agent::input_queue::InputQueueProjection; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum InputKind { + #[default] + User, + ParentSubrun, + FollowUp, +} + +pub(crate) fn input_queue_projection_target_agent_id( + payload: &StorageEventPayload, +) -> Option<&str> { + match payload { + StorageEventPayload::AgentInputQueued { payload } => Some(&payload.envelope.to_agent_id), + StorageEventPayload::AgentInputBatchStarted { payload } => Some(&payload.target_agent_id), + StorageEventPayload::AgentInputBatchAcked { payload } => Some(&payload.target_agent_id), + StorageEventPayload::AgentInputDiscarded { payload } => Some(&payload.target_agent_id), + _ => None, + } +} + +pub(crate) fn apply_input_queue_event_to_index( + index: &mut HashMap, + stored: &StoredEvent, +) { + let Some(target_agent_id) = input_queue_projection_target_agent_id(&stored.event.payload) + else { + return; + }; + let projection = index.entry(target_agent_id.to_string()).or_default(); + apply_input_queue_event_for_agent(projection, stored, target_agent_id); +} + +pub(crate) fn replay_input_queue_projection_index( + events: &[StoredEvent], +) -> HashMap { + let mut index = HashMap::new(); + for stored in events { + apply_input_queue_event_to_index(&mut index, stored); + } + index +} + +fn apply_input_queue_event_for_agent( + projection: &mut InputQueueProjection, + stored: &StoredEvent, + target_agent_id: &str, +) { + match &stored.event.payload { + StorageEventPayload::AgentInputQueued { payload } => { + if payload.envelope.to_agent_id != target_agent_id { + return; + } + let id = &payload.envelope.delivery_id; + if !projection.discarded_delivery_ids.contains(id) + && !projection.pending_delivery_ids.contains(id) + { + projection.pending_delivery_ids.push(id.clone()); + } + }, + StorageEventPayload::AgentInputBatchStarted { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + projection.active_batch_id = Some(payload.batch_id.clone()); + projection.active_delivery_ids = payload.delivery_ids.clone(); + }, + StorageEventPayload::AgentInputBatchAcked { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + let acked_set: HashSet<_> = payload.delivery_ids.iter().collect(); + projection.pending_delivery_ids.retain(|id| { + !acked_set.contains(id) && !projection.discarded_delivery_ids.contains(id) + }); + if projection.active_batch_id.as_deref() == Some(payload.batch_id.as_str()) { + projection.active_batch_id = None; + projection.active_delivery_ids.clear(); + } + }, + StorageEventPayload::AgentInputDiscarded { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + for id in &payload.delivery_ids { + if !projection.discarded_delivery_ids.contains(id) { + projection.discarded_delivery_ids.push(id.clone()); + } + } + projection + .pending_delivery_ids + .retain(|id| !projection.discarded_delivery_ids.contains(id)); + let discarded_set: HashSet<_> = projection.discarded_delivery_ids.iter().collect(); + if projection + .active_delivery_ids + .iter() + .any(|id| discarded_set.contains(id)) + { + projection.active_batch_id = None; + projection.active_delivery_ids.clear(); + } + }, + _ => {}, + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{ + AgentEventContext, AgentLifecycleStatus, InputQueuedPayload, QueuedInputEnvelope, + StorageEvent, StorageEventPayload, StoredEvent, + }; + + use super::{InputQueueProjection, replay_input_queue_projection_index}; + + #[test] + fn owner_bridge_exposes_durable_projection_shape() { + let projection = InputQueueProjection::default(); + + assert_eq!(projection.pending_input_count(), 0); + assert!(projection.pending_delivery_ids.is_empty()); + assert!(projection.active_batch_id.is_none()); + } + + #[test] + fn replay_index_tracks_pending_inputs_by_agent() { + let event = StoredEvent { + storage_seq: 1, + event: StorageEvent { + turn_id: Some("turn-1".into()), + agent: AgentEventContext::default(), + payload: StorageEventPayload::AgentInputQueued { + payload: InputQueuedPayload { + envelope: QueuedInputEnvelope { + delivery_id: "delivery-1".into(), + from_agent_id: "parent".into(), + to_agent_id: "child".into(), + message: "hello".into(), + queued_at: chrono::Utc::now(), + sender_lifecycle_status: AgentLifecycleStatus::Running, + sender_last_turn_outcome: None, + sender_open_session_id: "session-parent".into(), + }, + }, + }, + }, + }; + + let index = replay_input_queue_projection_index(&[event]); + + assert_eq!( + index + .get("child") + .expect("child queue should exist") + .pending_delivery_ids, + vec!["delivery-1".into()] + ); + } +} diff --git a/crates/host-session/src/lib.rs b/crates/host-session/src/lib.rs new file mode 100644 index 00000000..66e0599a --- /dev/null +++ b/crates/host-session/src/lib.rs @@ -0,0 +1,73 @@ +//! session owner 骨架。 +//! +//! 这个 crate 后续承接 durable truth、恢复、query/read model、branch/fork、 +//! compaction 与多 agent 协作真相。 + +pub mod branch; +pub mod catalog; +mod child_sessions; +pub mod collaboration; +pub mod compaction; +pub mod composer; +mod event_cache; +pub mod event_log; +pub mod execution_surface; +pub mod fork; +pub mod input_queue; +pub mod model_selection; +pub mod ports; +pub mod projection; +mod projection_registry; +pub mod query; +pub mod session_catalog; +pub mod session_plan; +pub mod state; +mod tasks; +pub mod turn_mutation; +mod turn_projection; +pub mod workflow; + +pub use branch::SubmitTarget; +pub use catalog::{LoadedSession, SessionCatalog, SessionModeState}; +pub use collaboration::{ + CollaborationExecutor, DeliveryState, ResultDeliveryState, SubAgentExecutor, SubRunFinishStats, + SubRunHandle, SubRunStatus, agent_event_context_from_subrun, subrun_finished_event, + subrun_started_event, +}; +pub use compaction::CompactPersistResult; +pub use composer::{ComposerOption, ComposerOptionActionKind, ComposerOptionKind}; +pub use event_log::SessionWriter; +pub use execution_surface::HostSessionSnapshot; +pub use fork::{ForkPoint, ForkResult}; +pub use input_queue::{InputKind, InputQueueProjection}; +pub use ports::{ + EventStore, ProjectionRegistrySnapshot, PromptAgentProfileSummary, PromptBuildCacheMetrics, + PromptBuildOutput, PromptBuildRequest, PromptEntrySummary, PromptFacts, PromptFactsProvider, + PromptFactsRequest, PromptGovernanceContext, PromptProvider, PromptSkillSummary, + RecoveredSessionState, SessionRecoveryCheckpoint, TurnProjectionSnapshot, +}; +pub use projection::{AgentState, AgentStateProjector, project}; +pub use query::{ + LastCompactMetaSnapshot, ProjectedTurnOutcome, SessionControlStateSnapshot, + SessionObserveSnapshot, SessionReadModelReplay, TurnTerminalSnapshot, +}; +pub use session_catalog::SessionCatalogEvent; +pub use session_plan::{ + SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER, SessionPlanState, SessionPlanStatus, + session_plan_content_digest, +}; +pub use state::{ + SESSION_BROADCAST_CAPACITY, SESSION_LIVE_BROADCAST_CAPACITY, SessionSnapshot, SessionState, + append_and_broadcast, checkpoint_if_compacted, +}; +pub use turn_mutation::{ + AcceptedSubmitPrompt, BegunAcceptedTurn, CompactSessionMutationInput, CompactSessionSummary, + InterruptSessionMutationInput, InterruptSessionSummary, PendingManualCompactRequest, + PromptAcceptedSummary, RuntimeTurnEventPersistenceInput, RuntimeTurnPersistenceInput, + SubmitPromptMutationInput, SubmitTurnBusyPolicy, TurnMutationFacade, TurnMutationPreparation, + TurnMutationPreparationOwner, +}; +pub use workflow::{ + WorkflowArtifactRef, WorkflowBridgeState, WorkflowDef, WorkflowInstanceState, WorkflowPhaseDef, + WorkflowSignal, WorkflowTransitionDef, WorkflowTransitionTrigger, +}; diff --git a/crates/host-session/src/model_selection.rs b/crates/host-session/src/model_selection.rs new file mode 100644 index 00000000..ed8a9f64 --- /dev/null +++ b/crates/host-session/src/model_selection.rs @@ -0,0 +1,150 @@ +use astrcode_core::{AstrError, HookEventKey, ModelSelection, Result}; +use astrcode_plugin_host::{HookBusEffectKind, HookBusRequest, HookBusStep, dispatch_hook_bus}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ModelSelectionDecision { + pub selection: ModelSelection, + pub diagnostics: Vec, +} + +pub fn apply_model_select_hooks( + selection: ModelSelection, + steps: Vec, +) -> Result { + let payload = serde_json::to_value(&selection).map_err(|error| { + AstrError::Internal(format!("serialize model selection failed: {error}")) + })?; + let outcome = dispatch_hook_bus( + HookBusRequest { + event: HookEventKey::ModelSelect, + payload, + }, + steps, + )?; + + if let Some(blocked_by) = outcome.blocked_by { + return Err(AstrError::Validation(format!( + "model_select blocked by hook '{blocked_by}'" + ))); + } + + let selection = serde_json::from_value(outcome.payload) + .map_err(|error| AstrError::Internal(format!("decode model selection failed: {error}")))?; + let diagnostics = outcome + .effects + .into_iter() + .filter(|effect| effect.kind == HookBusEffectKind::Diagnostic) + .filter_map(|effect| effect.payload.as_str().map(str::to_owned)) + .collect(); + + Ok(ModelSelectionDecision { + selection, + diagnostics, + }) +} + +#[cfg(test)] +mod tests { + use astrcode_core::ModelSelection; + use astrcode_plugin_host::{ + HookBusEffect, HookBusEffectKind, HookBusStep, HookDispatchMode, HookFailurePolicy, + HookRegistration, HookStage, + }; + use serde_json::json; + + use super::{ModelSelectionDecision, apply_model_select_hooks}; + + fn selection() -> ModelSelection { + ModelSelection::new("coding", "gpt-5.4", "openai") + } + + fn step(hook_id: &str, dispatch_mode: HookDispatchMode, effect: HookBusEffect) -> HookBusStep { + HookBusStep { + registration: HookRegistration { + descriptor: astrcode_plugin_host::HookDescriptor { + hook_id: hook_id.to_string(), + event: "model_select".to_string(), + }, + stage: HookStage::Host, + dispatch_mode, + failure_policy: HookFailurePolicy::FailClosed, + priority: 0, + }, + effect, + } + } + + #[test] + fn model_select_keeps_selection_when_hooks_only_report_diagnostics() { + let decision = apply_model_select_hooks( + selection(), + vec![step( + "diag", + HookDispatchMode::Sequential, + HookBusEffect { + kind: HookBusEffectKind::Diagnostic, + payload: json!("keep current model"), + terminal: false, + }, + )], + ) + .expect("diagnostic hook should not block selection"); + + assert_eq!( + decision, + ModelSelectionDecision { + selection: selection(), + diagnostics: vec!["keep current model".to_string()], + } + ); + } + + #[test] + fn model_select_can_rewrite_selection_payload() { + let decision = apply_model_select_hooks( + selection(), + vec![step( + "rewrite", + HookDispatchMode::Modify, + HookBusEffect { + kind: HookBusEffectKind::MutatePayload, + payload: json!({ + "profileName": "coding", + "model": "deepseek-chat", + "providerKind": "deepseek" + }), + terminal: false, + }, + )], + ) + .expect("rewrite hook should produce a new selection"); + + assert_eq!( + decision.selection, + ModelSelection::new("coding", "deepseek-chat", "deepseek") + ); + } + + #[test] + fn model_select_can_be_blocked_by_host_hook() { + let error = apply_model_select_hooks( + selection(), + vec![step( + "policy", + HookDispatchMode::Cancellable, + HookBusEffect { + kind: HookBusEffectKind::Block, + payload: json!({ "reason": "policy denied" }), + terminal: true, + }, + )], + ) + .expect_err("blocking hook should reject selection"); + + assert!( + error + .to_string() + .contains("model_select blocked by hook 'policy'") + ); + } +} diff --git a/crates/host-session/src/ports.rs b/crates/host-session/src/ports.rs new file mode 100644 index 00000000..0a9a2961 --- /dev/null +++ b/crates/host-session/src/ports.rs @@ -0,0 +1,294 @@ +use std::{ + collections::HashMap, + path::{Path, PathBuf}, +}; + +use astrcode_agent_runtime::provider::{PromptCacheGlobalStrategy, PromptCacheHints}; +use astrcode_core::{ + CapabilitySpec, ChildSessionNode, DeleteProjectResult, PromptDeclaration, Result, SessionId, + SessionMeta, SessionTurnAcquireResult, StorageEvent, StoredEvent, SystemPromptBlock, + SystemPromptLayer, TaskSnapshot, TurnId, TurnTerminalKind, mode::ModeId, +}; +use async_trait::async_trait; +use chrono::{DateTime, Utc}; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::{AgentState, InputQueueProjection}; + +/// host-session owner 的事件存储端口。 +#[async_trait] +pub trait EventStore: Send + Sync { + async fn ensure_session(&self, session_id: &SessionId, working_dir: &Path) -> Result<()>; + async fn append(&self, session_id: &SessionId, event: &StorageEvent) -> Result; + async fn replay(&self, session_id: &SessionId) -> Result>; + async fn recover_session(&self, session_id: &SessionId) -> Result { + Ok(RecoveredSessionState { + checkpoint: None, + tail_events: self.replay(session_id).await?, + }) + } + async fn checkpoint_session( + &self, + _session_id: &SessionId, + _checkpoint: &SessionRecoveryCheckpoint, + ) -> Result<()> { + Ok(()) + } + async fn try_acquire_turn( + &self, + session_id: &SessionId, + turn_id: &str, + ) -> Result; + async fn list_sessions(&self) -> Result>; + async fn list_session_metas(&self) -> Result>; + async fn delete_session(&self, session_id: &SessionId) -> Result<()>; + async fn delete_sessions_by_working_dir( + &self, + working_dir: &str, + ) -> Result; +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct TurnProjectionSnapshot { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub terminal_kind: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub last_error: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ProjectionRegistrySnapshot { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub last_mode_changed_at: Option>, + #[serde(default)] + pub child_nodes: HashMap, + #[serde(default)] + pub active_tasks: HashMap, + #[serde(default)] + pub input_queue_projection_index: HashMap, + #[serde(default)] + pub turn_projections: HashMap, +} + +impl ProjectionRegistrySnapshot { + pub fn is_empty(&self) -> bool { + self.last_mode_changed_at.is_none() + && self.child_nodes.is_empty() + && self.active_tasks.is_empty() + && self.input_queue_projection_index.is_empty() + && self.turn_projections.is_empty() + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SessionRecoveryCheckpoint { + pub agent_state: AgentState, + #[serde(default, skip_serializing_if = "ProjectionRegistrySnapshot::is_empty")] + pub projection_registry: ProjectionRegistrySnapshot, + pub checkpoint_storage_seq: u64, +} + +impl SessionRecoveryCheckpoint { + pub fn new( + agent_state: AgentState, + projection_registry: ProjectionRegistrySnapshot, + checkpoint_storage_seq: u64, + ) -> Self { + Self { + agent_state, + projection_registry, + checkpoint_storage_seq, + } + } + + pub fn projection_registry_snapshot(&self) -> ProjectionRegistrySnapshot { + self.projection_registry.clone() + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct RecoveredSessionState { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub checkpoint: Option, + #[serde(default)] + pub tail_events: Vec, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptGovernanceContext { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub allowed_capability_names: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub mode_id: Option, + #[serde(default, skip_serializing_if = "String::is_empty")] + pub approval_mode: String, + #[serde(default, skip_serializing_if = "String::is_empty")] + pub policy_revision: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub max_subrun_depth: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub max_spawn_per_turn: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptFactsRequest { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub session_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub turn_id: Option, + pub working_dir: PathBuf, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub allowed_capability_names: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub governance: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptEntrySummary { + pub id: String, + pub description: String, +} + +impl PromptEntrySummary { + pub fn new(id: impl Into, description: impl Into) -> Self { + Self { + id: id.into(), + description: description.into(), + } + } +} + +pub type PromptSkillSummary = PromptEntrySummary; +pub type PromptAgentProfileSummary = PromptEntrySummary; + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PromptFacts { + pub profile: String, + #[serde(default)] + pub profile_context: Value, + #[serde(default)] + pub metadata: Value, + #[serde(default)] + pub skills: Vec, + #[serde(default)] + pub agent_profiles: Vec, + #[serde(default)] + pub prompt_declarations: Vec, +} + +impl Default for PromptFacts { + fn default() -> Self { + Self { + profile: "coding".to_string(), + profile_context: Value::Null, + metadata: Value::Null, + skills: Vec::new(), + agent_profiles: Vec::new(), + prompt_declarations: Vec::new(), + } + } +} + +#[async_trait] +pub trait PromptFactsProvider: Send + Sync { + async fn resolve_prompt_facts(&self, request: &PromptFactsRequest) -> Result; +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PromptBuildRequest { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub session_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub turn_id: Option, + pub working_dir: PathBuf, + pub profile: String, + #[serde(default)] + pub step_index: usize, + #[serde(default)] + pub turn_index: usize, + #[serde(default)] + pub profile_context: Value, + #[serde(default)] + pub capabilities: Vec, + #[serde(default)] + pub skills: Vec, + #[serde(default)] + pub agent_profiles: Vec, + #[serde(default)] + pub prompt_declarations: Vec, + #[serde(default)] + pub metadata: Value, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptBuildCacheMetrics { + pub reuse_hits: u32, + pub reuse_misses: u32, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub unchanged_layers: Vec, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PromptBuildOutput { + pub system_prompt: String, + #[serde(default)] + pub system_prompt_blocks: Vec, + #[serde(default)] + pub prompt_cache_hints: PromptCacheHints, + #[serde(default)] + pub cache_metrics: PromptBuildCacheMetrics, + #[serde(default)] + pub metadata: Value, +} + +#[async_trait] +pub trait PromptProvider: Send + Sync { + async fn build_prompt(&self, request: PromptBuildRequest) -> Result; +} + +impl PromptBuildOutput { + pub fn empty() -> Self { + Self { + system_prompt: String::new(), + system_prompt_blocks: Vec::new(), + prompt_cache_hints: PromptCacheHints { + global_cache_strategy: PromptCacheGlobalStrategy::SystemPrompt, + ..PromptCacheHints::default() + }, + cache_metrics: PromptBuildCacheMetrics::default(), + metadata: Value::Null, + } + } +} + +#[cfg(test)] +mod tests { + use super::{ProjectionRegistrySnapshot, RecoveredSessionState}; + + #[test] + fn projection_registry_empty_checks_all_owned_indexes() { + let snapshot = ProjectionRegistrySnapshot::default(); + + assert!(snapshot.is_empty()); + } + + #[test] + fn recovered_session_state_defaults_to_tail_replay_only() { + let recovered = RecoveredSessionState::default(); + + assert!(recovered.checkpoint.is_none()); + assert!(recovered.tail_events.is_empty()); + } +} diff --git a/crates/core/src/projection/agent_state.rs b/crates/host-session/src/projection.rs similarity index 95% rename from crates/core/src/projection/agent_state.rs rename to crates/host-session/src/projection.rs index a8bb99ed..da7d779e 100644 --- a/crates/core/src/projection/agent_state.rs +++ b/crates/host-session/src/projection.rs @@ -19,15 +19,14 @@ use std::path::PathBuf; -use chrono::{DateTime, Utc}; -use serde::{Deserialize, Serialize}; - -use crate::{ +use astrcode_core::{ InvocationKind, LlmMessage, ModeId, Phase, ReasoningContent, ToolCallRequest, - UserMessageOrigin, + ToolExecutionResult, UserMessageOrigin, event::{StorageEvent, StorageEventPayload}, format_compact_summary, split_assistant_content, }; +use chrono::{DateTime, Utc}; +use serde::{Deserialize, Serialize}; /// Agent 的当前状态快照。 /// @@ -189,7 +188,7 @@ impl AgentStateProjector { .. } => { self.flush_pending_assistant(); - let result = crate::ToolExecutionResult { + let result = ToolExecutionResult { tool_call_id: tool_call_id.clone(), tool_name: tool_name.clone(), ok: *success, @@ -372,13 +371,13 @@ pub fn project(events: &[StorageEvent]) -> AgentState { #[cfg(test)] mod tests { + use astrcode_core::{ + AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, PersistedToolOutput, + StorageEvent, StorageEventPayload, SubRunStorageMode, TurnTerminalKind, + }; use serde_json::json; use super::*; - use crate::{ - AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, StorageEvent, - StorageEventPayload, SubRunStorageMode, - }; fn ts() -> chrono::DateTime { chrono::Utc::now() @@ -515,7 +514,7 @@ mod tests { agent, StorageEventPayload::ToolResultReferenceApplied { tool_call_id: tool_call_id.into(), - persisted_output: crate::PersistedToolOutput { + persisted_output: PersistedToolOutput { storage_kind: "toolResult".to_string(), absolute_path: "~/.astrcode/tool-results/sample.txt".to_string(), relative_path: "tool-results/sample.txt".to_string(), @@ -551,7 +550,7 @@ mod tests { fn turn_done( turn_id: Option<&str>, agent: AgentEventContext, - terminal_kind: crate::TurnTerminalKind, + terminal_kind: TurnTerminalKind, ) -> StorageEvent { event( turn_id, @@ -715,7 +714,7 @@ mod tests { session_start("s1", "/tmp"), user_message(None, root_agent(), "hi", UserMessageOrigin::User), assistant_final(None, root_agent(), "hello!", None), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let state = project(&events); assert_eq!(state.phase, Phase::Idle); @@ -734,11 +733,7 @@ mod tests { UserMessageOrigin::User, ), assistant_final(Some("turn-root"), root_agent(), "root answer", None), - turn_done( - Some("turn-root"), - root_agent(), - crate::TurnTerminalKind::Completed, - ), + turn_done(Some("turn-root"), root_agent(), TurnTerminalKind::Completed), user_message( Some("turn-child"), child_agent("session-child"), @@ -754,7 +749,7 @@ mod tests { turn_done( Some("turn-child"), child_agent("session-child"), - crate::TurnTerminalKind::Completed, + TurnTerminalKind::Completed, ), ]; @@ -791,11 +786,7 @@ mod tests { "child answer", None, ), - turn_done( - Some("turn-child"), - child_agent, - crate::TurnTerminalKind::Completed, - ), + turn_done(Some("turn-child"), child_agent, TurnTerminalKind::Completed), ]; let state = project(&events); @@ -823,11 +814,11 @@ mod tests { 10, ), assistant_final(None, root_agent(), "Here are the files", None), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), // Turn 2: simple user → assistant user_message(None, root_agent(), "thanks", UserMessageOrigin::User), assistant_final(None, root_agent(), "You're welcome!", None), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let state = project(&events); @@ -892,7 +883,7 @@ mod tests { timestamp: Some(ts()), }, ), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let state = project(&events); assert_eq!(state.messages.len(), 2); // User + Assistant only @@ -906,7 +897,7 @@ mod tests { user_message(None, root_agent(), "run tool", UserMessageOrigin::User), tool_call(None, root_agent(), "tc1", "listDir", json!({"path": "."})), tool_result(None, root_agent(), "tc1", "listDir", "[]", 2), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let state = project(&events); @@ -954,7 +945,7 @@ mod tests { section.\nSuggested first read: { path: \"~/.astrcode/tool-results/sample.txt\", \ charOffset: 0, maxChars: 20000 }\n", ), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let state = project(&events); @@ -981,7 +972,7 @@ mod tests { timestamp: None, }, ), - turn_done(None, root_agent(), crate::TurnTerminalKind::Completed), + turn_done(None, root_agent(), TurnTerminalKind::Completed), ]; let batch = project(&events); @@ -1009,11 +1000,7 @@ mod tests { UserMessageOrigin::User, ), assistant_final(Some("turn-1"), root_agent(), "first-answer", None), - turn_done( - Some("turn-1"), - root_agent(), - crate::TurnTerminalKind::Completed, - ), + turn_done(Some("turn-1"), root_agent(), TurnTerminalKind::Completed), user_message( Some("turn-2"), root_agent(), @@ -1021,11 +1008,7 @@ mod tests { UserMessageOrigin::User, ), assistant_final(Some("turn-2"), root_agent(), "second-answer", None), - turn_done( - Some("turn-2"), - root_agent(), - crate::TurnTerminalKind::Completed, - ), + turn_done(Some("turn-2"), root_agent(), TurnTerminalKind::Completed), compact_applied("condensed work", 1, 2), ]; diff --git a/crates/session-runtime/src/state/projection_registry.rs b/crates/host-session/src/projection_registry.rs similarity index 93% rename from crates/session-runtime/src/state/projection_registry.rs rename to crates/host-session/src/projection_registry.rs index 499f69c7..474b7660 100644 --- a/crates/session-runtime/src/state/projection_registry.rs +++ b/crates/host-session/src/projection_registry.rs @@ -1,19 +1,20 @@ use std::collections::{HashMap, VecDeque}; use astrcode_core::{ - AgentState, AgentStateProjector, ChildSessionNode, InputQueueProjection, ModeId, Phase, - ProjectionRegistrySnapshot, Result, SessionEventRecord, StorageEventPayload, StoredEvent, - TaskSnapshot, TurnProjectionSnapshot, event::PhaseTracker, + ChildSessionNode, ModeId, Phase, Result, SessionEventRecord, StorageEventPayload, StoredEvent, + TaskSnapshot, event::PhaseTracker, }; use chrono::{DateTime, Utc}; -use super::{ - cache::{RecentSessionEvents, RecentStoredEvents}, +use crate::{ + AgentState, AgentStateProjector, InputQueueProjection, ProjectionRegistrySnapshot, + TurnProjectionSnapshot, child_sessions::{child_node_from_stored_event, rebuild_child_nodes}, + event_cache::{RecentSessionEvents, RecentStoredEvents}, input_queue::{apply_input_queue_event_to_index, replay_input_queue_projection_index}, tasks::{apply_snapshot_to_map, rebuild_active_tasks, task_snapshot_from_stored_event}, + turn_projection::{apply_turn_projection_event, project_turn_projection}, }; -use crate::turn::projector::{apply_turn_projection_event, project_turn_projection}; #[derive(Debug, Clone, Default)] struct TurnProjection { @@ -53,7 +54,7 @@ impl ModeProjectionState { } #[derive(Debug, Clone, Default)] -pub(super) struct ChildNodeProjection { +pub(crate) struct ChildNodeProjection { nodes: HashMap, } @@ -74,7 +75,7 @@ impl ChildNodeProjection { } } - pub(super) fn upsert(&mut self, node: ChildSessionNode) { + pub(crate) fn upsert(&mut self, node: ChildSessionNode) { self.nodes.insert(node.sub_run_id().to_string(), node); } @@ -144,11 +145,6 @@ impl ActiveTaskProjection { } } - #[cfg(test)] - fn replace(&mut self, snapshot: TaskSnapshot) { - apply_snapshot_to_map(&mut self.snapshots, snapshot); - } - fn get(&self, owner: &str) -> Option { self.snapshots.get(owner).cloned() } @@ -263,7 +259,7 @@ pub(crate) struct ProjectionRegistry { phase_tracker: PhaseTracker, agent_projection: AgentStateProjector, mode: ModeProjectionState, - pub(super) children: ChildNodeProjection, + pub(crate) children: ChildNodeProjection, tasks: ActiveTaskProjection, input_queue: InputQueueProjectionIndex, turns: TurnProjectionIndex, @@ -399,11 +395,6 @@ impl ProjectionRegistry { self.children.subtree(root_agent_id) } - #[cfg(test)] - pub(crate) fn replace_active_task_snapshot(&mut self, snapshot: TaskSnapshot) { - self.tasks.replace(snapshot); - } - pub(crate) fn active_tasks_for(&self, owner: &str) -> Option { self.tasks.get(owner) } diff --git a/crates/host-session/src/query.rs b/crates/host-session/src/query.rs new file mode 100644 index 00000000..8dd7f2b6 --- /dev/null +++ b/crates/host-session/src/query.rs @@ -0,0 +1,532 @@ +use std::sync::Arc; + +use astrcode_core::{ + AgentEvent, ChildSessionNode, CompactAppliedMeta, CompactTrigger, ModeId, Phase, Result, + SessionEventRecord, SessionId, StoredEvent, TaskSnapshot, TurnTerminalKind, +}; +use chrono::{DateTime, Utc}; +use tokio::sync::broadcast::error::RecvError; + +use crate::{ + InputQueueProjection, SessionCatalog, SessionSnapshot, SessionState, TurnProjectionSnapshot, + turn_projection::project_turn_projection, +}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SessionObserveSnapshot { + pub state: SessionSnapshot, +} + +#[derive(Debug, Clone)] +pub struct SessionReadModelReplay { + pub cursor: Option, + pub seed_records: Vec, + pub history: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct LastCompactMetaSnapshot { + pub trigger: CompactTrigger, + pub meta: CompactAppliedMeta, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SessionControlStateSnapshot { + pub phase: Phase, + pub active_turn_id: Option, + pub manual_compact_pending: bool, + pub compacting: bool, + pub last_compact_meta: Option, + pub current_mode_id: ModeId, + pub last_mode_changed_at: Option>, +} + +#[derive(Debug, Clone)] +pub struct TurnTerminalSnapshot { + pub phase: Phase, + pub projection: Option, + pub events: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ProjectedTurnOutcome { + Completed { + summary: String, + }, + Cancelled { + summary: String, + }, + Failed { + summary: String, + technical_message: String, + }, +} + +impl SessionCatalog { + pub async fn session_state(&self, session_id: &SessionId) -> Result> { + Ok(Arc::clone( + &self.ensure_loaded_session(session_id).await?.state, + )) + } + + pub async fn observe_session(&self, session_id: &SessionId) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let projected = loaded.state.snapshot_projected_state()?; + let latest_turn_id = loaded + .state + .snapshot_recent_stored_events()? + .into_iter() + .rev() + .find_map(|stored| stored.event.turn_id); + Ok(SessionObserveSnapshot { + state: SessionSnapshot { + session_id: loaded.session_id.clone(), + working_dir: loaded.working_dir.display().to_string(), + latest_turn_id: latest_turn_id.map(Into::into), + turn_count: projected.turn_count, + }, + }) + } + + pub async fn session_child_nodes( + &self, + session_id: &SessionId, + ) -> Result> { + self.ensure_loaded_session(session_id) + .await? + .state + .list_child_session_nodes() + } + + pub async fn active_task_snapshot( + &self, + session_id: &SessionId, + owner: &str, + ) -> Result> { + self.ensure_loaded_session(session_id) + .await? + .state + .active_tasks_for(owner) + } + + pub async fn session_control_state( + &self, + session_id: &SessionId, + ) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let last_compact_meta = loaded + .state + .snapshot_recent_stored_events()? + .into_iter() + .rev() + .find_map(|stored| match stored.event.payload { + astrcode_core::StorageEventPayload::CompactApplied { trigger, meta, .. } => { + Some(LastCompactMetaSnapshot { trigger, meta }) + }, + _ => None, + }); + let (active_turn_id, manual_compact_pending) = + if let Some(state) = self.turn_mutations.get(session_id) { + ( + state + .active_turn_id_snapshot()? + .map(|turn_id| turn_id.to_string()), + state.has_pending_manual_compact()?, + ) + } else { + (None, false) + }; + + Ok(SessionControlStateSnapshot { + phase: loaded.state.current_phase()?, + active_turn_id, + manual_compact_pending, + compacting: false, + last_compact_meta, + current_mode_id: loaded.state.current_mode_id()?, + last_mode_changed_at: loaded.state.last_mode_changed_at()?, + }) + } + + pub async fn input_queue_projection_for_agent( + &self, + session_id: &SessionId, + agent_id: &str, + ) -> Result { + self.ensure_loaded_session(session_id) + .await? + .state + .input_queue_projection_for_agent(agent_id) + } + + pub async fn pending_delivery_ids_for_agent( + &self, + session_id: &SessionId, + agent_id: &str, + ) -> Result> { + Ok(self + .input_queue_projection_for_agent(session_id, agent_id) + .await? + .pending_delivery_ids + .into_iter() + .map(Into::into) + .collect()) + } + + pub async fn stored_events(&self, session_id: &SessionId) -> Result> { + self.ensure_session_exists(session_id).await?; + self.event_store.replay(session_id).await + } + + pub async fn conversation_stream_replay( + &self, + session_id: &SessionId, + last_event_id: Option<&str>, + ) -> Result { + self.ensure_session_exists(session_id).await?; + let full = astrcode_core::replay_records(&self.event_store.replay(session_id).await?, None); + let (seed_records, history) = split_records_at_cursor(full, last_event_id); + Ok(SessionReadModelReplay { + cursor: history.last().map(|record| record.event_id.clone()), + seed_records, + history, + }) + } + + pub async fn try_turn_terminal_snapshot( + &self, + session_id: &SessionId, + turn_id: &str, + allow_durable_fallback: bool, + ) -> Result> { + let loaded = self.ensure_loaded_session(session_id).await?; + if let Some(snapshot) = try_turn_terminal_snapshot_from_recent(&loaded.state, turn_id)? { + return Ok(Some(snapshot)); + } + + if !allow_durable_fallback { + return Ok(None); + } + + let events = turn_events(self.event_store.replay(session_id).await?, turn_id); + let phase = loaded.state.current_phase()?; + let projection = loaded + .state + .turn_projection(turn_id)? + .or_else(|| project_turn_projection(&events)); + if turn_snapshot_is_terminal(phase, projection.as_ref(), &events) { + return Ok(Some(TurnTerminalSnapshot { + phase, + projection, + events, + })); + } + + Ok(None) + } + + pub async fn wait_for_turn_terminal_snapshot( + &self, + session_id: &SessionId, + turn_id: &str, + ) -> Result { + let loaded = self.ensure_loaded_session(session_id).await?; + let mut receiver = loaded.state.broadcaster.subscribe(); + if let Some(snapshot) = self + .try_turn_terminal_snapshot(session_id, turn_id, true) + .await? + { + return Ok(snapshot); + } + loop { + match receiver.recv().await { + Ok(record) => { + if !record_targets_turn(&record, turn_id) { + continue; + } + if let Some(snapshot) = + try_turn_terminal_snapshot_from_recent(&loaded.state, turn_id)? + { + return Ok(snapshot); + } + }, + Err(RecvError::Lagged(_)) => { + if let Some(snapshot) = self + .try_turn_terminal_snapshot(session_id, turn_id, true) + .await? + { + return Ok(snapshot); + } + }, + Err(RecvError::Closed) => { + if let Some(snapshot) = self + .try_turn_terminal_snapshot(session_id, turn_id, true) + .await? + { + return Ok(snapshot); + } + return Err(astrcode_core::AstrError::Internal(format!( + "session '{}' broadcaster closed before turn '{}' reached a terminal \ + snapshot", + session_id, turn_id + ))); + }, + } + } + } + + pub async fn project_turn_outcome( + &self, + session_id: &SessionId, + turn_id: &str, + ) -> Result { + let terminal = self + .wait_for_turn_terminal_snapshot(session_id, turn_id) + .await?; + Ok(project_turn_outcome( + terminal.phase, + terminal.projection.as_ref(), + &terminal.events, + )) + } +} + +pub fn try_turn_terminal_snapshot_from_recent( + state: &SessionState, + turn_id: &str, +) -> Result> { + let events = turn_events(state.snapshot_recent_stored_events()?, turn_id); + let phase = state.current_phase()?; + let projection = state + .turn_projection(turn_id)? + .or_else(|| project_turn_projection(&events)); + if turn_snapshot_is_terminal(phase, projection.as_ref(), &events) { + return Ok(Some(TurnTerminalSnapshot { + phase, + projection, + events, + })); + } + + Ok(None) +} + +fn split_records_at_cursor( + mut records: Vec, + last_event_id: Option<&str>, +) -> (Vec, Vec) { + let Some(last_event_id) = last_event_id else { + return (Vec::new(), records); + }; + let Some(index) = records + .iter() + .position(|record| record.event_id == last_event_id) + else { + return (Vec::new(), records); + }; + let history = records.split_off(index + 1); + (records, history) +} + +fn turn_events(stored_events: Vec, turn_id: &str) -> Vec { + stored_events + .into_iter() + .filter(|stored| stored.event.turn_id() == Some(turn_id)) + .collect() +} + +fn turn_snapshot_is_terminal( + phase: Phase, + projection: Option<&TurnProjectionSnapshot>, + events: &[StoredEvent], +) -> bool { + has_terminal_projection(projection) + || (!events.is_empty() && matches!(phase, Phase::Interrupted)) +} + +fn has_terminal_projection(projection: Option<&TurnProjectionSnapshot>) -> bool { + projection.is_some_and(|projection| { + projection.terminal_kind.is_some() || projection.last_error.is_some() + }) +} + +fn project_turn_outcome( + phase: Phase, + projection: Option<&TurnProjectionSnapshot>, + events: &[StoredEvent], +) -> ProjectedTurnOutcome { + let replayed_projection = project_turn_projection(events); + let projection = projection.or(replayed_projection.as_ref()); + let last_assistant = last_non_empty_assistant_event(events); + let last_error = last_non_empty_error_event(events); + let terminal_kind = resolve_terminal_kind(phase, projection, last_error.as_deref()); + + match terminal_kind.as_ref() { + Some(TurnTerminalKind::Cancelled) => ProjectedTurnOutcome::Cancelled { + summary: last_error.unwrap_or_else(|| "child agent cancelled".to_string()), + }, + Some(TurnTerminalKind::Error { message }) => ProjectedTurnOutcome::Failed { + summary: last_error + .clone() + .or(last_assistant) + .unwrap_or_else(|| "child agent failed without readable output".to_string()), + technical_message: last_error.unwrap_or_else(|| message.clone()), + }, + Some(TurnTerminalKind::Completed) | None => ProjectedTurnOutcome::Completed { + summary: last_assistant + .unwrap_or_else(|| "child agent completed without readable output".to_string()), + }, + } +} + +fn resolve_terminal_kind( + phase: Phase, + projection: Option<&TurnProjectionSnapshot>, + last_error: Option<&str>, +) -> Option { + if let Some(turn_done_kind) = projection.and_then(|projection| projection.terminal_kind.clone()) + { + return Some(turn_done_kind); + } + if matches!(phase, Phase::Interrupted) { + return Some(TurnTerminalKind::Cancelled); + } + projection + .and_then(|projection| projection.last_error.as_deref()) + .or(last_error) + .map(str::trim) + .filter(|message| !message.is_empty()) + .map(|message| TurnTerminalKind::Error { + message: message.to_string(), + }) +} + +fn last_non_empty_assistant_event(events: &[StoredEvent]) -> Option { + events + .iter() + .rev() + .find_map(|stored| match &stored.event.payload { + astrcode_core::StorageEventPayload::AssistantFinal { content, .. } + if !content.trim().is_empty() => + { + Some(content.trim().to_string()) + }, + _ => None, + }) +} + +fn last_non_empty_error_event(events: &[StoredEvent]) -> Option { + events + .iter() + .rev() + .find_map(|stored| match &stored.event.payload { + astrcode_core::StorageEventPayload::Error { message, .. } + if !message.trim().is_empty() => + { + Some(message.trim().to_string()) + }, + _ => None, + }) +} + +fn record_targets_turn(record: &SessionEventRecord, turn_id: &str) -> bool { + match &record.event { + AgentEvent::UserMessage { turn_id: id, .. } + | AgentEvent::ModelDelta { turn_id: id, .. } + | AgentEvent::ThinkingDelta { turn_id: id, .. } + | AgentEvent::StreamRetryStarted { turn_id: id, .. } + | AgentEvent::AssistantMessage { turn_id: id, .. } + | AgentEvent::ToolCallStart { turn_id: id, .. } + | AgentEvent::ToolCallDelta { turn_id: id, .. } + | AgentEvent::ToolCallResult { turn_id: id, .. } + | AgentEvent::TurnDone { turn_id: id, .. } => id == turn_id, + AgentEvent::PhaseChanged { + turn_id: Some(id), .. + } + | AgentEvent::PromptMetrics { + turn_id: Some(id), .. + } + | AgentEvent::CompactApplied { + turn_id: Some(id), .. + } + | AgentEvent::SubRunStarted { + turn_id: Some(id), .. + } + | AgentEvent::SubRunFinished { + turn_id: Some(id), .. + } + | AgentEvent::ChildSessionNotification { + turn_id: Some(id), .. + } + | AgentEvent::AgentInputQueued { + turn_id: Some(id), .. + } + | AgentEvent::AgentInputBatchStarted { + turn_id: Some(id), .. + } + | AgentEvent::AgentInputBatchAcked { + turn_id: Some(id), .. + } + | AgentEvent::AgentInputDiscarded { + turn_id: Some(id), .. + } + | AgentEvent::Error { + turn_id: Some(id), .. + } => id == turn_id, + _ => false, + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{ + AgentEventContext, Phase, StorageEvent, StorageEventPayload, StoredEvent, TurnTerminalKind, + }; + + use super::{ProjectedTurnOutcome, project_turn_outcome, turn_snapshot_is_terminal}; + use crate::TurnProjectionSnapshot; + + #[test] + fn turn_snapshot_is_terminal_accepts_projection_terminal_kind() { + assert!(turn_snapshot_is_terminal( + Phase::Idle, + Some(&TurnProjectionSnapshot { + terminal_kind: Some(TurnTerminalKind::Completed), + last_error: None, + }), + &[] + )); + } + + #[test] + fn project_turn_outcome_prefers_assistant_summary_on_success() { + let outcome = project_turn_outcome( + Phase::Idle, + Some(&TurnProjectionSnapshot { + terminal_kind: Some(TurnTerminalKind::Completed), + last_error: None, + }), + &[StoredEvent { + storage_seq: 1, + event: StorageEvent { + turn_id: Some("turn-1".to_string()), + agent: AgentEventContext::default(), + payload: StorageEventPayload::AssistantFinal { + content: "done".to_string(), + reasoning_content: None, + reasoning_signature: None, + step_index: None, + timestamp: Some(chrono::Utc::now()), + }, + }, + }], + ); + + assert_eq!( + outcome, + ProjectedTurnOutcome::Completed { + summary: "done".to_string() + } + ); + } +} diff --git a/crates/core/src/session_catalog.rs b/crates/host-session/src/session_catalog.rs similarity index 100% rename from crates/core/src/session_catalog.rs rename to crates/host-session/src/session_catalog.rs diff --git a/crates/core/src/session_plan.rs b/crates/host-session/src/session_plan.rs similarity index 95% rename from crates/core/src/session_plan.rs rename to crates/host-session/src/session_plan.rs index f981c74d..45cf6004 100644 --- a/crates/core/src/session_plan.rs +++ b/crates/host-session/src/session_plan.rs @@ -1,6 +1,6 @@ //! session plan 领域模型。 //! -//! application 与 adapter-tools 需要读写同一份 `state.json`，状态结构和内容摘要算法 +//! host-session 与 adapter-tools 需要读写同一份 `state.json`，状态结构和内容摘要算法 //! 必须保持单一真相，避免跨 crate 漂移。 use std::fmt; diff --git a/crates/host-session/src/state.rs b/crates/host-session/src/state.rs new file mode 100644 index 00000000..d0862eb4 --- /dev/null +++ b/crates/host-session/src/state.rs @@ -0,0 +1,492 @@ +use std::sync::{Arc, Mutex as StdMutex}; + +use astrcode_core::{ + AgentEvent, ChildSessionNode, EventTranslator, LlmMessage, ModeId, Phase, Result, + SessionEventRecord, StoredEvent, TaskSnapshot, normalize_recovered_phase, + support::{self}, +}; +use chrono::Utc; +use tokio::sync::broadcast; + +use crate::{ + AgentState, AgentStateProjector, EventStore, InputQueueProjection, SessionRecoveryCheckpoint, + TurnProjectionSnapshot, event_log::SessionWriter, projection_registry::ProjectionRegistry, +}; + +pub const SESSION_BROADCAST_CAPACITY: usize = 2048; +pub const SESSION_LIVE_BROADCAST_CAPACITY: usize = 2048; + +pub struct SessionState { + pub(crate) projection_registry: StdMutex, + pub broadcaster: broadcast::Sender, + live_broadcaster: broadcast::Sender, + pub writer: Arc, +} + +impl std::fmt::Debug for SessionState { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("SessionState").finish_non_exhaustive() + } +} + +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SessionSnapshot { + pub session_id: astrcode_core::SessionId, + pub working_dir: String, + pub latest_turn_id: Option, + pub turn_count: usize, +} + +impl SessionState { + pub fn new( + phase: Phase, + writer: Arc, + projector: AgentStateProjector, + recent_records: Vec, + recent_stored: Vec, + ) -> Self { + Self::from_parts(phase, writer, projector, recent_records, recent_stored) + } + + pub fn from_recovery( + writer: Arc, + checkpoint: &SessionRecoveryCheckpoint, + tail_events: Vec, + ) -> Result { + let phase = normalize_recovered_phase(checkpoint.agent_state.phase); + let mut projection_registry = ProjectionRegistry::from_recovery( + phase, + &checkpoint.agent_state, + checkpoint.projection_registry_snapshot(), + Vec::new(), + Vec::new(), + ); + for stored in &tail_events { + stored.event.validate().map_err(|error| { + astrcode_core::AstrError::Validation(format!( + "session '{}' contains invalid stored event at storage_seq {}: {}", + checkpoint.agent_state.session_id, stored.storage_seq, error + )) + })?; + projection_registry.apply(stored)?; + } + projection_registry.cache_records(&astrcode_core::replay_records(&tail_events, None)); + let (broadcaster, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); + let (live_broadcaster, _) = broadcast::channel(SESSION_LIVE_BROADCAST_CAPACITY); + + Ok(Self { + projection_registry: StdMutex::new(projection_registry), + broadcaster, + live_broadcaster, + writer, + }) + } + + fn from_parts( + phase: Phase, + writer: Arc, + projector: AgentStateProjector, + recent_records: Vec, + recent_stored: Vec, + ) -> Self { + let (broadcaster, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); + let (live_broadcaster, _) = broadcast::channel(SESSION_LIVE_BROADCAST_CAPACITY); + Self { + projection_registry: StdMutex::new(ProjectionRegistry::new( + phase, + projector, + recent_records, + recent_stored, + )), + broadcaster, + live_broadcaster, + writer, + } + } + + pub fn recovery_checkpoint( + &self, + checkpoint_storage_seq: u64, + ) -> Result { + let projection_registry = + support::lock_anyhow(&self.projection_registry, "session projection registry")?; + Ok(SessionRecoveryCheckpoint::new( + projection_registry.snapshot_projected_state(), + projection_registry.projection_snapshot(), + checkpoint_storage_seq, + )) + } + + pub fn snapshot_projected_state(&self) -> Result { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .snapshot_projected_state(), + ) + } + + pub fn current_turn_messages(&self) -> Result> { + Ok(self.snapshot_projected_state()?.messages) + } + + pub fn subscribe_live(&self) -> broadcast::Receiver { + self.live_broadcaster.subscribe() + } + + pub fn broadcast_live_event(&self, event: AgentEvent) { + let _ = self.live_broadcaster.send(event); + } + + pub fn current_phase(&self) -> Result { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .current_phase(), + ) + } + + pub fn current_mode_id(&self) -> Result { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .current_mode_id(), + ) + } + + pub fn last_mode_changed_at(&self) -> Result>> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .last_mode_changed_at(), + ) + } + + pub fn translate_store_and_cache( + &self, + stored: &StoredEvent, + translator: &mut EventTranslator, + ) -> Result> { + stored.event.validate()?; + let mut projection_registry = + support::lock_anyhow(&self.projection_registry, "session projection registry")?; + projection_registry.apply(stored)?; + let records = translator.translate(stored); + projection_registry.cache_records(&records); + Ok(records) + } + + pub fn recent_records_after( + &self, + last_event_id: Option<&str>, + ) -> Result>> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .recent_records_after(last_event_id), + ) + } + + pub fn snapshot_recent_stored_events(&self) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .snapshot_recent_stored_events(), + ) + } + + pub fn turn_projection(&self, turn_id: &str) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .turn_projection(turn_id), + ) + } + + pub fn upsert_child_session_node(&self, node: ChildSessionNode) -> Result<()> { + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .children + .upsert(node); + Ok(()) + } + + pub fn child_session_node(&self, sub_run_id: &str) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .child_session_node(sub_run_id), + ) + } + + pub fn list_child_session_nodes(&self) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .list_child_session_nodes(), + ) + } + + pub fn child_nodes_for_parent(&self, parent_agent_id: &str) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .child_nodes_for_parent(parent_agent_id), + ) + } + + pub fn subtree_nodes(&self, root_agent_id: &str) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .subtree_nodes(root_agent_id), + ) + } + + pub fn active_tasks_for(&self, owner: &str) -> Result> { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .active_tasks_for(owner), + ) + } + + pub fn input_queue_projection_for_agent(&self, agent_id: &str) -> Result { + Ok( + support::lock_anyhow(&self.projection_registry, "session projection registry")? + .input_queue_projection_for_agent(agent_id), + ) + } + + pub async fn append_and_broadcast( + &self, + event: &astrcode_core::StorageEvent, + translator: &mut EventTranslator, + ) -> Result { + let stored = self.writer.clone().append(event.clone()).await?; + let records = self.translate_store_and_cache(&stored, translator)?; + for record in records { + let _ = self.broadcaster.send(record); + } + Ok(stored) + } +} + +pub async fn append_and_broadcast( + session: &SessionState, + event: &astrcode_core::StorageEvent, + translator: &mut EventTranslator, +) -> Result { + session.append_and_broadcast(event, translator).await +} + +pub async fn checkpoint_if_compacted( + event_store: &Arc, + session_id: &astrcode_core::SessionId, + session_state: &Arc, + persisted_events: &[StoredEvent], +) { + let Some(checkpoint_storage_seq) = persisted_events.last().map(|stored| stored.storage_seq) + else { + return; + }; + if !persisted_events.iter().any(|stored| { + matches!( + stored.event.payload, + astrcode_core::StorageEventPayload::CompactApplied { .. } + ) + }) { + return; + } + let checkpoint = match session_state.recovery_checkpoint(checkpoint_storage_seq) { + Ok(checkpoint) => checkpoint, + Err(error) => { + log::warn!( + "failed to build recovery checkpoint for session '{}': {}", + session_id, + error + ); + return; + }, + }; + if let Err(error) = event_store + .checkpoint_session(session_id, &checkpoint) + .await + { + log::warn!( + "failed to persist recovery checkpoint for session '{}': {}", + session_id, + error + ); + } +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use astrcode_core::{ + AgentEventContext, AgentLifecycleStatus, ChildSessionLineageKind, ChildSessionNotification, + ChildSessionNotificationKind, ChildSessionStatusSource, EventLogWriter, EventTranslator, + InputQueuedPayload, Phase, QueuedInputEnvelope, StorageEvent, StorageEventPayload, + StoreResult, StoredEvent, SubRunStorageMode, UserMessageOrigin, + }; + + use super::{SessionState, SessionWriter}; + use crate::{AgentStateProjector, SubRunHandle}; + + #[derive(Default)] + struct NoopEventLogWriter { + next_seq: u64, + } + + impl EventLogWriter for NoopEventLogWriter { + fn append(&mut self, event: &StorageEvent) -> StoreResult { + self.next_seq += 1; + Ok(StoredEvent { + storage_seq: self.next_seq, + event: event.clone(), + }) + } + } + + fn session_state() -> SessionState { + SessionState::new( + Phase::Idle, + Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter::default()))), + AgentStateProjector::default(), + Vec::new(), + Vec::new(), + ) + } + + fn user_message(content: &str) -> StorageEvent { + StorageEvent { + turn_id: Some("turn-1".to_string()), + agent: AgentEventContext::default(), + payload: StorageEventPayload::UserMessage { + content: content.to_string(), + origin: UserMessageOrigin::User, + timestamp: chrono::Utc::now(), + }, + } + } + + #[tokio::test] + async fn append_and_broadcast_persists_projects_caches_and_broadcasts() { + let session = session_state(); + let mut receiver = session.broadcaster.subscribe(); + let mut translator = EventTranslator::new(Phase::Idle); + + let stored = session + .append_and_broadcast(&user_message("hello"), &mut translator) + .await + .expect("event should append"); + + assert_eq!(stored.storage_seq, 1); + assert_eq!(session.snapshot_recent_stored_events().unwrap().len(), 1); + assert!( + !session + .recent_records_after(None) + .unwrap() + .unwrap() + .is_empty() + ); + assert_eq!(session.current_turn_messages().unwrap().len(), 1); + assert!(receiver.try_recv().is_ok()); + } + + #[test] + fn from_recovery_replays_tail_events_into_projection() { + let checkpoint = crate::SessionRecoveryCheckpoint::new( + crate::AgentState::default(), + crate::ProjectionRegistrySnapshot::default(), + 0, + ); + let stored = StoredEvent { + storage_seq: 1, + event: user_message("replayed"), + }; + + let recovered = SessionState::from_recovery( + Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter::default()))), + &checkpoint, + vec![stored], + ) + .expect("recovery should replay tail events"); + + assert_eq!(recovered.current_turn_messages().unwrap().len(), 1); + assert_eq!(recovered.snapshot_recent_stored_events().unwrap().len(), 1); + } + + #[test] + fn from_recovery_restores_child_session_nodes_and_input_queue_projection() { + let checkpoint = crate::SessionRecoveryCheckpoint::new( + crate::AgentState::default(), + crate::ProjectionRegistrySnapshot::default(), + 0, + ); + let handle = SubRunHandle { + sub_run_id: "subrun-1".into(), + agent_id: "agent-child".into(), + session_id: "session-parent".into(), + child_session_id: Some("session-child".into()), + depth: 1, + parent_turn_id: "turn-parent".into(), + parent_agent_id: Some("agent-parent".into()), + parent_sub_run_id: None, + lineage_kind: ChildSessionLineageKind::Spawn, + agent_profile: "coding".to_string(), + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: AgentLifecycleStatus::Running, + last_turn_outcome: None, + resolved_limits: Default::default(), + delegation: None, + }; + let notification = ChildSessionNotification { + notification_id: "delivery-child".into(), + child_ref: handle.child_ref_with_status(AgentLifecycleStatus::Running), + kind: ChildSessionNotificationKind::Started, + source_tool_call_id: Some("call-1".into()), + delivery: None, + }; + let recovered = SessionState::from_recovery( + Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter::default()))), + &checkpoint, + vec![ + StoredEvent { + storage_seq: 1, + event: StorageEvent { + turn_id: Some("turn-parent".into()), + agent: AgentEventContext::default(), + payload: StorageEventPayload::ChildSessionNotification { + notification, + timestamp: Some(chrono::Utc::now()), + }, + }, + }, + StoredEvent { + storage_seq: 2, + event: StorageEvent { + turn_id: Some("turn-parent".into()), + agent: AgentEventContext::default(), + payload: StorageEventPayload::AgentInputQueued { + payload: InputQueuedPayload { + envelope: QueuedInputEnvelope { + delivery_id: "delivery-1".into(), + from_agent_id: "agent-parent".into(), + to_agent_id: "agent-child".into(), + message: "resume work".into(), + queued_at: chrono::Utc::now(), + sender_lifecycle_status: AgentLifecycleStatus::Running, + sender_last_turn_outcome: None, + sender_open_session_id: "session-parent".into(), + }, + }, + }, + }, + }, + ], + ) + .expect("recovery should rebuild collaboration projections"); + + let node = recovered + .child_session_node("subrun-1") + .expect("projection access should succeed") + .expect("child session node should be restored"); + assert_eq!(node.child_session_id.as_str(), "session-child"); + assert_eq!(node.status_source, ChildSessionStatusSource::Durable); + + let queue = recovered + .input_queue_projection_for_agent("agent-child") + .expect("input queue projection should rebuild"); + assert_eq!(queue.pending_delivery_ids, vec!["delivery-1".into()]); + } +} diff --git a/crates/host-session/src/tasks.rs b/crates/host-session/src/tasks.rs new file mode 100644 index 00000000..309ec3d6 --- /dev/null +++ b/crates/host-session/src/tasks.rs @@ -0,0 +1,49 @@ +use std::collections::HashMap; + +use astrcode_core::{ + EXECUTION_TASK_SNAPSHOT_SCHEMA, ExecutionTaskSnapshotMetadata, StorageEventPayload, + StoredEvent, TaskSnapshot, +}; + +pub(crate) fn rebuild_active_tasks(events: &[StoredEvent]) -> HashMap { + let mut tasks = HashMap::new(); + for stored in events { + if let Some(snapshot) = task_snapshot_from_stored_event(stored) { + apply_snapshot_to_map(&mut tasks, snapshot); + } + } + tasks +} + +pub(crate) fn task_snapshot_from_stored_event(stored: &StoredEvent) -> Option { + let StorageEventPayload::ToolResult { + tool_name, + metadata: Some(metadata), + .. + } = &stored.event.payload + else { + return None; + }; + + if tool_name != "taskWrite" { + return None; + } + + let parsed = serde_json::from_value::(metadata.clone()).ok()?; + if parsed.schema != EXECUTION_TASK_SNAPSHOT_SCHEMA { + return None; + } + + Some(parsed.into_snapshot()) +} + +pub(crate) fn apply_snapshot_to_map( + tasks: &mut HashMap, + snapshot: TaskSnapshot, +) { + if snapshot.should_clear() { + tasks.remove(snapshot.owner.as_str()); + } else { + tasks.insert(snapshot.owner.clone(), snapshot); + } +} diff --git a/crates/host-session/src/turn_mutation.rs b/crates/host-session/src/turn_mutation.rs new file mode 100644 index 00000000..8071b493 --- /dev/null +++ b/crates/host-session/src/turn_mutation.rs @@ -0,0 +1,1314 @@ +//! turn mutation owner 合同。 +//! +//! `host-session` 最终拥有 submit / compact / interrupt 的 durable truth。 +//! server 或 application 只能提供治理、workflow、skill invocation 的输入材料， +//! 不能拥有 turn lease、事件持久化或投影真相。 + +use std::sync::{Arc, Mutex as StdMutex}; + +use astrcode_agent_runtime::RuntimeTurnEvent; +use astrcode_core::{ + AgentEventContext, AstrError, CancelToken, EventTranslator, ExecutionAccepted, + ExecutionControl, Result, SessionId, StorageEvent, StorageEventPayload, StoredEvent, TurnId, + TurnTerminalKind, UserMessageOrigin, generate_turn_id, +}; +use async_trait::async_trait; +use chrono::Utc; + +use crate::{SessionCatalog, SubmitTarget, state::checkpoint_if_compacted}; + +/// turn mutation 预处理来源。 +/// +/// Durable mutation owner 固定为 `host-session`；这里仅描述治理、workflow、skill +/// invocation 等准备材料当前由谁提供，避免把 bridge 误认为 owner。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum TurnMutationPreparationOwner { + HostSession, + ExternalPreparation { owner: String }, +} + +impl TurnMutationPreparationOwner { + pub fn external_preparation(owner: impl Into) -> Self { + Self::ExternalPreparation { + owner: owner.into(), + } + } + + pub fn is_external_preparation(&self) -> bool { + matches!(self, Self::ExternalPreparation { .. }) + } +} + +/// submit / compact 进入 durable mutation 前的准备归属快照。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TurnMutationPreparation { + pub governance: TurnMutationPreparationOwner, + pub workflow: TurnMutationPreparationOwner, + pub skill_invocation: TurnMutationPreparationOwner, +} + +impl TurnMutationPreparation { + pub fn host_session_owned() -> Self { + Self { + governance: TurnMutationPreparationOwner::HostSession, + workflow: TurnMutationPreparationOwner::HostSession, + skill_invocation: TurnMutationPreparationOwner::HostSession, + } + } + + pub fn external_preparation(owner: impl Into) -> Self { + let owner = owner.into(); + Self { + governance: TurnMutationPreparationOwner::external_preparation(owner.clone()), + workflow: TurnMutationPreparationOwner::external_preparation(owner.clone()), + skill_invocation: TurnMutationPreparationOwner::external_preparation(owner), + } + } + + pub fn has_external_preparation(&self) -> bool { + self.governance.is_external_preparation() + || self.workflow.is_external_preparation() + || self.skill_invocation.is_external_preparation() + } +} + +impl Default for TurnMutationPreparation { + fn default() -> Self { + Self::host_session_owned() + } +} + +/// Prompt submit 的 owner 输入。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SubmitPromptMutationInput { + pub requested_session_id: SessionId, + pub requested_turn_id: Option, + pub prompt_text: String, + pub queued_inputs: Vec, + pub control: Option, + pub preparation: TurnMutationPreparation, +} + +/// Submit 遇到 busy session 时的 owner 策略。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SubmitTurnBusyPolicy { + BranchOnBusy { max_branch_depth: usize }, + RejectOnBusy, +} + +/// Prompt submit 接受摘要。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PromptAcceptedSummary { + pub turn_id: TurnId, + pub session_id: SessionId, + pub branched_from_session_id: Option, + pub accepted_control: Option, +} + +impl PromptAcceptedSummary { + pub fn from_execution_accepted( + accepted: ExecutionAccepted, + accepted_control: Option, + ) -> Self { + Self { + turn_id: accepted.turn_id, + session_id: accepted.session_id, + branched_from_session_id: accepted.branched_from_session_id, + accepted_control, + } + } +} + +/// 已被 `host-session` 接受的 prompt submit。 +/// +/// 持有 [`SubmitTarget`] 会同时持有 turn lease，因此后续执行 bridge 必须在 turn +/// 生命周期内保留该值，不能只复制摘要后丢弃 lease。 +pub struct AcceptedSubmitPrompt { + pub summary: PromptAcceptedSummary, + pub target: SubmitTarget, + pub live_user_input: Option, + pub queued_inputs: Vec, + pub preparation: TurnMutationPreparation, +} + +/// 已进入 running 状态、并由 `host-session` 持有 lease/cancel owner 的 accepted turn。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BegunAcceptedTurn { + pub summary: PromptAcceptedSummary, + pub live_user_input: Option, + pub queued_inputs: Vec, + pub preparation: TurnMutationPreparation, +} + +/// `agent-runtime` turn output 写入 `host-session` durable log 的输入。 +pub struct RuntimeTurnPersistenceInput { + pub session_id: SessionId, + pub turn_id: TurnId, + pub agent: AgentEventContext, + pub runtime_events: Vec, +} + +/// 单个 runtime event 写入 durable log 的输入。 +pub struct RuntimeTurnEventPersistenceInput { + pub session_id: SessionId, + pub turn_id: TurnId, + pub agent: AgentEventContext, + pub runtime_event: RuntimeTurnEvent, +} + +impl RuntimeTurnPersistenceInput { + pub fn from_accepted_prompt( + accepted: &AcceptedSubmitPrompt, + agent: AgentEventContext, + runtime_events: Vec, + ) -> Self { + Self { + session_id: accepted.summary.session_id.clone(), + turn_id: accepted.summary.turn_id.clone(), + agent, + runtime_events, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PendingManualCompactRequest { + pub control: Option, + pub instructions: Option, + pub preparation: TurnMutationPreparation, +} + +struct ActiveTurnMutationState { + turn_id: TurnId, + agent: AgentEventContext, + cancel: CancelToken, + _target: SubmitTarget, +} + +#[derive(Default)] +pub(crate) struct TurnMutationState { + active_turn: StdMutex>, + pending_manual_compact: StdMutex>, +} + +impl TurnMutationState { + pub(crate) fn active_turn_id_snapshot(&self) -> Result> { + Ok(astrcode_core::support::lock_anyhow( + &self.active_turn, + "host-session active turn mutation", + )? + .as_ref() + .map(|active| active.turn_id.clone())) + } + + pub(crate) fn has_pending_manual_compact(&self) -> Result { + Ok(astrcode_core::support::lock_anyhow( + &self.pending_manual_compact, + "host-session pending manual compact", + )? + .is_some()) + } +} + +impl SessionCatalog { + pub async fn accept_submit_prompt( + &self, + input: SubmitPromptMutationInput, + busy_policy: SubmitTurnBusyPolicy, + ) -> Result> { + let SubmitPromptMutationInput { + requested_session_id, + requested_turn_id, + prompt_text, + queued_inputs, + control, + preparation, + } = input; + let live_user_input = normalize_prompt_text(prompt_text); + let queued_inputs = normalize_queued_inputs(queued_inputs); + if live_user_input.is_none() && queued_inputs.is_empty() { + return Err(AstrError::Validation( + "turn submission must include live user input or queued inputs".to_string(), + )); + } + + let requested_session_id = SessionId::from(requested_session_id.as_str().trim()); + let turn_id = requested_turn_id.unwrap_or_else(|| TurnId::from(generate_turn_id())); + let target = match busy_policy { + SubmitTurnBusyPolicy::BranchOnBusy { max_branch_depth } => Some( + self.resolve_submit_target( + &requested_session_id, + turn_id.as_str(), + max_branch_depth, + ) + .await?, + ), + SubmitTurnBusyPolicy::RejectOnBusy => { + self.try_resolve_submit_target_without_branch( + &requested_session_id, + turn_id.as_str(), + ) + .await? + }, + }; + + let Some(target) = target else { + return Ok(None); + }; + let summary = PromptAcceptedSummary { + turn_id, + session_id: target.session_id.clone(), + branched_from_session_id: target.branched_from_session_id.clone(), + accepted_control: control, + }; + + Ok(Some(AcceptedSubmitPrompt { + summary, + target, + live_user_input, + queued_inputs, + preparation, + })) + } + + pub fn begin_accepted_turn( + &self, + accepted: AcceptedSubmitPrompt, + agent: AgentEventContext, + cancel: CancelToken, + ) -> Result { + let AcceptedSubmitPrompt { + summary, + target, + live_user_input, + queued_inputs, + preparation, + } = accepted; + let state = self.turn_mutation_state(&summary.session_id); + let mut active_turn = astrcode_core::support::lock_anyhow( + &state.active_turn, + "host-session active turn mutation", + )?; + if active_turn.is_some() { + return Err(AstrError::Validation(format!( + "session '{}' already has an active turn", + summary.session_id + ))); + } + *active_turn = Some(ActiveTurnMutationState { + turn_id: summary.turn_id.clone(), + agent, + cancel, + _target: target, + }); + Ok(BegunAcceptedTurn { + summary, + live_user_input, + queued_inputs, + preparation, + }) + } + + pub async fn persist_begun_turn_inputs( + &self, + begun: &BegunAcceptedTurn, + agent: AgentEventContext, + ) -> Result> { + let mut storage_events = Vec::new(); + let now = Utc::now(); + for queued_input in &begun.queued_inputs { + storage_events.push(user_message_storage_event( + begun.summary.turn_id.as_str(), + &agent, + queued_input.clone(), + UserMessageOrigin::QueuedInput, + now, + )); + } + if let Some(live_user_input) = &begun.live_user_input { + storage_events.push(user_message_storage_event( + begun.summary.turn_id.as_str(), + &agent, + live_user_input.clone(), + UserMessageOrigin::User, + now, + )); + } + self.append_turn_storage_events(&begun.summary.session_id, storage_events) + .await + } + + pub async fn request_manual_compact( + &self, + input: CompactSessionMutationInput, + ) -> Result { + if matches!( + input + .control + .as_ref() + .and_then(|control| control.manual_compact), + Some(false) + ) { + return Err(AstrError::Validation( + "manualCompact must be true for manual compact requests".to_string(), + )); + } + + self.ensure_session_exists(&input.session_id).await?; + let state = self.turn_mutation_state(&input.session_id); + let is_running = astrcode_core::support::lock_anyhow( + &state.active_turn, + "host-session active turn mutation", + )? + .is_some(); + if is_running { + *astrcode_core::support::lock_anyhow( + &state.pending_manual_compact, + "host-session pending manual compact", + )? = Some(PendingManualCompactRequest { + control: input.control, + instructions: input.instructions, + preparation: input.preparation, + }); + return Ok(CompactSessionSummary::manual_compact_accepted(true)); + } + + Ok(CompactSessionSummary::manual_compact_accepted(false)) + } + + pub fn complete_running_turn( + &self, + session_id: &SessionId, + turn_id: &TurnId, + ) -> Result> { + let Some(state) = self.turn_mutations.get(session_id) else { + return Ok(None); + }; + let mut active_turn = astrcode_core::support::lock_anyhow( + &state.active_turn, + "host-session active turn mutation", + )?; + if active_turn + .as_ref() + .map(|active| &active.turn_id) + .filter(|active_turn_id| *active_turn_id == turn_id) + .is_none() + { + return Ok(None); + } + *active_turn = None; + let pending_manual_compact = astrcode_core::support::lock_anyhow( + &state.pending_manual_compact, + "host-session pending manual compact", + )? + .take(); + Ok(pending_manual_compact) + } + + pub async fn interrupt_running_turn( + &self, + input: InterruptSessionMutationInput, + ) -> Result { + let loaded = self.ensure_loaded_session(&input.session_id).await?; + let Some(state) = self.turn_mutations.get(&input.session_id) else { + return Ok(InterruptSessionSummary::not_running(input.session_id)); + }; + let active = astrcode_core::support::lock_anyhow( + &state.active_turn, + "host-session active turn mutation", + )? + .take(); + let Some(active) = active else { + return Ok(InterruptSessionSummary::not_running(input.session_id)); + }; + active.cancel.cancel(); + + let mut translator = EventTranslator::new(loaded.state.current_phase()?); + let event = StorageEvent { + turn_id: Some(active.turn_id.to_string()), + agent: active.agent, + payload: StorageEventPayload::TurnDone { + timestamp: Utc::now(), + terminal_kind: Some(TurnTerminalKind::Cancelled), + reason: None, + }, + }; + loaded + .state + .append_and_broadcast(&event, &mut translator) + .await?; + let pending_manual_compact = astrcode_core::support::lock_anyhow( + &state.pending_manual_compact, + "host-session pending manual compact", + )? + .take(); + Ok(InterruptSessionSummary { + session_id: input.session_id, + accepted: true, + interrupted_turn_id: Some(active.turn_id), + pending_manual_compact, + }) + } + + fn turn_mutation_state(&self, session_id: &SessionId) -> Arc { + Arc::clone( + self.turn_mutations + .entry(session_id.clone()) + .or_insert_with(|| Arc::new(TurnMutationState::default())) + .value(), + ) + } + + pub async fn persist_runtime_turn_events( + &self, + input: RuntimeTurnPersistenceInput, + ) -> Result> { + let RuntimeTurnPersistenceInput { + session_id, + turn_id, + agent, + runtime_events, + } = input; + let storage_events = runtime_turn_storage_events(turn_id.as_str(), &agent, runtime_events); + self.append_turn_storage_events(&session_id, storage_events) + .await + } + + pub async fn persist_runtime_turn_event( + &self, + input: RuntimeTurnEventPersistenceInput, + ) -> Result> { + let storage_events = runtime_turn_storage_events( + input.turn_id.as_str(), + &input.agent, + vec![input.runtime_event], + ); + if storage_events.is_empty() { + return Ok(Vec::new()); + } + self.append_turn_storage_events(&input.session_id, storage_events) + .await + } + + async fn append_turn_storage_events( + &self, + session_id: &SessionId, + storage_events: Vec, + ) -> Result> { + let loaded = self.ensure_loaded_session(session_id).await?; + let mut translator = EventTranslator::new(loaded.state.current_phase()?); + let mut persisted_events = Vec::with_capacity(storage_events.len()); + for event in storage_events { + persisted_events.push( + loaded + .state + .append_and_broadcast(&event, &mut translator) + .await?, + ); + } + checkpoint_if_compacted( + &self.event_store, + session_id, + &loaded.state, + &persisted_events, + ) + .await; + Ok(persisted_events) + } +} + +fn normalize_prompt_text(text: String) -> Option { + let text = text.trim().to_string(); + (!text.is_empty()).then_some(text) +} + +fn normalize_queued_inputs(inputs: Vec) -> Vec { + inputs + .into_iter() + .filter_map(normalize_prompt_text) + .collect() +} + +fn runtime_turn_storage_events( + turn_id: &str, + agent: &AgentEventContext, + runtime_events: Vec, +) -> Vec { + let mut events = Vec::new(); + for runtime_event in runtime_events { + match runtime_event { + RuntimeTurnEvent::StorageEvent { event } => { + events.push(*event); + }, + RuntimeTurnEvent::AssistantFinal { + content, reasoning, .. + } => { + events.push(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::AssistantFinal { + content, + reasoning_content: reasoning.as_ref().map(|value| value.content.clone()), + reasoning_signature: reasoning.and_then(|value| value.signature), + step_index: None, + timestamp: Some(Utc::now()), + }, + }); + }, + RuntimeTurnEvent::TurnCompleted { terminal_kind, .. } => { + events.push(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::TurnDone { + timestamp: Utc::now(), + terminal_kind: Some(terminal_kind), + reason: None, + }, + }); + }, + RuntimeTurnEvent::TurnErrored { message, .. } => { + events.push(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::Error { + message, + timestamp: Some(Utc::now()), + }, + }); + }, + RuntimeTurnEvent::HookPromptAugmented { content, .. } => { + events.push(user_message_storage_event( + turn_id, + agent, + content, + UserMessageOrigin::ReactivationPrompt, + Utc::now(), + )); + }, + RuntimeTurnEvent::TurnStarted { .. } + | RuntimeTurnEvent::ProviderStream { .. } + | RuntimeTurnEvent::ToolUseRequested { .. } + | RuntimeTurnEvent::ToolCallStarted { .. } + | RuntimeTurnEvent::ToolResultReady { .. } + | RuntimeTurnEvent::HookDispatched { .. } + | RuntimeTurnEvent::StepContinued { .. } => {}, + } + } + events +} + +fn user_message_storage_event( + turn_id: &str, + agent: &AgentEventContext, + content: String, + origin: UserMessageOrigin, + timestamp: chrono::DateTime, +) -> StorageEvent { + StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::UserMessage { + content, + timestamp, + origin, + }, + } +} + +/// Manual compact 的 owner 输入。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CompactSessionMutationInput { + pub session_id: SessionId, + pub control: Option, + pub instructions: Option, + pub preparation: TurnMutationPreparation, +} + +/// Manual compact 接受摘要。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CompactSessionSummary { + pub accepted: bool, + pub deferred: bool, + pub message: String, +} + +impl CompactSessionSummary { + pub fn manual_compact_accepted(deferred: bool) -> Self { + Self { + accepted: true, + deferred, + message: if deferred { + "手动 compact 已登记，会在当前 turn 完成后执行。".to_string() + } else { + "手动 compact 已执行。".to_string() + }, + } + } +} + +/// Interrupt 的 owner 输入。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct InterruptSessionMutationInput { + pub session_id: SessionId, +} + +/// Interrupt 接受摘要。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct InterruptSessionSummary { + pub session_id: SessionId, + pub accepted: bool, + pub interrupted_turn_id: Option, + pub pending_manual_compact: Option, +} + +impl InterruptSessionSummary { + pub fn accepted(session_id: SessionId, interrupted_turn_id: Option) -> Self { + Self { + session_id, + accepted: true, + interrupted_turn_id, + pending_manual_compact: None, + } + } + + pub fn not_running(session_id: SessionId) -> Self { + Self { + session_id, + accepted: false, + interrupted_turn_id: None, + pending_manual_compact: None, + } + } +} + +/// `host-session` 暴露给 server 的 turn mutation facade。 +#[async_trait] +pub trait TurnMutationFacade: Send + Sync { + async fn submit_prompt( + &self, + input: SubmitPromptMutationInput, + ) -> Result; + + async fn compact_session( + &self, + input: CompactSessionMutationInput, + ) -> Result; + + async fn interrupt_session( + &self, + input: InterruptSessionMutationInput, + ) -> Result; +} + +#[cfg(test)] +mod tests { + use std::{ + collections::HashMap, + path::{Path, PathBuf}, + sync::{Arc, Mutex}, + }; + + use astrcode_agent_runtime::TurnIdentity; + use astrcode_core::{ + AgentId, DeleteProjectResult, ExecutionAccepted, Phase, SessionMeta, + SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StorageEvent, + StorageEventPayload, StoredEvent, TurnTerminalKind, + }; + use async_trait::async_trait; + use chrono::Utc; + + use super::*; + use crate::{EventStore, catalog::display_name_from_working_dir}; + + #[derive(Debug)] + struct TestLease; + + impl SessionTurnLease for TestLease {} + + #[derive(Default)] + struct TurnMutationEventStore { + sessions: Mutex)>>, + busy_sessions: Mutex>, + } + + impl TurnMutationEventStore { + fn mark_busy(&self, session_id: &SessionId, active_turn_id: impl Into) { + self.busy_sessions + .lock() + .expect("busy sessions lock poisoned") + .insert(session_id.clone(), active_turn_id.into()); + } + } + + #[async_trait] + impl EventStore for TurnMutationEventStore { + async fn ensure_session(&self, session_id: &SessionId, working_dir: &Path) -> Result<()> { + self.sessions + .lock() + .expect("sessions lock poisoned") + .entry(session_id.clone()) + .or_insert_with(|| (working_dir.to_path_buf(), Vec::new())); + Ok(()) + } + + async fn append( + &self, + session_id: &SessionId, + event: &StorageEvent, + ) -> Result { + let mut sessions = self.sessions.lock().expect("sessions lock poisoned"); + let (_, events) = sessions + .get_mut(session_id) + .ok_or_else(|| AstrError::SessionNotFound(session_id.to_string()))?; + let stored = StoredEvent { + storage_seq: events.len() as u64 + 1, + event: event.clone(), + }; + events.push(stored.clone()); + Ok(stored) + } + + async fn replay(&self, session_id: &SessionId) -> Result> { + self.sessions + .lock() + .expect("sessions lock poisoned") + .get(session_id) + .map(|(_, events)| events.clone()) + .ok_or_else(|| AstrError::SessionNotFound(session_id.to_string())) + } + + async fn try_acquire_turn( + &self, + session_id: &SessionId, + _turn_id: &str, + ) -> Result { + if let Some(active_turn_id) = self + .busy_sessions + .lock() + .expect("busy sessions lock poisoned") + .get(session_id) + .cloned() + { + return Ok(SessionTurnAcquireResult::Busy(SessionTurnBusy { + turn_id: active_turn_id, + owner_pid: 42, + acquired_at: Utc::now(), + })); + } + + if !self + .sessions + .lock() + .expect("sessions lock poisoned") + .contains_key(session_id) + { + return Err(AstrError::SessionNotFound(session_id.to_string())); + } + + Ok(SessionTurnAcquireResult::Acquired(Box::new(TestLease))) + } + + async fn list_sessions(&self) -> Result> { + Ok(self + .sessions + .lock() + .expect("sessions lock poisoned") + .keys() + .cloned() + .collect()) + } + + async fn list_session_metas(&self) -> Result> { + let sessions = self.sessions.lock().expect("sessions lock poisoned"); + Ok(sessions + .iter() + .map(|(session_id, (working_dir, events))| { + let session_start = events.iter().find_map(|stored| { + if let StorageEventPayload::SessionStart { + timestamp, + working_dir, + parent_session_id, + parent_storage_seq, + .. + } = &stored.event.payload + { + return Some(( + *timestamp, + working_dir.clone(), + parent_session_id.clone(), + *parent_storage_seq, + )); + } + None + }); + let (created_at, stored_working_dir, parent_session_id, parent_storage_seq) = + session_start.unwrap_or_else(|| { + (Utc::now(), working_dir.display().to_string(), None, None) + }); + SessionMeta { + session_id: session_id.to_string(), + working_dir: stored_working_dir.clone(), + display_name: display_name_from_working_dir(Path::new(&stored_working_dir)), + title: "New Session".to_string(), + created_at, + updated_at: created_at, + parent_session_id, + parent_storage_seq, + phase: Phase::Idle, + } + }) + .collect()) + } + + async fn delete_session(&self, session_id: &SessionId) -> Result<()> { + self.sessions + .lock() + .expect("sessions lock poisoned") + .remove(session_id); + Ok(()) + } + + async fn delete_sessions_by_working_dir( + &self, + working_dir: &str, + ) -> Result { + let mut sessions = self.sessions.lock().expect("sessions lock poisoned"); + let before = sessions.len(); + sessions.retain(|_, (path, _)| path.display().to_string() != working_dir); + Ok(DeleteProjectResult { + success_count: before.saturating_sub(sessions.len()), + failed_session_ids: Vec::new(), + }) + } + } + + fn submit_input( + session_id: SessionId, + turn_id: impl Into, + prompt_text: impl Into, + ) -> SubmitPromptMutationInput { + SubmitPromptMutationInput { + requested_session_id: session_id, + requested_turn_id: Some(TurnId::from(turn_id.into())), + prompt_text: prompt_text.into(), + queued_inputs: Vec::new(), + control: None, + preparation: TurnMutationPreparation::external_preparation("application"), + } + } + + fn compact_input(session_id: SessionId) -> CompactSessionMutationInput { + CompactSessionMutationInput { + session_id, + control: Some(ExecutionControl { + manual_compact: Some(true), + }), + instructions: Some("keep latest facts".to_string()), + preparation: TurnMutationPreparation::external_preparation("application"), + } + } + + #[test] + fn preparation_marks_external_preparation_without_changing_owner_contract() { + let preparation = TurnMutationPreparation::external_preparation("application"); + + assert!(preparation.has_external_preparation()); + assert_eq!( + preparation.governance, + TurnMutationPreparationOwner::ExternalPreparation { + owner: "application".to_string() + } + ); + } + + #[test] + fn prompt_summary_preserves_accepted_control_and_branch_source() { + let accepted = ExecutionAccepted { + session_id: SessionId::from("session-branch"), + turn_id: TurnId::from("turn-1"), + agent_id: Some(AgentId::from("agent-root")), + branched_from_session_id: Some("session-source".to_string()), + }; + let control = Some(ExecutionControl { + manual_compact: Some(false), + }); + + let summary = PromptAcceptedSummary::from_execution_accepted(accepted, control.clone()); + + assert_eq!(summary.session_id.as_str(), "session-branch"); + assert_eq!(summary.turn_id.as_str(), "turn-1"); + assert_eq!( + summary.branched_from_session_id, + Some("session-source".to_string()) + ); + assert_eq!(summary.accepted_control, control); + } + + #[test] + fn compact_summary_keeps_existing_response_messages() { + let immediate = CompactSessionSummary::manual_compact_accepted(false); + let deferred = CompactSessionSummary::manual_compact_accepted(true); + + assert!(immediate.accepted); + assert!(!immediate.deferred); + assert_eq!(immediate.message, "手动 compact 已执行。"); + assert!(deferred.deferred); + assert_eq!( + deferred.message, + "手动 compact 已登记，会在当前 turn 完成后执行。" + ); + } + + #[test] + fn interrupt_summary_accepts_optional_interrupted_turn() { + let summary = InterruptSessionSummary::accepted( + SessionId::from("session-1"), + Some(TurnId::from("turn-1")), + ); + + assert!(summary.accepted); + assert_eq!(summary.session_id.as_str(), "session-1"); + assert_eq!( + summary + .interrupted_turn_id + .as_ref() + .map(|turn_id| turn_id.as_str()), + Some("turn-1") + ); + } + + #[tokio::test] + async fn accept_submit_prompt_rejects_empty_input() { + let catalog = SessionCatalog::new(Arc::new(TurnMutationEventStore::default())); + + let result = catalog + .accept_submit_prompt( + submit_input(SessionId::from("session-1"), "turn-1", " "), + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await; + + assert!(matches!( + result, + Err(AstrError::Validation(message)) + if message == "turn submission must include live user input or queued inputs" + )); + } + + #[tokio::test] + async fn accept_submit_prompt_keeps_accepted_response_shape() { + let catalog = SessionCatalog::new(Arc::new(TurnMutationEventStore::default())); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + let control = Some(ExecutionControl { + manual_compact: Some(true), + }); + let mut input = submit_input(session_id.clone(), "turn-shape", " hello "); + input.queued_inputs = vec![" queued ".to_string(), " ".to_string()]; + input.control = control.clone(); + + let accepted = catalog + .accept_submit_prompt(input, SubmitTurnBusyPolicy::RejectOnBusy) + .await + .expect("submit should be accepted") + .expect("reject-on-busy should accept idle session"); + + assert_eq!(accepted.summary.session_id, session_id); + assert_eq!(accepted.summary.turn_id.as_str(), "turn-shape"); + assert_eq!(accepted.summary.branched_from_session_id, None); + assert_eq!(accepted.summary.accepted_control, control); + assert_eq!(accepted.target.session_id, accepted.summary.session_id); + assert_eq!(accepted.live_user_input.as_deref(), Some("hello")); + assert_eq!(accepted.queued_inputs, vec!["queued".to_string()]); + assert!(accepted.preparation.has_external_preparation()); + } + + #[tokio::test] + async fn accept_submit_prompt_returns_none_when_reject_on_busy() { + let store = Arc::new(TurnMutationEventStore::default()); + let catalog = SessionCatalog::new(store.clone()); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + store.mark_busy(&session_id, "turn-active"); + + let accepted = catalog + .accept_submit_prompt( + submit_input(session_id, "turn-rejected", "hello"), + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await + .expect("busy rejection should be non-error"); + + assert!(accepted.is_none()); + } + + #[tokio::test] + async fn accept_submit_prompt_branches_when_source_is_busy() { + let store = Arc::new(TurnMutationEventStore::default()); + let catalog = SessionCatalog::new(store.clone()); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let source_session_id = SessionId::from(meta.session_id); + store.mark_busy(&source_session_id, "turn-active"); + + let accepted = catalog + .accept_submit_prompt( + submit_input(source_session_id.clone(), "turn-branch", "hello"), + SubmitTurnBusyPolicy::BranchOnBusy { + max_branch_depth: 2, + }, + ) + .await + .expect("branch submit should be accepted") + .expect("branch-on-busy should create a target"); + + assert_ne!(accepted.summary.session_id, source_session_id); + assert_eq!( + accepted.summary.branched_from_session_id, + Some(source_session_id.to_string()) + ); + assert_eq!(accepted.summary.turn_id.as_str(), "turn-branch"); + assert_eq!(accepted.target.session_id, accepted.summary.session_id); + } + + #[tokio::test] + async fn persist_runtime_turn_events_writes_and_recovers_read_model() { + let store = Arc::new(TurnMutationEventStore::default()); + let catalog = SessionCatalog::new(store.clone()); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + let mut input = submit_input(session_id.clone(), "turn-runtime", " live prompt "); + input.queued_inputs = vec![" queued prompt ".to_string()]; + let accepted = catalog + .accept_submit_prompt(input, SubmitTurnBusyPolicy::RejectOnBusy) + .await + .expect("submit should be accepted") + .expect("idle submit should have target"); + let agent = AgentEventContext::root_execution("root-agent", "planner"); + let begun = catalog + .begin_accepted_turn(accepted, agent.clone(), CancelToken::new()) + .expect("turn should begin"); + + let input_events = catalog + .persist_begun_turn_inputs(&begun, agent.clone()) + .await + .expect("turn inputs should persist"); + assert_eq!(input_events.len(), 2); + + let persisted = catalog + .persist_runtime_turn_events(RuntimeTurnPersistenceInput { + session_id: begun.summary.session_id.clone(), + turn_id: begun.summary.turn_id.clone(), + agent, + runtime_events: vec![ + RuntimeTurnEvent::AssistantFinal { + identity: TurnIdentity::new( + session_id.to_string(), + "turn-runtime".to_string(), + "root-agent".to_string(), + ), + content: "assistant answer".to_string(), + reasoning: Some(astrcode_core::ReasoningContent { + content: "assistant thinking".to_string(), + signature: Some("sig-1".to_string()), + }), + tool_call_count: 0, + }, + RuntimeTurnEvent::TurnCompleted { + identity: TurnIdentity::new( + session_id.to_string(), + "turn-runtime".to_string(), + "root-agent".to_string(), + ), + stop_cause: astrcode_agent_runtime::TurnStopCause::Completed, + terminal_kind: TurnTerminalKind::Completed, + }, + ], + }) + .await + .expect("runtime events should persist"); + + assert_eq!(persisted.len(), 2); + assert!(matches!( + &input_events[0].event.payload, + StorageEventPayload::UserMessage { content, origin, .. } + if content == "queued prompt" && *origin == UserMessageOrigin::QueuedInput + )); + assert!(matches!( + &input_events[1].event.payload, + StorageEventPayload::UserMessage { content, origin, .. } + if content == "live prompt" && *origin == UserMessageOrigin::User + )); + assert!(matches!( + &persisted[0].event.payload, + StorageEventPayload::AssistantFinal { + content, + reasoning_content, + reasoning_signature, + .. + } if content == "assistant answer" + && reasoning_content.as_deref() == Some("assistant thinking") + && reasoning_signature.as_deref() == Some("sig-1") + )); + assert!(matches!( + &persisted[1].event.payload, + StorageEventPayload::TurnDone { terminal_kind, .. } + if *terminal_kind == Some(TurnTerminalKind::Completed) + )); + + let recovered_catalog = SessionCatalog::new(store); + let loaded = recovered_catalog + .ensure_loaded_session(&begun.summary.session_id) + .await + .expect("session should recover"); + let recovered_turn = loaded + .state + .turn_projection("turn-runtime") + .expect("turn projection should be readable") + .expect("turn projection should exist"); + assert_eq!( + recovered_turn.terminal_kind, + Some(TurnTerminalKind::Completed) + ); + } + + #[tokio::test] + async fn request_manual_compact_is_immediate_when_no_turn_is_running() { + let catalog = SessionCatalog::new(Arc::new(TurnMutationEventStore::default())); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + + let summary = catalog + .request_manual_compact(compact_input(session_id)) + .await + .expect("manual compact request should be accepted"); + + assert!(summary.accepted); + assert!(!summary.deferred); + assert_eq!(summary.message, "手动 compact 已执行。"); + } + + #[tokio::test] + async fn request_manual_compact_defers_until_running_turn_completes() { + let catalog = SessionCatalog::new(Arc::new(TurnMutationEventStore::default())); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + let accepted = catalog + .accept_submit_prompt( + submit_input(session_id.clone(), "turn-deferred", "hello"), + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await + .expect("submit should be accepted") + .expect("idle submit should have target"); + let turn_id = accepted.summary.turn_id.clone(); + catalog + .begin_accepted_turn( + accepted, + AgentEventContext::root_execution("root-agent", "planner"), + CancelToken::new(), + ) + .expect("turn should begin"); + + let summary = catalog + .request_manual_compact(compact_input(session_id.clone())) + .await + .expect("manual compact request should be accepted"); + let pending = catalog + .complete_running_turn(&session_id, &turn_id) + .expect("turn should complete") + .expect("pending compact should flush"); + + assert!(summary.accepted); + assert!(summary.deferred); + assert_eq!( + summary.message, + "手动 compact 已登记，会在当前 turn 完成后执行。" + ); + assert_eq!(pending.instructions.as_deref(), Some("keep latest facts")); + assert!(pending.preparation.has_external_preparation()); + } + + #[tokio::test] + async fn interrupt_running_turn_cancels_and_persists_cancelled_terminal_event() { + let catalog = SessionCatalog::new(Arc::new(TurnMutationEventStore::default())); + let meta = catalog + .create_session("D:/workspace/project") + .await + .expect("session should be created"); + let session_id = SessionId::from(meta.session_id); + let accepted = catalog + .accept_submit_prompt( + submit_input(session_id.clone(), "turn-cancelled", "hello"), + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await + .expect("submit should be accepted") + .expect("idle submit should have target"); + let cancel = CancelToken::new(); + let cancel_probe = cancel.clone(); + catalog + .begin_accepted_turn( + accepted, + AgentEventContext::root_execution("root-agent", "planner"), + cancel, + ) + .expect("turn should begin"); + catalog + .request_manual_compact(compact_input(session_id.clone())) + .await + .expect("manual compact should defer"); + + let summary = catalog + .interrupt_running_turn(InterruptSessionMutationInput { + session_id: session_id.clone(), + }) + .await + .expect("interrupt should succeed"); + + assert!(summary.accepted); + assert!(cancel_probe.is_cancelled()); + assert_eq!( + summary + .interrupted_turn_id + .as_ref() + .map(|turn_id| turn_id.as_str()), + Some("turn-cancelled") + ); + assert!(summary.pending_manual_compact.is_some()); + let loaded = catalog + .ensure_loaded_session(&session_id) + .await + .expect("session should remain loaded"); + assert_eq!( + loaded.state.current_phase().expect("phase should read"), + Phase::Interrupted + ); + let stored = loaded + .state + .snapshot_recent_stored_events() + .expect("stored events should read"); + assert!(stored.iter().any(|stored| matches!( + &stored.event.payload, + StorageEventPayload::TurnDone { terminal_kind, .. } + if *terminal_kind == Some(TurnTerminalKind::Cancelled) + ))); + } +} diff --git a/crates/host-session/src/turn_projection.rs b/crates/host-session/src/turn_projection.rs new file mode 100644 index 00000000..81dbadd4 --- /dev/null +++ b/crates/host-session/src/turn_projection.rs @@ -0,0 +1,36 @@ +use astrcode_core::{StorageEventPayload, StoredEvent}; + +use crate::TurnProjectionSnapshot; + +pub(crate) fn apply_turn_projection_event( + projection: &mut TurnProjectionSnapshot, + stored: &StoredEvent, +) { + match &stored.event.payload { + StorageEventPayload::TurnDone { terminal_kind, .. } => { + projection.terminal_kind = terminal_kind.clone() + }, + StorageEventPayload::Error { message, .. } => { + let message = message.trim(); + if !message.is_empty() { + projection.last_error = Some(message.to_string()); + } + }, + _ => {}, + } +} + +pub(crate) fn project_turn_projection(events: &[StoredEvent]) -> Option { + if events.is_empty() { + return None; + } + + let mut projection = TurnProjectionSnapshot { + terminal_kind: None, + last_error: None, + }; + for stored in events { + apply_turn_projection_event(&mut projection, stored); + } + Some(projection) +} diff --git a/crates/core/src/workflow.rs b/crates/host-session/src/workflow.rs similarity index 99% rename from crates/core/src/workflow.rs rename to crates/host-session/src/workflow.rs index d343b93d..c30d47f5 100644 --- a/crates/core/src/workflow.rs +++ b/crates/host-session/src/workflow.rs @@ -1,11 +1,10 @@ use std::collections::BTreeMap; +use astrcode_core::ModeId; use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::ModeId; - /// workflow 的稳定定义。 /// /// Why: workflow 是跨 turn、跨 mode 的正式编排协议，不应散落在 application 的 if/else 中。 @@ -131,13 +130,13 @@ pub struct WorkflowInstanceState { mod tests { use std::collections::BTreeMap; + use astrcode_core::ModeId; use serde_json::json; use super::{ WorkflowArtifactRef, WorkflowBridgeState, WorkflowDef, WorkflowInstanceState, WorkflowPhaseDef, WorkflowSignal, WorkflowTransitionDef, WorkflowTransitionTrigger, }; - use crate::ModeId; #[test] fn workflow_def_serializes_with_explicit_transition_shape() { diff --git a/crates/kernel/Cargo.toml b/crates/kernel/Cargo.toml deleted file mode 100644 index f9ca2f91..00000000 --- a/crates/kernel/Cargo.toml +++ /dev/null @@ -1,15 +0,0 @@ -[package] -name = "astrcode-kernel" -version = "0.1.0" -edition.workspace = true -license-file.workspace = true -authors.workspace = true - -[dependencies] -astrcode-core = { path = "../core" } -async-trait.workspace = true -log.workspace = true -serde.workspace = true -serde_json.workspace = true -thiserror.workspace = true -tokio.workspace = true diff --git a/crates/kernel/src/agent_surface.rs b/crates/kernel/src/agent_surface.rs deleted file mode 100644 index 70b1423a..00000000 --- a/crates/kernel/src/agent_surface.rs +++ /dev/null @@ -1,348 +0,0 @@ -use astrcode_core::{ - AgentInboxEnvelope, AgentLifecycleStatus, AgentProfile, AgentTurnOutcome, - ChildSessionNotification, DelegationMetadata, ResolvedExecutionLimitsSnapshot, SubRunHandle, - SubRunStorageMode, -}; - -use crate::{ - agent_tree::{AgentControlError, PendingParentDelivery}, - kernel::Kernel, -}; - -/// 子运行稳定状态快照（不暴露内部树结构）。 -#[derive(Debug, Clone)] -pub struct SubRunStatusView { - pub sub_run_id: String, - pub agent_id: String, - pub session_id: String, - pub child_session_id: Option, - pub depth: usize, - pub parent_agent_id: Option, - pub agent_profile: String, - pub lifecycle: AgentLifecycleStatus, - pub last_turn_outcome: Option, - pub resolved_limits: ResolvedExecutionLimitsSnapshot, - pub delegation: Option, -} - -impl SubRunStatusView { - pub fn from_handle(handle: &SubRunHandle) -> Self { - Self { - sub_run_id: handle.sub_run_id.to_string(), - agent_id: handle.agent_id.to_string(), - session_id: handle.session_id.to_string(), - child_session_id: handle.child_session_id.clone().map(Into::into), - depth: handle.depth, - parent_agent_id: handle.parent_agent_id.clone().map(Into::into), - agent_profile: handle.agent_profile.clone(), - lifecycle: handle.lifecycle, - last_turn_outcome: handle.last_turn_outcome, - resolved_limits: handle.resolved_limits.clone(), - delegation: handle.delegation.clone(), - } - } -} - -/// 关闭子树的结果。 -#[derive(Debug, Clone)] -pub struct CloseSubtreeResult { - pub closed_agent_ids: Vec, -} - -/// Kernel 暴露给 application/server 的稳定 agent 控制面。 -/// -/// 这层只承载编排期真正需要的 agent 能力，避免调用方直接面向 -/// `AgentControl` 内部树结构编程。 -#[derive(Clone, Copy)] -pub struct KernelAgentSurface<'a> { - kernel: &'a Kernel, -} - -impl<'a> KernelAgentSurface<'a> { - pub(crate) fn new(kernel: &'a Kernel) -> Self { - Self { kernel } - } - - /// 查询子运行状态（稳定视图）。 - pub async fn query_subrun_status(&self, agent_id: &str) -> Option { - let handle = self.kernel.agent_control().get(agent_id).await?; - Some(SubRunStatusView::from_handle(&handle)) - } - - /// 查询原始子运行句柄（供 application 编排层使用）。 - pub async fn get_handle(&self, sub_run_or_agent_id: &str) -> Option { - self.kernel.agent_control().get(sub_run_or_agent_id).await - } - - /// 查询 agent 当前生命周期状态。 - pub async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option { - self.kernel - .agent_control() - .get_lifecycle(sub_run_or_agent_id) - .await - } - - /// 查询 agent 最近一轮执行结果。 - pub async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option { - self.kernel - .agent_control() - .get_turn_outcome(sub_run_or_agent_id) - .await - .flatten() - } - - /// 在 finalized 可复用节点上启动新的执行轮次。 - pub async fn resume( - &self, - sub_run_or_agent_id: &str, - parent_turn_id: impl Into, - ) -> Option { - self.kernel - .agent_control() - .resume(sub_run_or_agent_id, parent_turn_id) - .await - } - - /// 查询指定 session 的根 agent 状态。 - pub async fn query_root_status(&self, session_id: &str) -> Option { - let handle = self - .kernel - .agent_control() - .find_root_agent_for_session(session_id) - .await?; - Some(SubRunStatusView::from_handle(&handle)) - } - - /// 查询指定 session 的根 agent 原始句柄。 - pub async fn find_root_handle_for_session(&self, session_id: &str) -> Option { - self.kernel - .agent_control() - .find_root_agent_for_session(session_id) - .await - } - - /// 注册根 agent；如果已存在则返回既有句柄。 - pub async fn register_root_agent( - &self, - agent_id: String, - session_id: String, - profile_id: String, - ) -> Result { - self.kernel - .agent_control() - .register_root_agent(agent_id, session_id, profile_id) - .await - } - - /// 以独立 child session 模式创建新的子代理执行实例。 - pub async fn spawn_independent_child( - &self, - profile: &AgentProfile, - session_id: impl Into, - child_session_id: String, - parent_turn_id: String, - parent_agent_id: String, - ) -> Result { - self.kernel - .agent_control() - .spawn_with_storage( - profile, - session_id, - Some(child_session_id), - parent_turn_id, - Some(parent_agent_id), - SubRunStorageMode::IndependentSession, - ) - .await - } - - /// 显式推进 agent 生命周期（仅限编排层需要的少量控制面操作）。 - pub async fn set_lifecycle( - &self, - sub_run_or_agent_id: &str, - new_status: AgentLifecycleStatus, - ) -> Option<()> { - self.kernel - .agent_control() - .set_lifecycle(sub_run_or_agent_id, new_status) - .await - } - - pub async fn set_resolved_limits( - &self, - sub_run_or_agent_id: &str, - resolved_limits: ResolvedExecutionLimitsSnapshot, - ) -> Option<()> { - self.kernel - .agent_control() - .set_resolved_limits(sub_run_or_agent_id, resolved_limits) - .await - } - - pub async fn set_delegation( - &self, - sub_run_or_agent_id: &str, - delegation: Option, - ) -> Option<()> { - self.kernel - .agent_control() - .set_delegation(sub_run_or_agent_id, delegation) - .await - } - - /// 列出所有 agent 的状态快照。 - pub async fn list_statuses(&self) -> Vec { - self.kernel - .agent_control() - .list() - .await - .iter() - .map(SubRunStatusView::from_handle) - .collect() - } - - /// 统计某个 parent turn 下已经派生出的 child 数量。 - /// - /// 这是编排层的 spawn budget 查询，不暴露底层树节点结构，只返回当前需要的计数结果。 - pub async fn count_children_spawned_for_turn( - &self, - parent_agent_id: &str, - parent_turn_id: &str, - ) -> usize { - self.kernel - .agent_control() - .list() - .await - .into_iter() - .filter(|handle| { - handle.parent_turn_id.as_str() == parent_turn_id - && handle - .parent_agent_id - .as_ref() - .is_some_and(|id| id.as_str() == parent_agent_id) - && matches!( - handle.lineage_kind, - astrcode_core::ChildSessionLineageKind::Spawn - | astrcode_core::ChildSessionLineageKind::Fork - ) - }) - .count() - } - - /// 关闭指定 agent 及其子树，并返回被关闭的 agent id 列表。 - pub async fn close_subtree( - &self, - agent_id: &str, - ) -> Result { - let closed_agent_ids = self - .kernel - .agent_control() - .terminate_subtree_and_collect_handles(agent_id) - .await - .map(|handles| { - handles - .into_iter() - .map(|handle| handle.agent_id.to_string()) - .collect() - }) - .ok_or(AgentControlError::ParentAgentNotFound { - agent_id: agent_id.to_string(), - })?; - Ok(CloseSubtreeResult { closed_agent_ids }) - } - - /// 向 agent inbox 推送一条信封（用于 send 工具的 durable queue 路径）。 - pub async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()> { - self.kernel - .agent_control() - .push_inbox(agent_id, envelope) - .await - } - - /// 一次性取出 inbox 中所有待处理信封并清空（用于 idle agent resume 时合并消息）。 - pub async fn drain_inbox(&self, agent_id: &str) -> Option> { - self.kernel.agent_control().drain_inbox(agent_id).await - } - - /// 收集以指定 agent 为根的整棵子树 handle（用于 close 前的 durable discard 批量标记）。 - pub async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec { - self.kernel - .agent_control() - .collect_subtree_handles(sub_run_or_agent_id) - .await - } - - /// 终止子树但不收集 handle（用于内部 cancel 路径，不需要返回被终止列表）。 - pub async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option { - self.kernel - .agent_control() - .terminate_subtree(sub_run_or_agent_id) - .await - } - - /// 将 child terminal delivery 排入父 session 的 delivery queue。 - /// 返回 true 表示入队成功，false 表示容量已满或重复 delivery_id。 - pub async fn enqueue_child_delivery( - &self, - parent_session_id: impl Into, - parent_turn_id: impl Into, - notification: ChildSessionNotification, - ) -> bool { - self.kernel - .agent_control() - .enqueue_parent_delivery(parent_session_id, parent_turn_id, notification) - .await - } - - /// 从队列头部批量 checkout 同一 parent_agent_id 的连续 delivery（状态 Queued → WakingParent）。 - pub async fn checkout_parent_delivery_batch( - &self, - parent_session_id: &str, - ) -> Option> { - self.kernel - .agent_control() - .checkout_parent_delivery_batch(parent_session_id) - .await - } - - /// wake 失败时将 delivery 重新标记为 Queued，等待下次 retry。 - pub async fn requeue_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) { - self.kernel - .agent_control() - .requeue_parent_delivery_batch(parent_session_id, delivery_ids) - .await; - } - - /// wake 成功后从队列中移除已消费的 delivery；队列为空时清理整个 session 条目。 - pub async fn consume_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) -> bool { - self.kernel - .agent_control() - .consume_parent_delivery_batch(parent_session_id, delivery_ids) - .await - } - - /// 取消指定 parent turn 下所有仍在运行的子 agent（用于 turn 结束时的级联清理）。 - pub async fn cancel_subruns_for_turn(&self, parent_turn_id: &str) -> Vec { - self.kernel - .agent_control() - .cancel_for_parent_turn(parent_turn_id) - .await - .into_iter() - .map(|handle| handle.agent_id.to_string()) - .collect() - } -} - -impl Kernel { - pub fn agent(&self) -> KernelAgentSurface<'_> { - KernelAgentSurface::new(self) - } -} diff --git a/crates/kernel/src/agent_tree/mod.rs b/crates/kernel/src/agent_tree/mod.rs deleted file mode 100644 index 9b9e0eff..00000000 --- a/crates/kernel/src/agent_tree/mod.rs +++ /dev/null @@ -1,949 +0,0 @@ -//! # Agent 控制平面 -//! -//! 提供轻量的 in-memory Agent 注册表，负责： -//! - 分配 agent 实例 ID -//! - 跟踪 parent-child 关系 -//! - 对外暴露 spawn / list / cancel / wait -//! - 维护父取消传播 -//! -//! 之所以单独拆成 crate，是为了把“控制平面”从“执行引擎”中拿出来： -//! `runtime-agent-loop` 专注一次 turn 如何执行， -//! `runtime-agent-control` 专注多 Agent 生命周期如何被编排和取消。 - -mod delivery_queue; -mod state; -mod tree_ops; - -use std::{ - collections::{BTreeSet, HashSet, VecDeque}, - sync::{ - Arc, - atomic::{AtomicU64, Ordering}, - }, -}; - -use astrcode_core::{ - AgentInboxEnvelope, AgentLifecycleStatus, AgentProfile, AgentTurnOutcome, AstrError, - CancelToken, ChildSessionLineageKind, LiveSubRunControlBoundary, - ResolvedExecutionLimitsSnapshot, SessionId, SpawnAgentParams, SubRunHandle, SubRunResult, - SubRunStorageMode, ToolContext, -}; -use async_trait::async_trait; -use delivery_queue::{ - checkout_parent_delivery_batch_locked, checkout_parent_delivery_locked, - consume_parent_delivery_batch_locked, consume_parent_delivery_locked, - enqueue_parent_delivery_locked, pending_parent_delivery_count_locked, - requeue_parent_delivery_batch_locked, requeue_parent_delivery_locked, -}; -use state::{AgentEntry, AgentRegistryState, resolve_entry_key}; -use thiserror::Error; -use tokio::sync::{RwLock, watch}; -use tree_ops::{ - cancel_tree, cancel_tree_collect, discard_parent_deliveries_locked, - prune_finalized_agents_locked, terminate_tree_collect, -}; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PendingParentDelivery { - pub delivery_id: String, - pub parent_session_id: String, - pub parent_turn_id: String, - pub queued_at_ms: i64, - pub notification: astrcode_core::ChildSessionNotification, -} - -#[derive(Debug, Clone, PartialEq, Eq, Error)] -pub enum AgentControlError { - #[error("parent agent '{agent_id}' does not exist")] - ParentAgentNotFound { agent_id: String }, - #[error("agent depth {current} exceeds max depth {max}")] - MaxDepthExceeded { current: usize, max: usize }, - #[error("active agent count {current} exceeds max concurrent {max}")] - MaxConcurrentExceeded { current: usize, max: usize }, -} - -/// Agent 控制平面主句柄。 -#[derive(Clone)] -pub struct AgentControl { - next_id: Arc, - next_finalized_seq: Arc, - max_depth: usize, - max_concurrent: usize, - finalized_retain_limit: usize, - inbox_capacity: usize, - parent_delivery_capacity: usize, - state: Arc>, -} - -/// Agent 控制平面的显式限额配置。 -/// -/// kernel 不再读取 runtime-config；由组合根在构造时把策略值显式注入。 -#[derive(Debug, Clone, Copy)] -pub struct AgentControlLimits { - pub max_depth: usize, - pub max_concurrent: usize, - pub finalized_retain_limit: usize, - pub inbox_capacity: usize, - pub parent_delivery_capacity: usize, -} - -impl Default for AgentControlLimits { - fn default() -> Self { - Self { - max_depth: 3, - max_concurrent: 32, - finalized_retain_limit: 256, - inbox_capacity: 1024, - parent_delivery_capacity: 1024, - } - } -} - -pub trait AgentProfileSource: Send + Sync { - fn list_profiles(&self) -> Vec; -} - -#[derive(Clone)] -pub struct StaticAgentProfileSource { - profiles: Vec, -} - -impl StaticAgentProfileSource { - pub fn new(profiles: Vec) -> Self { - Self { profiles } - } -} - -impl AgentProfileSource for StaticAgentProfileSource { - fn list_profiles(&self) -> Vec { - self.profiles.clone() - } -} - -/// `runtime-agent-control` 对外暴露的 live 控制面。 -/// -/// live registry 负责 handle/cancel 真相，profile 列表由外部 profile catalog 注入， -/// 避免控制平面反向依赖 loader/runtime façade。 -#[derive(Clone)] -pub struct LiveSubRunControl

{ - control: AgentControl, - profiles: P, -} - -impl

LiveSubRunControl

{ - pub fn new(control: AgentControl, profiles: P) -> Self { - Self { control, profiles } - } - - pub fn control(&self) -> &AgentControl { - &self.control - } -} - -#[async_trait] -impl

LiveSubRunControlBoundary for LiveSubRunControl

-where - P: AgentProfileSource, -{ - async fn get_subrun_handle( - &self, - _session_id: &SessionId, - sub_run_id: &str, - ) -> std::result::Result, AstrError> { - Ok(self.control.get(sub_run_id).await) - } - - async fn cancel_subrun( - &self, - _session_id: &SessionId, - sub_run_id: &str, - ) -> std::result::Result<(), AstrError> { - // 故意忽略：取消子运行时的错误不应阻断父级流程 - let _ = self.control.cancel(sub_run_id).await; - Ok(()) - } - - /// 控制平面本身不持有执行引擎，launch_subagent 应由 runtime service 层实现。 - /// - /// 此 impl 仅满足 trait 约束；实际调用不会到达这里，因为 runtime service - /// 会使用自己的 `LiveSubRunControlBoundary` impl 来组合 control + execution。 - async fn launch_subagent( - &self, - _params: SpawnAgentParams, - _ctx: &ToolContext, - ) -> std::result::Result { - Err(AstrError::Internal( - "launch_subagent must be called through the runtime service LiveSubRunControlBoundary \ - impl, not the bare control-plane wrapper" - .to_string(), - )) - } - - async fn list_profiles(&self) -> std::result::Result, AstrError> { - Ok(self.profiles.list_profiles()) - } -} - -impl Default for AgentControl { - fn default() -> Self { - Self::from_limits(AgentControlLimits::default()) - } -} - -impl AgentControl { - /// 用显式限额构建 AgentControl。 - pub fn from_limits(limits: AgentControlLimits) -> Self { - Self { - next_id: Arc::new(AtomicU64::new(0)), - next_finalized_seq: Arc::new(AtomicU64::new(0)), - max_depth: limits.max_depth, - max_concurrent: limits.max_concurrent, - finalized_retain_limit: limits.finalized_retain_limit, - inbox_capacity: limits.inbox_capacity, - parent_delivery_capacity: limits.parent_delivery_capacity, - state: Arc::new(RwLock::new(AgentRegistryState::default())), - } - } - - pub fn new() -> Self { - Self::from_limits(AgentControlLimits::default()) - } - - #[cfg(test)] - fn with_limits(max_depth: usize, max_concurrent: usize, finalized_retain_limit: usize) -> Self { - Self { - max_depth, - max_concurrent, - finalized_retain_limit, - inbox_capacity: 1024, - parent_delivery_capacity: 1024, - ..Self::default() - } - } - - /// 注册一个新的子 Agent 实例。 - /// - /// 只建立控制面，不假设 spawn 立刻意味着开始执行，因此初始状态为 Pending。 - pub async fn spawn( - &self, - profile: &AgentProfile, - session_id: impl Into, - parent_turn_id: String, - parent_agent_id: Option, - ) -> Result { - self.spawn_with_storage( - profile, - session_id, - None, - parent_turn_id, - parent_agent_id, - SubRunStorageMode::IndependentSession, - ) - .await - } - - /// 注册一个新的子 Agent / 子会话实例，并显式指定存储模式。 - pub async fn spawn_with_storage( - &self, - profile: &AgentProfile, - session_id: impl Into, - child_session_id: Option, - parent_turn_id: String, - parent_agent_id: Option, - storage_mode: SubRunStorageMode, - ) -> Result { - let mut state = self.state.write().await; - let depth = match parent_agent_id.as_ref() { - Some(parent_agent_id) => { - let Some(parent_sub_run_id) = state.agent_index.get(parent_agent_id) else { - return Err(AgentControlError::ParentAgentNotFound { - agent_id: parent_agent_id.clone(), - }); - }; - let Some(parent) = state.entries.get(parent_sub_run_id) else { - return Err(AgentControlError::ParentAgentNotFound { - agent_id: parent_agent_id.clone(), - }); - }; - parent.handle.depth + 1 - }, - None => 1, - }; - if depth > self.max_depth { - return Err(AgentControlError::MaxDepthExceeded { - current: depth, - max: self.max_depth, - }); - } - if state.active_count >= self.max_concurrent { - return Err(AgentControlError::MaxConcurrentExceeded { - current: state.active_count, - max: self.max_concurrent, - }); - } - // 只有在父节点校验通过后才分配新 ID，避免失败的 spawn 留下无意义的编号空洞。 - let next_id = self.next_id.fetch_add(1, Ordering::SeqCst) + 1; - let agent_id = format!("agent-{next_id}"); - let sub_run_id = format!("subrun-{next_id}"); - let session_id = session_id.into(); - let parent_sub_run_id = parent_agent_id - .as_ref() - .and_then(|parent_agent_id| state.agent_index.get(parent_agent_id)) - .cloned(); - let handle = SubRunHandle { - sub_run_id: sub_run_id.clone().into(), - agent_id: agent_id.clone().into(), - session_id: session_id.into(), - child_session_id: child_session_id.map(Into::into), - depth, - parent_turn_id: parent_turn_id.into(), - parent_agent_id: parent_agent_id.clone().map(Into::into), - parent_sub_run_id: parent_sub_run_id.map(Into::into), - lineage_kind: ChildSessionLineageKind::Spawn, - agent_profile: profile.id.clone(), - storage_mode, - lifecycle: AgentLifecycleStatus::Pending, - last_turn_outcome: None, - resolved_limits: ResolvedExecutionLimitsSnapshot, - delegation: None, - }; - let cancel = CancelToken::new(); - let (status_tx, _status_rx) = watch::channel(handle.lifecycle); - state.entries.insert( - sub_run_id.clone(), - AgentEntry { - handle: handle.clone(), - cancel, - status_tx, - parent_agent_id: parent_agent_id.clone(), - children: BTreeSet::new(), - finalized_seq: None, - inbox: VecDeque::new(), - inbox_version: watch::channel(0).0, - lifecycle_status: AgentLifecycleStatus::Pending, - last_turn_outcome: None, - }, - ); - state.agent_index.insert(agent_id, sub_run_id.clone()); - state.active_count += 1; - if let Some(parent_agent_id) = parent_agent_id { - if let Some(parent_sub_run_id) = state.agent_index.get(&parent_agent_id).cloned() { - if let Some(parent) = state.entries.get_mut(&parent_sub_run_id) { - parent.children.insert(sub_run_id); - } - } - } - prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); - Ok(handle) - } - - /// 注册根 Agent 到控制树。 - /// - /// 四工具模型要求根 Agent 也成为一等控制对象， - /// 这样 child 可以通过 `send(parentId, ...)` 向根发送消息， - /// `observe` 也可以沿着统一父子树进行权限校验。 - /// - /// 根 Agent 深度为 0，无父节点，生命周期初始为 Running（根已在执行中）。 - pub async fn register_root_agent( - &self, - agent_id: String, - session_id: String, - profile_id: String, - ) -> Result { - let mut state = self.state.write().await; - // 如果该 agent 已注册，直接返回现有句柄（幂等） - if let Some(existing_key) = state.agent_index.get(&agent_id) { - if let Some(entry) = state.entries.get(existing_key) { - return Ok(entry.handle.clone()); - } - } - // 根 agent 没有真实 sub_run_id，使用 agent_id 等价 - let sub_run_id = format!("root-{agent_id}"); - let handle = SubRunHandle { - sub_run_id: sub_run_id.clone().into(), - agent_id: agent_id.clone().into(), - session_id: session_id.into(), - child_session_id: None, - depth: 0, - parent_turn_id: String::new().into(), - parent_agent_id: None, - parent_sub_run_id: None, - lineage_kind: ChildSessionLineageKind::Spawn, - agent_profile: profile_id, - storage_mode: SubRunStorageMode::IndependentSession, - lifecycle: AgentLifecycleStatus::Running, - last_turn_outcome: None, - resolved_limits: ResolvedExecutionLimitsSnapshot, - delegation: None, - }; - let cancel = CancelToken::new(); - let (status_tx, _status_rx) = watch::channel(handle.lifecycle); - state.entries.insert( - sub_run_id.clone(), - AgentEntry { - handle: handle.clone(), - cancel, - status_tx, - parent_agent_id: None, - children: BTreeSet::new(), - finalized_seq: None, - inbox: VecDeque::new(), - inbox_version: watch::channel(0).0, - lifecycle_status: AgentLifecycleStatus::Running, - last_turn_outcome: None, - }, - ); - state.agent_index.insert(agent_id, sub_run_id); - state.active_count += 1; - Ok(handle) - } - - // ── 生命周期与轮次结果（四工具模型） ────────────────────────────── - - /// 读取 agent 的持久生命周期状态。 - pub async fn get_lifecycle(&self, id: &str) -> Option { - let state = self.state.read().await; - let key = resolve_entry_key(&state, id)?; - state.entries.get(key).map(|e| e.lifecycle_status) - } - - /// 读取 agent 的最近一轮执行结果。 - pub async fn get_turn_outcome(&self, id: &str) -> Option> { - let state = self.state.read().await; - let key = resolve_entry_key(&state, id)?; - state.entries.get(key).map(|e| e.last_turn_outcome) - } - - /// 更新 agent 的持久生命周期状态。 - /// - /// 状态迁移规则由调用方保证合法性（Pending→Running→Idle→Terminated）， - /// 此方法不做状态机校验，只做原子写入。 - pub async fn set_lifecycle(&self, id: &str, new_status: AgentLifecycleStatus) -> Option<()> { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, id)?.to_string(); - let entry = state.entries.get_mut(&key)?; - entry.lifecycle_status = new_status; - entry.handle.lifecycle = new_status; - entry.status_tx.send_replace(new_status); - Some(()) - } - - /// 更新 agent 的最近一轮执行结果。 - /// - /// 在 turn 完成（无论是正常完成还是失败）时调用， - /// 同时将 lifecycle 从 Running 推进到 Idle。 - /// - /// 四工具模型下 Idle 表示"不在执行但仍存活"， - /// 并发槽位在此时释放，后续 resume 会重新占用。 - pub async fn complete_turn( - &self, - id: &str, - outcome: AgentTurnOutcome, - ) -> Option { - let next_seq = self.next_finalized_seq.fetch_add(1, Ordering::SeqCst); - let retain_limit = self.finalized_retain_limit; - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, id)?.to_string(); - let was_active = { - let entry = state.entries.get_mut(&key)?; - let was_active = entry.handle.lifecycle.occupies_slot(); - entry.last_turn_outcome = Some(outcome); - entry.lifecycle_status = AgentLifecycleStatus::Idle; - entry.handle.lifecycle = AgentLifecycleStatus::Idle; - entry.handle.last_turn_outcome = Some(outcome); - entry.finalized_seq = Some(next_seq); - entry.status_tx.send_replace(AgentLifecycleStatus::Idle); - was_active - }; - if was_active { - state.active_count = state.active_count.saturating_sub(1); - } - prune_finalized_agents_locked(&mut state, retain_limit); - Some(AgentLifecycleStatus::Idle) - } - - /// 更新 agent 当前执行实例的 resolved limits 快照。 - pub async fn set_resolved_limits( - &self, - id: &str, - resolved_limits: ResolvedExecutionLimitsSnapshot, - ) -> Option<()> { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, id)?.to_string(); - let entry = state.entries.get_mut(&key)?; - entry.handle.resolved_limits = resolved_limits; - Some(()) - } - - /// 更新 agent 当前执行实例的 delegation 元数据。 - pub async fn set_delegation( - &self, - id: &str, - delegation: Option, - ) -> Option<()> { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, id)?.to_string(); - let entry = state.entries.get_mut(&key)?; - entry.handle.delegation = delegation; - Some(()) - } - - /// 列出当前已注册的 Agent。 - pub async fn list(&self) -> Vec { - let state = self.state.read().await; - let mut handles = state - .entries - .values() - .map(|entry| entry.handle.clone()) - .collect::>(); - handles.sort_by(|left, right| left.sub_run_id.cmp(&right.sub_run_id)); - handles - } - - /// 查询单个 Agent。 - pub async fn get(&self, sub_run_or_agent_id: &str) -> Option { - let state = self.state.read().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?; - state.entries.get(key).map(|entry| entry.handle.clone()) - } - - /// 根据 session_id 查找该 session 的根 agent（depth=0）。 - /// - /// 为什么需要：`submit_prompt` 路径不经过 `execute_root_agent`，无法直接获得根 agent ID， - /// 但四工具模型要求 ToolContext 中的 agent_id 正确设置，以便子 agent 建立父子关系。 - pub async fn find_root_agent_for_session(&self, session_id: &str) -> Option { - let state = self.state.read().await; - state - .entries - .values() - .find(|entry| entry.handle.depth == 0 && entry.handle.session_id.as_str() == session_id) - .map(|entry| entry.handle.clone()) - } - - /// 获取某个 Agent 的取消令牌，供真正的执行器复用。 - pub async fn cancel_token(&self, sub_run_or_agent_id: &str) -> Option { - let state = self.state.read().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?; - state.entries.get(key).map(|entry| entry.cancel.clone()) - } - - /// 为已终态的 Agent 创建新的执行实例。 - /// - /// 只有 Completed/Failed/Cancelled 状态的 Agent 可以被恢复。 - /// 恢复不会篡改旧执行实例，而是为同一个 agent mint 一个新的 `sub_run_id`， - /// 这样 child session 可以沿用稳定身份，同时把新的执行实例显式暴露出来。 - pub async fn resume( - &self, - sub_run_or_agent_id: &str, - parent_turn_id: impl Into, - ) -> Option { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); - - // 先检查状态是否可恢复：只有 lifecycle 不占槽（Idle/Terminated）才可恢复 - if state - .entries - .get(&key) - .is_none_or(|entry| entry.handle.lifecycle.occupies_slot()) - { - return None; - } - - let old_entry = state.entries.get(&key)?; - let old_handle = old_entry.handle.clone(); - let parent_agent_id = old_entry.parent_agent_id.clone(); - let children = old_entry.children.clone(); - - let next_id = self.next_id.fetch_add(1, Ordering::SeqCst) + 1; - let new_sub_run_id = format!("subrun-{next_id}"); - let mut new_handle = old_handle.clone(); - new_handle.sub_run_id = new_sub_run_id.clone().into(); - new_handle.parent_turn_id = parent_turn_id.into().into(); - new_handle.lineage_kind = ChildSessionLineageKind::Resume; - new_handle.lifecycle = AgentLifecycleStatus::Running; - new_handle.last_turn_outcome = None; - - let cancel = CancelToken::new(); - let (status_tx, _status_rx) = watch::channel(new_handle.lifecycle); - let inbox_version = watch::channel(0).0; - - state.active_count += 1; - state.entries.insert( - new_sub_run_id.clone(), - AgentEntry { - handle: new_handle.clone(), - cancel, - status_tx, - parent_agent_id: parent_agent_id.clone(), - children: children.clone(), - finalized_seq: None, - inbox: VecDeque::new(), - inbox_version, - lifecycle_status: AgentLifecycleStatus::Running, - last_turn_outcome: None, - }, - ); - state - .agent_index - .insert(new_handle.agent_id.to_string(), new_sub_run_id.clone()); - - if let Some(parent_agent_id) = parent_agent_id { - if let Some(parent_sub_run_id) = state.agent_index.get(&parent_agent_id).cloned() { - if let Some(parent) = state.entries.get_mut(&parent_sub_run_id) { - parent.children.remove(&key); - parent.children.insert(new_sub_run_id); - } - } - } - - Some(new_handle) - } - - /// 取消指定 Agent，并级联取消其子树。 - pub async fn cancel(&self, sub_run_or_agent_id: &str) -> Option { - let mut state = self.state.write().await; - let mut visited = HashSet::new(); - let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); - let handle = cancel_tree(&mut state, &key, &mut visited, &self.next_finalized_seq); - prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); - handle - } - - /// 按父 turn 取消所有子 Agent。 - /// - /// 这里显式按 parent turn 做传播，而不是把取消关系隐式塞进 `CancelToken`， - /// 因为控制平面只关心“谁挂在谁下面”，不应该把执行器内部任务结构反向泄漏进来。 - pub async fn cancel_for_parent_turn(&self, parent_turn_id: &str) -> Vec { - let mut state = self.state.write().await; - // 只取 parent_turn 的直接子树根，排除嵌套子 agent。 - // 如果 agent 的 parent 也在同一个 turn 下，它是孙子节点， - // 会被祖父级 cancel_tree 级联处理，此处不重复取消。 - let mut roots = state - .entries - .values() - .filter(|entry| entry.handle.parent_turn_id.as_str() == parent_turn_id) - .filter(|entry| { - !entry - .parent_agent_id - .as_ref() - .is_some_and(|parent_agent_id| { - state - .agent_index - .get(parent_agent_id) - .and_then(|parent_sub_run_id| state.entries.get(parent_sub_run_id)) - .is_some_and(|parent| { - parent.handle.parent_turn_id.as_str() == parent_turn_id - }) - }) - }) - .map(|entry| entry.handle.sub_run_id.clone()) - .collect::>(); - roots.sort(); - - let mut cancelled = Vec::new(); - let mut visited = HashSet::new(); - for agent_id in roots { - cancel_tree_collect( - &mut state, - &agent_id, - &mut visited, - &mut cancelled, - &self.next_finalized_seq, - ); - } - prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); - cancelled - } - - /// 等待 Agent 到达终态。 - pub async fn wait(&self, sub_run_or_agent_id: &str) -> Option { - let mut status_rx = { - let state = self.state.read().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?; - state.entries.get(key)?.status_tx.subscribe() - }; - - loop { - let current = *status_rx.borrow_and_update(); - // 等到 agent 不再占槽（turn 完成或已终止） - if !current.occupies_slot() { - return self.get(sub_run_or_agent_id).await; - } - if status_rx.changed().await.is_err() { - return self.get(sub_run_or_agent_id).await; - } - } - } - - /// 向 Agent 收件箱推送一封信封。 - /// - /// 若目标 agent 不存在则返回 None。 - /// 若收件箱已满（超过 `inbox_capacity`）则返回 None。 - /// 推送后会递增收件箱版本号，唤醒正在 wait_for_inbox 的调用方。 - pub async fn push_inbox( - &self, - sub_run_or_agent_id: &str, - envelope: AgentInboxEnvelope, - ) -> Option<()> { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); - let entry = state.entries.get_mut(&key)?; - if entry.inbox.len() >= self.inbox_capacity { - log::warn!( - "inbox 已满 ({}/{}), 丢弃来自 {} 的信封 {}", - entry.inbox.len(), - self.inbox_capacity, - envelope.from_agent_id, - envelope.delivery_id - ); - return None; - } - entry.inbox.push_back(envelope); - // 递增版本号唤醒 wait_for_inbox - let current = *entry.inbox_version.borrow(); - entry.inbox_version.send_replace(current + 1); - Some(()) - } - - /// 排空 Agent 收件箱，返回所有待处理信封。 - pub async fn drain_inbox(&self, sub_run_or_agent_id: &str) -> Option> { - let mut state = self.state.write().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); - let entry = state.entries.get_mut(&key)?; - let envelopes: Vec<_> = entry.inbox.drain(..).collect(); - Some(envelopes) - } - - /// 等待 Agent 收件箱收到新信封。 - /// - /// 若目标不存在或 agent 已到达终态则立即返回 None。 - /// 否则阻塞直到收件箱版本号变化（即有新信封到达）。 - pub async fn wait_for_inbox(&self, sub_run_or_agent_id: &str) -> Option { - let mut inbox_rx = { - let state = self.state.read().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?; - state.entries.get(key)?.inbox_version.subscribe() - }; - - loop { - // 单次读锁内同时获取 handle 和 inbox 状态，避免两次独立读锁竞争 - let (handle, inbox_non_empty) = { - let state = self.state.read().await; - let key = resolve_entry_key(&state, sub_run_or_agent_id)?; - let entry = state.entries.get(key)?; - let handle = entry.handle.clone(); - let inbox_non_empty = !entry.inbox.is_empty(); - (handle, inbox_non_empty) - }; - // 如果 agent 已终态（Terminated），直接返回当前 handle - if handle.lifecycle.is_final() { - return Some(handle); - } - // 如果收件箱非空，返回当前 handle - if inbox_non_empty { - return Some(handle); - } - // 等待收件箱版本号变化 - if inbox_rx.changed().await.is_err() { - return self.get(sub_run_or_agent_id).await; - } - } - } - - /// 向父会话排入一个待消费的 child terminal delivery。 - /// - /// 以 `delivery_id` 做幂等去重；重复交付会被忽略，保持原队列顺序不变。 - /// 队列变更全部限制在单个写锁临界区内完成，避免把异步工作带进锁作用域。 - /// - /// 若队列已满（超过 `parent_delivery_capacity`）则返回 false。 - pub async fn enqueue_parent_delivery( - &self, - parent_session_id: impl Into, - parent_turn_id: impl Into, - notification: astrcode_core::ChildSessionNotification, - ) -> bool { - let mut state = self.state.write().await; - enqueue_parent_delivery_locked( - &mut state, - self.parent_delivery_capacity, - parent_session_id.into(), - parent_turn_id.into(), - notification, - ) - } - - /// 查看并锁定当前父会话最前面的待消费交付。 - /// - /// 只有队头处于 `Queued` 状态时才会返回，并原子地标记为 `WakingParent`， - /// 避免并发唤醒时重复消费同一条交付。 - pub async fn checkout_parent_delivery( - &self, - parent_session_id: &str, - ) -> Option { - let mut state = self.state.write().await; - checkout_parent_delivery_locked(&mut state, parent_session_id) - } - - /// 以 turn-start snapshot drain 的方式锁定一个父级交付批次。 - /// - /// 批次规则： - /// - 只从队头开始抓取连续的 `Queued` 项 - /// - 批内 delivery 必须属于同一个直接父 agent，避免一次 wake turn 混入不同 owner - /// - 抓取后统一标记为 `WakingParent`，后续必须整体 consume 或 requeue - pub async fn checkout_parent_delivery_batch( - &self, - parent_session_id: &str, - ) -> Option> { - let mut state = self.state.write().await; - checkout_parent_delivery_batch_locked(&mut state, parent_session_id) - } - - /// 将正在唤醒中的交付标记回 `Queued`，用于父会话繁忙或启动失败后的重试。 - pub async fn requeue_parent_delivery( - &self, - parent_session_id: &str, - delivery_id: &str, - ) -> bool { - let mut state = self.state.write().await; - requeue_parent_delivery_locked(&mut state, parent_session_id, delivery_id) - } - - /// 将一批正在唤醒中的交付重新标记为 `Queued`。 - pub async fn requeue_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) -> usize { - let mut state = self.state.write().await; - requeue_parent_delivery_batch_locked(&mut state, parent_session_id, delivery_ids) - } - - /// 确认最前面的交付已经被父 turn 消费，并将其从缓冲中移除。 - pub async fn consume_parent_delivery( - &self, - parent_session_id: &str, - delivery_id: &str, - ) -> bool { - let mut state = self.state.write().await; - consume_parent_delivery_locked(&mut state, parent_session_id, delivery_id) - } - - /// 确认一整个交付批次已经被父 turn 消费，并按 FIFO 从队头移除。 - pub async fn consume_parent_delivery_batch( - &self, - parent_session_id: &str, - delivery_ids: &[String], - ) -> bool { - let mut state = self.state.write().await; - consume_parent_delivery_batch_locked(&mut state, parent_session_id, delivery_ids) - } - - pub async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { - let state = self.state.read().await; - pending_parent_delivery_count_locked(&state, parent_session_id) - } - - /// 终止指定 agent 及其整棵子树（四工具模型 close 语义）。 - /// - /// 四工具模型要求 `close` 后 agent - /// 进入 `Terminated` 生命周期，且后续 `send` 被拒绝。 - /// - /// 终止过程中： - /// 1. 对每个节点设置 lifecycle = Terminated - /// 2. 触发 cancel token 以中断正在运行的 turn - /// 3. 级联到所有后代 - pub async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option { - self.terminate_subtree_and_collect_handles(sub_run_or_agent_id) - .await - .and_then(|mut handles| handles.drain(..).next()) - } - - pub(crate) async fn terminate_subtree_and_collect_handles( - &self, - sub_run_or_agent_id: &str, - ) -> Option> { - let mut state = self.state.write().await; - let mut visited = HashSet::new(); - let mut terminated = Vec::new(); - let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); - terminate_tree_collect( - &mut state, - &key, - &mut visited, - &mut terminated, - &self.next_finalized_seq, - )?; - let terminated_agent_ids = terminated - .iter() - .map(|handle| handle.agent_id.clone()) - .collect::>(); - discard_parent_deliveries_locked(&mut state, &terminated_agent_ids); - prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); - Some(terminated) - } - - /// 收集指定 agent 子树的所有 agent handle（不含自身）。 - /// - /// 从给定 agent 出发，递归查找其所有后代 agent， - /// 用于层级协作场景下的子树隔离和级联关闭范围确认。 - pub async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec { - let state = self.state.read().await; - let mut result = Vec::new(); - let mut queue = std::collections::VecDeque::new(); - - // 从直接子节点开始，不包含自身 - if let Some(key) = resolve_entry_key(&state, sub_run_or_agent_id) { - if let Some(entry) = state.entries.get(key) { - for child_sub_run_id in &entry.children { - queue.push_back(child_sub_run_id.clone()); - } - } - } - - while let Some(child_key) = queue.pop_front() { - if let Some(entry) = state.entries.get(&child_key) { - result.push(entry.handle.clone()); - for grandchild in &entry.children { - queue.push_back(grandchild.clone()); - } - } - } - - result - } - - /// 获取指定 agent 的祖先链（从自身到根节点的路径）。 - /// - /// 返回从自身开始向上到根的所有 agent handle， - /// 用于 send 验证直接父路由。 - pub async fn ancestor_chain(&self, sub_run_or_agent_id: &str) -> Vec { - let state = self.state.read().await; - let mut chain = Vec::new(); - - // 先加入自身 - if let Some(key) = resolve_entry_key(&state, sub_run_or_agent_id) { - if let Some(entry) = state.entries.get(key) { - chain.push(entry.handle.clone()); - // 向上遍历父节点 - let mut current_parent = entry.parent_agent_id.clone(); - while let Some(parent_agent_id) = current_parent { - if let Some(parent_key) = state.agent_index.get(&parent_agent_id) { - if let Some(parent_entry) = state.entries.get(parent_key) { - chain.push(parent_entry.handle.clone()); - current_parent = parent_entry.parent_agent_id.clone(); - } else { - break; - } - } else { - break; - } - } - } - } - - chain - } -} - -#[cfg(test)] -mod tests; diff --git a/crates/kernel/src/agent_tree/state.rs b/crates/kernel/src/agent_tree/state.rs deleted file mode 100644 index 63816d94..00000000 --- a/crates/kernel/src/agent_tree/state.rs +++ /dev/null @@ -1,88 +0,0 @@ -use std::collections::{BTreeSet, HashMap, HashSet, VecDeque}; - -use astrcode_core::{ - AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, CancelToken, SubRunHandle, -}; -use tokio::sync::watch; - -use super::PendingParentDelivery; - -/// agent 注册表的可变核心状态，受 `RwLock` 保护。 -/// -/// 所有写入操作通过 `*_locked` 后缀函数在持锁期间完成， -/// 读操作通过快照或 `watch` channel 实现无锁读取。 -#[derive(Default)] -pub(super) struct AgentRegistryState { - /// `sub_run_id → AgentEntry`，所有已注册 agent 的完整信息。 - pub(super) entries: HashMap, - /// `agent_id → sub_run_id`，允许用 agent_id 反查 entry key。 - pub(super) agent_index: HashMap, - /// 当前占用 slot 的活跃 agent 数量（Pending/Running），受 capacity 限制。 - pub(super) active_count: usize, - /// `parent_session_id → ParentDeliveryQueue`，child→parent 终态投递队列。 - pub(super) parent_delivery_queues: HashMap, -} - -pub(super) struct AgentEntry { - pub(super) handle: SubRunHandle, - pub(super) cancel: CancelToken, - pub(super) status_tx: watch::Sender, - pub(super) parent_agent_id: Option, - pub(super) children: BTreeSet, - pub(super) finalized_seq: Option, - /// 协作消息收件箱。send / child-delivery 产出信封存放在此。 - pub(super) inbox: VecDeque, - /// 收件箱版本号，每次 push_inbox 递增，用于 wait_for_inbox 的变化检测。 - pub(super) inbox_version: watch::Sender, - /// 四工具模型的持久生命周期状态。 - /// Pending → Running → Idle → Terminated，完成单轮后不自动终止。 - pub(super) lifecycle_status: AgentLifecycleStatus, - /// 最近一轮执行的结束原因。Running 期间为 None，turn 完成后设为 Some。 - pub(super) last_turn_outcome: Option, -} - -/// delivery 在队列中的生命周期状态。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(super) enum PendingParentDeliveryState { - /// 已入队，等待被 checkout。 - Queued, - /// 已被 checkout，正在唤醒父 agent 消费。 - WakingParent, -} - -/// 队列中的单条投递条目，携带状态以支持 checkout → consume/requeue 生命周期。 -#[derive(Debug, Clone)] -pub(super) struct PendingParentDeliveryEntry { - pub(super) delivery: PendingParentDelivery, - pub(super) state: PendingParentDeliveryState, -} - -/// 按 session 维度的 delivery 队列，FIFO 顺序，配合 dedup set 防止重复入队。 -#[derive(Default)] -pub(super) struct ParentDeliveryQueue { - pub(super) deliveries: VecDeque, - pub(super) known_delivery_ids: HashSet, -} - -/// 根据 sub_run_id 或 agent_id 解析到 entry 的主键（sub_run_id）。 -/// entries 以 sub_run_id 为 key，agent_index 允许用 agent_id 反查。 -pub(super) fn resolve_entry_key<'a>( - state: &'a AgentRegistryState, - sub_run_or_agent_id: &'a str, -) -> Option<&'a str> { - if state.entries.contains_key(sub_run_or_agent_id) { - return Some(sub_run_or_agent_id); - } - state - .agent_index - .get(sub_run_or_agent_id) - .map(String::as_str) -} - -/// 返回指定 agent 的直接子节点 agent_id 列表。 -pub(super) fn entry_children(state: &AgentRegistryState, agent_id: &str) -> Option> { - state - .entries - .get(agent_id) - .map(|entry| entry.children.iter().cloned().collect()) -} diff --git a/crates/kernel/src/agent_tree/tests.rs b/crates/kernel/src/agent_tree/tests.rs deleted file mode 100644 index 4cf571ed..00000000 --- a/crates/kernel/src/agent_tree/tests.rs +++ /dev/null @@ -1,1810 +0,0 @@ -use std::time::Duration; - -use astrcode_core::{ - AgentInboxEnvelope, AgentLifecycleStatus, AgentMode, AgentProfile, AgentTurnOutcome, - ChildAgentRef, ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNotification, - ChildSessionNotificationKind, CompletedParentDeliveryPayload, LiveSubRunControlBoundary, - ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, - ParentExecutionRef, SessionId, SubRunHandle, -}; - -use super::{ - AgentControl, AgentControlError, AgentControlLimits, LiveSubRunControl, - StaticAgentProfileSource, -}; - -fn default_limits() -> AgentControlLimits { - AgentControlLimits::default() -} - -fn completed_delivery(id: &str, message: String) -> ParentDelivery { - ParentDelivery { - idempotency_key: id.to_string(), - origin: ParentDeliveryOrigin::Explicit, - terminal_semantics: ParentDeliveryTerminalSemantics::Terminal, - source_turn_id: Some(format!("turn-{id}")), - payload: ParentDeliveryPayload::Completed(CompletedParentDeliveryPayload { - message, - findings: Vec::new(), - artifacts: Vec::new(), - }), - } -} - -fn explore_profile() -> AgentProfile { - AgentProfile { - id: "explore".to_string(), - name: "Explore".to_string(), - description: "只读探索".to_string(), - mode: AgentMode::SubAgent, - system_prompt: None, - model_preference: Some("fast".to_string()), - } -} - -fn build_child_ref( - agent_id: impl Into, - session_id: impl Into, - sub_run_id: impl Into, - parent_agent_id: Option>, - parent_sub_run_id: Option>, - status: AgentLifecycleStatus, - open_session_id: impl Into, -) -> ChildAgentRef { - ChildAgentRef { - identity: ChildExecutionIdentity { - agent_id: agent_id.into(), - session_id: session_id.into(), - sub_run_id: sub_run_id.into(), - }, - parent: ParentExecutionRef { - parent_agent_id: parent_agent_id.map(Into::into), - parent_sub_run_id: parent_sub_run_id.map(Into::into), - }, - lineage_kind: ChildSessionLineageKind::Spawn, - status, - open_session_id: open_session_id.into(), - } -} - -fn sample_parent_delivery( - notification_id: &str, - parent_session_id: &str, - parent_turn_id: &str, -) -> (String, String, ChildSessionNotification) { - ( - parent_session_id.to_string(), - parent_turn_id.to_string(), - ChildSessionNotification { - notification_id: notification_id.into(), - child_ref: build_child_ref( - format!("agent-{notification_id}"), - parent_session_id, - format!("subrun-{notification_id}"), - None::, - None::, - AgentLifecycleStatus::Idle, - format!("child-session-{notification_id}"), - ), - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: None, - delivery: Some(completed_delivery( - notification_id, - format!("final-{notification_id}"), - )), - }, - ) -} - -fn sample_parent_delivery_for_child( - notification_id: &str, - parent_session_id: &str, - _parent_turn_id: &str, - child: &SubRunHandle, -) -> ChildSessionNotification { - ChildSessionNotification { - notification_id: notification_id.into(), - child_ref: build_child_ref( - child.agent_id.clone(), - parent_session_id, - child.sub_run_id.clone(), - child.parent_agent_id.clone(), - child.parent_sub_run_id.clone(), - child.lifecycle, - child - .child_session_id - .clone() - .unwrap_or_else(|| child.session_id.clone()), - ), - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: None, - delivery: Some(completed_delivery( - notification_id, - format!("final-{notification_id}"), - )), - } -} - -#[tokio::test] -async fn spawn_list_and_wait_track_status() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - - assert_eq!(handle.lifecycle, AgentLifecycleStatus::Pending); - assert_eq!(control.list().await.len(), 1); - - let agent_id = handle.agent_id.clone(); - let waiter = { - let control = control.clone(); - tokio::spawn(async move { control.wait(&agent_id).await }) - }; - // 先让 waiter 完成订阅，避免测试依赖调度时序而偶发卡住。 - tokio::task::yield_now().await; - - control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await - .expect("agent should exist"); - let running = control - .get(&handle.agent_id) - .await - .expect("agent should exist"); - assert_eq!(running.lifecycle, AgentLifecycleStatus::Running); - - control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Completed) - .await - .expect("agent should exist"); - let completed = control - .get(&handle.agent_id) - .await - .expect("agent should exist"); - assert_eq!(completed.lifecycle, AgentLifecycleStatus::Idle); - - let waited = tokio::time::timeout(Duration::from_secs(5), waiter) - .await - .expect("waiter should finish before timeout") - .expect("waiter should join"); - assert_eq!( - waited.expect("wait should resolve").lifecycle, - AgentLifecycleStatus::Idle - ); -} - -#[tokio::test] -async fn cancelling_parent_turn_cascades_to_children() { - // 需要 depth >= 2 才能测试 parent → child 嵌套 - let control = AgentControl::with_limits(3, 10, 256); - let parent = control - .spawn( - &explore_profile(), - "session-parent", - "turn-root".to_string(), - None, - ) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&parent.agent_id, AgentLifecycleStatus::Running) - .await; - - let child = control - .spawn( - &explore_profile(), - "session-child", - "turn-root".to_string(), - Some(parent.agent_id.to_string()), - ) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&child.agent_id, AgentLifecycleStatus::Running) - .await; - - let cancelled = control.cancel_for_parent_turn("turn-root").await; - assert_eq!(cancelled.len(), 2); - - let parent_handle = control - .get(&parent.agent_id) - .await - .expect("parent should exist"); - let child_handle = control - .get(&child.agent_id) - .await - .expect("child should exist"); - assert_eq!(parent_handle.lifecycle, AgentLifecycleStatus::Terminated); - assert_eq!(child_handle.lifecycle, AgentLifecycleStatus::Terminated); - - let child_cancel = control - .cancel_token(&child.agent_id) - .await - .expect("child cancel token should exist"); - assert!(child_cancel.is_cancelled()); -} - -#[tokio::test] -async fn spawn_rejects_unknown_parent_agent() { - let control = AgentControl::new(); - - let error = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some("missing-parent".to_string()), - ) - .await - .expect_err("spawn should reject unknown parent"); - - assert_eq!( - error, - AgentControlError::ParentAgentNotFound { - agent_id: "missing-parent".to_string(), - } - ); - assert!(control.list().await.is_empty()); -} - -#[tokio::test] -async fn failed_spawn_does_not_consume_agent_id() { - let control = AgentControl::new(); - - let _ = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some("missing-parent".to_string()), - ) - .await - .expect_err("spawn should reject unknown parent"); - - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("first successful spawn should still get the first id"); - - assert_eq!(handle.agent_id.as_str(), "agent-1"); -} - -#[tokio::test] -async fn cancel_directly_cascades_to_child_tree() { - // 需要 depth >= 3 才能测试 parent → child → grandchild 嵌套 - let control = AgentControl::with_limits(3, 10, 256); - let parent = control - .spawn( - &explore_profile(), - "session-parent", - "turn-root".to_string(), - None, - ) - .await - .expect("parent spawn should succeed"); - let child = control - .spawn( - &explore_profile(), - "session-child", - "turn-root".to_string(), - Some(parent.agent_id.to_string()), - ) - .await - .expect("child spawn should succeed"); - let grandchild = control - .spawn( - &explore_profile(), - "session-grandchild", - "turn-root".to_string(), - Some(child.agent_id.to_string()), - ) - .await - .expect("grandchild spawn should succeed"); - let _ = control - .set_lifecycle(&parent.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&child.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&grandchild.agent_id, AgentLifecycleStatus::Running) - .await; - - let cancelled = control - .cancel(&parent.agent_id) - .await - .expect("parent cancel should exist"); - assert_eq!(cancelled.lifecycle, AgentLifecycleStatus::Terminated); - - for agent_id in [&parent.agent_id, &child.agent_id, &grandchild.agent_id] { - let handle = control - .get(agent_id) - .await - .expect("agent should still exist"); - assert_eq!(handle.lifecycle, AgentLifecycleStatus::Terminated); - } -} - -#[tokio::test] -async fn mark_failed_transitions_agent_to_final_failed_state() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Failed) - .await - .expect("agent should exist"); - let failed = control - .get(&handle.agent_id) - .await - .expect("agent should exist"); - assert_eq!(failed.lifecycle, AgentLifecycleStatus::Idle); - - let waited = control - .wait(&handle.agent_id) - .await - .expect("failed agent should still be queryable"); - assert_eq!(waited.lifecycle, AgentLifecycleStatus::Idle); -} - -#[tokio::test] -async fn gc_prunes_old_finalized_leaf_agents_but_keeps_recent_and_live_nodes() { - let limits = default_limits(); - let control = AgentControl::with_limits(limits.max_depth, limits.max_concurrent, 1); - - let first = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("first spawn should succeed"); - let second = control - .spawn(&explore_profile(), "session-1", "turn-2".to_string(), None) - .await - .expect("second spawn should succeed"); - let live = control - .spawn(&explore_profile(), "session-1", "turn-3".to_string(), None) - .await - .expect("live spawn should succeed"); - - let _ = control - .complete_turn(&first.agent_id, AgentTurnOutcome::Completed) - .await; - let _ = control - .complete_turn(&second.agent_id, AgentTurnOutcome::Failed) - .await; - - let handles = control.list().await; - assert_eq!( - handles.len(), - 2, - "gc should evict the oldest finalized leaf" - ); - assert!(control.get(&first.agent_id).await.is_none()); - assert_eq!( - control - .get(&second.agent_id) - .await - .expect("newer finalized agent") - .lifecycle, - AgentLifecycleStatus::Idle - ); - assert_eq!( - control - .get(&live.agent_id) - .await - .expect("live agent should remain") - .lifecycle, - AgentLifecycleStatus::Pending - ); -} - -#[tokio::test] -async fn spawn_rejects_agents_that_exceed_max_depth() { - let control = AgentControl::with_limits(2, 8, usize::MAX); - let root = control - .spawn( - &explore_profile(), - "session-root", - "turn-root".to_string(), - None, - ) - .await - .expect("root should fit within depth 1"); - let child = control - .spawn( - &explore_profile(), - "session-child", - "turn-root".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("child should fit within depth 2"); - assert_eq!(root.depth, 1); - assert_eq!(child.depth, 2); - - let error = control - .spawn( - &explore_profile(), - "session-grandchild", - "turn-root".to_string(), - Some(child.agent_id.to_string()), - ) - .await - .expect_err("grandchild should exceed max depth"); - assert_eq!( - error, - AgentControlError::MaxDepthExceeded { current: 3, max: 2 } - ); -} - -#[tokio::test] -async fn finalized_agents_release_concurrency_slots() { - let control = AgentControl::with_limits(8, 2, usize::MAX); - let first = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("first spawn should succeed"); - let second = control - .spawn(&explore_profile(), "session-2", "turn-2".to_string(), None) - .await - .expect("second spawn should succeed"); - - let error = control - .spawn(&explore_profile(), "session-3", "turn-3".to_string(), None) - .await - .expect_err("third active agent should exceed concurrent limit"); - assert_eq!( - error, - AgentControlError::MaxConcurrentExceeded { current: 2, max: 2 } - ); - - let _ = control - .complete_turn(&first.agent_id, AgentTurnOutcome::Completed) - .await; - let third = control - .spawn(&explore_profile(), "session-3", "turn-3".to_string(), None) - .await - .expect("finalizing one agent should release a slot"); - assert_eq!(third.depth, 1); - assert_eq!( - control - .get(&second.agent_id) - .await - .expect("second should still exist") - .lifecycle, - AgentLifecycleStatus::Pending - ); -} - -#[tokio::test] -async fn live_subrun_control_surface_delegates_registry_and_profiles() { - let control = AgentControl::new(); - let profile = explore_profile(); - let handle = control - .spawn(&profile, "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let surface = LiveSubRunControl::new( - control.clone(), - StaticAgentProfileSource::new(vec![profile.clone()]), - ); - let session_id = SessionId::from("session-1"); - - let loaded = surface - .get_subrun_handle(&session_id, &handle.sub_run_id) - .await - .expect("lookup should succeed") - .expect("handle should exist"); - assert_eq!(loaded.agent_id, handle.agent_id); - assert_eq!( - surface - .list_profiles() - .await - .expect("profiles should load") - .len(), - 1 - ); - - surface - .cancel_subrun(&session_id, &handle.sub_run_id) - .await - .expect("cancel should succeed"); - assert_eq!( - control - .get(&handle.sub_run_id) - .await - .expect("handle should remain visible") - .lifecycle, - AgentLifecycleStatus::Terminated - ); -} - -// ─── T028 协作操作运行时测试 ─────────────────────────── - -#[tokio::test] -async fn targeted_wait_resolves_only_specific_agent_not_siblings() { - let control = AgentControl::with_limits(3, 10, 256); - let agent_a = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("agent A spawn should succeed"); - let agent_b = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("agent B spawn should succeed"); - let _ = control - .set_lifecycle(&agent_a.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&agent_b.agent_id, AgentLifecycleStatus::Running) - .await; - - // 只完成 agent_a，agent_b 仍运行中 - let _ = control - .complete_turn(&agent_a.agent_id, AgentTurnOutcome::Completed) - .await; - - // wait 应该立即返回已终态的 agent_a - let waited = control - .wait(&agent_a.agent_id) - .await - .expect("wait should resolve"); - assert_eq!(waited.lifecycle, AgentLifecycleStatus::Idle); - - // agent_b 仍然处于 Running 状态，不受影响 - let b_handle = control - .get(&agent_b.agent_id) - .await - .expect("agent B should exist"); - assert_eq!(b_handle.lifecycle, AgentLifecycleStatus::Running); -} - -#[tokio::test] -async fn resume_mints_new_execution_for_completed_agent() { - let control = AgentControl::with_limits(3, 10, 256); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Completed) - .await; - - // 恢复已完成的 agent - let resumed = control - .resume(&handle.agent_id, "turn-2") - .await - .expect("resume should succeed"); - assert_eq!(resumed.lifecycle, AgentLifecycleStatus::Running); - assert_eq!(resumed.agent_id, handle.agent_id); - assert_eq!(resumed.parent_turn_id, "turn-2".into()); - assert_eq!(resumed.lineage_kind, ChildSessionLineageKind::Resume); - assert_ne!( - resumed.sub_run_id, handle.sub_run_id, - "resume should mint a new execution id" - ); - - let historical = control - .get(&handle.sub_run_id) - .await - .expect("historical execution should remain queryable by old sub-run id"); - assert_eq!(historical.lifecycle, AgentLifecycleStatus::Idle); - - // 验证恢复后能再次正常到达终态 - let _ = control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Completed) - .await; - let final_handle = control - .get(&handle.agent_id) - .await - .expect("agent should exist"); - assert_eq!(final_handle.lifecycle, AgentLifecycleStatus::Idle); -} - -#[tokio::test] -async fn resume_rejects_non_final_agent() { - let control = AgentControl::with_limits(3, 10, 256); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - // Running 状态的 agent 不能被恢复 - let result = control.resume(&handle.agent_id, "turn-2").await; - assert!(result.is_none(), "running agent should not be resumable"); -} - -#[tokio::test] -async fn close_cascades_to_entire_subtree_but_not_siblings() { - let control = AgentControl::with_limits(4, 10, 256); - - // 构建两棵独立子树 - let tree_a_parent = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("tree A parent spawn should succeed"); - let tree_a_child = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(tree_a_parent.agent_id.to_string()), - ) - .await - .expect("tree A child spawn should succeed"); - - let tree_b_parent = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("tree B parent spawn should succeed"); - let _tree_b_child = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(tree_b_parent.agent_id.to_string()), - ) - .await - .expect("tree B child spawn should succeed"); - - let _ = control - .set_lifecycle(&tree_a_parent.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&tree_a_child.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&tree_b_parent.agent_id, AgentLifecycleStatus::Running) - .await; - - // 关闭 tree A 的根，应级联到 tree A 的 child - let cancelled = control - .cancel(&tree_a_parent.agent_id) - .await - .expect("cancel should succeed"); - assert_eq!(cancelled.lifecycle, AgentLifecycleStatus::Terminated); - - // tree A 的 parent 和 child 都被取消 - assert_eq!( - control - .get(&tree_a_parent.agent_id) - .await - .expect("should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - assert_eq!( - control - .get(&tree_a_child.agent_id) - .await - .expect("should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - - // tree B 不受影响 - assert_eq!( - control - .get(&tree_b_parent.agent_id) - .await - .expect("should exist") - .lifecycle, - AgentLifecycleStatus::Running - ); -} - -#[tokio::test] -async fn terminate_subtree_and_collect_handles_survives_pruning_closed_branch() { - let control = AgentControl::with_limits(4, 10, 0); - let parent = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("parent spawn should succeed"); - let child = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(parent.agent_id.to_string()), - ) - .await - .expect("child spawn should succeed"); - let grandchild = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(child.agent_id.to_string()), - ) - .await - .expect("grandchild spawn should succeed"); - - let closed = control - .terminate_subtree_and_collect_handles(&parent.agent_id) - .await - .expect("terminate should succeed"); - - assert_eq!( - closed - .iter() - .map(|handle| handle.agent_id.as_str()) - .collect::>(), - vec![ - parent.agent_id.as_str(), - child.agent_id.as_str(), - grandchild.agent_id.as_str() - ] - ); - assert!( - control.get(&parent.agent_id).await.is_none(), - "retain limit 0 should prune the terminated branch from registry" - ); -} - -#[tokio::test] -async fn resume_reoccupies_concurrency_slot() { - let control = AgentControl::with_limits(8, 2, usize::MAX); - let first = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("first spawn should succeed"); - let _second = control - .spawn(&explore_profile(), "session-2", "turn-2".to_string(), None) - .await - .expect("second spawn should succeed"); - - let _ = control - .set_lifecycle(&first.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .complete_turn(&first.agent_id, AgentTurnOutcome::Completed) - .await; - - // first 完成后释放了槽位，可以创建第三个 - let _third = control - .spawn(&explore_profile(), "session-3", "turn-3".to_string(), None) - .await - .expect("third spawn should succeed after first completed"); - - // 恢复 first 会重新占用槽位，此时已有 3 个活跃（first resumed + second + third） - let _ = control.resume(&first.agent_id, "turn-1b").await; - - let error = control - .spawn(&explore_profile(), "session-4", "turn-4".to_string(), None) - .await - .expect_err("should exceed concurrent limit after resume"); - assert_eq!( - error, - AgentControlError::MaxConcurrentExceeded { current: 3, max: 2 } - ); -} - -// ─── 收件箱测试 ────────────────────────────────────── - -fn sample_envelope(id: &str, from: &str, to: &str, message: &str) -> AgentInboxEnvelope { - AgentInboxEnvelope { - delivery_id: id.to_string(), - from_agent_id: from.to_string(), - to_agent_id: to.to_string(), - kind: astrcode_core::InboxEnvelopeKind::ParentMessage, - message: message.to_string(), - context: None, - is_final: false, - summary: None, - findings: Vec::new(), - artifacts: Vec::new(), - } -} - -#[tokio::test] -async fn push_and_drain_inbox_enqueues_and_consumes_envelopes() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - // 推送两封信封 - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-1", "agent-parent", &handle.agent_id, "请修改"), - ) - .await - .expect("push should succeed"); - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-2", "agent-parent", &handle.agent_id, "补充说明"), - ) - .await - .expect("push should succeed"); - - // 排空收件箱 - let envelopes = control - .drain_inbox(&handle.agent_id) - .await - .expect("drain should succeed"); - assert_eq!(envelopes.len(), 2); - assert_eq!(envelopes[0].delivery_id, "d-1"); - assert_eq!(envelopes[1].delivery_id, "d-2"); - - // 二次排空为空 - let empty = control - .drain_inbox(&handle.agent_id) - .await - .expect("drain should succeed"); - assert!(empty.is_empty()); -} - -#[tokio::test] -async fn complete_turn_moves_agent_into_idle_with_last_outcome() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - let lifecycle = control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Completed) - .await - .expect("complete turn should succeed"); - assert_eq!(lifecycle, AgentLifecycleStatus::Idle); - assert_eq!( - control.get_lifecycle(&handle.agent_id).await, - Some(AgentLifecycleStatus::Idle) - ); - assert_eq!( - control.get_turn_outcome(&handle.agent_id).await, - Some(Some(AgentTurnOutcome::Completed)) - ); - assert_eq!( - control - .get(&handle.agent_id) - .await - .expect("completed handle should remain queryable") - .lifecycle, - AgentLifecycleStatus::Idle - ); -} - -#[tokio::test] -async fn push_inbox_deduplication_by_delivery_id() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - - // 推送相同 delivery_id 的信封两次 - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-dup", "agent-parent", &handle.agent_id, "消息"), - ) - .await - .expect("push should succeed"); - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-dup", "agent-parent", &handle.agent_id, "消息"), - ) - .await - .expect("push should succeed"); - - // 当前实现不内置去重，由调用方保证幂等； - // 验证两封信封都入队（调用方负责 dedupe 语义） - let envelopes = control - .drain_inbox(&handle.agent_id) - .await - .expect("drain should succeed"); - assert_eq!(envelopes.len(), 2); -} - -#[tokio::test] -async fn wait_for_inbox_resolves_on_new_envelope() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - let agent_id = handle.agent_id.clone(); - let control_clone = control.clone(); - let waiter = tokio::spawn(async move { control_clone.wait_for_inbox(&agent_id).await }); - - // 让 waiter 完成订阅 - tokio::task::yield_now().await; - - // 推送信封唤醒 waiter - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-wait", "agent-parent", &handle.agent_id, "唤醒"), - ) - .await - .expect("push should succeed"); - - let result = tokio::time::timeout(Duration::from_secs(3), waiter) - .await - .expect("waiter should finish before timeout") - .expect("waiter should join"); - assert!(result.is_some()); -} - -#[tokio::test] -async fn terminate_subtree_clears_pending_inbox_messages() { - let control = AgentControl::with_limits(4, 16, 256); - let parent = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("parent spawn should succeed"); - let child = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(parent.agent_id.to_string()), - ) - .await - .expect("child spawn should succeed"); - let _ = control - .set_lifecycle(&parent.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&child.agent_id, AgentLifecycleStatus::Running) - .await; - - control - .push_inbox( - &child.agent_id, - sample_envelope("d-close", "agent-parent", &child.agent_id, "终止前排队消息"), - ) - .await - .expect("push should succeed"); - - control - .terminate_subtree(&parent.agent_id) - .await - .expect("terminate subtree should succeed"); - - let child_inbox = control - .drain_inbox(&child.agent_id) - .await - .expect("drain should succeed after close"); - assert!(child_inbox.is_empty()); - assert_eq!( - control.get_lifecycle(&child.agent_id).await, - Some(AgentLifecycleStatus::Terminated) - ); -} - -#[tokio::test] -async fn terminate_subtree_discards_pending_parent_deliveries_for_closed_branch() { - let control = AgentControl::with_limits(4, 16, 256); - let root = control - .spawn( - &explore_profile(), - "session-parent", - "turn-root".to_string(), - None, - ) - .await - .expect("root spawn should succeed"); - let child = control - .spawn( - &explore_profile(), - "session-child-a", - "turn-root".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("child spawn should succeed"); - let sibling = control - .spawn( - &explore_profile(), - "session-child-b", - "turn-root".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("sibling spawn should succeed"); - - let session_id = "session-parent".to_string(); - let turn_id = "turn-root".to_string(); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - sample_parent_delivery_for_child("closed-branch", &session_id, &turn_id, &child,) - ) - .await - ); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - sample_parent_delivery_for_child("live-branch", &session_id, &turn_id, &sibling,) - ) - .await - ); - assert_eq!(control.pending_parent_delivery_count(&session_id).await, 2); - - control - .terminate_subtree(&child.agent_id) - .await - .expect("terminate should succeed"); - - assert_eq!(control.pending_parent_delivery_count(&session_id).await, 1); - let remaining = control - .checkout_parent_delivery(&session_id) - .await - .expect("sibling delivery should remain queued"); - assert_eq!( - remaining.notification.child_ref.agent_id(), - &sibling.agent_id - ); -} - -#[tokio::test] -async fn wait_for_inbox_returns_immediately_for_final_agent() { - let control = AgentControl::new(); - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .complete_turn(&handle.agent_id, AgentTurnOutcome::Completed) - .await; - - // complete_turn 后 lifecycle 为 Idle（非 Terminated）， - // wait_for_inbox 需要看到 is_final() 才立即返回。 - // 但 Idle 不是 final，所以先 terminate 使之成为 Terminated。 - // 先恢复为 Running 再 terminate - let _ = control.resume(&handle.agent_id, "turn-2").await; - control - .terminate_subtree(&handle.agent_id) - .await - .expect("terminate should succeed"); - - let result = control - .wait_for_inbox(&handle.agent_id) - .await - .expect("should resolve immediately"); - assert_eq!(result.lifecycle, AgentLifecycleStatus::Terminated); -} - -#[tokio::test] -async fn push_inbox_returns_none_for_nonexistent_agent() { - let control = AgentControl::new(); - let result = control - .push_inbox( - "missing-agent", - sample_envelope("d-1", "agent-parent", "missing-agent", "消息"), - ) - .await; - assert!(result.is_none()); -} - -#[tokio::test] -async fn parent_delivery_queue_deduplicates_and_preserves_fifo_order() { - let control = AgentControl::new(); - let (session_id, turn_id, first) = - sample_parent_delivery("delivery-1", "session-parent", "turn-parent"); - let (_, _, duplicate) = sample_parent_delivery("delivery-1", "session-parent", "turn-parent"); - let (_, _, second) = sample_parent_delivery("delivery-2", "session-parent", "turn-parent"); - - assert!( - control - .enqueue_parent_delivery(session_id.clone(), turn_id.clone(), first) - .await - ); - assert!( - !control - .enqueue_parent_delivery(session_id.clone(), turn_id.clone(), duplicate) - .await - ); - assert!( - control - .enqueue_parent_delivery(session_id.clone(), turn_id, second) - .await - ); - - let first_checked_out = control - .checkout_parent_delivery(&session_id) - .await - .expect("first queued delivery should be available"); - assert_eq!(first_checked_out.delivery_id, "delivery-1"); - assert!( - control - .consume_parent_delivery(&session_id, &first_checked_out.delivery_id) - .await - ); - - let second_checked_out = control - .checkout_parent_delivery(&session_id) - .await - .expect("second queued delivery should be available"); - assert_eq!(second_checked_out.delivery_id, "delivery-2"); - assert_eq!(control.pending_parent_delivery_count(&session_id).await, 1); -} - -#[tokio::test] -async fn parent_delivery_queue_can_requeue_busy_head_without_losing_it() { - let control = AgentControl::new(); - let (session_id, turn_id, delivery) = - sample_parent_delivery("delivery-busy", "session-parent", "turn-parent"); - - assert!( - control - .enqueue_parent_delivery(session_id.clone(), turn_id, delivery) - .await - ); - - let checked_out = control - .checkout_parent_delivery(&session_id) - .await - .expect("delivery should be checked out"); - assert!( - control - .checkout_parent_delivery(&session_id) - .await - .is_none(), - "waking delivery should block duplicate checkout" - ); - - assert!( - control - .requeue_parent_delivery(&session_id, &checked_out.delivery_id) - .await - ); - - let retried = control - .checkout_parent_delivery(&session_id) - .await - .expect("requeued delivery should become available again"); - assert_eq!(retried.delivery_id, checked_out.delivery_id); - assert!( - control - .consume_parent_delivery(&session_id, &retried.delivery_id) - .await - ); - assert_eq!(control.pending_parent_delivery_count(&session_id).await, 0); -} - -#[tokio::test] -async fn parent_delivery_batch_checkout_uses_turn_start_snapshot_for_same_parent_agent() { - let control = AgentControl::new(); - let session_id = "session-parent".to_string(); - let turn_id = "turn-parent".to_string(); - let make_delivery = - |delivery_id: &str, child_id: &str, parent_agent_id: &str| ChildSessionNotification { - notification_id: delivery_id.into(), - child_ref: build_child_ref( - child_id, - session_id.clone(), - format!("subrun-{delivery_id}"), - Some(parent_agent_id), - Some(format!("subrun-{parent_agent_id}")), - AgentLifecycleStatus::Idle, - format!("child-session-{delivery_id}"), - ), - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: None, - delivery: Some(completed_delivery( - delivery_id, - format!("final-{delivery_id}"), - )), - }; - - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - make_delivery("delivery-1", "agent-child-1", "agent-parent-a"), - ) - .await - ); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - make_delivery("delivery-2", "agent-child-2", "agent-parent-a"), - ) - .await - ); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id, - make_delivery("delivery-3", "agent-child-3", "agent-parent-b"), - ) - .await - ); - - let first_batch = control - .checkout_parent_delivery_batch(&session_id) - .await - .expect("same parent-agent head deliveries should form a batch"); - assert_eq!( - first_batch - .iter() - .map(|delivery| delivery.delivery_id.as_str()) - .collect::>(), - vec!["delivery-1", "delivery-2"] - ); - assert!( - control - .checkout_parent_delivery_batch(&session_id) - .await - .is_none(), - "head batch is already waking; next batch must wait for consume/requeue" - ); - assert!( - control - .consume_parent_delivery_batch( - &session_id, - &first_batch - .iter() - .map(|delivery| delivery.delivery_id.clone()) - .collect::>(), - ) - .await - ); - - let second_batch = control - .checkout_parent_delivery_batch(&session_id) - .await - .expect("next parent-agent group should become the next batch"); - assert_eq!(second_batch.len(), 1); - assert_eq!(second_batch[0].delivery_id, "delivery-3"); -} - -#[tokio::test] -async fn parent_delivery_batch_requeue_restores_started_snapshot_for_retry() { - let control = AgentControl::new(); - let session_id = "session-parent".to_string(); - let turn_id = "turn-parent".to_string(); - let make_delivery = - |delivery_id: &str, child_id: &str, parent_agent_id: &str| ChildSessionNotification { - notification_id: delivery_id.into(), - child_ref: build_child_ref( - child_id, - session_id.clone(), - format!("subrun-{delivery_id}"), - Some(parent_agent_id), - Some(format!("subrun-{parent_agent_id}")), - AgentLifecycleStatus::Idle, - format!("child-session-{delivery_id}"), - ), - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: None, - delivery: Some(completed_delivery( - delivery_id, - format!("final-{delivery_id}"), - )), - }; - - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - make_delivery("delivery-1", "agent-child-1", "agent-parent-a"), - ) - .await - ); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id, - make_delivery("delivery-2", "agent-child-2", "agent-parent-a"), - ) - .await - ); - - let started_batch = control - .checkout_parent_delivery_batch(&session_id) - .await - .expect("queued deliveries should form a started batch"); - let delivery_ids = started_batch - .iter() - .map(|delivery| delivery.delivery_id.clone()) - .collect::>(); - assert_eq!( - delivery_ids, - vec!["delivery-1".to_string(), "delivery-2".to_string()] - ); - - assert_eq!( - control - .requeue_parent_delivery_batch(&session_id, &delivery_ids) - .await, - 2 - ); - - let replayed_batch = control - .checkout_parent_delivery_batch(&session_id) - .await - .expect("requeued started batch should become available again"); - assert_eq!( - replayed_batch - .iter() - .map(|delivery| delivery.delivery_id.as_str()) - .collect::>(), - vec!["delivery-1", "delivery-2"] - ); -} - -// ─── T035 层级协作回归测试 ──────────────────────────── - -/// 验证级联关闭是 leaf-first 语义： -/// 三层链 root → middle → leaf，关闭 middle 时， -/// leaf 先被取消（子树从叶子向上传播），root 不受影响。 -#[tokio::test] -async fn leaf_first_cascade_cancels_deepest_child_before_parent() { - let control = AgentControl::with_limits(4, 10, 256); - - let root = control - .spawn( - &explore_profile(), - "session-root", - "turn-1".to_string(), - None, - ) - .await - .expect("root spawn should succeed"); - let middle = control - .spawn( - &explore_profile(), - "session-middle", - "turn-1".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("middle spawn should succeed"); - let leaf = control - .spawn( - &explore_profile(), - "session-leaf", - "turn-1".to_string(), - Some(middle.agent_id.to_string()), - ) - .await - .expect("leaf spawn should succeed"); - let _ = control - .set_lifecycle(&root.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&middle.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&leaf.agent_id, AgentLifecycleStatus::Running) - .await; - - // 关闭 middle，应级联到 leaf，但不影响 root - let cancelled = control - .cancel(&middle.agent_id) - .await - .expect("cancel should succeed"); - assert_eq!(cancelled.lifecycle, AgentLifecycleStatus::Terminated); - - // middle 和 leaf 都被取消 - assert_eq!( - control - .get(&middle.agent_id) - .await - .expect("middle should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - assert_eq!( - control - .get(&leaf.agent_id) - .await - .expect("leaf should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - - // root 不受影响 - assert_eq!( - control - .get(&root.agent_id) - .await - .expect("root should exist") - .lifecycle, - AgentLifecycleStatus::Running - ); -} - -/// 验证子树隔离：关闭一个分支的中间节点不会影响兄弟分支。 -/// root → middle_a → leaf_a -/// root → middle_b → leaf_b -/// 关闭 middle_a 只影响 middle_a + leaf_a，middle_b + leaf_b 不受影响。 -#[tokio::test] -async fn subtree_isolation_closing_one_branch_does_not_affect_sibling_branch() { - let control = AgentControl::with_limits(4, 10, 256); - - let root = control - .spawn( - &explore_profile(), - "session-root", - "turn-1".to_string(), - None, - ) - .await - .expect("root spawn should succeed"); - let middle_a = control - .spawn( - &explore_profile(), - "session-middle-a", - "turn-1".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("middle_a spawn should succeed"); - let leaf_a = control - .spawn( - &explore_profile(), - "session-leaf-a", - "turn-1".to_string(), - Some(middle_a.agent_id.to_string()), - ) - .await - .expect("leaf_a spawn should succeed"); - let middle_b = control - .spawn( - &explore_profile(), - "session-middle-b", - "turn-1".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("middle_b spawn should succeed"); - let leaf_b = control - .spawn( - &explore_profile(), - "session-leaf-b", - "turn-1".to_string(), - Some(middle_b.agent_id.to_string()), - ) - .await - .expect("leaf_b spawn should succeed"); - - let _ = control - .set_lifecycle(&root.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&middle_a.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&leaf_a.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&middle_b.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&leaf_b.agent_id, AgentLifecycleStatus::Running) - .await; - - // 关闭 middle_a 分支 - let _ = control - .cancel(&middle_a.agent_id) - .await - .expect("cancel should succeed"); - - // branch A 全部被取消 - assert_eq!( - control - .get(&middle_a.agent_id) - .await - .expect("middle_a should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - assert_eq!( - control - .get(&leaf_a.agent_id) - .await - .expect("leaf_a should exist") - .lifecycle, - AgentLifecycleStatus::Terminated - ); - - // branch B 完全不受影响 - assert_eq!( - control - .get(&middle_b.agent_id) - .await - .expect("middle_b should exist") - .lifecycle, - AgentLifecycleStatus::Running - ); - assert_eq!( - control - .get(&leaf_b.agent_id) - .await - .expect("leaf_b should exist") - .lifecycle, - AgentLifecycleStatus::Running - ); - - // root 也不受影响 - assert_eq!( - control - .get(&root.agent_id) - .await - .expect("root should exist") - .lifecycle, - AgentLifecycleStatus::Running - ); -} - -/// 验证子向父 send 只投递给直接父 agent，不越级投递到祖父 agent。 -/// root → middle → leaf -/// leaf 通过 send 只能投递到 middle 的 inbox， -/// root 的 inbox 不应收到 leaf 的投递。 -#[tokio::test] -async fn deliver_to_parent_only_reaches_direct_parent_not_grandparent() { - let control = AgentControl::with_limits(4, 10, 256); - - let root = control - .spawn( - &explore_profile(), - "session-root", - "turn-1".to_string(), - None, - ) - .await - .expect("root spawn should succeed"); - let middle = control - .spawn( - &explore_profile(), - "session-middle", - "turn-1".to_string(), - Some(root.agent_id.to_string()), - ) - .await - .expect("middle spawn should succeed"); - let leaf = control - .spawn( - &explore_profile(), - "session-leaf", - "turn-1".to_string(), - Some(middle.agent_id.to_string()), - ) - .await - .expect("leaf spawn should succeed"); - let _ = control - .set_lifecycle(&root.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&middle.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&leaf.agent_id, AgentLifecycleStatus::Running) - .await; - - // leaf 向直接父 (middle) 投递 - let leaf_delivery = AgentInboxEnvelope { - delivery_id: "delivery-leaf-to-middle".to_string(), - from_agent_id: leaf.agent_id.to_string(), - to_agent_id: middle.agent_id.to_string(), - kind: astrcode_core::InboxEnvelopeKind::ChildDelivery, - message: "leaf 的结果".to_string(), - context: None, - is_final: true, - summary: Some("leaf 完成了任务".to_string()), - findings: vec!["发现1".to_string()], - artifacts: Vec::new(), - }; - - control - .push_inbox(&middle.agent_id, leaf_delivery) - .await - .expect("push to middle should succeed"); - - // middle 的 inbox 应该有 leaf 的投递 - let middle_inbox = control - .drain_inbox(&middle.agent_id) - .await - .expect("drain middle inbox should succeed"); - assert_eq!(middle_inbox.len(), 1); - assert_eq!(middle_inbox[0].from_agent_id, leaf.agent_id.to_string()); - assert_eq!( - middle_inbox[0].kind, - astrcode_core::InboxEnvelopeKind::ChildDelivery - ); - assert!(middle_inbox[0].is_final); - - // root 的 inbox 应该为空（leaf 不能越级投递） - let root_inbox = control - .drain_inbox(&root.agent_id) - .await - .expect("drain root inbox should succeed"); - assert!( - root_inbox.is_empty(), - "leaf delivery should not reach grandparent inbox" - ); -} - -/// 验证 wait_for_inbox 在 agent 被 terminate_subtree 后能被正确唤醒， -/// 并返回终态 handle 而非永远阻塞。 -#[tokio::test] -async fn wait_for_inbox_resolves_on_terminate_subtree() { - let control = AgentControl::with_limits(4, 10, 256); - let parent = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("parent spawn should succeed"); - let child = control - .spawn( - &explore_profile(), - "session-1", - "turn-1".to_string(), - Some(parent.agent_id.to_string()), - ) - .await - .expect("child spawn should succeed"); - let _ = control - .set_lifecycle(&parent.agent_id, AgentLifecycleStatus::Running) - .await; - let _ = control - .set_lifecycle(&child.agent_id, AgentLifecycleStatus::Running) - .await; - - // 在另一个任务中等待 child 的 inbox - let child_id = child.agent_id.clone(); - let control_clone = control.clone(); - let waiter = tokio::spawn(async move { control_clone.wait_for_inbox(&child_id).await }); - - // 让 waiter 完成订阅 - tokio::task::yield_now().await; - - // terminate parent 的子树，应级联 terminate child 并唤醒 wait_for_inbox - control - .terminate_subtree(&parent.agent_id) - .await - .expect("terminate should succeed"); - - let result = tokio::time::timeout(Duration::from_secs(3), waiter) - .await - .expect("waiter should finish before timeout") - .expect("waiter should join"); - assert!( - result.is_some(), - "wait_for_inbox should return Some after terminate" - ); - let handle = result.expect("result should be Some after terminate"); - assert!( - handle.lifecycle.is_final(), - "handle should be in final state after terminate, got {:?}", - handle.lifecycle - ); -} - -/// 验证 inbox 容量上限生效：超出容量时 push_inbox 返回 None。 -#[tokio::test] -async fn push_inbox_rejects_when_at_capacity() { - let control = AgentControl::with_limits(4, 10, 256); - // 手动构造小容量 control - let control = AgentControl { - inbox_capacity: 2, - ..control - }; - let handle = control - .spawn(&explore_profile(), "session-1", "turn-1".to_string(), None) - .await - .expect("spawn should succeed"); - let _ = control - .set_lifecycle(&handle.agent_id, AgentLifecycleStatus::Running) - .await; - - // 推送到容量上限 - assert!( - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-1", "from", &handle.agent_id, "msg-1"), - ) - .await - .is_some() - ); - assert!( - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-2", "from", &handle.agent_id, "msg-2"), - ) - .await - .is_some() - ); - - // 超出容量应被拒绝 - assert!( - control - .push_inbox( - &handle.agent_id, - sample_envelope("d-3", "from", &handle.agent_id, "msg-3"), - ) - .await - .is_none(), - "push beyond capacity should return None" - ); -} - -/// 验证 parent_delivery_queue 容量上限生效：超出容量时 enqueue 返回 false。 -#[tokio::test] -async fn enqueue_parent_delivery_rejects_when_at_capacity() { - let control = AgentControl::with_limits(4, 10, 256); - let control = AgentControl { - parent_delivery_capacity: 2, - ..control - }; - - let session_id = "session-parent".to_string(); - let turn_id = "turn-parent".to_string(); - - // 入队到容量上限 - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - sample_parent_delivery("d-1", &session_id, &turn_id).2, - ) - .await - ); - assert!( - control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - sample_parent_delivery("d-2", &session_id, &turn_id).2, - ) - .await - ); - - // 超出容量应被拒绝 - assert!( - !control - .enqueue_parent_delivery( - session_id.clone(), - turn_id.clone(), - sample_parent_delivery("d-3", &session_id, &turn_id).2, - ) - .await, - "enqueue beyond capacity should return false" - ); -} diff --git a/crates/kernel/src/error.rs b/crates/kernel/src/error.rs deleted file mode 100644 index 1a5c1a59..00000000 --- a/crates/kernel/src/error.rs +++ /dev/null @@ -1,23 +0,0 @@ -use astrcode_core::AstrError; -use thiserror::Error; - -#[derive(Debug, Error)] -pub enum KernelError { - #[error("{0}")] - Validation(String), - #[error("{0}")] - NotFound(String), - #[error("{0}")] - Invoke(String), -} - -impl From for KernelError { - fn from(value: AstrError) -> Self { - match value { - AstrError::Validation(message) => Self::Validation(message), - AstrError::SessionNotFound(id) => Self::NotFound(format!("session '{}' not found", id)), - AstrError::ProjectNotFound(id) => Self::NotFound(format!("project '{}' not found", id)), - other => Self::Invoke(other.to_string()), - } - } -} diff --git a/crates/kernel/src/events/mod.rs b/crates/kernel/src/events/mod.rs deleted file mode 100644 index 4428c1cb..00000000 --- a/crates/kernel/src/events/mod.rs +++ /dev/null @@ -1,28 +0,0 @@ -use serde::{Deserialize, Serialize}; -use tokio::sync::broadcast; - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase", tag = "type")] -pub enum KernelEvent { - SurfaceRefreshed { capability_count: usize }, -} - -#[derive(Clone)] -pub struct EventHub { - sender: broadcast::Sender, -} - -impl EventHub { - pub fn new(capacity: usize) -> Self { - let (sender, _) = broadcast::channel(capacity.max(1)); - Self { sender } - } - - pub fn publish(&self, event: KernelEvent) { - let _ = self.sender.send(event); - } - - pub fn subscribe(&self) -> broadcast::Receiver { - self.sender.subscribe() - } -} diff --git a/crates/kernel/src/gateway/mod.rs b/crates/kernel/src/gateway/mod.rs deleted file mode 100644 index dfe239ba..00000000 --- a/crates/kernel/src/gateway/mod.rs +++ /dev/null @@ -1,104 +0,0 @@ -use std::sync::Arc; - -use astrcode_core::{ - LlmEventSink, LlmOutput, LlmProvider, LlmRequest, PromptBuildOutput, PromptBuildRequest, - PromptProvider, ResourceProvider, ResourceReadResult, ResourceRequestContext, ToolCallRequest, - ToolContext, ToolExecutionResult, -}; - -use crate::{error::KernelError, registry::CapabilityRouter}; - -#[derive(Clone)] -pub struct KernelGateway { - llm: Arc, - prompt: Arc, - resource: Arc, - capabilities: CapabilityRouter, -} - -impl KernelGateway { - pub fn new( - capabilities: CapabilityRouter, - llm: Arc, - prompt: Arc, - resource: Arc, - ) -> Self { - Self { - llm, - prompt, - resource, - capabilities, - } - } - - pub fn capabilities(&self) -> &CapabilityRouter { - &self.capabilities - } - - pub fn with_capabilities(&self, capabilities: CapabilityRouter) -> Self { - Self { - llm: Arc::clone(&self.llm), - prompt: Arc::clone(&self.prompt), - resource: Arc::clone(&self.resource), - capabilities, - } - } - - pub fn subset_for_tools_checked( - &self, - allowed_tool_names: &[String], - ) -> Result { - let capabilities = self - .capabilities - .subset_for_tools_checked(allowed_tool_names)?; - Ok(self.with_capabilities(capabilities)) - } - - pub fn model_limits(&self) -> astrcode_core::ModelLimits { - self.llm.model_limits() - } - - pub fn supports_cache_metrics(&self) -> bool { - self.llm.supports_cache_metrics() - } - - pub async fn invoke_tool( - &self, - call: &ToolCallRequest, - ctx: &ToolContext, - ) -> ToolExecutionResult { - self.capabilities.execute_tool(call, ctx).await - } - - pub async fn call_llm( - &self, - request: LlmRequest, - sink: Option, - ) -> Result { - self.llm - .generate(request, sink) - .await - .map_err(KernelError::from) - } - - pub async fn build_prompt( - &self, - request: PromptBuildRequest, - ) -> Result { - self.prompt - .build_prompt(request) - .await - .map_err(KernelError::from) - } - - pub async fn read_resource( - &self, - uri: &str, - context: &ResourceRequestContext, - ) -> Result { - self.resource - .read_resource(uri, context) - .await - .map_err(KernelError::from) - } -} diff --git a/crates/kernel/src/kernel.rs b/crates/kernel/src/kernel.rs deleted file mode 100644 index 04a5975d..00000000 --- a/crates/kernel/src/kernel.rs +++ /dev/null @@ -1,111 +0,0 @@ -use std::sync::Arc; - -use astrcode_core::{LlmProvider, PromptProvider, ResourceProvider}; - -use crate::{ - agent_tree::{AgentControl, AgentControlLimits}, - error::KernelError, - events::EventHub, - gateway::KernelGateway, - registry::CapabilityRouter, - surface::SurfaceManager, -}; - -// ── Kernel 主结构 ────────────────────────────────────── - -#[derive(Clone)] -pub struct Kernel { - gateway: KernelGateway, - agent_control: AgentControl, - surface: SurfaceManager, - events: EventHub, -} - -impl Kernel { - pub fn builder() -> KernelBuilder { - KernelBuilder::default() - } - - pub fn gateway(&self) -> &KernelGateway { - &self.gateway - } - - pub fn agent_control(&self) -> &AgentControl { - &self.agent_control - } - - pub fn surface(&self) -> &SurfaceManager { - &self.surface - } - - pub fn events(&self) -> &EventHub { - &self.events - } -} - -#[derive(Default)] -pub struct KernelBuilder { - capabilities: Option, - llm: Option>, - prompt: Option>, - resource: Option>, - agent_limits: Option, - event_bus_capacity: Option, -} - -impl KernelBuilder { - pub fn with_capabilities(mut self, capabilities: CapabilityRouter) -> Self { - self.capabilities = Some(capabilities); - self - } - - pub fn with_llm_provider(mut self, provider: Arc) -> Self { - self.llm = Some(provider); - self - } - - pub fn with_prompt_provider(mut self, provider: Arc) -> Self { - self.prompt = Some(provider); - self - } - - pub fn with_resource_provider(mut self, provider: Arc) -> Self { - self.resource = Some(provider); - self - } - - pub fn with_agent_limits(mut self, limits: AgentControlLimits) -> Self { - self.agent_limits = Some(limits); - self - } - - pub fn with_event_bus_capacity(mut self, capacity: usize) -> Self { - self.event_bus_capacity = Some(capacity); - self - } - - pub fn build(self) -> Result { - let capabilities = self.capabilities.unwrap_or_default(); - let llm = self - .llm - .ok_or_else(|| KernelError::Validation("missing llm provider".to_string()))?; - let prompt = self - .prompt - .ok_or_else(|| KernelError::Validation("missing prompt provider".to_string()))?; - let resource = self - .resource - .ok_or_else(|| KernelError::Validation("missing resource provider".to_string()))?; - - let gateway = KernelGateway::new(capabilities.clone(), llm, prompt, resource); - let events = EventHub::new(self.event_bus_capacity.unwrap_or(256)); - let surface = SurfaceManager::new(); - surface.replace_capabilities(&capabilities.invokers(), &events); - - Ok(Kernel { - gateway, - agent_control: AgentControl::from_limits(self.agent_limits.unwrap_or_default()), - surface, - events, - }) - } -} diff --git a/crates/kernel/src/lib.rs b/crates/kernel/src/lib.rs deleted file mode 100644 index 5f0643db..00000000 --- a/crates/kernel/src/lib.rs +++ /dev/null @@ -1,20 +0,0 @@ -pub mod agent_surface; -pub mod agent_tree; -pub mod error; -pub mod events; -pub mod gateway; -pub mod kernel; -pub mod registry; -pub mod surface; - -pub use agent_surface::{CloseSubtreeResult, KernelAgentSurface, SubRunStatusView}; -pub use agent_tree::{ - AgentControl, AgentControlError, AgentControlLimits, AgentProfileSource, LiveSubRunControl, - PendingParentDelivery, StaticAgentProfileSource, -}; -pub use error::KernelError; -pub use events::{EventHub, KernelEvent}; -pub use gateway::KernelGateway; -pub use kernel::{Kernel, KernelBuilder}; -pub use registry::{CapabilityRouter, CapabilityRouterBuilder, ToolCapabilityInvoker}; -pub use surface::{SurfaceManager, SurfaceSnapshot}; diff --git a/crates/kernel/src/registry/mod.rs b/crates/kernel/src/registry/mod.rs deleted file mode 100644 index 40de8ddc..00000000 --- a/crates/kernel/src/registry/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! 能力注册表。 - -mod router; -mod tool; - -pub use router::{CapabilityRouter, CapabilityRouterBuilder}; -pub use tool::ToolCapabilityInvoker; diff --git a/crates/kernel/src/registry/router.rs b/crates/kernel/src/registry/router.rs deleted file mode 100644 index b63b13a9..00000000 --- a/crates/kernel/src/registry/router.rs +++ /dev/null @@ -1,345 +0,0 @@ -//! 能力路由器具体实现。 - -use std::{ - collections::{HashMap, HashSet}, - sync::{Arc, RwLock}, -}; - -use astrcode_core::{ - AstrError, CapabilityInvoker, CapabilitySpec, Result, ToolCallRequest, ToolContext, - ToolDefinition, ToolExecutionResult, - support::{self}, -}; - -use super::tool::capability_context_from_tool_context; - -fn validate_capability_spec(capability_spec: &CapabilitySpec) -> Result<()> { - capability_spec.validate().map_err(|error| { - AstrError::Validation(format!( - "invalid capability spec '{}': {}", - capability_spec.name, error - )) - }) -} - -fn build_registry_snapshot( - invokers: impl IntoIterator>, -) -> Result { - let mut invokers_by_name = HashMap::new(); - let mut order = Vec::new(); - let mut tool_order = Vec::new(); - - for invoker in invokers { - let capability_spec = invoker.capability_spec(); - validate_capability_spec(&capability_spec)?; - if invokers_by_name - .insert(capability_spec.name.to_string(), Arc::clone(&invoker)) - .is_some() - { - return Err(AstrError::Validation(format!( - "duplicate capability '{}' registered", - capability_spec.name - ))); - } - if capability_spec.kind.is_tool() { - tool_order.push(capability_spec.name.to_string()); - } - order.push(capability_spec.name.to_string()); - } - - Ok(CapabilityRouterInner { - invokers_by_name, - order, - tool_order, - }) -} - -fn append_invoker( - inner: &mut CapabilityRouterInner, - invoker: Arc, -) -> Result<()> { - let capability_spec = invoker.capability_spec(); - validate_capability_spec(&capability_spec)?; - if inner - .invokers_by_name - .contains_key(capability_spec.name.as_str()) - { - return Err(AstrError::Validation(format!( - "duplicate capability '{}' registered", - capability_spec.name - ))); - } - - if capability_spec.kind.is_tool() { - inner.tool_order.push(capability_spec.name.to_string()); - } - inner.order.push(capability_spec.name.to_string()); - inner - .invokers_by_name - .insert(capability_spec.name.to_string(), invoker); - Ok(()) -} - -pub struct CapabilityRouterBuilder { - invokers: Vec>, -} - -impl Default for CapabilityRouterBuilder { - fn default() -> Self { - Self::new() - } -} - -impl CapabilityRouterBuilder { - pub fn new() -> Self { - Self { - invokers: Vec::new(), - } - } - - pub fn register_invoker(mut self, invoker: Arc) -> Self { - self.invokers.push(invoker); - self - } - - pub fn build(self) -> Result { - let snapshot = build_registry_snapshot(self.invokers)?; - - Ok(CapabilityRouter { - inner: Arc::new(RwLock::new(snapshot)), - }) - } -} - -struct CapabilityRouterInner { - invokers_by_name: HashMap>, - order: Vec, - tool_order: Vec, -} - -#[derive(Clone)] -pub struct CapabilityRouter { - inner: Arc>, -} - -impl Default for CapabilityRouter { - fn default() -> Self { - Self::empty() - } -} - -impl CapabilityRouter { - pub fn builder() -> CapabilityRouterBuilder { - CapabilityRouterBuilder::new() - } - - pub fn empty() -> Self { - Self { - inner: Arc::new(RwLock::new(CapabilityRouterInner { - invokers_by_name: HashMap::new(), - order: Vec::new(), - tool_order: Vec::new(), - })), - } - } - - pub fn register_invoker(&self, invoker: Arc) -> Result<()> { - support::with_write_lock_recovery(&self.inner, "capability_router", |inner| { - append_invoker(inner, invoker) - }) - } - - pub fn register_invokers(&self, invokers: Vec>) -> Result<()> { - support::with_write_lock_recovery(&self.inner, "capability_router", |inner| { - let mut merged = inner - .order - .iter() - .filter_map(|name| inner.invokers_by_name.get(name).cloned()) - .collect::>(); - merged.extend(invokers); - *inner = build_registry_snapshot(merged)?; - Ok(()) - }) - } - - /// 用新的执行器集合原子替换整份能力路由。 - /// - /// 外部 surface（如 MCP）发生变化时，组合根需要同步刷新 kernel 能力面。 - /// 这里直接替换整份注册表，避免旧能力只增不减地残留。 - pub fn replace_invokers(&self, invokers: Vec>) -> Result<()> { - let snapshot = build_registry_snapshot(invokers)?; - - support::with_write_lock_recovery(&self.inner, "capability_router", |inner| { - *inner = snapshot; - Ok(()) - }) - } - - pub fn capability_specs(&self) -> Vec { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner - .order - .iter() - .filter_map(|name| inner.invokers_by_name.get(name)) - .map(|invoker| invoker.capability_spec()) - .collect() - }) - } - - pub fn descriptors(&self) -> Vec { - self.capability_specs() - } - - /// 返回按注册顺序排列的 invoker 快照。 - /// - /// runtime surface 热替换需要拿到现有 invoker，再按来源增删外部能力后 - /// 重建整份路由；直接暴露 `Arc` 克隆可以避免重新解析 descriptor 丢失执行器。 - pub fn invokers(&self) -> Vec> { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner - .order - .iter() - .filter_map(|name| inner.invokers_by_name.get(name).cloned()) - .collect() - }) - } - - pub fn capability_spec(&self, name: &str) -> Option { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner - .invokers_by_name - .get(name) - .map(|invoker| invoker.capability_spec()) - }) - } - - pub fn descriptor(&self, name: &str) -> Option { - self.capability_spec(name) - } - - pub fn tool_definitions(&self) -> Vec { - self.capability_specs() - .into_iter() - .filter(|capability_spec| capability_spec.kind.is_tool()) - .map(|capability_spec| ToolDefinition { - name: capability_spec.name.into_string(), - description: capability_spec.description, - parameters: capability_spec.input_schema, - }) - .collect() - } - - pub fn tool_names(&self) -> Vec { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner.tool_order.clone() - }) - } - - pub fn subset_for_tools(&self, allowed_tool_names: &[String]) -> Result { - self.subset_for_tools_checked(allowed_tool_names) - } - - pub fn subset_for_tools_checked(&self, allowed_tool_names: &[String]) -> Result { - let allowed = allowed_tool_names - .iter() - .map(|name| name.as_str()) - .collect::>(); - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - let unknown = allowed_tool_names - .iter() - .filter(|name| !inner.tool_order.iter().any(|candidate| candidate == *name)) - .cloned() - .collect::>(); - if !unknown.is_empty() { - return Err(AstrError::Validation(format!( - "unknown tool capabilities in grant: {}", - unknown.join(", ") - ))); - } - let mut builder = CapabilityRouter::builder(); - - for name in &inner.order { - let Some(invoker) = inner.invokers_by_name.get(name) else { - continue; - }; - let capability_spec = invoker.capability_spec(); - if capability_spec.kind.is_tool() - && !allowed.contains(capability_spec.name.as_str()) - { - continue; - } - builder = builder.register_invoker(Arc::clone(invoker)); - } - - builder.build() - }) - } - - pub async fn execute_tool( - &self, - call: &ToolCallRequest, - ctx: &ToolContext, - ) -> ToolExecutionResult { - let invoker = support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner.invokers_by_name.get(&call.name).cloned() - }); - - let Some(invoker) = invoker else { - return ToolExecutionResult { - tool_call_id: call.id.clone(), - tool_name: call.name.clone(), - ok: false, - output: String::new(), - error: Some(format!("unknown tool '{}'", call.name)), - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }; - }; - - let capability_spec = invoker.capability_spec(); - if !capability_spec.kind.is_tool() { - return ToolExecutionResult { - tool_call_id: call.id.clone(), - tool_name: call.name.clone(), - ok: false, - output: String::new(), - error: Some(format!("capability '{}' is not tool-callable", call.name)), - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }; - } - - let capability_ctx = capability_context_from_tool_context(ctx, Some(call.id.clone())); - - match invoker.invoke(call.args.clone(), &capability_ctx).await { - Ok(result) => result.into_tool_execution_result(call.id.clone()), - Err(error) => ToolExecutionResult { - tool_call_id: call.id.clone(), - tool_name: call.name.clone(), - ok: false, - output: String::new(), - error: Some(error.to_string()), - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }, - } - } - - pub fn has_capability(&self, name: &str) -> bool { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner.invokers_by_name.contains_key(name) - }) - } - - pub fn capability_count(&self) -> usize { - support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { - inner.invokers_by_name.len() - }) - } -} diff --git a/crates/kernel/src/registry/tool.rs b/crates/kernel/src/registry/tool.rs deleted file mode 100644 index 4f7d9d7d..00000000 --- a/crates/kernel/src/registry/tool.rs +++ /dev/null @@ -1,426 +0,0 @@ -//! 工具到能力调用器的桥接。 -//! -//! `ToolCapabilityInvoker` 将 `Tool` trait 适配为 `CapabilityInvoker`， -//! 是生产路径中工具注册的唯一入口。 - -use std::sync::Arc; - -use astrcode_core::{ - AgentEventContext, AstrError, BoundModeToolContractSnapshot, CancelToken, CapabilityContext, - CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, ExecutionOwner, Result, - SessionId, Tool, ToolContext, ToolEventSink, ToolOutputDelta, -}; -use async_trait::async_trait; -use serde_json::Value; -use tokio::sync::mpsc::UnboundedSender; - -const DEFAULT_TOOL_CAPABILITY_PROFILE: &str = "coding"; - -pub struct ToolCapabilityInvoker { - tool: Arc, - capability_spec: CapabilitySpec, -} - -impl ToolCapabilityInvoker { - pub fn new(tool: Arc) -> Result { - let capability_spec = tool.capability_spec().map_err(|error| { - let fallback_name = tool.definition().name; - AstrError::Validation(format!( - "invalid tool capability spec '{}': {}", - display_tool_label(&fallback_name), - error - )) - })?; - capability_spec.validate().map_err(|error| { - AstrError::Validation(format!( - "invalid tool capability spec '{}': {}", - display_tool_label(capability_spec.name.as_str()), - error - )) - })?; - Ok(Self { - tool, - capability_spec, - }) - } - - pub fn boxed(tool: Box) -> Result> { - Ok(Arc::new(Self::new(Arc::from(tool))?)) - } -} - -#[async_trait] -impl CapabilityInvoker for ToolCapabilityInvoker { - fn capability_spec(&self) -> CapabilitySpec { - self.capability_spec.clone() - } - - async fn invoke( - &self, - payload: Value, - ctx: &astrcode_core::CapabilityContext, - ) -> Result { - let tool_ctx = tool_context_from_capability_context(ctx); - let result = self - .tool - .execute( - ctx.request_id - .clone() - .unwrap_or_else(|| "capability-call".to_string()), - payload, - &tool_ctx, - ) - .await; - - match result { - Ok(result) => { - let common = result.common(); - Ok(CapabilityExecutionResult::from_common( - result.tool_name, - result.ok, - Value::String(result.output), - result.continuation, - common, - )) - }, - Err(error) => Ok(CapabilityExecutionResult::failure( - self.capability_spec.name.to_string(), - error.to_string(), - Value::Null, - )), - } - } -} - -pub(crate) fn capability_context_from_tool_context( - ctx: &ToolContext, - request_id: Option, -) -> CapabilityContext { - ToolBridgeContext::from_tool_context(ctx).into_capability_context(request_id) -} - -fn tool_context_from_capability_context(ctx: &CapabilityContext) -> ToolContext { - ToolBridgeContext::from_capability_context(ctx).into_tool_context() -} - -#[derive(Clone)] -struct ToolBridgeContext { - session_id: SessionId, - working_dir: std::path::PathBuf, - cancel: CancelToken, - turn_id: Option, - request_id: Option, - agent: AgentEventContext, - current_mode_id: astrcode_core::ModeId, - bound_mode_tool_contract: Option, - execution_owner: Option, - tool_output_sender: Option>, - event_sink: Option>, -} - -impl ToolBridgeContext { - fn from_tool_context(ctx: &ToolContext) -> Self { - Self { - session_id: ctx.session_id().into(), - working_dir: ctx.working_dir().to_path_buf(), - cancel: ctx.cancel().clone(), - turn_id: ctx.turn_id().map(ToString::to_string), - request_id: None, - agent: ctx.agent_context().clone(), - current_mode_id: ctx.current_mode_id().clone(), - bound_mode_tool_contract: ctx.bound_mode_tool_contract().cloned(), - execution_owner: ctx.execution_owner().cloned(), - tool_output_sender: ctx.tool_output_sender(), - event_sink: ctx.event_sink(), - } - } - - fn from_capability_context(ctx: &CapabilityContext) -> Self { - Self { - session_id: ctx.session_id.clone(), - working_dir: ctx.working_dir.clone(), - cancel: ctx.cancel.clone(), - turn_id: ctx.turn_id.clone(), - request_id: ctx.request_id.clone(), - agent: ctx.agent.clone(), - current_mode_id: ctx.current_mode_id.clone(), - bound_mode_tool_contract: ctx.bound_mode_tool_contract.clone(), - execution_owner: ctx.execution_owner.clone(), - tool_output_sender: ctx.tool_output_sender.clone(), - event_sink: ctx.event_sink.clone(), - } - } - - fn into_capability_context(self, request_id: Option) -> CapabilityContext { - let profile_context = default_tool_capability_profile_context(&self.working_dir); - - CapabilityContext { - request_id, - trace_id: None, - session_id: self.session_id, - working_dir: self.working_dir, - cancel: self.cancel, - turn_id: self.turn_id, - agent: self.agent, - current_mode_id: self.current_mode_id, - bound_mode_tool_contract: self.bound_mode_tool_contract, - execution_owner: self.execution_owner, - profile: default_tool_capability_profile().to_string(), - profile_context, - metadata: Value::Null, - tool_output_sender: self.tool_output_sender, - event_sink: self.event_sink, - } - } - - fn into_tool_context(self) -> ToolContext { - let mut tool_ctx = ToolContext::new(self.session_id, self.working_dir, self.cancel); - if let Some(turn_id) = self.turn_id { - tool_ctx = tool_ctx.with_turn_id(turn_id); - } - if let Some(tool_call_id) = self.request_id { - tool_ctx = tool_ctx.with_tool_call_id(tool_call_id); - } - tool_ctx = tool_ctx.with_agent_context(self.agent); - tool_ctx = tool_ctx.with_current_mode_id(self.current_mode_id); - if let Some(snapshot) = self.bound_mode_tool_contract { - tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot); - } - if let Some(sender) = self.tool_output_sender { - tool_ctx = tool_ctx.with_tool_output_sender(sender); - } - if let Some(event_sink) = self.event_sink { - tool_ctx = tool_ctx.with_event_sink(event_sink); - } - if let Some(owner) = self.execution_owner { - tool_ctx = tool_ctx.with_execution_owner(owner); - } - tool_ctx - } -} - -fn display_tool_label(name: &str) -> &str { - let trimmed = name.trim(); - if trimmed.is_empty() { - "" - } else { - trimmed - } -} - -fn default_tool_capability_profile() -> &'static str { - DEFAULT_TOOL_CAPABILITY_PROFILE -} - -fn default_tool_capability_profile_context(working_dir: &std::path::Path) -> Value { - let working_dir = working_dir.to_string_lossy().into_owned(); - serde_json::json!({ - "workingDir": working_dir, - "repoRoot": working_dir, - "approvalMode": "inherit" - }) -} - -#[cfg(test)] -mod tests { - use std::{path::PathBuf, sync::Arc}; - - use astrcode_core::{ - AgentLifecycleStatus, BoundModeToolContractSnapshot, CapabilityInvoker, - ChildExecutionIdentity, ChildSessionLineageKind, ExecutionOwner, InvocationKind, - ParentExecutionRef, Tool, ToolContext, ToolDefinition, ToolExecutionResult, - }; - use async_trait::async_trait; - use serde_json::{Value, json}; - - use super::{ - ToolCapabilityInvoker, capability_context_from_tool_context, - default_tool_capability_profile, default_tool_capability_profile_context, - tool_context_from_capability_context, - }; - - #[test] - fn capability_bridge_preserves_tool_context_fields() { - let tool_ctx = ToolContext::new( - "session-1".into(), - PathBuf::from("/repo"), - astrcode_core::CancelToken::new(), - ) - .with_turn_id("turn-1") - .with_tool_call_id("call-1") - .with_agent_context(astrcode_core::AgentEventContext::root_execution( - "agent-root", - "planner", - )) - .with_execution_owner(ExecutionOwner::root( - "session-1", - "turn-root", - InvocationKind::RootExecution, - )) - .with_bound_mode_tool_contract(BoundModeToolContractSnapshot { - mode_id: "plan".into(), - artifact: None, - exit_gate: None, - }); - - let capability_ctx = - capability_context_from_tool_context(&tool_ctx, Some("request-1".to_string())); - - assert_eq!(capability_ctx.session_id.as_str(), "session-1"); - assert_eq!(capability_ctx.working_dir, PathBuf::from("/repo")); - assert_eq!(capability_ctx.turn_id.as_deref(), Some("turn-1")); - assert_eq!(capability_ctx.request_id.as_deref(), Some("request-1")); - assert_eq!(capability_ctx.agent.agent_id.as_deref(), Some("agent-root")); - assert_eq!( - capability_ctx - .execution_owner - .as_ref() - .map(|owner| owner.root_turn_id.as_str()), - Some("turn-root") - ); - assert_eq!( - capability_ctx - .bound_mode_tool_contract - .as_ref() - .map(|snapshot| snapshot.mode_id.as_str()), - Some("plan") - ); - assert_eq!(capability_ctx.profile, default_tool_capability_profile()); - assert_eq!( - capability_ctx.profile_context, - default_tool_capability_profile_context(&PathBuf::from("/repo")) - ); - } - - #[test] - fn tool_bridge_restores_request_id_as_tool_call_id() { - let tool_ctx = ToolContext::new( - "session-2".into(), - PathBuf::from("/workspace"), - astrcode_core::CancelToken::new(), - ) - .with_turn_id("turn-2") - .with_bound_mode_tool_contract(BoundModeToolContractSnapshot { - mode_id: "review".into(), - artifact: None, - exit_gate: None, - }) - .with_agent_context(astrcode_core::AgentEventContext::root_execution( - "agent-2", "reviewer", - )); - - let capability_ctx = - capability_context_from_tool_context(&tool_ctx, Some("request-2".to_string())); - let bridged_tool_ctx = tool_context_from_capability_context(&capability_ctx); - - assert_eq!(bridged_tool_ctx.session_id(), "session-2"); - assert_eq!(bridged_tool_ctx.working_dir(), PathBuf::from("/workspace")); - assert_eq!(bridged_tool_ctx.turn_id(), Some("turn-2")); - assert_eq!(bridged_tool_ctx.tool_call_id(), Some("request-2")); - assert_eq!( - bridged_tool_ctx.agent_context().agent_id.as_deref(), - Some("agent-2") - ); - assert_eq!( - bridged_tool_ctx - .bound_mode_tool_contract() - .map(|snapshot| snapshot.mode_id.as_str()), - Some("review") - ); - } - - struct ChildRefTool; - - #[async_trait] - impl Tool for ChildRefTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "spawn".to_string(), - description: "returns child ref".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result< - astrcode_core::CapabilitySpec, - astrcode_core::CapabilitySpecBuildError, - > { - astrcode_core::CapabilitySpec::builder("spawn", astrcode_core::CapabilityKind::Tool) - .description("returns child ref") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - _ctx: &ToolContext, - ) -> astrcode_core::Result { - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "spawn".to_string(), - ok: true, - output: "spawn accepted".to_string(), - error: None, - metadata: Some(json!({ "schema": "subRunResult" })), - continuation: Some(astrcode_core::ExecutionContinuation::child_agent( - astrcode_core::ChildAgentRef { - identity: ChildExecutionIdentity { - agent_id: "agent-child".into(), - session_id: "session-parent".into(), - sub_run_id: "subrun-1".into(), - }, - parent: ParentExecutionRef { - parent_agent_id: Some("agent-parent".into()), - parent_sub_run_id: Some("subrun-parent".into()), - }, - lineage_kind: ChildSessionLineageKind::Spawn, - status: AgentLifecycleStatus::Running, - open_session_id: "session-child".into(), - }, - )), - duration_ms: 0, - truncated: false, - }) - } - } - - #[tokio::test] - async fn tool_capability_invoker_preserves_child_continuation_in_capability_result() { - let invoker = - ToolCapabilityInvoker::new(Arc::new(ChildRefTool)).expect("tool invoker should build"); - let tool_ctx = ToolContext::new( - "session-3".into(), - PathBuf::from("/workspace"), - astrcode_core::CancelToken::new(), - ) - .with_tool_call_id("call-3"); - let capability_ctx = - capability_context_from_tool_context(&tool_ctx, Some("call-3".to_string())); - - let result = invoker - .invoke(json!({}), &capability_ctx) - .await - .expect("invocation should succeed"); - - assert_eq!( - result - .continuation - .as_ref() - .and_then(|continuation| continuation.child_agent_ref()) - .map(|child_ref| child_ref.agent_id().as_str()), - Some("agent-child") - ); - assert_eq!( - result - .continuation - .as_ref() - .and_then(|continuation| continuation.child_agent_ref()) - .map(|child_ref| child_ref.open_session_id.as_str()), - Some("session-child") - ); - } -} diff --git a/crates/kernel/src/surface/mod.rs b/crates/kernel/src/surface/mod.rs deleted file mode 100644 index 5353c836..00000000 --- a/crates/kernel/src/surface/mod.rs +++ /dev/null @@ -1,134 +0,0 @@ -use std::sync::{Arc, RwLock}; - -use astrcode_core::{CapabilityInvoker, CapabilitySpec, support}; - -use crate::events::{EventHub, KernelEvent}; - -/// Kernel 对外暴露的能力面快照。 -/// -/// 这层不持有执行器本身，只保留稳定的 capability 元信息， -/// 供上层查看“当前 kernel 能做什么”。 -#[derive(Debug, Clone, PartialEq, Default)] -pub struct SurfaceSnapshot { - pub capability_specs: Vec, -} - -impl SurfaceSnapshot { - fn from_invokers(invokers: &[Arc]) -> Self { - Self { - capability_specs: invokers - .iter() - .map(|invoker| invoker.capability_spec()) - .collect(), - } - } - - fn capability_count(&self) -> usize { - self.capability_specs.len() - } -} - -/// 维护当前 capability surface 的只读快照，并在刷新时发出事件。 -#[derive(Clone, Default)] -pub struct SurfaceManager { - snapshot: Arc>, -} - -impl SurfaceManager { - pub fn new() -> Self { - Self::default() - } - - pub fn snapshot(&self) -> SurfaceSnapshot { - support::with_read_lock_recovery(&self.snapshot, "kernel.surface", Clone::clone) - } - - pub fn replace_capabilities( - &self, - invokers: &[Arc], - events: &EventHub, - ) -> SurfaceSnapshot { - let next = SurfaceSnapshot::from_invokers(invokers); - support::with_write_lock_recovery(&self.snapshot, "kernel.surface", |snapshot| { - *snapshot = next.clone(); - }); - events.publish(KernelEvent::SurfaceRefreshed { - capability_count: next.capability_count(), - }); - next - } -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, CapabilityKind, - CapabilitySpec, Result, - }; - use async_trait::async_trait; - use serde_json::{Value, json}; - - use super::SurfaceManager; - use crate::events::{EventHub, KernelEvent}; - - struct FakeInvoker { - spec: CapabilitySpec, - } - - #[async_trait] - impl CapabilityInvoker for FakeInvoker { - fn capability_spec(&self) -> CapabilitySpec { - self.spec.clone() - } - - async fn invoke( - &self, - _payload: Value, - _ctx: &CapabilityContext, - ) -> Result { - unreachable!("surface tests only inspect capability metadata") - } - } - - fn fake_invoker(name: &str) -> Arc { - Arc::new(FakeInvoker { - spec: CapabilitySpec::builder(name, CapabilityKind::Tool) - .description(format!("tool {name}")) - .input_schema(json!({ - "type": "object", - "properties": {}, - "additionalProperties": false - })) - .output_schema(json!({ - "type": "string" - })) - .build() - .expect("fake capability spec should build"), - }) - } - - #[test] - fn replace_capabilities_updates_snapshot_and_publishes_event() { - let manager = SurfaceManager::new(); - let events = EventHub::new(8); - let mut receiver = events.subscribe(); - - let snapshot = manager - .replace_capabilities(&[fake_invoker("list_dir"), fake_invoker("grep")], &events); - - assert_eq!(snapshot.capability_specs.len(), 2); - assert_eq!(snapshot.capability_specs[0].name.as_str(), "list_dir"); - assert_eq!(snapshot.capability_specs[1].name.as_str(), "grep"); - assert_eq!(manager.snapshot(), snapshot); - assert_eq!( - receiver - .try_recv() - .expect("surface refresh event should publish"), - KernelEvent::SurfaceRefreshed { - capability_count: 2 - } - ); - } -} diff --git a/crates/plugin/Cargo.toml b/crates/plugin-host/Cargo.toml similarity index 82% rename from crates/plugin/Cargo.toml rename to crates/plugin-host/Cargo.toml index 819eaaea..f9e827f3 100644 --- a/crates/plugin/Cargo.toml +++ b/crates/plugin-host/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "astrcode-plugin" +name = "astrcode-plugin-host" version = "0.1.0" edition.workspace = true license-file.workspace = true @@ -8,11 +8,10 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } astrcode-protocol = { path = "../protocol" } -async-trait.workspace = true +astrcode-support = { path = "../support" } log.workspace = true +async-trait.workspace = true serde.workspace = true serde_json.workspace = true -thiserror.workspace = true tokio.workspace = true toml.workspace = true -uuid.workspace = true diff --git a/crates/plugin-host/src/backend.rs b/crates/plugin-host/src/backend.rs new file mode 100644 index 00000000..5869fdb0 --- /dev/null +++ b/crates/plugin-host/src/backend.rs @@ -0,0 +1,806 @@ +use std::{ + process::Stdio, + sync::Arc, + time::{SystemTime, UNIX_EPOCH}, +}; + +use astrcode_core::{AstrError, Result}; +use astrcode_protocol::plugin::{EventMessage, InitializeResultData, InvokeMessage, ResultMessage}; +use tokio::process::{Child, Command}; + +use crate::{ + PluginDescriptor, PluginInitializeState, RemotePluginHandshakeSummary, + transport::PluginStdioTransport, +}; + +/// plugin-host 视角下的后端执行形态。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum PluginBackendKind { + InProcess, + Process, + Command, + Http, +} + +/// 统一的后端启动计划。 +/// +/// 第一阶段只抽出描述层，不直接启动进程或建立 RPC。 +/// 这样后续把旧 `process/peer/supervisor` 迁进来时， +/// 可以直接消费这份计划，而不用重新解释 descriptor。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PluginBackendPlan { + pub plugin_id: String, + pub backend_kind: PluginBackendKind, + pub source_ref: String, + pub launch_command: Option, + pub launch_args: Vec, + pub working_dir: Option, +} + +/// 外部插件子进程状态。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PluginProcessStatus { + pub running: bool, + pub exit_code: Option, +} + +/// 外部 backend 的最小健康状态。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum PluginBackendHealth { + Healthy, + Unavailable, +} + +/// 外部 backend 的最小健康报告。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PluginBackendHealthReport { + pub plugin_id: String, + pub health: PluginBackendHealth, + pub started_at_ms: u64, + pub shutdown_requested: bool, + pub message: Option, +} + +/// `plugin-host` 中的最小 process backend。 +/// +/// 这一层只负责： +/// - 根据 `PluginBackendPlan` 启动子进程 +/// - 非阻塞检查状态 +/// - 在需要时关闭子进程 +/// +/// JSON-RPC transport / peer / supervisor 会在后续阶段继续接入。 +#[derive(Debug)] +pub struct PluginProcessBackend { + pub plan: PluginBackendPlan, + child: Child, + stdio_transport: Option>, +} + +/// plugin-host 持有的最小 builtin runtime handle。 +/// +/// builtin backend 不需要外部进程，但宿主仍然需要一个统一运行时对象， +/// 避免 builtin/external 在组合根侧继续分裂成两套消费方式。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BuiltinPluginRuntimeHandle { + pub plugin_id: String, + pub started_at_ms: u64, +} + +/// plugin-host 持有的最小 external runtime handle。 +/// +/// 先把宿主真正关心的状态固化在这里： +/// - 哪个 plugin +/// - 何时启动 +/// - 是否已经进入 shutdown 流程 +/// - 底层进程 backend +/// +/// 之后迁入 peer / supervisor 时，这个 handle 继续当 owner 外壳即可。 +#[derive(Debug)] +pub struct ExternalPluginRuntimeHandle { + pub plugin_id: String, + pub started_at_ms: u64, + shutdown_requested: bool, + backend: PluginProcessBackend, + protocol_state: Option, +} + +impl PluginBackendPlan { + pub fn from_descriptor(descriptor: &PluginDescriptor) -> Result { + let backend_kind = descriptor.source_kind.to_backend_kind(); + + match backend_kind { + PluginBackendKind::InProcess => Ok(Self { + plugin_id: descriptor.plugin_id.clone(), + backend_kind, + source_ref: descriptor.source_ref.clone(), + launch_command: None, + launch_args: Vec::new(), + working_dir: None, + }), + PluginBackendKind::Process | PluginBackendKind::Command => { + let launch_command = descriptor.launch_command.clone().ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 launch_command，无法构建外部插件后端计划", + descriptor.plugin_id + )) + })?; + Ok(Self { + plugin_id: descriptor.plugin_id.clone(), + backend_kind, + source_ref: descriptor.source_ref.clone(), + launch_command: Some(launch_command), + launch_args: descriptor.launch_args.clone(), + working_dir: descriptor.working_dir.clone(), + }) + }, + PluginBackendKind::Http => { + if descriptor.source_ref.trim().is_empty() { + return Err(AstrError::Validation(format!( + "plugin '{}' 缺少 source_ref，无法构建 HTTP 插件后端计划", + descriptor.plugin_id + ))); + } + Ok(Self { + plugin_id: descriptor.plugin_id.clone(), + backend_kind, + source_ref: descriptor.source_ref.clone(), + launch_command: None, + launch_args: Vec::new(), + working_dir: None, + }) + }, + } + } + + pub async fn start_process(&self) -> Result { + match self.backend_kind { + PluginBackendKind::Process | PluginBackendKind::Command => { + let executable = self.launch_command.as_ref().ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 launch_command，无法启动外部插件后端", + self.plugin_id + )) + })?; + let mut command = Command::new(executable); + command + .args(&self.launch_args) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()); + if let Some(working_dir) = &self.working_dir { + command.current_dir(working_dir); + } + let child = command.spawn().map_err(|error| { + AstrError::io( + format!("failed to spawn plugin backend '{}'", self.plugin_id), + error, + ) + })?; + Ok(PluginProcessBackend { + plan: self.clone(), + child, + stdio_transport: None, + }) + }, + PluginBackendKind::InProcess => Err(AstrError::Validation(format!( + "plugin '{}' 是 builtin backend，不应走 process 启动路径", + self.plugin_id + ))), + PluginBackendKind::Http => Err(AstrError::Validation(format!( + "plugin '{}' 是 HTTP backend，当前尚未实现进程启动路径", + self.plugin_id + ))), + } + } +} + +impl PluginProcessBackend { + pub fn ensure_stdio_transport(&mut self) -> Result> { + if let Some(transport) = &self.stdio_transport { + return Ok(Arc::clone(transport)); + } + let stdin = self.child.stdin.take().ok_or_else(|| { + AstrError::Internal(format!( + "plugin backend '{}' did not expose stdin", + self.plan.plugin_id + )) + })?; + let stdout = self.child.stdout.take().ok_or_else(|| { + AstrError::Internal(format!( + "plugin backend '{}' did not expose stdout", + self.plan.plugin_id + )) + })?; + let transport = Arc::new(PluginStdioTransport::from_child(stdin, stdout)); + self.stdio_transport = Some(Arc::clone(&transport)); + Ok(transport) + } + + pub fn status(&mut self) -> Result { + let exit_status = self + .child + .try_wait() + .map_err(|error| AstrError::io("failed to poll plugin backend process", error))?; + Ok(match exit_status { + Some(status) => PluginProcessStatus { + running: false, + exit_code: status.code(), + }, + None => PluginProcessStatus { + running: true, + exit_code: None, + }, + }) + } + + pub fn health_report(&mut self) -> Result { + let status = self.status()?; + if status.running { + Ok(PluginBackendHealthReport { + plugin_id: self.plan.plugin_id.clone(), + health: PluginBackendHealth::Healthy, + started_at_ms: 0, + shutdown_requested: false, + message: None, + }) + } else { + Ok(PluginBackendHealthReport { + plugin_id: self.plan.plugin_id.clone(), + health: PluginBackendHealth::Unavailable, + started_at_ms: 0, + shutdown_requested: false, + message: Some(match status.exit_code { + Some(code) => format!("plugin backend exited with code {code}"), + None => "plugin backend exited".to_string(), + }), + }) + } + } + + pub async fn shutdown(&mut self) -> Result<()> { + match self.child.kill().await { + Ok(()) => Ok(()), + Err(error) if error.kind() == std::io::ErrorKind::InvalidInput => Ok(()), + Err(error) => Err(AstrError::io( + format!( + "failed to terminate plugin backend '{}'", + self.plan.plugin_id + ), + error, + )), + } + } +} + +impl BuiltinPluginRuntimeHandle { + pub fn new(plugin_id: impl Into) -> Self { + Self { + plugin_id: plugin_id.into(), + started_at_ms: now_millis(), + } + } + + pub fn health_report(&self) -> PluginBackendHealthReport { + PluginBackendHealthReport { + plugin_id: self.plugin_id.clone(), + health: PluginBackendHealth::Healthy, + started_at_ms: self.started_at_ms, + shutdown_requested: false, + message: None, + } + } +} + +impl ExternalPluginRuntimeHandle { + pub fn from_backend(backend: PluginProcessBackend) -> Self { + Self { + plugin_id: backend.plan.plugin_id.clone(), + started_at_ms: now_millis(), + shutdown_requested: false, + backend, + protocol_state: None, + } + } + + pub fn with_initialize_state(mut self, state: PluginInitializeState) -> Self { + self.protocol_state = Some(state); + self + } + + pub fn protocol_state(&self) -> Option<&PluginInitializeState> { + self.protocol_state.as_ref() + } + + pub fn remote_handshake_summary(&self) -> Option { + self.protocol_state + .as_ref() + .and_then(PluginInitializeState::remote_handshake_summary) + } + + pub fn record_remote_initialize( + &mut self, + remote_initialize: InitializeResultData, + ) -> Result<&InitializeResultData> { + let state = self.protocol_state.as_mut().ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 尚未挂接 initialize state，无法记录远端握手结果", + self.plugin_id + )) + })?; + Ok(state.record_remote_initialize(remote_initialize)) + } + + pub fn backend_kind(&self) -> PluginBackendKind { + self.backend.plan.backend_kind + } + + pub fn clone_for_snapshot(&mut self) -> SnapshotExternalPluginRuntimeHandle<'_> { + SnapshotExternalPluginRuntimeHandle { inner: self } + } + + pub fn protocol_transport(&mut self) -> Result> { + self.backend.ensure_stdio_transport() + } + + pub async fn initialize_remote(&mut self) -> Result<&InitializeResultData> { + let request = self + .protocol_state + .as_ref() + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 尚未挂接 initialize state，无法发起握手", + self.plugin_id + )) + })? + .local_initialize + .clone(); + let transport = self.protocol_transport()?; + let remote = transport.initialize(&request).await?; + self.record_remote_initialize(remote) + } + + pub async fn invoke_unary(&mut self, request: &InvokeMessage) -> Result { + let transport = self.protocol_transport()?; + transport.invoke_unary(request).await + } + + pub async fn invoke_stream(&mut self, request: &InvokeMessage) -> Result> { + let transport = self.protocol_transport()?; + transport.invoke_stream(request).await + } + + pub fn status(&mut self) -> Result { + self.backend.status() + } + + pub fn health_report(&mut self) -> Result { + let mut report = self.backend.health_report()?; + report.started_at_ms = self.started_at_ms; + report.shutdown_requested = self.shutdown_requested; + Ok(report) + } + + pub async fn shutdown(&mut self) -> Result<()> { + self.shutdown_requested = true; + self.backend.shutdown().await + } +} + +pub struct SnapshotExternalPluginRuntimeHandle<'a> { + inner: &'a mut ExternalPluginRuntimeHandle, +} + +impl SnapshotExternalPluginRuntimeHandle<'_> { + pub fn health_report(&mut self) -> Result { + self.inner.health_report() + } +} + +fn now_millis() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() as u64 +} + +#[cfg(test)] +mod tests { + use astrcode_protocol::plugin::{ + EventPhase, InitializeResultData, InvokeMessage, PeerDescriptor, PeerRole, + }; + use serde_json::json; + + use super::{ + BuiltinPluginRuntimeHandle, ExternalPluginRuntimeHandle, PluginBackendHealth, + PluginBackendKind, PluginBackendPlan, + }; + use crate::{ + PluginDescriptor, PluginInitializeState, PluginSourceKind, default_initialize_message, + default_profiles, + }; + + fn shell_command_with_args(script: &str) -> (String, Vec) { + #[cfg(windows)] + { + let command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + (command, vec!["/C".to_string(), script.to_string()]) + } + #[cfg(not(windows))] + { + ( + "/bin/sh".to_string(), + vec!["-c".to_string(), script.to_string()], + ) + } + } + + fn node_protocol_command() -> (String, Vec) { + let script = r#" +const readline = require('node:readline'); +const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity }); +rl.on('line', (line) => { + const msg = JSON.parse(line); + if (msg.type === 'initialize') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'initialize', + success: true, + output: { + protocolVersion: '5', + peer: { + id: 'fixture-worker', + name: 'fixture-worker', + role: 'worker', + version: '0.1.0', + supportedProfiles: ['coding'], + metadata: { fixture: true } + }, + capabilities: [], + handlers: [], + profiles: [{ + name: 'coding', + version: '1', + description: 'coding', + contextSchema: null, + metadata: null + }], + skills: [], + modes: [], + metadata: null + }, + metadata: null + })); + return; + } + if (msg.type === 'invoke' && msg.stream) { + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'started', + event: 'tool.started', + payload: { capability: msg.capability }, + seq: 0 + })); + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'delta', + event: 'tool.delta', + payload: { chunk: 1 }, + seq: 1 + })); + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'completed', + event: 'tool.completed', + payload: { ok: true }, + seq: 2 + })); + return; + } + if (msg.type === 'invoke') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'tool_result', + success: true, + output: { echoed: msg.input }, + metadata: { transport: 'node-fixture' } + })); + } +}); +"#; + ( + "node".to_string(), + vec!["-e".to_string(), script.to_string()], + ) + } + + #[test] + fn builtin_descriptor_maps_to_in_process_backend() { + let descriptor = PluginDescriptor::builtin("core-tools", "Core Tools"); + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("builtin descriptor should map to backend plan"); + + assert_eq!(plan.backend_kind, PluginBackendKind::InProcess); + assert!(plan.launch_command.is_none()); + } + + #[test] + fn process_descriptor_requires_launch_command() { + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + + let error = PluginBackendPlan::from_descriptor(&descriptor) + .expect_err("process descriptor without command should fail"); + + assert!(error.to_string().contains("缺少 launch_command")); + } + + #[test] + fn process_descriptor_keeps_launch_fields() { + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + descriptor.launch_command = Some("/bin/repo-inspector".to_string()); + descriptor.launch_args = vec!["--stdio".to_string()]; + descriptor.working_dir = Some("/repo".to_string()); + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("process descriptor should map to backend plan"); + + assert_eq!(plan.backend_kind, PluginBackendKind::Process); + assert_eq!(plan.launch_command.as_deref(), Some("/bin/repo-inspector")); + assert_eq!(plan.launch_args, vec!["--stdio".to_string()]); + assert_eq!(plan.working_dir.as_deref(), Some("/repo")); + } + + #[test] + fn builtin_runtime_handle_reports_healthy_status() { + let handle = BuiltinPluginRuntimeHandle::new("core-tools"); + let report = handle.health_report(); + + assert_eq!(report.plugin_id, "core-tools"); + assert_eq!(report.health, PluginBackendHealth::Healthy); + assert!(report.started_at_ms > 0); + assert!(!report.shutdown_requested); + assert!(report.message.is_none()); + } + + #[tokio::test] + async fn process_backend_can_start_check_status_and_shutdown() { + let (command, args) = shell_command_with_args("ping 127.0.0.1 -n 5 >nul"); + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + descriptor.launch_command = Some(command); + descriptor.launch_args = args; + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("process descriptor should map to backend plan"); + let mut backend = plan + .start_process() + .await + .expect("process backend should start"); + + let status = backend.status().expect("status should be readable"); + assert!(status.running); + let report = backend + .health_report() + .expect("health report should be readable"); + assert_eq!(report.health, PluginBackendHealth::Healthy); + + backend.shutdown().await.expect("shutdown should succeed"); + } + + #[tokio::test] + async fn external_runtime_handle_tracks_start_and_shutdown_state() { + let (command, args) = shell_command_with_args("ping 127.0.0.1 -n 5 >nul"); + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + descriptor.launch_command = Some(command); + descriptor.launch_args = args; + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("process descriptor should map to backend plan"); + let backend = plan + .start_process() + .await + .expect("process backend should start"); + let mut handle = ExternalPluginRuntimeHandle::from_backend(backend); + + let report = handle + .health_report() + .expect("health report should be readable"); + assert_eq!(report.plugin_id, "repo-inspector"); + assert_eq!(report.health, PluginBackendHealth::Healthy); + assert!(report.started_at_ms > 0); + assert!(!report.shutdown_requested); + + handle.shutdown().await.expect("shutdown should succeed"); + } + + #[tokio::test] + async fn external_runtime_handle_can_store_initialize_state() { + let (command, args) = shell_command_with_args("ping 127.0.0.1 -n 5 >nul"); + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + descriptor.launch_command = Some(command); + descriptor.launch_args = args; + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("process descriptor should map to backend plan"); + let backend = plan + .start_process() + .await + .expect("process backend should start"); + let local_peer = PeerDescriptor { + id: "host-1".to_string(), + name: "plugin-host".to_string(), + role: PeerRole::Supervisor, + version: "0.1.0".to_string(), + supported_profiles: vec!["coding".to_string()], + metadata: serde_json::Value::Null, + }; + let initialize_state = PluginInitializeState::new(default_initialize_message( + local_peer.clone(), + Vec::new(), + default_profiles(), + )); + let mut handle = ExternalPluginRuntimeHandle::from_backend(backend) + .with_initialize_state(initialize_state); + + assert!(handle.protocol_state().is_some()); + assert_eq!( + handle + .protocol_state() + .expect("protocol state should exist") + .negotiated_protocol_version(), + "5" + ); + + handle + .record_remote_initialize(InitializeResultData { + protocol_version: "5".to_string(), + peer: local_peer, + capabilities: Vec::new(), + handlers: Vec::new(), + profiles: default_profiles(), + skills: Vec::new(), + modes: Vec::new(), + metadata: serde_json::Value::Null, + }) + .expect("record remote initialize should succeed"); + + assert!( + handle + .protocol_state() + .expect("protocol state should exist") + .remote_initialize + .is_some() + ); + let summary = handle + .remote_handshake_summary() + .expect("remote handshake summary should exist"); + assert_eq!(summary.peer_id, "host-1"); + assert_eq!(summary.profile_names, vec!["coding".to_string()]); + + handle.shutdown().await.expect("shutdown should succeed"); + } + + #[tokio::test] + async fn builtin_backend_is_rejected_by_process_launcher() { + let descriptor = PluginDescriptor::builtin("core-tools", "Core Tools"); + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("builtin descriptor should map to backend plan"); + + let error = plan + .start_process() + .await + .expect_err("builtin backend should not start as process"); + + assert!(error.to_string().contains("builtin backend")); + } + + #[tokio::test] + async fn external_runtime_handle_can_initialize_and_invoke_over_stdio_transport() { + let (command, args) = node_protocol_command(); + let mut descriptor = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + descriptor.source_kind = PluginSourceKind::Process; + descriptor.source_ref = "plugins/repo-inspector.toml".to_string(); + descriptor.launch_command = Some(command); + descriptor.launch_args = args; + + let plan = PluginBackendPlan::from_descriptor(&descriptor) + .expect("process descriptor should map to backend plan"); + let backend = plan + .start_process() + .await + .expect("process backend should start"); + let local_peer = PeerDescriptor { + id: "host-1".to_string(), + name: "plugin-host".to_string(), + role: PeerRole::Supervisor, + version: "0.1.0".to_string(), + supported_profiles: vec!["coding".to_string()], + metadata: serde_json::Value::Null, + }; + let initialize_state = PluginInitializeState::new(default_initialize_message( + local_peer, + Vec::new(), + default_profiles(), + )); + let mut handle = ExternalPluginRuntimeHandle::from_backend(backend) + .with_initialize_state(initialize_state); + + let negotiated = handle + .initialize_remote() + .await + .expect("initialize should succeed"); + assert_eq!(negotiated.peer.id, "fixture-worker"); + + let unary = handle + .invoke_unary(&InvokeMessage { + id: "req-1".to_string(), + capability: "tool.echo".to_string(), + input: json!({ "path": "README.md" }), + context: astrcode_protocol::plugin::InvocationContext { + request_id: "req-1".to_string(), + trace_id: None, + session_id: Some("session-1".to_string()), + caller: Some(astrcode_protocol::plugin::CallerRef { + id: "test".to_string(), + role: "integration-test".to_string(), + metadata: serde_json::Value::Null, + }), + workspace: None, + deadline_ms: None, + budget: None, + profile: "coding".to_string(), + profile_context: serde_json::Value::Null, + metadata: serde_json::Value::Null, + }, + stream: false, + }) + .await + .expect("unary invoke should succeed"); + assert!(unary.success); + assert_eq!(unary.output, json!({ "echoed": { "path": "README.md" } })); + + let stream = handle + .invoke_stream(&InvokeMessage { + id: "req-2".to_string(), + capability: "tool.patch_stream".to_string(), + input: json!({ "path": "src/main.rs" }), + context: astrcode_protocol::plugin::InvocationContext { + request_id: "req-2".to_string(), + trace_id: None, + session_id: Some("session-1".to_string()), + caller: Some(astrcode_protocol::plugin::CallerRef { + id: "test".to_string(), + role: "integration-test".to_string(), + metadata: serde_json::Value::Null, + }), + workspace: None, + deadline_ms: None, + budget: None, + profile: "coding".to_string(), + profile_context: serde_json::Value::Null, + metadata: serde_json::Value::Null, + }, + stream: true, + }) + .await + .expect("stream invoke should succeed"); + assert_eq!(stream.len(), 3); + assert_eq!(stream[1].phase, EventPhase::Delta); + assert_eq!(stream[2].phase, EventPhase::Completed); + + handle.shutdown().await.expect("shutdown should succeed"); + } +} diff --git a/crates/plugin-host/src/descriptor.rs b/crates/plugin-host/src/descriptor.rs new file mode 100644 index 00000000..6ab5db7d --- /dev/null +++ b/crates/plugin-host/src/descriptor.rs @@ -0,0 +1,404 @@ +use std::collections::BTreeSet; + +use astrcode_core::{AstrError, CapabilitySpec, GovernanceModeSpec, Result}; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum PluginSourceKind { + #[default] + Builtin, + Process, + Command, + Http, +} + +impl PluginSourceKind { + pub fn to_backend_kind(self) -> crate::backend::PluginBackendKind { + match self { + Self::Builtin => crate::backend::PluginBackendKind::InProcess, + Self::Process => crate::backend::PluginBackendKind::Process, + Self::Command => crate::backend::PluginBackendKind::Command, + Self::Http => crate::backend::PluginBackendKind::Http, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct HookDescriptor { + pub hook_id: String, + pub event: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ProviderDescriptor { + pub provider_id: String, + pub api_kind: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ResourceDescriptor { + pub resource_id: String, + pub kind: String, + pub locator: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct CommandDescriptor { + pub command_id: String, + pub entry_ref: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ThemeDescriptor { + pub theme_id: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct PromptDescriptor { + pub prompt_id: String, + pub body: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct SkillDescriptor { + pub skill_id: String, + pub entry_ref: String, +} + +#[derive(Debug, Clone, PartialEq, Default)] +pub struct PluginDescriptor { + pub plugin_id: String, + pub display_name: String, + pub version: String, + pub source_kind: PluginSourceKind, + pub source_ref: String, + pub enabled: bool, + pub priority: i32, + pub launch_command: Option, + pub launch_args: Vec, + pub working_dir: Option, + pub repository: Option, + pub tools: Vec, + pub hooks: Vec, + pub providers: Vec, + pub resources: Vec, + pub commands: Vec, + pub themes: Vec, + pub prompts: Vec, + pub skills: Vec, + pub modes: Vec, +} + +impl PluginDescriptor { + pub fn builtin(plugin_id: impl Into, display_name: impl Into) -> Self { + Self { + plugin_id: plugin_id.into(), + display_name: display_name.into(), + version: "0.1.0".to_string(), + source_kind: PluginSourceKind::Builtin, + source_ref: "builtin".to_string(), + enabled: true, + priority: 0, + launch_command: None, + launch_args: Vec::new(), + working_dir: None, + repository: None, + tools: Vec::new(), + hooks: Vec::new(), + providers: Vec::new(), + resources: Vec::new(), + commands: Vec::new(), + themes: Vec::new(), + prompts: Vec::new(), + skills: Vec::new(), + modes: Vec::new(), + } + } +} + +pub fn validate_descriptors(descriptors: &[PluginDescriptor]) -> Result<()> { + let mut plugin_ids = BTreeSet::new(); + let mut tool_names = BTreeSet::new(); + let mut hook_ids = BTreeSet::new(); + let mut provider_ids = BTreeSet::new(); + let mut resource_ids = BTreeSet::new(); + let mut command_ids = BTreeSet::new(); + let mut theme_ids = BTreeSet::new(); + let mut prompt_ids = BTreeSet::new(); + let mut skill_ids = BTreeSet::new(); + let mut mode_ids = BTreeSet::new(); + + for descriptor in descriptors { + if descriptor.plugin_id.trim().is_empty() { + return Err(AstrError::Validation("plugin_id 不能为空".to_string())); + } + + if !plugin_ids.insert(descriptor.plugin_id.clone()) { + return Err(AstrError::Validation(format!( + "plugin_id '{}' 重复，无法构建统一 active snapshot", + descriptor.plugin_id + ))); + } + + for tool in &descriptor.tools { + let tool_name = tool.name.to_string(); + if !tool_names.insert(tool_name.clone()) { + return Err(AstrError::Validation(format!( + "tool '{}' 在同一 snapshot 中重复注册", + tool_name + ))); + } + } + + for hook in &descriptor.hooks { + if !hook_ids.insert(hook.hook_id.clone()) { + return Err(AstrError::Validation(format!( + "hook '{}' 在同一 snapshot 中重复注册", + hook.hook_id + ))); + } + } + + for provider in &descriptor.providers { + if !provider_ids.insert(provider.provider_id.clone()) { + return Err(AstrError::Validation(format!( + "provider '{}' 在同一 snapshot 中重复注册", + provider.provider_id + ))); + } + } + + for resource in &descriptor.resources { + if !resource_ids.insert(resource.resource_id.clone()) { + return Err(AstrError::Validation(format!( + "resource '{}' 在同一 snapshot 中重复注册", + resource.resource_id + ))); + } + } + + for command in &descriptor.commands { + if !command_ids.insert(command.command_id.clone()) { + return Err(AstrError::Validation(format!( + "command '{}' 在同一 snapshot 中重复注册", + command.command_id + ))); + } + } + + for theme in &descriptor.themes { + if !theme_ids.insert(theme.theme_id.clone()) { + return Err(AstrError::Validation(format!( + "theme '{}' 在同一 snapshot 中重复注册", + theme.theme_id + ))); + } + } + + for prompt in &descriptor.prompts { + if !prompt_ids.insert(prompt.prompt_id.clone()) { + return Err(AstrError::Validation(format!( + "prompt '{}' 在同一 snapshot 中重复注册", + prompt.prompt_id + ))); + } + } + + for skill in &descriptor.skills { + if !skill_ids.insert(skill.skill_id.clone()) { + return Err(AstrError::Validation(format!( + "skill '{}' 在同一 snapshot 中重复注册", + skill.skill_id + ))); + } + } + + for mode in &descriptor.modes { + mode.validate()?; + let mode_id = mode.id.as_str().to_string(); + if !mode_ids.insert(mode_id.clone()) { + return Err(AstrError::Validation(format!( + "mode '{}' 在同一 snapshot 中重复注册", + mode_id + ))); + } + } + } + + Ok(()) +} + +#[cfg(test)] +mod tests { + use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; + + use super::{ + CommandDescriptor, HookDescriptor, PluginDescriptor, PluginSourceKind, PromptDescriptor, + ProviderDescriptor, ResourceDescriptor, SkillDescriptor, ThemeDescriptor, + validate_descriptors, + }; + + fn tool(name: &str) -> CapabilitySpec { + CapabilitySpec { + name: name.into(), + kind: CapabilityKind::Tool, + description: format!("{name} capability"), + input_schema: Default::default(), + output_schema: Default::default(), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: false, + profiles: vec!["coding".to_string()], + tags: Vec::new(), + permissions: Vec::new(), + side_effect: SideEffect::None, + stability: Stability::Stable, + metadata: Default::default(), + max_result_inline_size: None, + } + } + + #[test] + fn builtin_descriptor_uses_builtin_defaults() { + let descriptor = PluginDescriptor::builtin("core-tools", "Core Tools"); + + assert_eq!(descriptor.plugin_id, "core-tools"); + assert_eq!(descriptor.display_name, "Core Tools"); + assert_eq!(descriptor.source_kind, PluginSourceKind::Builtin); + assert!(descriptor.enabled); + assert!(descriptor.tools.is_empty()); + assert!(descriptor.hooks.is_empty()); + assert!(descriptor.modes.is_empty()); + } + + #[test] + fn validate_descriptors_rejects_duplicate_plugin_ids() { + let descriptors = vec![ + PluginDescriptor::builtin("alpha", "Alpha"), + PluginDescriptor::builtin("alpha", "Alpha Again"), + ]; + + let error = + validate_descriptors(&descriptors).expect_err("duplicate plugin ids should fail"); + assert!(error.to_string().contains("plugin_id 'alpha' 重复")); + } + + #[test] + fn validate_descriptors_rejects_duplicate_tool_names() { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.tools.push(tool("tool.shared")); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.tools.push(tool("tool.shared")); + + let error = + validate_descriptors(&[alpha, beta]).expect_err("duplicate tool names should fail"); + assert!(error.to_string().contains("tool 'tool.shared'")); + } + + #[test] + fn validate_descriptors_rejects_duplicate_resource_like_ids() { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.hooks.push(HookDescriptor { + hook_id: "hook.shared".to_string(), + event: "tool_call".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.hooks.push(HookDescriptor { + hook_id: "hook.shared".to_string(), + event: "tool_result".to_string(), + }); + + let error = + validate_descriptors(&[alpha, beta]).expect_err("duplicate hook ids should fail"); + assert!(error.to_string().contains("hook 'hook.shared'")); + } + + #[test] + fn validate_descriptors_rejects_duplicate_resource_command_theme_prompt_skill_ids() { + let cases = vec![ + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.resources.push(ResourceDescriptor { + resource_id: "resource.shared".to_string(), + kind: "docs".to_string(), + locator: "docs".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.resources.push(ResourceDescriptor { + resource_id: "resource.shared".to_string(), + kind: "docs".to_string(), + locator: "docs-other".to_string(), + }); + (vec![alpha, beta], "resource 'resource.shared'") + }, + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.commands.push(CommandDescriptor { + command_id: "command.shared".to_string(), + entry_ref: "commands/a.md".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.commands.push(CommandDescriptor { + command_id: "command.shared".to_string(), + entry_ref: "commands/b.md".to_string(), + }); + (vec![alpha, beta], "command 'command.shared'") + }, + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.themes.push(ThemeDescriptor { + theme_id: "theme.shared".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.themes.push(ThemeDescriptor { + theme_id: "theme.shared".to_string(), + }); + (vec![alpha, beta], "theme 'theme.shared'") + }, + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "a".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "b".to_string(), + }); + (vec![alpha, beta], "prompt 'prompt.shared'") + }, + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.skills.push(SkillDescriptor { + skill_id: "skill.shared".to_string(), + entry_ref: "skills/a/SKILL.md".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.skills.push(SkillDescriptor { + skill_id: "skill.shared".to_string(), + entry_ref: "skills/b/SKILL.md".to_string(), + }); + (vec![alpha, beta], "skill 'skill.shared'") + }, + { + let mut alpha = PluginDescriptor::builtin("alpha", "Alpha"); + alpha.providers.push(ProviderDescriptor { + provider_id: "provider.shared".to_string(), + api_kind: "openai".to_string(), + }); + let mut beta = PluginDescriptor::builtin("beta", "Beta"); + beta.providers.push(ProviderDescriptor { + provider_id: "provider.shared".to_string(), + api_kind: "anthropic".to_string(), + }); + (vec![alpha, beta], "provider 'provider.shared'") + }, + ]; + + for (descriptors, expected) in cases { + let error = validate_descriptors(&descriptors) + .expect_err("duplicate resource-like ids should fail"); + assert!(error.to_string().contains(expected), "{expected}"); + } + } +} diff --git a/crates/plugin-host/src/hooks.rs b/crates/plugin-host/src/hooks.rs new file mode 100644 index 00000000..c42d5a82 --- /dev/null +++ b/crates/plugin-host/src/hooks.rs @@ -0,0 +1,323 @@ +use astrcode_core::{AstrError, HookEventKey, Result}; +use serde_json::Value; + +use crate::HookDescriptor; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HookStage { + Runtime, + Host, + Resource, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HookDispatchMode { + Sequential, + Cancellable, + Intercept, + Modify, + Pipeline, + ShortCircuit, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HookFailurePolicy { + FailClosed, + FailOpen, + ReportOnly, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HookBusEffectKind { + Continue, + Block, + CancelTurn, + TransformInput, + AugmentPrompt, + MutatePayload, + OverrideToolResult, + ResourcePath, + ModelHint, + Diagnostic, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct HookBusEffect { + pub kind: HookBusEffectKind, + pub payload: Value, + pub terminal: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct HookRegistration { + pub descriptor: HookDescriptor, + pub stage: HookStage, + pub dispatch_mode: HookDispatchMode, + pub failure_policy: HookFailurePolicy, + pub priority: i32, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct HookBusStep { + pub registration: HookRegistration, + pub effect: HookBusEffect, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct HookBusRequest { + pub event: HookEventKey, + pub payload: Value, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct HookBusOutcome { + pub payload: Value, + pub effects: Vec, + pub blocked_by: Option, +} + +pub const SUPPORTED_HOOK_EVENTS: &[HookEventKey] = &[ + HookEventKey::Input, + HookEventKey::Context, + HookEventKey::BeforeAgentStart, + HookEventKey::BeforeProviderRequest, + HookEventKey::ToolCall, + HookEventKey::ToolResult, + HookEventKey::TurnStart, + HookEventKey::TurnEnd, + HookEventKey::SessionBeforeCompact, + HookEventKey::ResourcesDiscover, + HookEventKey::ModelSelect, +]; + +pub fn dispatch_hook_bus( + request: HookBusRequest, + mut steps: Vec, +) -> Result { + if !SUPPORTED_HOOK_EVENTS.contains(&request.event) { + return Err(AstrError::Validation(format!( + "hook event '{:?}' is not supported by plugin-host hook bus", + request.event + ))); + } + steps.sort_by(|left, right| { + right + .registration + .priority + .cmp(&left.registration.priority) + .then_with(|| { + left.registration + .descriptor + .hook_id + .cmp(&right.registration.descriptor.hook_id) + }) + }); + + let mut payload = request.payload; + let mut effects = Vec::new(); + let mut blocked_by = None; + + for step in steps { + if !hook_targets_event(&step.registration.descriptor, request.event) { + continue; + } + + let effect = step.effect; + match step.registration.dispatch_mode { + HookDispatchMode::Modify | HookDispatchMode::Pipeline => { + if matches!( + effect.kind, + HookBusEffectKind::TransformInput | HookBusEffectKind::MutatePayload + ) { + payload = effect.payload.clone(); + } + }, + HookDispatchMode::Cancellable + | HookDispatchMode::Intercept + | HookDispatchMode::ShortCircuit => { + if effect.terminal + || matches!( + effect.kind, + HookBusEffectKind::Block | HookBusEffectKind::CancelTurn + ) + { + blocked_by = Some(step.registration.descriptor.hook_id.clone()); + effects.push(effect); + break; + } + }, + HookDispatchMode::Sequential => {}, + } + effects.push(effect); + } + + Ok(HookBusOutcome { + payload, + effects, + blocked_by, + }) +} + +fn hook_targets_event(descriptor: &HookDescriptor, event: HookEventKey) -> bool { + descriptor.event == format!("{event:?}") || descriptor.event == hook_event_key_name(event) +} + +fn hook_event_key_name(event: HookEventKey) -> &'static str { + match event { + HookEventKey::Input => "input", + HookEventKey::Context => "context", + HookEventKey::BeforeAgentStart => "before_agent_start", + HookEventKey::BeforeProviderRequest => "before_provider_request", + HookEventKey::ToolCall => "tool_call", + HookEventKey::ToolResult => "tool_result", + HookEventKey::TurnStart => "turn_start", + HookEventKey::TurnEnd => "turn_end", + HookEventKey::SessionBeforeCompact => "session_before_compact", + HookEventKey::ResourcesDiscover => "resources_discover", + HookEventKey::ModelSelect => "model_select", + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + + fn registration( + id: &str, + event: &str, + priority: i32, + dispatch_mode: HookDispatchMode, + ) -> HookRegistration { + HookRegistration { + descriptor: HookDescriptor { + hook_id: id.to_string(), + event: event.to_string(), + }, + stage: HookStage::Runtime, + dispatch_mode, + failure_policy: HookFailurePolicy::FailClosed, + priority, + } + } + + fn effect(kind: HookBusEffectKind, payload: Value, terminal: bool) -> HookBusEffect { + HookBusEffect { + kind, + payload, + terminal, + } + } + + #[test] + fn hook_bus_lists_the_full_event_surface() { + assert_eq!(SUPPORTED_HOOK_EVENTS.len(), 11); + assert!(SUPPORTED_HOOK_EVENTS.contains(&HookEventKey::ResourcesDiscover)); + assert!(SUPPORTED_HOOK_EVENTS.contains(&HookEventKey::ModelSelect)); + } + + #[test] + fn hook_bus_runs_matching_hooks_by_priority_order() { + let outcome = dispatch_hook_bus( + HookBusRequest { + event: HookEventKey::ToolCall, + payload: json!({ "tool": "readFile" }), + }, + vec![ + HookBusStep { + registration: registration("low", "tool_call", 1, HookDispatchMode::Sequential), + effect: effect(HookBusEffectKind::Diagnostic, json!("low"), false), + }, + HookBusStep { + registration: registration( + "high", + "tool_call", + 10, + HookDispatchMode::Sequential, + ), + effect: effect(HookBusEffectKind::Diagnostic, json!("high"), false), + }, + ], + ) + .expect("hook bus should dispatch"); + + assert_eq!(outcome.effects[0].payload, json!("high")); + assert_eq!(outcome.effects[1].payload, json!("low")); + assert!(outcome.blocked_by.is_none()); + } + + #[test] + fn hook_bus_stops_on_terminal_blocking_effect() { + let outcome = dispatch_hook_bus( + HookBusRequest { + event: HookEventKey::BeforeProviderRequest, + payload: json!({ "model": "gpt" }), + }, + vec![ + HookBusStep { + registration: registration( + "blocker", + "before_provider_request", + 10, + HookDispatchMode::Cancellable, + ), + effect: effect( + HookBusEffectKind::Block, + json!({ "reason": "policy" }), + true, + ), + }, + HookBusStep { + registration: registration( + "later", + "before_provider_request", + 1, + HookDispatchMode::Sequential, + ), + effect: effect( + HookBusEffectKind::Diagnostic, + json!("should-not-run"), + false, + ), + }, + ], + ) + .expect("hook bus should dispatch"); + + assert_eq!(outcome.blocked_by.as_deref(), Some("blocker")); + assert_eq!(outcome.effects.len(), 1); + } + + #[test] + fn hook_bus_applies_modify_and_pipeline_payloads() { + let outcome = dispatch_hook_bus( + HookBusRequest { + event: HookEventKey::Input, + payload: json!({ "text": "original" }), + }, + vec![ + HookBusStep { + registration: registration("rewrite", "input", 1, HookDispatchMode::Modify), + effect: effect( + HookBusEffectKind::TransformInput, + json!({ "text": "rewritten" }), + false, + ), + }, + HookBusStep { + registration: registration("pipeline", "input", 0, HookDispatchMode::Pipeline), + effect: effect( + HookBusEffectKind::MutatePayload, + json!({ "text": "pipelined" }), + false, + ), + }, + ], + ) + .expect("hook bus should dispatch"); + + assert_eq!(outcome.payload, json!({ "text": "pipelined" })); + assert_eq!(outcome.effects.len(), 2); + } +} diff --git a/crates/plugin-host/src/host.rs b/crates/plugin-host/src/host.rs new file mode 100644 index 00000000..0401215d --- /dev/null +++ b/crates/plugin-host/src/host.rs @@ -0,0 +1,320 @@ +use std::time::{SystemTime, UNIX_EPOCH}; + +use astrcode_core::{CapabilityContext, Result}; +use astrcode_protocol::plugin::{ + CapabilityWireDescriptor, InvocationContext, PeerDescriptor, WorkspaceRef, +}; +use serde_json::Value; + +use crate::{ + PluginActiveSnapshot, PluginDescriptor, PluginInitializeState, PluginLoader, PluginRegistry, + ResourceCatalog, + backend::{ + BuiltinPluginRuntimeHandle, ExternalPluginRuntimeHandle, PluginBackendHealthReport, + PluginBackendKind, PluginBackendPlan, + }, + default_local_peer_descriptor, resources_discover, +}; + +/// `plugin-host` 的最小外观。 +/// +/// 它先只承接 registry 的 staging / commit / rollback， +/// 后续再把 loader、backend 和资源发现逐步接进来。 +#[derive(Debug)] +pub struct PluginHost { + registry: PluginRegistry, + local_peer: PeerDescriptor, +} + +#[derive(Debug)] +pub struct PluginHostReload { + pub descriptors: Vec, + pub snapshot: PluginActiveSnapshot, + pub builtin_backends: Vec, + pub external_backends: Vec, + pub resources: ResourceCatalog, + pub backend_health: ExternalBackendHealthCatalog, + pub negotiated_plugins: NegotiatedPluginCatalog, + pub runtime_catalog: ActivePluginRuntimeCatalog, +} + +#[path = "host_dispatch.rs"] +mod dispatch; + +pub use dispatch::*; + +#[path = "host_catalog.rs"] +mod catalog; + +pub use catalog::*; + + +#[path = "host_reload.rs"] +mod reload; + +impl PluginHost { + pub fn new() -> Self { + Self::with_local_peer(default_local_peer_descriptor()) + } + + pub fn with_local_peer(local_peer: PeerDescriptor) -> Self { + Self { + registry: PluginRegistry::default(), + local_peer, + } + } + + pub fn registry(&self) -> &PluginRegistry { + &self.registry + } + + pub fn local_peer(&self) -> &PeerDescriptor { + &self.local_peer + } + + pub fn stage_candidate( + &self, + descriptors: impl IntoIterator, + ) -> Result { + self.registry.stage_candidate(descriptors) + } + + pub fn commit_candidate(&self) -> Option { + self.registry.commit_candidate() + } + + pub fn rollback_candidate(&self) -> Option { + self.registry.rollback_candidate() + } + + pub fn active_snapshot(&self) -> Option { + self.registry.active_snapshot() + } + + pub fn backend_plans( + &self, + descriptors: &[PluginDescriptor], + ) -> Result> { + descriptors + .iter() + .map(PluginBackendPlan::from_descriptor) + .collect() + } + + fn sort_descriptors_for_reload(descriptors: &mut [PluginDescriptor]) { + descriptors.sort_by(|left, right| { + left.plugin_id + .cmp(&right.plugin_id) + .then_with(|| left.version.cmp(&right.version)) + .then_with(|| left.source_ref.cmp(&right.source_ref)) + }); + } + + pub async fn start_external_process_backends( + &self, + plans: &[PluginBackendPlan], + ) -> Result> { + self.start_external_process_backends_with_capabilities(plans, &[]) + .await + } + + pub async fn start_external_process_backends_with_capabilities( + &self, + plans: &[PluginBackendPlan], + capabilities: &[CapabilityWireDescriptor], + ) -> Result> { + let mut backends = Vec::new(); + for plan in plans { + match plan.backend_kind { + PluginBackendKind::Process | PluginBackendKind::Command => { + let backend = plan.start_process().await?; + let initialize_state = PluginInitializeState::with_defaults( + self.local_peer.clone(), + capabilities.to_vec(), + ); + backends.push( + ExternalPluginRuntimeHandle::from_backend(backend) + .with_initialize_state(initialize_state), + ); + }, + PluginBackendKind::InProcess | PluginBackendKind::Http => { + // builtin 和 http backend 在后续阶段走各自 owner 路径， + // 这里不误触发外部进程启动。 + }, + } + } + Ok(backends) + } + + pub fn materialize_builtin_backends( + &self, + plans: &[PluginBackendPlan], + ) -> Vec { + plans + .iter() + .filter(|plan| plan.backend_kind == PluginBackendKind::InProcess) + .map(|plan| BuiltinPluginRuntimeHandle::new(plan.plugin_id.clone())) + .collect() + } + + pub fn external_backend_health_reports( + &self, + backends: &mut [ExternalPluginRuntimeHandle], + ) -> Result> { + backends + .iter_mut() + .map(ExternalPluginRuntimeHandle::health_report) + .collect() + } + + pub async fn reload_from_descriptors( + &self, + descriptors: Vec, + ) -> Result { + self.reload_from_descriptors_with_capabilities(descriptors, &[]) + .await + } + + pub async fn reload_from_descriptors_with_capabilities( + &self, + mut descriptors: Vec, + capabilities: &[CapabilityWireDescriptor], + ) -> Result { + Self::sort_descriptors_for_reload(&mut descriptors); + let plans = self.backend_plans(&descriptors)?; + let resources = resources_discover(&descriptors)?.catalog; + self.registry.stage_candidate(descriptors.clone())?; + let builtin_backends = self.materialize_builtin_backends(&plans); + let external_backends = match self + .start_external_process_backends_with_capabilities(&plans, capabilities) + .await + { + Ok(backends) => backends, + Err(error) => { + self.registry.rollback_candidate(); + return Err(error); + }, + }; + let snapshot = self.registry.commit_candidate().ok_or_else(|| { + astrcode_core::AstrError::Internal("candidate commit unexpectedly failed".to_string()) + })?; + let negotiated_plugins = + NegotiatedPluginCatalog::from_external_backends(&external_backends); + let mut reload = PluginHostReload { + descriptors, + snapshot, + builtin_backends, + external_backends, + resources, + backend_health: ExternalBackendHealthCatalog::default(), + negotiated_plugins, + runtime_catalog: ActivePluginRuntimeCatalog { + snapshot_id: String::new(), + revision: 0, + plugin_ids: Vec::new(), + entries: Vec::new(), + tool_names: Vec::new(), + hook_ids: Vec::new(), + provider_ids: Vec::new(), + resource_ids: Vec::new(), + command_ids: Vec::new(), + theme_ids: Vec::new(), + prompt_ids: Vec::new(), + skill_ids: Vec::new(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + }, + }; + reload.refresh_external_backend_health(self)?; + reload.refresh_runtime_catalog(); + Ok(reload) + } + + pub async fn reload_with_builtin_and_loader( + &self, + builtin_descriptors: Vec, + loader: &PluginLoader, + ) -> Result { + self.reload_with_builtin_loader_and_capabilities(builtin_descriptors, loader, &[]) + .await + } + + pub async fn reload_with_builtin_loader_and_capabilities( + &self, + builtin_descriptors: Vec, + loader: &PluginLoader, + capabilities: &[CapabilityWireDescriptor], + ) -> Result { + let discovered_descriptors = loader.discover_descriptors()?; + let mut descriptors = builtin_descriptors; + descriptors.extend(discovered_descriptors); + let reload = self + .reload_from_descriptors_with_capabilities(descriptors, capabilities) + .await?; + Ok(reload) + } + + pub async fn reload_with_external_backends( + &self, + loader: &PluginLoader, + ) -> Result { + let descriptors = loader.discover_descriptors()?; + self.reload_from_descriptors(descriptors).await + } + + /// 从 loader 发现 descriptors，并将其提交为新的 active snapshot。 + pub fn reload_from_loader(&self, loader: &PluginLoader) -> Result { + let descriptors = loader.discover_descriptors()?; + let _plans = self.backend_plans(&descriptors)?; + self.registry.stage_candidate(descriptors)?; + self.registry.commit_candidate().ok_or_else(|| { + astrcode_core::AstrError::Internal("candidate commit unexpectedly failed".to_string()) + }) + } +} + +impl Default for PluginHost { + fn default() -> Self { + Self::new() + } +} + +fn to_plugin_invocation_context( + ctx: &CapabilityContext, + capability_name: &str, +) -> InvocationContext { + let working_dir = ctx.working_dir.to_string_lossy().into_owned(); + let request_id = ctx.request_id.clone().unwrap_or_else(|| { + format!( + "{}:{}:{}", + ctx.session_id, + capability_name, + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() + ) + }); + + InvocationContext { + request_id, + trace_id: ctx.trace_id.clone(), + session_id: Some(ctx.session_id.to_string()), + caller: None, + workspace: Some(WorkspaceRef { + working_dir: Some(working_dir.clone()), + repo_root: Some(working_dir), + branch: None, + metadata: Value::Null, + }), + deadline_ms: None, + budget: None, + profile: ctx.profile.clone(), + profile_context: ctx.profile_context.clone(), + metadata: ctx.metadata.clone(), + } +} + + +#[cfg(test)] +#[path = "host_tests.rs"] +mod host_tests; diff --git a/crates/plugin-host/src/host_catalog.rs b/crates/plugin-host/src/host_catalog.rs new file mode 100644 index 00000000..cd1de2be --- /dev/null +++ b/crates/plugin-host/src/host_catalog.rs @@ -0,0 +1,292 @@ +use super::PluginHostReload; +use crate::{ + RemotePluginHandshakeSummary, + backend::{ExternalPluginRuntimeHandle, PluginBackendHealthReport}, +}; + +/// 宿主可直接消费的 external plugin 协商目录。 +/// +/// 这层故意不暴露进程句柄，也不暴露完整协议对象； +/// 它只是 reload 后交给组合根的只读协商视图。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct NegotiatedPluginCatalog { + pub plugin_ids: Vec, + pub remote_plugins: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct NegotiatedPluginEntry { + pub plugin_id: String, + pub local_protocol_version: String, + pub remote: Option, +} + +/// external backend 健康目录。 +/// +/// 组合根可以通过这层看到当前 external plugin 的健康状态， +/// 不需要直接拿到底层 runtime handle。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ExternalBackendHealthCatalog { + pub reports: Vec, +} + +/// 组合根直接消费的统一运行时目录。 +/// +/// 这层把 active snapshot、资源目录、协商目录收成单一只读视图， +/// 让后续 server/host-session 不必分别拉三份事实源。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ActivePluginRuntimeCatalog { + pub snapshot_id: String, + pub revision: u64, + pub plugin_ids: Vec, + pub entries: Vec, + pub tool_names: Vec, + pub hook_ids: Vec, + pub provider_ids: Vec, + pub resource_ids: Vec, + pub command_ids: Vec, + pub theme_ids: Vec, + pub prompt_ids: Vec, + pub skill_ids: Vec, + pub negotiated_plugins: NegotiatedPluginCatalog, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ActivePluginRuntimeEntry { + pub plugin_id: String, + pub display_name: String, + pub source_kind: crate::PluginSourceKind, + pub enabled: bool, + pub has_external_backend: bool, + pub has_builtin_backend: bool, + pub has_runtime_handle: bool, + pub backend_health: Option, + pub backend_health_message: Option, + pub tool_names: Vec, + pub hook_ids: Vec, + pub provider_ids: Vec, + pub resource_ids: Vec, + pub command_ids: Vec, + pub theme_ids: Vec, + pub prompt_ids: Vec, + pub skill_ids: Vec, + pub local_protocol_version: Option, + pub remote: Option, +} + +impl NegotiatedPluginCatalog { + pub fn from_external_backends(backends: &[ExternalPluginRuntimeHandle]) -> Self { + Self { + plugin_ids: backends + .iter() + .map(|backend| backend.plugin_id.clone()) + .collect(), + remote_plugins: backends + .iter() + .map(|backend| NegotiatedPluginEntry { + plugin_id: backend.plugin_id.clone(), + local_protocol_version: backend + .protocol_state() + .map(|state| state.local_initialize.protocol_version.clone()) + .unwrap_or_default(), + remote: backend.remote_handshake_summary(), + }) + .collect(), + } + } + + pub fn refresh_from_external_backends(&mut self, backends: &[ExternalPluginRuntimeHandle]) { + *self = Self::from_external_backends(backends); + } +} + +impl ExternalBackendHealthCatalog { + pub fn from_reports(reports: Vec) -> Self { + Self { reports } + } + + pub fn report(&self, plugin_id: &str) -> Option<&PluginBackendHealthReport> { + self.reports + .iter() + .find(|report| report.plugin_id == plugin_id) + } +} + +impl ActivePluginRuntimeCatalog { + pub fn from_reload(reload: &PluginHostReload) -> Self { + let entries = reload + .descriptors + .iter() + .map(|descriptor| { + let backend = reload + .external_backends + .iter() + .find(|backend| backend.plugin_id == descriptor.plugin_id); + let builtin_backend = reload + .builtin_backends + .iter() + .find(|backend| backend.plugin_id == descriptor.plugin_id); + let health = reload.backend_health.report(&descriptor.plugin_id); + ActivePluginRuntimeEntry { + plugin_id: descriptor.plugin_id.clone(), + display_name: descriptor.display_name.clone(), + source_kind: descriptor.source_kind, + enabled: descriptor.enabled, + has_external_backend: backend.is_some(), + has_builtin_backend: builtin_backend.is_some(), + has_runtime_handle: backend.is_some() || builtin_backend.is_some(), + backend_health: health.map(|report| report.health.clone()), + backend_health_message: health.and_then(|report| report.message.clone()), + tool_names: descriptor + .tools + .iter() + .map(|tool| tool.name.to_string()) + .collect(), + hook_ids: descriptor + .hooks + .iter() + .map(|hook| hook.hook_id.clone()) + .collect(), + provider_ids: descriptor + .providers + .iter() + .map(|provider| provider.provider_id.clone()) + .collect(), + resource_ids: descriptor + .resources + .iter() + .map(|resource| resource.resource_id.clone()) + .collect(), + command_ids: descriptor + .commands + .iter() + .map(|command| command.command_id.clone()) + .collect(), + theme_ids: descriptor + .themes + .iter() + .map(|theme| theme.theme_id.clone()) + .collect(), + prompt_ids: descriptor + .prompts + .iter() + .map(|prompt| prompt.prompt_id.clone()) + .collect(), + skill_ids: descriptor + .skills + .iter() + .map(|skill| skill.skill_id.clone()) + .collect(), + local_protocol_version: backend.and_then(|backend| { + backend + .protocol_state() + .map(|state| state.local_initialize.protocol_version.clone()) + }), + remote: backend.and_then(ExternalPluginRuntimeHandle::remote_handshake_summary), + } + }) + .collect(); + + Self { + snapshot_id: reload.snapshot.snapshot_id.clone(), + revision: reload.snapshot.revision, + plugin_ids: reload.snapshot.plugin_ids.clone(), + entries, + tool_names: reload + .snapshot + .tools + .iter() + .map(|tool| tool.name.to_string()) + .collect(), + hook_ids: reload + .snapshot + .hooks + .iter() + .map(|hook| hook.hook_id.clone()) + .collect(), + provider_ids: reload + .snapshot + .providers + .iter() + .map(|provider| provider.provider_id.clone()) + .collect(), + resource_ids: reload + .resources + .resources + .iter() + .map(|resource| resource.resource_id.clone()) + .collect(), + command_ids: reload + .resources + .commands + .iter() + .map(|command| command.command_id.clone()) + .collect(), + theme_ids: reload + .resources + .themes + .iter() + .map(|theme| theme.theme_id.clone()) + .collect(), + prompt_ids: reload + .resources + .prompts + .iter() + .map(|prompt| prompt.prompt_id.clone()) + .collect(), + skill_ids: reload + .resources + .skills + .iter() + .map(|skill| skill.skill_id.clone()) + .collect(), + negotiated_plugins: reload.negotiated_plugins.clone(), + } + } + + pub fn entry(&self, plugin_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.plugin_id == plugin_id) + } + + pub fn enabled_entries(&self) -> Vec<&ActivePluginRuntimeEntry> { + self.entries.iter().filter(|entry| entry.enabled).collect() + } + + pub fn tool_owner(&self, tool_name: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.tool_names.iter().any(|name| name == tool_name)) + } + + pub fn hook_owner(&self, hook_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.hook_ids.iter().any(|id| id == hook_id)) + } + + pub fn provider_owner(&self, provider_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.provider_ids.iter().any(|id| id == provider_id)) + } + + pub fn command_owner(&self, command_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.command_ids.iter().any(|id| id == command_id)) + } + + pub fn prompt_owner(&self, prompt_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.prompt_ids.iter().any(|id| id == prompt_id)) + } + + pub fn skill_owner(&self, skill_id: &str) -> Option<&ActivePluginRuntimeEntry> { + self.entries + .iter() + .find(|entry| entry.skill_ids.iter().any(|id| id == skill_id)) + } +} diff --git a/crates/plugin-host/src/host_dispatch.rs b/crates/plugin-host/src/host_dispatch.rs new file mode 100644 index 00000000..fc6e9afe --- /dev/null +++ b/crates/plugin-host/src/host_dispatch.rs @@ -0,0 +1,447 @@ +use std::{collections::BTreeMap, sync::Arc}; + +use astrcode_core::{AstrError, CapabilityContext, CapabilityExecutionResult, Result}; +use astrcode_protocol::plugin::{ + CapabilityWireDescriptor, EventMessage, EventPhase, InvocationContext, InvokeMessage, + ResultMessage, +}; +use serde_json::Value; + +use crate::backend::{BuiltinPluginRuntimeHandle, ExternalPluginRuntimeHandle, PluginBackendKind}; + +#[derive(Debug, Clone, Copy)] +pub enum PluginRuntimeHandleRef<'a> { + Builtin(&'a BuiltinPluginRuntimeHandle), + External(&'a ExternalPluginRuntimeHandle), +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PluginRuntimeHandleSnapshot { + pub plugin_id: String, + pub backend_kind: PluginBackendKind, + pub started_at_ms: u64, + pub shutdown_requested: bool, + pub health: Option, + pub message: Option, + pub local_protocol_version: Option, + pub remote_negotiated: bool, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityBinding { + pub plugin_id: String, + pub display_name: String, + pub backend_kind: PluginBackendKind, + pub capability: CapabilityWireDescriptor, + pub runtime_handle: Option, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityInvocationPlan { + pub binding: PluginCapabilityBinding, + pub payload: Value, + pub stream: bool, + pub invocation_context: InvocationContext, + pub invoke_message: InvokeMessage, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum PluginCapabilityDispatchKind { + BuiltinInProcess, + ExternalProtocol, + ExternalHttp, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityInvocationTarget { + pub dispatch_kind: PluginCapabilityDispatchKind, + pub plan: PluginCapabilityInvocationPlan, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityDispatchTicket { + pub target: PluginCapabilityInvocationTarget, +} + +/// 统一调用 owner 给出的最小分派结果。 +/// +/// builtin 直接在宿主内执行并返回结果； +/// external backend 先收口成稳定的 dispatch 请求对象， +/// 后续再由真正的 transport / protocol owner 接手。 +#[derive(Debug, Clone, PartialEq)] +pub enum PluginCapabilityDispatchOutcome { + Completed(CapabilityExecutionResult), + ExternalProtocol(PluginCapabilityProtocolDispatch), + ExternalHttp(PluginCapabilityHttpDispatch), +} + +/// external protocol backend 的最小分派请求。 +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityProtocolDispatch { + pub runtime_handle: PluginRuntimeHandleSnapshot, + pub target: PluginCapabilityInvocationTarget, +} + +/// external HTTP backend 的最小分派请求。 +#[derive(Debug, Clone, PartialEq)] +pub struct PluginCapabilityHttpDispatch { + pub target: PluginCapabilityInvocationTarget, +} + +/// external protocol backend 的最小执行结果。 +#[derive(Debug, Clone, PartialEq)] +pub enum PluginCapabilityProtocolExecution { + Unary(ResultMessage), + Stream(Vec), +} + +/// external protocol dispatcher 合同。 +/// +/// transport / peer / supervisor 的真实实现后续可以挂在这层后面， +/// 但 `plugin-host` 先把统一调用 owner 的执行入口固定下来。 +pub trait PluginCapabilityProtocolDispatcher { + fn dispatch( + &self, + dispatch: &PluginCapabilityProtocolDispatch, + ) -> Result; +} + +/// protocol transport 合同。 +/// +/// 真实 stdio / rpc / remote peer 实现后续只需要满足这层发送接口， +/// 不需要重新解释 invocation target 或结果映射。 +pub trait PluginCapabilityProtocolTransport: Send + Sync { + fn invoke_unary(&self, dispatch: &PluginCapabilityProtocolDispatch) -> Result; + + fn invoke_stream( + &self, + dispatch: &PluginCapabilityProtocolDispatch, + ) -> Result>; +} + +/// external HTTP dispatcher 合同。 +pub trait PluginCapabilityHttpDispatcher { + fn dispatch( + &self, + dispatch: &PluginCapabilityHttpDispatch, + ) -> Result; +} + +/// protocol dispatcher 注册表。 +#[derive(Default)] +pub struct PluginCapabilityProtocolDispatcherRegistry { + dispatchers: BTreeMap>, +} + +/// HTTP dispatcher 注册表。 +#[derive(Default)] +pub struct PluginCapabilityHttpDispatcherRegistry { + dispatchers: BTreeMap>, +} + +/// `plugin-host` 的统一 dispatcher set。 +/// +/// 组合根后续只需要持有这一份宿主执行集合， +/// 不必在每次调用时再拆开传三份 registry。 +#[derive(Default)] +pub struct PluginCapabilityDispatcherSet { + pub builtin: BuiltinCapabilityExecutorRegistry, + pub protocol: PluginCapabilityProtocolDispatcherRegistry, + pub http: PluginCapabilityHttpDispatcherRegistry, + default_protocol: Option>, + default_http: Option>, +} + +/// 基于 transport 的 protocol dispatcher。 +pub struct TransportBackedProtocolDispatcher { + transport: T, +} + +impl PluginCapabilityProtocolDispatch { + pub fn into_execution_result(self, result: ResultMessage) -> CapabilityExecutionResult { + let error = if result.success { + None + } else { + Some( + result + .error + .map(|value| value.message) + .unwrap_or_else(|| "plugin invocation failed".to_string()), + ) + }; + CapabilityExecutionResult::from_common( + self.target.plan.binding.capability.name.to_string(), + result.success, + result.output, + None, + astrcode_core::ExecutionResultCommon { + error: error.clone(), + metadata: Some(result.metadata), + duration_ms: 0, + truncated: false, + }, + ) + } + + pub fn finish_stream_execution_result(self, events: I) -> Result + where + I: IntoIterator, + { + let mut deltas = Vec::new(); + + for event in events { + match event.phase { + EventPhase::Started => {}, + EventPhase::Delta => { + deltas.push(serde_json::json!({ + "event": event.event, + "payload": event.payload, + "seq": event.seq, + })); + }, + EventPhase::Completed => { + return Ok(CapabilityExecutionResult::from_common( + self.target.plan.binding.capability.name.to_string(), + true, + event.payload, + None, + astrcode_core::ExecutionResultCommon::success( + Some(serde_json::json!({ "streamEvents": deltas })), + 0, + false, + ), + )); + }, + EventPhase::Failed => { + let error = event + .error + .map(|value| value.message) + .unwrap_or_else(|| "stream invocation failed".to_string()); + return Ok(CapabilityExecutionResult::from_common( + self.target.plan.binding.capability.name.to_string(), + false, + Value::Null, + None, + astrcode_core::ExecutionResultCommon::failure( + error, + Some(serde_json::json!({ "streamEvents": deltas })), + 0, + false, + ), + )); + }, + } + } + + Err(AstrError::Internal( + "plugin stream ended without terminal event".to_string(), + )) + } + + pub fn into_execution_result_from_dispatch( + self, + execution: PluginCapabilityProtocolExecution, + ) -> Result { + match execution { + PluginCapabilityProtocolExecution::Unary(result) => { + Ok(self.into_execution_result(result)) + }, + PluginCapabilityProtocolExecution::Stream(events) => { + self.finish_stream_execution_result(events) + }, + } + } +} + +impl TransportBackedProtocolDispatcher { + pub fn new(transport: T) -> Self { + Self { transport } + } +} + +impl PluginCapabilityProtocolDispatcher for TransportBackedProtocolDispatcher +where + T: PluginCapabilityProtocolTransport, +{ + fn dispatch( + &self, + dispatch: &PluginCapabilityProtocolDispatch, + ) -> Result { + if dispatch.target.plan.stream { + self.transport + .invoke_stream(dispatch) + .map(PluginCapabilityProtocolExecution::Stream) + } else { + self.transport + .invoke_unary(dispatch) + .map(PluginCapabilityProtocolExecution::Unary) + } + } +} + +impl PluginCapabilityDispatchOutcome { + pub fn execute_with_dispatchers( + self, + protocol_dispatcher: &P, + http_dispatcher: &H, + ) -> Result + where + P: PluginCapabilityProtocolDispatcher, + H: PluginCapabilityHttpDispatcher, + { + match self { + PluginCapabilityDispatchOutcome::Completed(result) => Ok(result), + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => dispatch + .clone() + .into_execution_result_from_dispatch(protocol_dispatcher.dispatch(&dispatch)?), + PluginCapabilityDispatchOutcome::ExternalHttp(dispatch) => { + http_dispatcher.dispatch(&dispatch) + }, + } + } +} + +/// builtin capability 的最小进程内执行合同。 +pub trait BuiltinCapabilityExecutor: Send + Sync { + fn execute( + &self, + plan: &PluginCapabilityInvocationPlan, + ctx: &CapabilityContext, + ) -> Result; +} + +/// builtin capability 执行器注册表。 +/// +/// 这一层先只按 capability name 做最小注册， +/// 让 `plugin-host` 可以真正持有 builtin 的进程内执行入口。 +#[derive(Default)] +pub struct BuiltinCapabilityExecutorRegistry { + executors: BTreeMap>, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum PluginCapabilityDispatchReadiness { + Ready, + MissingRuntimeHandle, + BackendUnavailable { message: Option }, + ProtocolNotReady, +} + +impl BuiltinCapabilityExecutorRegistry { + pub fn new() -> Self { + Self::default() + } + + pub fn register( + &mut self, + capability_name: impl Into, + executor: Arc, + ) -> Option> { + self.executors.insert(capability_name.into(), executor) + } + + pub fn executor(&self, capability_name: &str) -> Option> { + self.executors.get(capability_name).cloned() + } +} + +impl PluginCapabilityProtocolDispatcherRegistry { + pub fn new() -> Self { + Self::default() + } + + pub fn register( + &mut self, + plugin_id: impl Into, + dispatcher: Arc, + ) -> Option> { + self.dispatchers.insert(plugin_id.into(), dispatcher) + } + + pub fn dispatcher( + &self, + plugin_id: &str, + ) -> Option> { + self.dispatchers.get(plugin_id).cloned() + } +} + +impl PluginCapabilityHttpDispatcherRegistry { + pub fn new() -> Self { + Self::default() + } + + pub fn register( + &mut self, + plugin_id: impl Into, + dispatcher: Arc, + ) -> Option> { + self.dispatchers.insert(plugin_id.into(), dispatcher) + } + + pub fn dispatcher(&self, plugin_id: &str) -> Option> { + self.dispatchers.get(plugin_id).cloned() + } +} + +impl PluginCapabilityDispatcherSet { + pub fn new() -> Self { + Self::default() + } + + pub fn register_builtin( + &mut self, + capability_name: impl Into, + executor: Arc, + ) -> Option> { + self.builtin.register(capability_name, executor) + } + + pub fn register_protocol( + &mut self, + plugin_id: impl Into, + dispatcher: Arc, + ) -> Option> { + self.protocol.register(plugin_id, dispatcher) + } + + pub fn register_default_protocol( + &mut self, + dispatcher: Arc, + ) -> Option> { + self.default_protocol.replace(dispatcher) + } + + pub fn register_http( + &mut self, + plugin_id: impl Into, + dispatcher: Arc, + ) -> Option> { + self.http.register(plugin_id, dispatcher) + } + + pub fn register_default_http( + &mut self, + dispatcher: Arc, + ) -> Option> { + self.default_http.replace(dispatcher) + } + + pub fn protocol_dispatcher_for( + &self, + plugin_id: &str, + ) -> Option> { + self.protocol + .dispatcher(plugin_id) + .or_else(|| self.default_protocol.clone()) + } + + pub fn http_dispatcher_for( + &self, + plugin_id: &str, + ) -> Option> { + self.http + .dispatcher(plugin_id) + .or_else(|| self.default_http.clone()) + } +} diff --git a/crates/plugin-host/src/host_reload.rs b/crates/plugin-host/src/host_reload.rs new file mode 100644 index 00000000..06248ae1 --- /dev/null +++ b/crates/plugin-host/src/host_reload.rs @@ -0,0 +1,655 @@ +use astrcode_core::{ + AstrError, CapabilityContext, CapabilityExecutionResult, InvocationMode, Result, +}; +use astrcode_protocol::plugin::{CapabilityWireDescriptor, InitializeResultData, InvokeMessage}; +use serde_json::Value; + +use super::{ + PluginHost, PluginHostReload, + catalog::{ActivePluginRuntimeCatalog, ExternalBackendHealthCatalog}, + dispatch::{ + BuiltinCapabilityExecutorRegistry, PluginCapabilityBinding, PluginCapabilityDispatchKind, + PluginCapabilityDispatchOutcome, PluginCapabilityDispatchReadiness, + PluginCapabilityDispatchTicket, PluginCapabilityDispatcherSet, + PluginCapabilityHttpDispatch, PluginCapabilityHttpDispatcherRegistry, + PluginCapabilityInvocationPlan, PluginCapabilityInvocationTarget, + PluginCapabilityProtocolDispatch, PluginCapabilityProtocolDispatcherRegistry, + PluginCapabilityProtocolExecution, PluginRuntimeHandleRef, PluginRuntimeHandleSnapshot, + }, + to_plugin_invocation_context, +}; +use crate::{ + PluginDescriptor, + backend::{ + BuiltinPluginRuntimeHandle, PluginBackendHealth, PluginBackendHealthReport, + PluginBackendKind, + }, + descriptor::{ + CommandDescriptor, HookDescriptor, PromptDescriptor, ProviderDescriptor, + ResourceDescriptor, SkillDescriptor, ThemeDescriptor, + }, +}; + +/// 在所有 plugin descriptor 中按字段名查找贡献项，返回 (所在 descriptor, 匹配项)。 +macro_rules! define_descriptor_lookup { + ($method:ident, $field:ident, $id_field:ident, $item_type:ty) => { + pub fn $method(&self, id: &str) -> Option<(&PluginDescriptor, &$item_type)> { + self.descriptors.iter().find_map(|descriptor| { + descriptor + .$field + .iter() + .find(|item| item.$id_field.as_str() == id) + .map(|item| (descriptor, item)) + }) + } + }; +} + +impl PluginHostReload { + pub async fn execute_capability_live( + &mut self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + dispatchers: &PluginCapabilityDispatcherSet, + ) -> Result { + self.refresh_backend_health_from_runtime_handles()?; + let target = self + .prepare_ready_capability_dispatch(capability_name, payload, ctx)? + .target; + + match target.dispatch_kind { + PluginCapabilityDispatchKind::BuiltinInProcess => { + let executor = dispatchers + .builtin + .executor(capability_name) + .ok_or_else(|| { + AstrError::Validation(format!( + "能力 '{}' 缺少 builtin executor 注册", + capability_name + )) + })?; + executor.execute(&target.plan, ctx) + }, + PluginCapabilityDispatchKind::ExternalProtocol => { + self.execute_protocol_capability_live(target).await + }, + PluginCapabilityDispatchKind::ExternalHttp => { + let dispatcher = dispatchers + .http_dispatcher_for(&target.plan.binding.plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 http dispatcher 注册", + target.plan.binding.plugin_id + )) + })?; + dispatcher.dispatch(&PluginCapabilityHttpDispatch { target }) + }, + } + } + + pub fn execute_capability( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + dispatchers: &PluginCapabilityDispatcherSet, + ) -> Result { + let binding = self.capability_binding(capability_name).ok_or_else(|| { + AstrError::Validation(format!("plugin-host 中不存在能力 '{}'", capability_name)) + })?; + let outcome = self.dispatch_capability_with_registry( + capability_name, + payload, + ctx, + &dispatchers.builtin, + )?; + match outcome { + PluginCapabilityDispatchOutcome::Completed(result) => Ok(result), + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => { + let dispatcher = dispatchers + .protocol_dispatcher_for(&binding.plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 protocol dispatcher 注册", + binding.plugin_id + )) + })?; + dispatch + .clone() + .into_execution_result_from_dispatch(dispatcher.dispatch(&dispatch)?) + }, + PluginCapabilityDispatchOutcome::ExternalHttp(dispatch) => { + let dispatcher = dispatchers + .http_dispatcher_for(&binding.plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 http dispatcher 注册", + binding.plugin_id + )) + })?; + dispatcher.dispatch(&dispatch) + }, + } + } + + pub fn execute_capability_with_registries( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + builtin_registry: &BuiltinCapabilityExecutorRegistry, + protocol_registry: &PluginCapabilityProtocolDispatcherRegistry, + http_registry: &PluginCapabilityHttpDispatcherRegistry, + ) -> Result { + let binding = self.capability_binding(capability_name).ok_or_else(|| { + AstrError::Validation(format!("plugin-host 中不存在能力 '{}'", capability_name)) + })?; + let outcome = self.dispatch_capability_with_registry( + capability_name, + payload, + ctx, + builtin_registry, + )?; + match outcome { + PluginCapabilityDispatchOutcome::Completed(result) => Ok(result), + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => { + let dispatcher = protocol_registry + .dispatcher(&binding.plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 protocol dispatcher 注册", + binding.plugin_id + )) + })?; + dispatch + .clone() + .into_execution_result_from_dispatch(dispatcher.dispatch(&dispatch)?) + }, + PluginCapabilityDispatchOutcome::ExternalHttp(dispatch) => { + let dispatcher = http_registry + .dispatcher(&binding.plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin '{}' 缺少 http dispatcher 注册", + binding.plugin_id + )) + })?; + dispatcher.dispatch(&dispatch) + }, + } + } + + pub fn dispatch_capability_with_registry( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + registry: &BuiltinCapabilityExecutorRegistry, + ) -> Result { + self.dispatch_capability_with_builtin_executor(capability_name, payload, ctx, |plan| { + let executor = registry.executor(capability_name).ok_or_else(|| { + AstrError::Validation(format!( + "能力 '{}' 缺少 builtin executor 注册", + capability_name + )) + })?; + executor.execute(plan, ctx) + }) + } + + pub fn dispatch_capability_with_builtin_executor( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + builtin_executor: F, + ) -> Result + where + F: FnOnce(&PluginCapabilityInvocationPlan) -> Result, + { + let ticket = self.prepare_ready_capability_dispatch(capability_name, payload, ctx)?; + match ticket.target.dispatch_kind { + PluginCapabilityDispatchKind::BuiltinInProcess => builtin_executor(&ticket.target.plan) + .map(PluginCapabilityDispatchOutcome::Completed), + PluginCapabilityDispatchKind::ExternalProtocol => { + let runtime_handle = ticket + .target + .plan + .binding + .runtime_handle + .clone() + .ok_or_else(|| { + AstrError::Validation(format!( + "能力 '{}' 的 external backend 缺少运行时快照", + capability_name + )) + })?; + Ok(PluginCapabilityDispatchOutcome::ExternalProtocol( + PluginCapabilityProtocolDispatch { + runtime_handle, + target: ticket.target, + }, + )) + }, + PluginCapabilityDispatchKind::ExternalHttp => Ok( + PluginCapabilityDispatchOutcome::ExternalHttp(PluginCapabilityHttpDispatch { + target: ticket.target, + }), + ), + } + } + + pub fn prepare_ready_capability_dispatch( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + ) -> Result { + let readiness = self + .capability_dispatch_readiness(capability_name) + .ok_or_else(|| { + AstrError::Validation(format!("plugin-host 中不存在能力 '{}'", capability_name)) + })?; + match readiness { + PluginCapabilityDispatchReadiness::Ready => { + let target = self + .resolve_capability_invocation_target(capability_name, payload, ctx) + .ok_or_else(|| { + AstrError::Validation(format!( + "plugin-host 无法解析能力 '{}' 的调用目标", + capability_name + )) + })?; + Ok(PluginCapabilityDispatchTicket { target }) + }, + PluginCapabilityDispatchReadiness::MissingRuntimeHandle => Err(AstrError::Validation( + format!("能力 '{}' 缺少运行时句柄，无法分派", capability_name), + )), + PluginCapabilityDispatchReadiness::BackendUnavailable { message } => { + Err(AstrError::Validation(format!( + "能力 '{}' 的插件后端不可用: {}", + capability_name, + message.unwrap_or_else(|| "unknown backend state".to_string()) + ))) + }, + PluginCapabilityDispatchReadiness::ProtocolNotReady => Err(AstrError::Validation( + format!("能力 '{}' 的协议握手尚未完成，无法分派", capability_name), + )), + } + } + + pub fn capability_dispatch_readiness( + &self, + capability_name: &str, + ) -> Option { + let binding = self.capability_binding(capability_name)?; + let runtime_handle = binding.runtime_handle.as_ref(); + + let readiness = match binding.backend_kind { + PluginBackendKind::InProcess => { + if runtime_handle.is_some() { + PluginCapabilityDispatchReadiness::Ready + } else { + PluginCapabilityDispatchReadiness::MissingRuntimeHandle + } + }, + PluginBackendKind::Process | PluginBackendKind::Command => match runtime_handle { + None => PluginCapabilityDispatchReadiness::MissingRuntimeHandle, + Some(handle) => match handle.health.clone() { + Some(crate::backend::PluginBackendHealth::Unavailable) => { + PluginCapabilityDispatchReadiness::BackendUnavailable { + message: handle.message.clone(), + } + }, + Some(crate::backend::PluginBackendHealth::Healthy) => { + if handle.local_protocol_version.is_some() { + PluginCapabilityDispatchReadiness::Ready + } else { + PluginCapabilityDispatchReadiness::ProtocolNotReady + } + }, + None => PluginCapabilityDispatchReadiness::ProtocolNotReady, + }, + }, + PluginBackendKind::Http => PluginCapabilityDispatchReadiness::Ready, + }; + + Some(readiness) + } + + pub fn resolve_capability_invocation_target( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + ) -> Option { + let plan = self.prepare_capability_invocation(capability_name, payload, ctx)?; + let dispatch_kind = match plan.binding.backend_kind { + PluginBackendKind::InProcess => PluginCapabilityDispatchKind::BuiltinInProcess, + PluginBackendKind::Process | PluginBackendKind::Command => { + PluginCapabilityDispatchKind::ExternalProtocol + }, + PluginBackendKind::Http => PluginCapabilityDispatchKind::ExternalHttp, + }; + Some(PluginCapabilityInvocationTarget { + dispatch_kind, + plan, + }) + } + + pub fn prepare_capability_invocation( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + ) -> Option { + let binding = self.capability_binding(capability_name)?; + let invocation_context = to_plugin_invocation_context(ctx, capability_name); + let stream = matches!( + binding.capability.invocation_mode, + InvocationMode::Streaming + ); + let invoke_message = InvokeMessage { + id: invocation_context.request_id.clone(), + capability: binding.capability.name.to_string(), + input: payload.clone(), + context: invocation_context.clone(), + stream, + }; + Some(PluginCapabilityInvocationPlan { + binding, + payload, + stream, + invocation_context, + invoke_message, + }) + } + + pub fn capability_binding(&self, capability_name: &str) -> Option { + self.descriptors.iter().find_map(|descriptor| { + descriptor + .tools + .iter() + .find(|tool| tool.name.as_ref() == capability_name) + .map(|tool| PluginCapabilityBinding { + plugin_id: descriptor.plugin_id.clone(), + display_name: descriptor.display_name.clone(), + backend_kind: descriptor.source_kind.to_backend_kind(), + capability: tool.clone(), + runtime_handle: self.runtime_handle_snapshot(&descriptor.plugin_id), + }) + }) + } + + pub fn capability_bindings(&self) -> Vec { + self.descriptors + .iter() + .flat_map(|descriptor| { + descriptor.tools.iter().map(|tool| PluginCapabilityBinding { + plugin_id: descriptor.plugin_id.clone(), + display_name: descriptor.display_name.clone(), + backend_kind: descriptor.source_kind.to_backend_kind(), + capability: tool.clone(), + runtime_handle: self.runtime_handle_snapshot(&descriptor.plugin_id), + }) + }) + .collect() + } + + pub fn runtime_handle_snapshot(&self, plugin_id: &str) -> Option { + if let Some(handle) = self + .builtin_backends + .iter() + .find(|handle| handle.plugin_id == plugin_id) + { + let health = self.backend_health.report(plugin_id); + return Some(PluginRuntimeHandleSnapshot { + plugin_id: handle.plugin_id.clone(), + backend_kind: PluginBackendKind::InProcess, + started_at_ms: handle.started_at_ms, + shutdown_requested: false, + health: health.map(|report| report.health.clone()), + message: health.and_then(|report| report.message.clone()), + local_protocol_version: None, + remote_negotiated: false, + }); + } + + self.external_backends + .iter() + .find(|handle| handle.plugin_id == plugin_id) + .map(|handle| { + let health = self.backend_health.report(plugin_id); + PluginRuntimeHandleSnapshot { + plugin_id: handle.plugin_id.clone(), + backend_kind: PluginBackendKind::Process, + started_at_ms: handle.started_at_ms, + shutdown_requested: health + .map(|report| report.shutdown_requested) + .unwrap_or(false), + health: health.map(|report| report.health.clone()), + message: health.and_then(|report| report.message.clone()), + local_protocol_version: handle + .protocol_state() + .map(|state| state.local_initialize.protocol_version.clone()), + remote_negotiated: handle.remote_handshake_summary().is_some(), + } + }) + } + + pub fn runtime_handle_snapshots(&self) -> Vec { + self.runtime_catalog + .plugin_ids + .iter() + .filter_map(|plugin_id| self.runtime_handle_snapshot(plugin_id)) + .collect() + } + + pub fn runtime_handle(&self, plugin_id: &str) -> Option> { + if let Some(handle) = self + .builtin_backends + .iter() + .find(|handle| handle.plugin_id == plugin_id) + { + return Some(PluginRuntimeHandleRef::Builtin(handle)); + } + + self.external_backends + .iter() + .find(|handle| handle.plugin_id == plugin_id) + .map(PluginRuntimeHandleRef::External) + } + + pub fn refresh_external_backend_health(&mut self, host: &PluginHost) -> Result<()> { + let mut reports = self + .builtin_backends + .iter() + .map(BuiltinPluginRuntimeHandle::health_report) + .collect::>(); + reports.extend(host.external_backend_health_reports(&mut self.external_backends)?); + self.backend_health = ExternalBackendHealthCatalog::from_reports(reports); + self.refresh_runtime_catalog(); + Ok(()) + } + + pub fn plugin_descriptor(&self, plugin_id: &str) -> Option<&PluginDescriptor> { + self.descriptors + .iter() + .find(|descriptor| descriptor.plugin_id == plugin_id) + } + + define_descriptor_lookup!(tool_descriptor, tools, name, CapabilityWireDescriptor); + define_descriptor_lookup!(hook_descriptor, hooks, hook_id, HookDescriptor); + define_descriptor_lookup!( + provider_descriptor, + providers, + provider_id, + ProviderDescriptor + ); + define_descriptor_lookup!( + resource_descriptor, + resources, + resource_id, + ResourceDescriptor + ); + define_descriptor_lookup!(command_descriptor, commands, command_id, CommandDescriptor); + define_descriptor_lookup!(theme_descriptor, themes, theme_id, ThemeDescriptor); + define_descriptor_lookup!(prompt_descriptor, prompts, prompt_id, PromptDescriptor); + define_descriptor_lookup!(skill_descriptor, skills, skill_id, SkillDescriptor); + + pub fn refresh_negotiated_plugins(&mut self) { + self.negotiated_plugins + .refresh_from_external_backends(&self.external_backends); + self.refresh_runtime_catalog(); + } + + pub fn refresh_runtime_catalog(&mut self) { + self.runtime_catalog = ActivePluginRuntimeCatalog::from_reload(self); + } + + pub fn record_remote_initialize( + &mut self, + plugin_id: &str, + remote_initialize: InitializeResultData, + ) -> Result<()> { + let backend = self + .external_backends + .iter_mut() + .find(|backend| backend.plugin_id == plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "reload 结果中不存在 external plugin '{}'", + plugin_id + )) + })?; + backend.record_remote_initialize(remote_initialize)?; + self.refresh_negotiated_plugins(); + Ok(()) + } + + async fn execute_protocol_capability_live( + &mut self, + target: PluginCapabilityInvocationTarget, + ) -> Result { + let plugin_id = target.plan.binding.plugin_id.clone(); + let needs_remote_initialize = self + .external_backends + .iter() + .find(|backend| backend.plugin_id == plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "reload 结果中不存在 external plugin '{}'", + plugin_id + )) + })? + .protocol_state() + .map(|state| state.remote_initialize.is_none()) + .unwrap_or(true); + + if needs_remote_initialize { + let remote_initialize = { + let backend = self + .external_backends + .iter_mut() + .find(|backend| backend.plugin_id == plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "reload 结果中不存在 external plugin '{}'", + plugin_id + )) + })?; + backend.initialize_remote().await?.clone() + }; + self.record_remote_initialize(&plugin_id, remote_initialize)?; + } + + let runtime_handle = self.runtime_handle_snapshot(&plugin_id).ok_or_else(|| { + AstrError::Validation(format!( + "能力 '{}' 的 external backend 缺少运行时快照", + target.plan.binding.capability.name + )) + })?; + let dispatch = PluginCapabilityProtocolDispatch { + runtime_handle, + target, + }; + let execution_result = { + let backend = self + .external_backends + .iter_mut() + .find(|backend| backend.plugin_id == plugin_id) + .ok_or_else(|| { + AstrError::Validation(format!( + "reload 结果中不存在 external plugin '{}'", + plugin_id + )) + })?; + if dispatch.target.plan.stream { + backend + .invoke_stream(&dispatch.target.plan.invoke_message) + .await + .map(PluginCapabilityProtocolExecution::Stream) + } else { + backend + .invoke_unary(&dispatch.target.plan.invoke_message) + .await + .map(PluginCapabilityProtocolExecution::Unary) + } + }; + match execution_result { + Ok(execution) => dispatch.into_execution_result_from_dispatch(execution), + Err(error) => { + let _ = self.refresh_backend_health_from_runtime_handles(); + self.mark_backend_unavailable( + &plugin_id, + Some(format!("live protocol invoke failed: {error}")), + ); + Err(error) + }, + } + } + + fn refresh_backend_health_from_runtime_handles(&mut self) -> Result<()> { + let mut reports = self + .builtin_backends + .iter() + .map(BuiltinPluginRuntimeHandle::health_report) + .collect::>(); + reports.extend( + self.external_backends + .iter_mut() + .map(|backend| backend.health_report()) + .collect::>>()?, + ); + self.backend_health = ExternalBackendHealthCatalog::from_reports(reports); + self.refresh_runtime_catalog(); + Ok(()) + } + + fn mark_backend_unavailable(&mut self, plugin_id: &str, message: Option) { + let started_at_ms = self + .external_backends + .iter() + .find(|backend| backend.plugin_id == plugin_id) + .map(|backend| backend.started_at_ms) + .unwrap_or(0); + let shutdown_requested = self + .backend_health + .report(plugin_id) + .map(|report| report.shutdown_requested) + .unwrap_or(false); + let report = PluginBackendHealthReport { + plugin_id: plugin_id.to_string(), + health: PluginBackendHealth::Unavailable, + started_at_ms, + shutdown_requested, + message, + }; + self.backend_health + .reports + .retain(|item| item.plugin_id != plugin_id); + self.backend_health.reports.push(report); + self.refresh_runtime_catalog(); + } +} diff --git a/crates/plugin-host/src/host_tests.rs b/crates/plugin-host/src/host_tests.rs new file mode 100644 index 00000000..4a52db08 --- /dev/null +++ b/crates/plugin-host/src/host_tests.rs @@ -0,0 +1,3498 @@ +use std::{ + fs, + path::PathBuf, + sync::Arc, + time::{SystemTime, UNIX_EPOCH}, +}; + +use astrcode_core::{ + AgentEventContext, AstrError, BoundModeToolContractSnapshot, CancelToken, CapabilityContext, + CapabilityExecutionResult, ExecutionOwner, InvocationKind, InvocationMode, ModeId, Result, + SessionId, TurnId, +}; +use astrcode_protocol::plugin::{ + CapabilityWireDescriptor, ErrorPayload, EventMessage, EventPhase, InitializeResultData, + InvokeMessage, ResultMessage, SkillDescriptor, +}; + +use super::{ + ActivePluginRuntimeCatalog, BuiltinCapabilityExecutor, BuiltinCapabilityExecutorRegistry, + NegotiatedPluginCatalog, PluginCapabilityBinding, PluginCapabilityDispatchKind, + PluginCapabilityDispatchOutcome, PluginCapabilityDispatchReadiness, + PluginCapabilityDispatcherSet, PluginCapabilityHttpDispatch, PluginCapabilityHttpDispatcher, + PluginCapabilityHttpDispatcherRegistry, PluginCapabilityInvocationPlan, + PluginCapabilityProtocolDispatch, PluginCapabilityProtocolDispatcher, + PluginCapabilityProtocolDispatcherRegistry, PluginCapabilityProtocolExecution, + PluginCapabilityProtocolTransport, PluginHost, PluginRuntimeHandleRef, + TransportBackedProtocolDispatcher, +}; +use crate::{ + PluginDescriptor, PluginLoader, PluginSourceKind, + backend::{PluginBackendHealth, PluginBackendKind, PluginProcessStatus}, +}; + +fn unique_temp_dir(name: &str) -> PathBuf { + let suffix = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should be monotonic enough") + .as_nanos(); + std::env::temp_dir().join(format!("astrcode-plugin-host-host-{name}-{suffix}")) +} + +fn shell_command_with_args(script: &str) -> (String, Vec) { + #[cfg(windows)] + { + let command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + (command, vec!["/C".to_string(), script.to_string()]) + } + #[cfg(not(windows))] + { + ( + "/bin/sh".to_string(), + vec!["-c".to_string(), script.to_string()], + ) + } +} + +fn node_protocol_command() -> (String, Vec) { + let script = r#" +const readline = require('node:readline'); +const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity }); +rl.on('line', (line) => { + const msg = JSON.parse(line); + if (msg.type === 'initialize') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'initialize', + success: true, + output: { + protocolVersion: '5', + peer: { + id: 'fixture-worker', + name: 'fixture-worker', + role: 'worker', + version: '0.1.0', + supportedProfiles: ['coding'], + metadata: { fixture: true } + }, + capabilities: [], + handlers: [], + profiles: [{ + name: 'coding', + version: '1', + description: 'coding', + contextSchema: null, + metadata: null + }], + skills: [], + modes: [], + metadata: null + }, + metadata: null + })); + return; + } + if (msg.type === 'invoke' && msg.stream) { + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'started', + event: 'tool.started', + payload: { capability: msg.capability }, + seq: 0 + })); + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'delta', + event: 'tool.delta', + payload: { chunk: 1 }, + seq: 1 + })); + console.log(JSON.stringify({ + type: 'event', + id: msg.id, + phase: 'completed', + event: 'tool.completed', + payload: { ok: true }, + seq: 2 + })); + return; + } + if (msg.type === 'invoke') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'tool_result', + success: true, + output: { echoed: msg.input }, + metadata: { transport: 'node-fixture' } + })); + } +}); +"#; + ( + "node".to_string(), + vec!["-e".to_string(), script.to_string()], + ) +} + +fn node_protocol_command_exit_after_initialize() -> (String, Vec) { + let script = r#" +const readline = require('node:readline'); +const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity }); +let initialized = false; +rl.on('line', (line) => { + const msg = JSON.parse(line); + if (msg.type === 'initialize' && !initialized) { + initialized = true; + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'initialize', + success: true, + output: { + protocolVersion: '5', + peer: { + id: 'fixture-worker', + name: 'fixture-worker', + role: 'worker', + version: '0.1.0', + supportedProfiles: ['coding'], + metadata: { fixture: true } + }, + capabilities: [], + handlers: [], + profiles: [{ + name: 'coding', + version: '1', + description: 'coding', + contextSchema: null, + metadata: null + }], + skills: [], + modes: [], + metadata: null + }, + metadata: null + })); + setImmediate(() => process.exit(0)); + } +}); +"#; + ( + "node".to_string(), + vec!["-e".to_string(), script.to_string()], + ) +} + +fn sample_capability_context() -> CapabilityContext { + CapabilityContext { + request_id: Some("req-1".to_string()), + trace_id: Some("trace-1".to_string()), + session_id: SessionId::from("session-1"), + working_dir: PathBuf::from("D:/repo"), + cancel: CancelToken::new(), + turn_id: Some("turn-1".to_string()), + agent: AgentEventContext::root_execution("agent-1", "coding"), + current_mode_id: ModeId::from("coding"), + bound_mode_tool_contract: Some(BoundModeToolContractSnapshot { + mode_id: ModeId::from("coding"), + artifact: None, + exit_gate: None, + }), + execution_owner: Some(ExecutionOwner::root( + SessionId::from("session-1"), + TurnId::from("turn-1"), + InvocationKind::RootExecution, + )), + profile: "coding".to_string(), + profile_context: serde_json::json!({ "cwd": "D:/repo" }), + metadata: serde_json::json!({ "source": "test" }), + tool_output_sender: None, + event_sink: None, + } +} + +struct StaticBuiltinExecutor; + +impl BuiltinCapabilityExecutor for StaticBuiltinExecutor { + fn execute( + &self, + plan: &PluginCapabilityInvocationPlan, + _ctx: &CapabilityContext, + ) -> Result { + Ok(CapabilityExecutionResult::ok( + plan.binding.capability.name.to_string(), + serde_json::json!({ + "executedBy": plan.binding.plugin_id, + "input": plan.payload, + }), + )) + } +} + +struct StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution, +} + +impl PluginCapabilityProtocolDispatcher for StaticProtocolDispatcher { + fn dispatch( + &self, + _dispatch: &PluginCapabilityProtocolDispatch, + ) -> Result { + Ok(self.execution.clone()) + } +} + +struct StaticHttpDispatcher; + +impl PluginCapabilityHttpDispatcher for StaticHttpDispatcher { + fn dispatch( + &self, + dispatch: &PluginCapabilityHttpDispatch, + ) -> Result { + Ok(CapabilityExecutionResult::ok( + dispatch.target.plan.binding.capability.name.to_string(), + serde_json::json!({ + "transport": "http", + "pluginId": dispatch.target.plan.binding.plugin_id, + }), + )) + } +} + +#[derive(Clone)] +struct FakeProtocolTransport { + unary: Option, + stream: Vec, +} + +impl PluginCapabilityProtocolTransport for FakeProtocolTransport { + fn invoke_unary(&self, _dispatch: &PluginCapabilityProtocolDispatch) -> Result { + self.unary.clone().ok_or_else(|| { + AstrError::Validation("fake protocol transport missing unary response".to_string()) + }) + } + + fn invoke_stream( + &self, + _dispatch: &PluginCapabilityProtocolDispatch, + ) -> Result> { + Ok(self.stream.clone()) + } +} + +#[test] +fn reload_from_loader_promotes_discovered_snapshot() { + let root = unique_temp_dir("reload"); + fs::create_dir_all(&root).expect("temp dir should create"); + fs::write( + root.join("repo-inspector.toml"), + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "./bin/repo-inspector" +args = ["--stdio"] +working_dir = "." +repository = "https://example.com/repo-inspector" +"#, + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let snapshot = host + .reload_from_loader(&PluginLoader { + search_paths: vec![root.clone()], + }) + .expect("reload should succeed"); + + assert_eq!(snapshot.plugin_ids, vec!["repo-inspector".to_string()]); + assert_eq!( + host.active_snapshot() + .expect("active snapshot should exist") + .plugin_ids, + vec!["repo-inspector".to_string()] + ); + + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_with_external_backends_returns_snapshot_and_external_handles() { + let root = unique_temp_dir("reload-with-backends"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let mut reload = host + .reload_with_external_backends(&PluginLoader { + search_paths: vec![root.clone()], + }) + .await + .expect("reload with backends should succeed"); + + assert_eq!( + reload.snapshot.plugin_ids, + vec!["repo-inspector".to_string()] + ); + assert_eq!(reload.descriptors.len(), 1); + assert!(reload.builtin_backends.is_empty()); + assert_eq!(reload.external_backends.len(), 1); + assert_eq!( + reload.resources.plugin_ids, + vec!["repo-inspector".to_string()] + ); + assert_eq!( + reload.negotiated_plugins.plugin_ids, + vec!["repo-inspector".to_string()] + ); + assert_eq!( + reload.runtime_catalog.plugin_ids, + vec!["repo-inspector".to_string()] + ); + assert_eq!(reload.runtime_catalog.entries.len(), 1); + assert_eq!( + reload.runtime_catalog.snapshot_id, + reload.snapshot.snapshot_id + ); + assert_eq!(reload.runtime_catalog.revision, reload.snapshot.revision); + assert_eq!( + reload.runtime_catalog.entries[0].plugin_id, + "repo-inspector" + ); + assert!(reload.runtime_catalog.entries[0].has_external_backend); + assert!(!reload.runtime_catalog.entries[0].has_builtin_backend); + assert!(reload.runtime_catalog.entries[0].has_runtime_handle); + assert_eq!( + reload.runtime_catalog.entries[0].backend_health, + Some(PluginBackendHealth::Healthy) + ); + assert!( + reload.runtime_catalog.entries[0] + .backend_health_message + .is_none() + ); + assert_eq!( + reload.external_backends[0] + .protocol_state() + .expect("protocol state should be attached") + .local_initialize + .peer + .id, + "plugin-host" + ); + assert_eq!( + reload.negotiated_plugins.remote_plugins[0].local_protocol_version, + "5" + ); + assert_eq!( + reload.runtime_catalog.negotiated_plugins.remote_plugins[0].local_protocol_version, + "5" + ); + assert_eq!( + reload.runtime_catalog.entries[0] + .local_protocol_version + .as_deref(), + Some("5") + ); + assert!(reload.negotiated_plugins.remote_plugins[0].remote.is_none()); + let reports = host + .external_backend_health_reports(&mut reload.external_backends) + .expect("health reports should be readable"); + assert_eq!(reports[0].health, PluginBackendHealth::Healthy); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_can_record_remote_initialize_and_refresh_catalog() { + let root = unique_temp_dir("reload-with-remote-handshake"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let mut reload = host + .reload_with_external_backends(&PluginLoader { + search_paths: vec![root.clone()], + }) + .await + .expect("reload with backends should succeed"); + + reload + .record_remote_initialize( + "repo-inspector", + InitializeResultData { + protocol_version: "5".to_string(), + peer: reload.external_backends[0] + .protocol_state() + .expect("protocol state should exist") + .local_initialize + .peer + .clone(), + capabilities: Vec::new(), + handlers: Vec::new(), + profiles: vec![crate::default_profiles()[0].clone()], + skills: vec![SkillDescriptor { + name: "skill.review".to_string(), + description: "review".to_string(), + guide: "guide".to_string(), + allowed_tools: Vec::new(), + assets: Vec::new(), + metadata: serde_json::Value::Null, + }], + modes: Vec::new(), + metadata: serde_json::Value::Null, + }, + ) + .expect("record remote initialize should succeed"); + + let negotiated = &reload.negotiated_plugins.remote_plugins[0]; + assert_eq!(negotiated.plugin_id, "repo-inspector"); + assert_eq!(negotiated.local_protocol_version, "5"); + assert_eq!( + negotiated + .remote + .as_ref() + .expect("remote summary should exist") + .skill_ids, + vec!["skill.review".to_string()] + ); + assert_eq!( + reload.runtime_catalog.negotiated_plugins.remote_plugins[0] + .remote + .as_ref() + .expect("runtime catalog remote summary should exist") + .skill_ids, + vec!["skill.review".to_string()] + ); + assert_eq!( + reload.runtime_catalog.entries[0] + .remote + .as_ref() + .expect("runtime entry remote summary should exist") + .skill_ids, + vec!["skill.review".to_string()] + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_with_external_backends_rolls_back_candidate_on_backend_failure() { + let root = unique_temp_dir("reload-rollback"); + fs::create_dir_all(&root).expect("temp dir should create"); + fs::write( + root.join("alpha.toml"), + r#" +name = "alpha" +version = "0.1.0" +description = "alpha" +plugin_type = ["Tool"] +capabilities = [] +executable = "cmd.exe" +args = ["/C", "ping 127.0.0.1 -n 5 >nul"] +working_dir = "." +repository = "https://example.com/alpha" +"#, + ) + .expect("alpha manifest should write"); + + let host = PluginHost::new(); + let mut first = host + .reload_with_external_backends(&PluginLoader { + search_paths: vec![root.clone()], + }) + .await + .expect("initial reload should succeed"); + for backend in &mut first.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + + fs::write( + root.join("beta.toml"), + r#" +name = "beta" +version = "0.1.0" +description = "beta" +plugin_type = ["Tool"] +capabilities = [] +executable = "definitely-missing-command.exe" +args = [] +working_dir = "." +repository = "https://example.com/beta" +"#, + ) + .expect("beta manifest should write"); + + let error = host + .reload_with_external_backends(&PluginLoader { + search_paths: vec![root.clone()], + }) + .await + .expect_err("reload should fail when backend start fails"); + + assert!( + error + .to_string() + .contains("failed to spawn plugin backend 'beta'") + ); + assert!(host.registry().candidate_snapshot().is_none()); + assert_eq!( + host.active_snapshot() + .expect("previous active snapshot should remain") + .plugin_ids, + vec!["alpha".to_string()] + ); + + let _ = fs::remove_dir_all(root); +} + +#[test] +fn backend_plans_cover_builtin_and_process_descriptors() { + let host = PluginHost::new(); + let builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some("/bin/repo-inspector".to_string()); + external.launch_args = vec!["--stdio".to_string()]; + + let plans = host + .backend_plans(&[builtin, external]) + .expect("backend plans should build"); + + assert_eq!(plans.len(), 2); + assert_eq!(plans[0].backend_kind, PluginBackendKind::InProcess); + assert_eq!(plans[1].backend_kind, PluginBackendKind::Process); + assert_eq!(host.local_peer().id, "plugin-host"); +} + +#[tokio::test] +async fn start_external_process_backends_only_launches_external_entries() { + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + + let host = PluginHost::new(); + let builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + + let plans = host + .backend_plans(&[builtin, external]) + .expect("backend plans should build"); + let mut backends = host + .start_external_process_backends(&plans) + .await + .expect("external backends should start"); + + assert_eq!(backends.len(), 1); + assert!(backends[0].protocol_state().is_some()); + let status = backends[0].status().expect("status should be readable"); + assert_eq!( + status, + PluginProcessStatus { + running: true, + exit_code: None + } + ); + let reports = host + .external_backend_health_reports(&mut backends) + .expect("health reports should be readable"); + assert_eq!(reports.len(), 1); + assert_eq!(reports[0].health, PluginBackendHealth::Healthy); + + for backend in &mut backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn reload_from_descriptors_unifies_builtin_and_external_entries() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.commands.push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + assert_eq!( + reload.runtime_catalog.plugin_ids, + vec!["core-tools".to_string(), "repo-inspector".to_string()] + ); + assert_eq!(reload.runtime_catalog.entries.len(), 2); + assert!(!reload.runtime_catalog.entries[0].has_external_backend); + assert!(reload.runtime_catalog.entries[0].has_builtin_backend); + assert!(reload.runtime_catalog.entries[0].has_runtime_handle); + assert!(reload.runtime_catalog.entries[1].has_external_backend); + assert!(!reload.runtime_catalog.entries[1].has_builtin_backend); + assert!(reload.runtime_catalog.entries[1].has_runtime_handle); + assert_eq!( + reload.runtime_catalog.entries[0].backend_health, + Some(PluginBackendHealth::Healthy) + ); + assert_eq!( + reload.runtime_catalog.entries[1].backend_health, + Some(PluginBackendHealth::Healthy) + ); + assert_eq!( + reload.runtime_catalog.entries[0].command_ids, + vec!["review".to_string()] + ); + assert_eq!( + reload.runtime_catalog.entries[1] + .local_protocol_version + .as_deref(), + Some("5") + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn reload_with_builtin_and_loader_unifies_mixed_sources() { + let root = unique_temp_dir("reload-builtin-and-loader"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.commands.push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + + let mut reload = host + .reload_with_builtin_and_loader( + vec![builtin], + &PluginLoader { + search_paths: vec![root.clone()], + }, + ) + .await + .expect("mixed builtin + loader reload should succeed"); + + assert_eq!( + reload.runtime_catalog.plugin_ids, + vec!["core-tools".to_string(), "repo-inspector".to_string()] + ); + assert_eq!(reload.runtime_catalog.entries.len(), 2); + assert_eq!(reload.runtime_catalog.entries[0].plugin_id, "core-tools"); + assert!(!reload.runtime_catalog.entries[0].has_external_backend); + assert!(reload.runtime_catalog.entries[0].has_builtin_backend); + assert!(reload.runtime_catalog.entries[0].has_runtime_handle); + assert_eq!( + reload.runtime_catalog.entries[1].plugin_id, + "repo-inspector" + ); + assert!(reload.runtime_catalog.entries[1].has_external_backend); + assert!(!reload.runtime_catalog.entries[1].has_builtin_backend); + assert!(reload.runtime_catalog.entries[1].has_runtime_handle); + assert_eq!( + reload.runtime_catalog.entries[1].backend_health, + Some(PluginBackendHealth::Healthy) + ); + assert_eq!( + reload.runtime_catalog.entries[1] + .local_protocol_version + .as_deref(), + Some("5") + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_with_builtin_and_loader_merges_resource_batches_through_single_catalog_owner() { + let root = unique_temp_dir("reload-builtin-loader-resources"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} + +[[commands]] +id = "external-review" +entry_ref = ".codex/commands/external-review.md" + +[[prompts]] +id = "prompt.external-review" +body = "Review external repository" + +[[skills]] +id = "skill.external-review" +entry_ref = ".codex/skills/review/SKILL.md" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.commands.push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + + let mut reload = host + .reload_with_builtin_and_loader( + vec![builtin], + &PluginLoader { + search_paths: vec![root.clone()], + }, + ) + .await + .expect("mixed builtin + loader reload should succeed"); + + assert_eq!( + reload.resources.plugin_ids, + vec!["core-tools".to_string(), "repo-inspector".to_string()] + ); + assert_eq!(reload.resources.commands.len(), 2); + assert_eq!(reload.resources.prompts.len(), 1); + assert_eq!(reload.resources.skills.len(), 1); + assert_eq!( + reload.runtime_catalog.command_ids, + vec!["review".to_string(), "external-review".to_string()] + ); + assert_eq!( + reload.runtime_catalog.prompt_ids, + vec!["prompt.external-review".to_string()] + ); + assert_eq!( + reload.runtime_catalog.skill_ids, + vec!["skill.external-review".to_string()] + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_with_builtin_loader_and_capabilities_propagates_local_capabilities() { + let root = unique_temp_dir("reload-builtin-loader-with-capabilities"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + let capabilities = vec![ + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .tags(["io", "read"]) + .build() + .expect("capability should build"), + ]; + + let mut reload = host + .reload_with_builtin_loader_and_capabilities( + vec![builtin], + &PluginLoader { + search_paths: vec![root.clone()], + }, + &capabilities, + ) + .await + .expect("mixed builtin + loader reload with capabilities should succeed"); + + assert_eq!(reload.external_backends.len(), 1); + let protocol_state = reload.external_backends[0] + .protocol_state() + .expect("protocol state should be attached"); + assert_eq!(protocol_state.local_initialize.capabilities, capabilities); + assert_eq!(protocol_state.local_initialize.peer.id, "plugin-host"); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[test] +fn negotiated_plugin_catalog_reflects_backend_protocol_state() { + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + let (command, args) = shell_command_with_args("ping 127.0.0.1 -n 5 >nul"); + external.launch_command = Some(command); + external.launch_args = args; + + let plans = host + .backend_plans(&[external]) + .expect("backend plans should build"); + let mut backends = tokio::runtime::Runtime::new() + .expect("runtime should build") + .block_on(host.start_external_process_backends(&plans)) + .expect("external backends should start"); + + let catalog = NegotiatedPluginCatalog::from_external_backends(&backends); + assert_eq!(catalog.plugin_ids, vec!["repo-inspector".to_string()]); + assert_eq!(catalog.remote_plugins.len(), 1); + assert_eq!(catalog.remote_plugins[0].plugin_id, "repo-inspector"); + assert_eq!(catalog.remote_plugins[0].local_protocol_version, "5"); + assert!(catalog.remote_plugins[0].remote.is_none()); + + tokio::runtime::Runtime::new() + .expect("runtime should build") + .block_on(async { + for backend in &mut backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + }); +} + +#[test] +fn active_runtime_catalog_collects_runtime_facts() { + let mut descriptor = PluginDescriptor::builtin("core-tools", "Core Tools"); + descriptor + .commands + .push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + descriptor + .prompts + .push(crate::descriptor::PromptDescriptor { + prompt_id: "prompt.review".to_string(), + body: "review".to_string(), + }); + + let snapshot = + crate::PluginActiveSnapshot::from_descriptors(7, "snapshot-7", &[descriptor.clone()]); + let resources = crate::ResourceCatalog::from_descriptors(&[descriptor.clone()]); + let reload = super::PluginHostReload { + descriptors: vec![descriptor], + snapshot, + builtin_backends: Vec::new(), + external_backends: Vec::new(), + resources, + backend_health: super::ExternalBackendHealthCatalog::default(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + runtime_catalog: ActivePluginRuntimeCatalog { + snapshot_id: String::new(), + revision: 0, + plugin_ids: Vec::new(), + entries: Vec::new(), + tool_names: Vec::new(), + hook_ids: Vec::new(), + provider_ids: Vec::new(), + resource_ids: Vec::new(), + command_ids: Vec::new(), + theme_ids: Vec::new(), + prompt_ids: Vec::new(), + skill_ids: Vec::new(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + }, + }; + + let catalog = ActivePluginRuntimeCatalog::from_reload(&reload); + assert_eq!(catalog.snapshot_id, "snapshot-7"); + assert_eq!(catalog.revision, 7); + assert_eq!(catalog.plugin_ids, vec!["core-tools".to_string()]); + assert_eq!(catalog.entries.len(), 1); + assert_eq!(catalog.entries[0].plugin_id, "core-tools"); + assert!(!catalog.entries[0].has_external_backend); + assert!(!catalog.entries[0].has_builtin_backend); + assert!(!catalog.entries[0].has_runtime_handle); + assert_eq!(catalog.command_ids, vec!["review".to_string()]); + assert_eq!(catalog.prompt_ids, vec!["prompt.review".to_string()]); +} + +#[test] +fn active_runtime_catalog_resolves_plugin_ownership() { + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("tool capability should build"), + ); + builtin.hooks.push(crate::descriptor::HookDescriptor { + hook_id: "tool_call".to_string(), + event: "tool_call".to_string(), + }); + builtin.commands.push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + builtin.prompts.push(crate::descriptor::PromptDescriptor { + prompt_id: "prompt.review".to_string(), + body: "review".to_string(), + }); + builtin.skills.push(crate::descriptor::SkillDescriptor { + skill_id: "skill.review".to_string(), + entry_ref: ".codex/skills/review/SKILL.md".to_string(), + }); + + let mut external = PluginDescriptor::builtin("corp-provider", "Corp Provider"); + external.source_kind = PluginSourceKind::Process; + external + .providers + .push(crate::descriptor::ProviderDescriptor { + provider_id: "corp-ai".to_string(), + api_kind: "openai-compatible".to_string(), + }); + + let snapshot = crate::PluginActiveSnapshot::from_descriptors( + 8, + "snapshot-8", + &[builtin.clone(), external.clone()], + ); + let resources = crate::ResourceCatalog::from_descriptors(&[builtin.clone(), external.clone()]); + let reload = super::PluginHostReload { + descriptors: vec![builtin, external], + snapshot, + builtin_backends: Vec::new(), + external_backends: Vec::new(), + resources, + backend_health: super::ExternalBackendHealthCatalog::default(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + runtime_catalog: ActivePluginRuntimeCatalog { + snapshot_id: String::new(), + revision: 0, + plugin_ids: Vec::new(), + entries: Vec::new(), + tool_names: Vec::new(), + hook_ids: Vec::new(), + provider_ids: Vec::new(), + resource_ids: Vec::new(), + command_ids: Vec::new(), + theme_ids: Vec::new(), + prompt_ids: Vec::new(), + skill_ids: Vec::new(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + }, + }; + + let catalog = ActivePluginRuntimeCatalog::from_reload(&reload); + assert_eq!( + catalog + .entry("core-tools") + .expect("entry should exist") + .display_name, + "Core Tools" + ); + assert_eq!(catalog.enabled_entries().len(), 2); + assert_eq!( + catalog + .tool_owner("tool.read") + .expect("tool owner should exist") + .plugin_id, + "core-tools" + ); + assert_eq!( + catalog + .hook_owner("tool_call") + .expect("hook owner should exist") + .plugin_id, + "core-tools" + ); + assert_eq!( + catalog + .command_owner("review") + .expect("command owner should exist") + .plugin_id, + "core-tools" + ); + assert_eq!( + catalog + .prompt_owner("prompt.review") + .expect("prompt owner should exist") + .plugin_id, + "core-tools" + ); + assert_eq!( + catalog + .skill_owner("skill.review") + .expect("skill owner should exist") + .plugin_id, + "core-tools" + ); + assert_eq!( + catalog + .provider_owner("corp-ai") + .expect("provider owner should exist") + .plugin_id, + "corp-provider" + ); +} + +#[test] +fn plugin_host_reload_resolves_descriptors_by_contribution_id() { + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("tool capability should build"), + ); + builtin.hooks.push(crate::descriptor::HookDescriptor { + hook_id: "tool_call".to_string(), + event: "tool_call".to_string(), + }); + builtin + .resources + .push(crate::descriptor::ResourceDescriptor { + resource_id: "skill-dir".to_string(), + kind: "skill".to_string(), + locator: ".codex/skills".to_string(), + }); + builtin.commands.push(crate::descriptor::CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + builtin.themes.push(crate::descriptor::ThemeDescriptor { + theme_id: "light".to_string(), + }); + builtin.prompts.push(crate::descriptor::PromptDescriptor { + prompt_id: "prompt.review".to_string(), + body: "review".to_string(), + }); + builtin.skills.push(crate::descriptor::SkillDescriptor { + skill_id: "skill.review".to_string(), + entry_ref: ".codex/skills/review/SKILL.md".to_string(), + }); + + let mut external = PluginDescriptor::builtin("corp-provider", "Corp Provider"); + external.source_kind = PluginSourceKind::Process; + external + .providers + .push(crate::descriptor::ProviderDescriptor { + provider_id: "corp-ai".to_string(), + api_kind: "openai-compatible".to_string(), + }); + + let snapshot = crate::PluginActiveSnapshot::from_descriptors( + 9, + "snapshot-9", + &[builtin.clone(), external.clone()], + ); + let resources = crate::ResourceCatalog::from_descriptors(&[builtin.clone(), external.clone()]); + let reload = super::PluginHostReload { + descriptors: vec![builtin, external], + snapshot, + builtin_backends: Vec::new(), + external_backends: Vec::new(), + resources, + backend_health: super::ExternalBackendHealthCatalog::default(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + runtime_catalog: ActivePluginRuntimeCatalog { + snapshot_id: String::new(), + revision: 0, + plugin_ids: Vec::new(), + entries: Vec::new(), + tool_names: Vec::new(), + hook_ids: Vec::new(), + provider_ids: Vec::new(), + resource_ids: Vec::new(), + command_ids: Vec::new(), + theme_ids: Vec::new(), + prompt_ids: Vec::new(), + skill_ids: Vec::new(), + negotiated_plugins: NegotiatedPluginCatalog::default(), + }, + }; + + assert_eq!( + reload + .plugin_descriptor("core-tools") + .expect("plugin should exist") + .display_name, + "Core Tools" + ); + assert_eq!( + reload + .tool_descriptor("tool.read") + .expect("tool descriptor should exist") + .0 + .plugin_id, + "core-tools" + ); + assert_eq!( + reload + .hook_descriptor("tool_call") + .expect("hook descriptor should exist") + .1 + .event, + "tool_call" + ); + assert_eq!( + reload + .provider_descriptor("corp-ai") + .expect("provider descriptor should exist") + .0 + .plugin_id, + "corp-provider" + ); + assert_eq!( + reload + .resource_descriptor("skill-dir") + .expect("resource descriptor should exist") + .1 + .locator, + ".codex/skills" + ); + assert_eq!( + reload + .command_descriptor("review") + .expect("command descriptor should exist") + .1 + .entry_ref, + ".codex/commands/review.md" + ); + assert_eq!( + reload + .theme_descriptor("light") + .expect("theme descriptor should exist") + .0 + .plugin_id, + "core-tools" + ); + assert_eq!( + reload + .prompt_descriptor("prompt.review") + .expect("prompt descriptor should exist") + .1 + .body, + "review" + ); + assert_eq!( + reload + .skill_descriptor("skill.review") + .expect("skill descriptor should exist") + .1 + .entry_ref, + ".codex/skills/review/SKILL.md" + ); +} + +#[tokio::test] +async fn reload_can_refresh_backend_health_into_runtime_catalog() { + let root = unique_temp_dir("reload-refresh-backend-health"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let mut reload = host + .reload_with_external_backends(&PluginLoader { + search_paths: vec![root.clone()], + }) + .await + .expect("reload with backends should succeed"); + + assert_eq!( + reload.runtime_catalog.entries[0].backend_health, + Some(PluginBackendHealth::Healthy) + ); + + reload + .refresh_external_backend_health(&host) + .expect("refresh external backend health should succeed"); + assert_eq!( + reload.runtime_catalog.entries[0].backend_health, + Some(PluginBackendHealth::Healthy) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_exposes_unified_runtime_handles_for_builtin_and_external() { + let root = unique_temp_dir("reload-unified-runtime-handles"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + let mut reload = host + .reload_with_builtin_and_loader( + vec![builtin], + &PluginLoader { + search_paths: vec![root.clone()], + }, + ) + .await + .expect("mixed reload should succeed"); + + match reload + .runtime_handle("core-tools") + .expect("builtin runtime handle should exist") + { + PluginRuntimeHandleRef::Builtin(handle) => { + assert_eq!(handle.plugin_id, "core-tools"); + assert!(handle.started_at_ms > 0); + }, + PluginRuntimeHandleRef::External(_) => { + panic!("builtin plugin should not resolve to external handle"); + }, + } + + match reload + .runtime_handle("repo-inspector") + .expect("external runtime handle should exist") + { + PluginRuntimeHandleRef::Builtin(_) => { + panic!("external plugin should not resolve to builtin handle"); + }, + PluginRuntimeHandleRef::External(handle) => { + assert_eq!(handle.plugin_id, "repo-inspector"); + assert!(handle.started_at_ms > 0); + }, + } + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_exposes_runtime_handle_snapshots_without_raw_handle_access() { + let root = unique_temp_dir("reload-runtime-handle-snapshots"); + fs::create_dir_all(&root).expect("temp dir should create"); + #[cfg(windows)] + let executable = "cmd.exe"; + #[cfg(not(windows))] + let executable = "/bin/sh"; + #[cfg(windows)] + let args = r#"args = ["/C", "ping 127.0.0.1 -n 5 >nul"]"#; + #[cfg(not(windows))] + let args = r#"args = ["-c", "sleep 2"]"#; + fs::write( + root.join("repo-inspector.toml"), + format!( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "{executable}" +{args} +working_dir = "." +repository = "https://example.com/repo-inspector" +"# + ), + ) + .expect("manifest should write"); + + let host = PluginHost::new(); + let builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + let mut reload = host + .reload_with_builtin_and_loader( + vec![builtin], + &PluginLoader { + search_paths: vec![root.clone()], + }, + ) + .await + .expect("mixed reload should succeed"); + + let builtin_snapshot = reload + .runtime_handle_snapshot("core-tools") + .expect("builtin snapshot should exist"); + assert_eq!(builtin_snapshot.backend_kind, PluginBackendKind::InProcess); + assert_eq!(builtin_snapshot.health, Some(PluginBackendHealth::Healthy)); + assert!(!builtin_snapshot.remote_negotiated); + + let external_snapshot = reload + .runtime_handle_snapshot("repo-inspector") + .expect("external snapshot should exist"); + assert_eq!(external_snapshot.backend_kind, PluginBackendKind::Process); + assert_eq!( + external_snapshot.local_protocol_version.as_deref(), + Some("5") + ); + assert_eq!(external_snapshot.health, Some(PluginBackendHealth::Healthy)); + + let snapshots = reload.runtime_handle_snapshots(); + assert_eq!(snapshots.len(), 2); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + let _ = fs::remove_dir_all(root); +} + +#[tokio::test] +async fn reload_exposes_unified_capability_bindings() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + let builtin_binding = reload + .capability_binding("tool.read") + .expect("builtin binding should exist"); + assert_eq!(builtin_binding.plugin_id, "core-tools"); + assert_eq!(builtin_binding.backend_kind, PluginBackendKind::InProcess); + assert_eq!( + builtin_binding + .runtime_handle + .expect("runtime handle should exist") + .backend_kind, + PluginBackendKind::InProcess + ); + + let external_binding = reload + .capability_binding("tool.search") + .expect("external binding should exist"); + assert_eq!(external_binding.plugin_id, "repo-inspector"); + assert_eq!(external_binding.backend_kind, PluginBackendKind::Process); + assert_eq!( + external_binding + .runtime_handle + .expect("runtime handle should exist") + .backend_kind, + PluginBackendKind::Process + ); + + let bindings = reload.capability_bindings(); + assert_eq!(bindings.len(), 2); + assert_eq!(bindings[0].capability.name.to_string(), "tool.read"); + assert_eq!(bindings[1].capability.name.to_string(), "tool.search"); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn reload_prepares_unified_capability_invocation_plan() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + let builtin_plan = reload + .prepare_capability_invocation( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + ) + .expect("builtin invocation plan should exist"); + assert_eq!(builtin_plan.binding.plugin_id, "core-tools"); + assert_eq!( + builtin_plan.binding.backend_kind, + PluginBackendKind::InProcess + ); + assert!(!builtin_plan.stream); + assert_eq!(builtin_plan.invoke_message.capability, "tool.read"); + assert_eq!(builtin_plan.invoke_message.context.request_id, "req-1"); + + let external_plan = reload + .prepare_capability_invocation( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + ) + .expect("external invocation plan should exist"); + assert_eq!(external_plan.binding.plugin_id, "repo-inspector"); + assert_eq!( + external_plan.binding.backend_kind, + PluginBackendKind::Process + ); + assert!(external_plan.stream); + assert_eq!(external_plan.invoke_message.capability, "tool.search"); + assert_eq!( + external_plan.invoke_message.context.session_id.as_deref(), + Some("session-1") + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn reload_resolves_unified_capability_invocation_targets() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + let builtin_target = reload + .resolve_capability_invocation_target( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + ) + .expect("builtin target should exist"); + assert_eq!( + builtin_target.dispatch_kind, + PluginCapabilityDispatchKind::BuiltinInProcess + ); + assert_eq!(builtin_target.plan.binding.plugin_id, "core-tools"); + assert!(!builtin_target.plan.stream); + + let external_target = reload + .resolve_capability_invocation_target( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + ) + .expect("external target should exist"); + assert_eq!( + external_target.dispatch_kind, + PluginCapabilityDispatchKind::ExternalProtocol + ); + assert_eq!(external_target.plan.binding.plugin_id, "repo-inspector"); + assert!(external_target.plan.stream); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn reload_reports_capability_dispatch_readiness() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + assert_eq!( + reload + .capability_dispatch_readiness("tool.read") + .expect("builtin readiness should exist"), + PluginCapabilityDispatchReadiness::Ready + ); + assert_eq!( + reload + .capability_dispatch_readiness("tool.search") + .expect("external readiness should exist"), + PluginCapabilityDispatchReadiness::Ready + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + reload + .refresh_external_backend_health(&host) + .expect("health refresh should succeed"); + match reload + .capability_dispatch_readiness("tool.search") + .expect("external readiness should exist after shutdown") + { + PluginCapabilityDispatchReadiness::BackendUnavailable { message } => { + assert!( + message + .as_deref() + .is_some_and(|value| value.contains("plugin backend exited")), + "unexpected backend unavailable message: {message:?}" + ); + }, + other => panic!("unexpected readiness after shutdown: {other:?}"), + } +} + +#[tokio::test] +async fn reload_prepares_ready_capability_dispatch_ticket() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![builtin, external]) + .await + .expect("mixed reload should succeed"); + + let builtin_ticket = reload + .prepare_ready_capability_dispatch( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + ) + .expect("builtin dispatch ticket should be ready"); + assert_eq!( + builtin_ticket.target.dispatch_kind, + PluginCapabilityDispatchKind::BuiltinInProcess + ); + assert_eq!(builtin_ticket.target.plan.binding.plugin_id, "core-tools"); + + let external_ticket = reload + .prepare_ready_capability_dispatch( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + ) + .expect("external dispatch ticket should be ready"); + assert_eq!( + external_ticket.target.dispatch_kind, + PluginCapabilityDispatchKind::ExternalProtocol + ); + assert!(external_ticket.target.plan.stream); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + reload + .refresh_external_backend_health(&host) + .expect("health refresh should succeed"); + let error = reload + .prepare_ready_capability_dispatch( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + ) + .expect_err("unavailable backend should block dispatch ticket creation"); + assert!(error.to_string().contains("插件后端不可用")); +} + +#[tokio::test] +async fn reload_dispatches_builtin_with_in_process_executor() { + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![builtin]) + .await + .expect("builtin reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + |plan| { + assert_eq!(plan.binding.plugin_id, "core-tools"); + assert_eq!(plan.invoke_message.capability, "tool.read"); + Ok(CapabilityExecutionResult::ok( + plan.binding.capability.name.to_string(), + serde_json::json!({ "content": "hello" }), + )) + }, + ) + .expect("builtin dispatch should succeed"); + + match outcome { + PluginCapabilityDispatchOutcome::Completed(result) => { + assert!(result.success); + assert_eq!(result.capability_name, "tool.read"); + assert_eq!(result.output, serde_json::json!({ "content": "hello" })); + }, + other => panic!("unexpected builtin dispatch outcome: {other:?}"), + } +} + +#[tokio::test] +async fn reload_dispatches_builtin_with_registered_executor() { + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![builtin]) + .await + .expect("builtin reload should succeed"); + let mut registry = BuiltinCapabilityExecutorRegistry::new(); + registry.register("tool.read", Arc::new(StaticBuiltinExecutor)); + + let outcome = reload + .dispatch_capability_with_registry( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + ®istry, + ) + .expect("registered builtin dispatch should succeed"); + + match outcome { + PluginCapabilityDispatchOutcome::Completed(result) => { + assert!(result.success); + assert_eq!(result.capability_name, "tool.read"); + assert_eq!( + result.output, + serde_json::json!({ + "executedBy": "core-tools", + "input": { "path": "README.md" }, + }) + ); + }, + other => panic!("unexpected builtin dispatch outcome: {other:?}"), + } +} + +#[tokio::test] +async fn reload_dispatches_external_as_protocol_request() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve into protocol request"); + + match outcome { + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => { + assert_eq!(dispatch.runtime_handle.plugin_id, "repo-inspector"); + assert_eq!( + dispatch.runtime_handle.backend_kind, + PluginBackendKind::Process + ); + assert_eq!( + dispatch.target.dispatch_kind, + PluginCapabilityDispatchKind::ExternalProtocol + ); + assert!(dispatch.target.plan.stream); + assert_eq!( + dispatch.target.plan.invoke_message.capability, + "tool.search" + ); + }, + other => panic!("unexpected external dispatch outcome: {other:?}"), + } + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn protocol_dispatch_maps_success_result_into_execution_result() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let dispatch = match outcome { + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => dispatch, + other => panic!("unexpected external dispatch outcome: {other:?}"), + }; + + let result = dispatch.into_execution_result(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 3 }), + error: None, + metadata: serde_json::json!({ "source": "protocol" }), + }); + assert!(result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.output, serde_json::json!({ "matches": 3 })); + assert_eq!( + result.metadata, + Some(serde_json::json!({ "source": "protocol" })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn protocol_dispatch_maps_failure_result_into_execution_result() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let dispatch = match outcome { + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => dispatch, + other => panic!("unexpected external dispatch outcome: {other:?}"), + }; + + let result = dispatch.into_execution_result(ResultMessage { + id: "req-1".to_string(), + kind: None, + success: false, + output: serde_json::Value::Null, + error: Some(ErrorPayload { + code: "plugin_failed".to_string(), + message: "search failed".to_string(), + details: serde_json::json!({ "query": "plugin-host" }), + retriable: false, + }), + metadata: serde_json::json!({ "source": "protocol" }), + }); + assert!(!result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.error.as_deref(), Some("search failed")); + assert_eq!( + result.metadata, + Some(serde_json::json!({ "source": "protocol" })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn protocol_dispatch_maps_completed_stream_into_execution_result() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let dispatch = match outcome { + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => dispatch, + other => panic!("unexpected external dispatch outcome: {other:?}"), + }; + + let result = dispatch + .finish_stream_execution_result(vec![ + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Started, + event: "started".to_string(), + payload: serde_json::Value::Null, + seq: 0, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Delta, + event: "chunk".to_string(), + payload: serde_json::json!({ "text": "hello" }), + seq: 1, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Completed, + event: "done".to_string(), + payload: serde_json::json!({ "matches": 3 }), + seq: 2, + error: None, + }, + ]) + .expect("stream completion should map to execution result"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.output, serde_json::json!({ "matches": 3 })); + assert_eq!( + result.metadata, + Some(serde_json::json!({ + "streamEvents": [{ + "event": "chunk", + "payload": { "text": "hello" }, + "seq": 1 + }] + })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn protocol_dispatch_maps_failed_stream_into_execution_result() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let dispatch = match outcome { + PluginCapabilityDispatchOutcome::ExternalProtocol(dispatch) => dispatch, + other => panic!("unexpected external dispatch outcome: {other:?}"), + }; + + let result = dispatch + .finish_stream_execution_result(vec![ + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Started, + event: "started".to_string(), + payload: serde_json::Value::Null, + seq: 0, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Delta, + event: "chunk".to_string(), + payload: serde_json::json!({ "text": "hello" }), + seq: 1, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Failed, + event: "failed".to_string(), + payload: serde_json::Value::Null, + seq: 2, + error: Some(ErrorPayload { + code: "stream_failed".to_string(), + message: "stream failed".to_string(), + details: serde_json::json!({ "reason": "boom" }), + retriable: false, + }), + }, + ]) + .expect("stream failure should map to execution result"); + + assert!(!result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.error.as_deref(), Some("stream failed")); + assert_eq!( + result.metadata, + Some(serde_json::json!({ + "streamEvents": [{ + "event": "chunk", + "payload": { "text": "hello" }, + "seq": 1 + }] + })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[test] +fn completed_dispatch_outcome_executes_without_external_dispatchers() { + let outcome = PluginCapabilityDispatchOutcome::Completed(CapabilityExecutionResult::ok( + "tool.read", + serde_json::json!({ "content": "hello" }), + )); + + let result = outcome + .execute_with_dispatchers( + &StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage::success( + "ignored", + serde_json::Value::Null, + )), + }, + &StaticHttpDispatcher, + ) + .expect("completed outcome should pass through"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.read"); + assert_eq!(result.output, serde_json::json!({ "content": "hello" })); +} + +#[tokio::test] +async fn protocol_dispatch_outcome_executes_via_protocol_dispatcher() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let result = outcome + .execute_with_dispatchers( + &StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 5 }), + error: None, + metadata: serde_json::json!({ "source": "protocol-dispatcher" }), + }), + }, + &StaticHttpDispatcher, + ) + .expect("protocol dispatcher should execute outcome"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.output, serde_json::json!({ "matches": 5 })); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[test] +fn http_dispatch_outcome_executes_via_http_dispatcher() { + let binding = PluginCapabilityBinding { + plugin_id: "http-plugin".to_string(), + display_name: "HTTP Plugin".to_string(), + backend_kind: PluginBackendKind::Http, + capability: CapabilityWireDescriptor::builder( + "tool.fetch", + astrcode_core::CapabilityKind::tool(), + ) + .description("fetch data") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("http capability should build"), + runtime_handle: None, + }; + let target = super::PluginCapabilityInvocationTarget { + dispatch_kind: PluginCapabilityDispatchKind::ExternalHttp, + plan: super::PluginCapabilityInvocationPlan { + binding, + payload: serde_json::json!({ "url": "https://example.com" }), + stream: false, + invocation_context: super::to_plugin_invocation_context( + &sample_capability_context(), + "tool.fetch", + ), + invoke_message: InvokeMessage { + id: "req-1".to_string(), + capability: "tool.fetch".to_string(), + input: serde_json::json!({ "url": "https://example.com" }), + context: super::to_plugin_invocation_context( + &sample_capability_context(), + "tool.fetch", + ), + stream: false, + }, + }, + }; + let outcome = + PluginCapabilityDispatchOutcome::ExternalHttp(PluginCapabilityHttpDispatch { target }); + + let result = outcome + .execute_with_dispatchers( + &StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage::success( + "ignored", + serde_json::Value::Null, + )), + }, + &StaticHttpDispatcher, + ) + .expect("http dispatcher should execute outcome"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.fetch"); + assert_eq!( + result.output, + serde_json::json!({ + "transport": "http", + "pluginId": "http-plugin", + }) + ); +} + +#[tokio::test] +async fn transport_backed_protocol_dispatcher_uses_unary_transport_for_non_streaming() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let result = outcome + .execute_with_dispatchers( + &TransportBackedProtocolDispatcher::new(FakeProtocolTransport { + unary: Some(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 17 }), + error: None, + metadata: serde_json::json!({ "source": "transport" }), + }), + stream: Vec::new(), + }), + &StaticHttpDispatcher, + ) + .expect("transport-backed protocol dispatcher should execute unary result"); + + assert!(result.success); + assert_eq!(result.output, serde_json::json!({ "matches": 17 })); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn transport_backed_protocol_dispatcher_uses_stream_transport_for_streaming() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let outcome = reload + .dispatch_capability_with_builtin_executor( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + |_| panic!("external capability should not use builtin executor"), + ) + .expect("external dispatch should resolve"); + + let result = outcome + .execute_with_dispatchers( + &TransportBackedProtocolDispatcher::new(FakeProtocolTransport { + unary: None, + stream: vec![ + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Started, + event: "started".to_string(), + payload: serde_json::Value::Null, + seq: 0, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Delta, + event: "chunk".to_string(), + payload: serde_json::json!({ "text": "hello" }), + seq: 1, + error: None, + }, + EventMessage { + id: "req-1".to_string(), + phase: EventPhase::Completed, + event: "done".to_string(), + payload: serde_json::json!({ "matches": 19 }), + seq: 2, + error: None, + }, + ], + }), + &StaticHttpDispatcher, + ) + .expect("transport-backed protocol dispatcher should execute stream result"); + + assert!(result.success); + assert_eq!(result.output, serde_json::json!({ "matches": 19 })); + assert_eq!( + result.metadata, + Some(serde_json::json!({ + "streamEvents": [{ + "event": "chunk", + "payload": { "text": "hello" }, + "seq": 1 + }] + })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn execute_capability_with_registries_runs_builtin_path() { + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![builtin]) + .await + .expect("builtin reload should succeed"); + let mut builtin_registry = BuiltinCapabilityExecutorRegistry::new(); + builtin_registry.register("tool.read", Arc::new(StaticBuiltinExecutor)); + + let result = reload + .execute_capability_with_registries( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + &builtin_registry, + &PluginCapabilityProtocolDispatcherRegistry::new(), + &PluginCapabilityHttpDispatcherRegistry::new(), + ) + .expect("builtin execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.read"); + assert_eq!( + result.output, + serde_json::json!({ + "executedBy": "core-tools", + "input": { "path": "README.md" }, + }) + ); +} + +#[tokio::test] +async fn execute_capability_with_registries_runs_protocol_path() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + let mut protocol_registry = PluginCapabilityProtocolDispatcherRegistry::new(); + protocol_registry.register( + "repo-inspector", + Arc::new(StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 7 }), + error: None, + metadata: serde_json::json!({ "source": "registry" }), + }), + }), + ); + + let result = reload + .execute_capability_with_registries( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + &BuiltinCapabilityExecutorRegistry::new(), + &protocol_registry, + &PluginCapabilityHttpDispatcherRegistry::new(), + ) + .expect("protocol execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.output, serde_json::json!({ "matches": 7 })); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn execute_capability_with_registries_runs_http_path() { + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("remote-fetch", "Remote Fetch"); + external.source_kind = PluginSourceKind::Http; + external.source_ref = "https://plugins.example.com/remote-fetch".to_string(); + external.tools.push( + CapabilityWireDescriptor::builder("tool.fetch", astrcode_core::CapabilityKind::tool()) + .description("fetch remote data") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("http capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("http reload should succeed"); + let mut http_registry = PluginCapabilityHttpDispatcherRegistry::new(); + http_registry.register("remote-fetch", Arc::new(StaticHttpDispatcher)); + + let result = reload + .execute_capability_with_registries( + "tool.fetch", + serde_json::json!({ "url": "https://example.com" }), + &sample_capability_context(), + &BuiltinCapabilityExecutorRegistry::new(), + &PluginCapabilityProtocolDispatcherRegistry::new(), + &http_registry, + ) + .expect("http execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.fetch"); + assert_eq!( + result.output, + serde_json::json!({ + "transport": "http", + "pluginId": "remote-fetch", + }) + ); +} + +#[tokio::test] +async fn execute_capability_runs_builtin_path_with_dispatcher_set() { + let host = PluginHost::new(); + let mut builtin = PluginDescriptor::builtin("core-tools", "Core Tools"); + builtin.tools.push( + CapabilityWireDescriptor::builder("tool.read", astrcode_core::CapabilityKind::tool()) + .description("read file") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("builtin capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![builtin]) + .await + .expect("builtin reload should succeed"); + let mut dispatchers = PluginCapabilityDispatcherSet::new(); + dispatchers.register_builtin("tool.read", Arc::new(StaticBuiltinExecutor)); + + let result = reload + .execute_capability( + "tool.read", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + &dispatchers, + ) + .expect("builtin execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.read"); +} + +#[tokio::test] +async fn execute_capability_runs_protocol_path_with_dispatcher_set() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + let mut dispatchers = PluginCapabilityDispatcherSet::new(); + dispatchers.register_protocol( + "repo-inspector", + Arc::new(StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 11 }), + error: None, + metadata: serde_json::json!({ "source": "dispatcher-set" }), + }), + }), + ); + + let result = reload + .execute_capability( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + &dispatchers, + ) + .expect("protocol execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.search"); + assert_eq!(result.output, serde_json::json!({ "matches": 11 })); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn execute_capability_live_uses_real_external_runtime_handle() { + let (command, args) = node_protocol_command(); + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(command); + external.launch_args = args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.echo", astrcode_core::CapabilityKind::tool()) + .description("echo payload") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("echo capability should build"), + ); + external.tools.push( + CapabilityWireDescriptor::builder( + "tool.patch_stream", + astrcode_core::CapabilityKind::tool(), + ) + .description("stream patch result") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .invocation_mode(InvocationMode::Streaming) + .build() + .expect("stream capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let unary = reload + .execute_capability_live( + "tool.echo", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + &PluginCapabilityDispatcherSet::new(), + ) + .await + .expect("live unary execution should succeed"); + + assert!(unary.success); + assert_eq!( + unary.output, + serde_json::json!({ "echoed": { "path": "README.md" } }) + ); + assert!( + reload + .runtime_handle_snapshot("repo-inspector") + .expect("runtime snapshot should exist") + .remote_negotiated + ); + + let stream = reload + .execute_capability_live( + "tool.patch_stream", + serde_json::json!({ "path": "src/main.rs" }), + &sample_capability_context(), + &PluginCapabilityDispatcherSet::new(), + ) + .await + .expect("live streaming execution should succeed"); + + assert!(stream.success); + assert_eq!(stream.output, serde_json::json!({ "ok": true })); + assert_eq!( + stream.metadata, + Some(serde_json::json!({ + "streamEvents": [{ + "event": "tool.delta", + "payload": { "chunk": 1 }, + "seq": 1 + }] + })) + ); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn execute_capability_live_rechecks_external_backend_health_before_dispatch() { + let (command, args) = node_protocol_command(); + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(command); + external.launch_args = args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.echo", astrcode_core::CapabilityKind::tool()) + .description("echo payload") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("echo capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } + + let error = reload + .execute_capability_live( + "tool.echo", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + &PluginCapabilityDispatcherSet::new(), + ) + .await + .expect_err("dead external backend should not dispatch"); + + assert!(error.to_string().contains("插件后端不可用")); + let snapshot = reload + .runtime_handle_snapshot("repo-inspector") + .expect("runtime snapshot should still exist"); + assert_eq!(snapshot.health, Some(PluginBackendHealth::Unavailable)); +} + +#[tokio::test] +async fn execute_capability_live_refreshes_backend_health_after_runtime_invoke_failure() { + let (command, args) = node_protocol_command_exit_after_initialize(); + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(command); + external.launch_args = args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.echo", astrcode_core::CapabilityKind::tool()) + .description("echo payload") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("echo capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + + let error = reload + .execute_capability_live( + "tool.echo", + serde_json::json!({ "path": "README.md" }), + &sample_capability_context(), + &PluginCapabilityDispatcherSet::new(), + ) + .await + .expect_err("invoke after remote exit should fail"); + + assert!( + error.to_string().contains("transport closed") + || error.to_string().contains("failed to read plugin payload") + ); + let snapshot = reload + .runtime_handle_snapshot("repo-inspector") + .expect("runtime snapshot should still exist"); + assert_eq!(snapshot.health, Some(PluginBackendHealth::Unavailable)); +} + +#[tokio::test] +async fn execute_capability_runs_http_path_with_dispatcher_set() { + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("remote-fetch", "Remote Fetch"); + external.source_kind = PluginSourceKind::Http; + external.source_ref = "https://plugins.example.com/remote-fetch".to_string(); + external.tools.push( + CapabilityWireDescriptor::builder("tool.fetch", astrcode_core::CapabilityKind::tool()) + .description("fetch remote data") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("http capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("http reload should succeed"); + let mut dispatchers = PluginCapabilityDispatcherSet::new(); + dispatchers.register_http("remote-fetch", Arc::new(StaticHttpDispatcher)); + + let result = reload + .execute_capability( + "tool.fetch", + serde_json::json!({ "url": "https://example.com" }), + &sample_capability_context(), + &dispatchers, + ) + .expect("http execution should succeed"); + + assert!(result.success); + assert_eq!(result.capability_name, "tool.fetch"); + assert_eq!( + result.output, + serde_json::json!({ + "transport": "http", + "pluginId": "remote-fetch", + }) + ); +} + +#[tokio::test] +async fn execute_capability_uses_default_protocol_dispatcher_when_plugin_specific_missing() { + #[cfg(windows)] + let process_command = std::env::var("ComSpec").unwrap_or_else(|_| "cmd.exe".to_string()); + #[cfg(not(windows))] + let process_command = "/bin/sh".to_string(); + #[cfg(windows)] + let process_args = vec!["/C".to_string(), "ping 127.0.0.1 -n 5 >nul".to_string()]; + #[cfg(not(windows))] + let process_args = vec!["-c".to_string(), "sleep 2".to_string()]; + + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("repo-inspector", "Repo Inspector"); + external.source_kind = PluginSourceKind::Process; + external.source_ref = "plugins/repo-inspector.toml".to_string(); + external.launch_command = Some(process_command); + external.launch_args = process_args; + external.tools.push( + CapabilityWireDescriptor::builder("tool.search", astrcode_core::CapabilityKind::tool()) + .description("search repository") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("external capability should build"), + ); + + let mut reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("external reload should succeed"); + let mut dispatchers = PluginCapabilityDispatcherSet::new(); + dispatchers.register_default_protocol(Arc::new(StaticProtocolDispatcher { + execution: PluginCapabilityProtocolExecution::Unary(ResultMessage { + id: "req-1".to_string(), + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ "matches": 13 }), + error: None, + metadata: serde_json::json!({ "source": "default-protocol" }), + }), + })); + + let result = reload + .execute_capability( + "tool.search", + serde_json::json!({ "query": "plugin-host" }), + &sample_capability_context(), + &dispatchers, + ) + .expect("default protocol dispatcher should execute capability"); + + assert!(result.success); + assert_eq!(result.output, serde_json::json!({ "matches": 13 })); + + for backend in &mut reload.external_backends { + backend.shutdown().await.expect("shutdown should succeed"); + } +} + +#[tokio::test] +async fn execute_capability_uses_default_http_dispatcher_when_plugin_specific_missing() { + let host = PluginHost::new(); + let mut external = PluginDescriptor::builtin("remote-fetch", "Remote Fetch"); + external.source_kind = PluginSourceKind::Http; + external.source_ref = "https://plugins.example.com/remote-fetch".to_string(); + external.tools.push( + CapabilityWireDescriptor::builder("tool.fetch", astrcode_core::CapabilityKind::tool()) + .description("fetch remote data") + .input_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .output_schema(serde_json::json!({ + "type": "object", + "properties": {} + })) + .build() + .expect("http capability should build"), + ); + + let reload = host + .reload_from_descriptors(vec![external]) + .await + .expect("http reload should succeed"); + let mut dispatchers = PluginCapabilityDispatcherSet::new(); + dispatchers.register_default_http(Arc::new(StaticHttpDispatcher)); + + let result = reload + .execute_capability( + "tool.fetch", + serde_json::json!({ "url": "https://example.com" }), + &sample_capability_context(), + &dispatchers, + ) + .expect("default http dispatcher should execute capability"); + + assert!(result.success); + assert_eq!( + result.output, + serde_json::json!({ + "transport": "http", + "pluginId": "remote-fetch", + }) + ); +} diff --git a/crates/plugin-host/src/lib.rs b/crates/plugin-host/src/lib.rs new file mode 100644 index 00000000..30161b0a --- /dev/null +++ b/crates/plugin-host/src/lib.rs @@ -0,0 +1,69 @@ +//! 统一 plugin 宿主骨架。 +//! +//! 后续这里将承接旧 `crates/plugin` 的进程管理、descriptor 校验、 +//! snapshot 激活和资源发现。 + +pub mod backend; +pub mod descriptor; +pub mod hooks; +pub mod host; +pub mod loader; +pub mod manifest; +pub mod modes; +pub mod protocol; +pub mod providers; +pub mod registry; +pub mod resource_provider; +pub mod resources; +pub mod snapshot; +pub mod tools; +pub mod transport; + +pub use descriptor::{ + CommandDescriptor, HookDescriptor, PluginDescriptor, PluginSourceKind, PromptDescriptor, + ProviderDescriptor, ResourceDescriptor, SkillDescriptor, ThemeDescriptor, +}; +pub use hooks::{ + HookBusEffect, HookBusEffectKind, HookBusOutcome, HookBusRequest, HookBusStep, + HookDispatchMode, HookFailurePolicy, HookRegistration, HookStage, SUPPORTED_HOOK_EVENTS, + dispatch_hook_bus, +}; +pub use host::{ + ActivePluginRuntimeCatalog, ActivePluginRuntimeEntry, BuiltinCapabilityExecutor, + BuiltinCapabilityExecutorRegistry, ExternalBackendHealthCatalog, PluginCapabilityBinding, + PluginCapabilityDispatchKind, PluginCapabilityDispatchOutcome, + PluginCapabilityDispatchReadiness, PluginCapabilityDispatchTicket, + PluginCapabilityDispatcherSet, PluginCapabilityHttpDispatch, PluginCapabilityHttpDispatcher, + PluginCapabilityHttpDispatcherRegistry, PluginCapabilityInvocationPlan, + PluginCapabilityInvocationTarget, PluginCapabilityProtocolDispatch, + PluginCapabilityProtocolDispatcher, PluginCapabilityProtocolDispatcherRegistry, + PluginCapabilityProtocolExecution, PluginCapabilityProtocolTransport, PluginHost, + PluginHostReload, PluginRuntimeHandleRef, PluginRuntimeHandleSnapshot, + TransportBackedProtocolDispatcher, +}; +pub use loader::PluginLoader; +pub use manifest::{ + CommandManifestEntry, PluginManifest, PluginType, PromptManifestEntry, ProviderManifestEntry, + ResourceManifestEntry, SkillManifestEntry, ThemeManifestEntry, +}; +pub use modes::builtin_modes_descriptor; +pub use protocol::{ + PluginInitializeState, RemotePluginHandshakeSummary, default_initialize_message, + default_local_peer_descriptor, default_profiles, +}; +pub use providers::{ + OPENAI_API_KIND, OPENAI_PROVIDER_ID, ProviderContributionCatalog, + builtin_openai_provider_descriptor, +}; +pub use registry::{PluginEntry, PluginHealth, PluginRegistry, PluginState}; +pub use resource_provider::{ResourceProvider, ResourceReadResult, ResourceRequestContext}; +pub use resources::{ + ResourceCatalog, ResourceDiscoverReport, SkillCatalogBaseBuild, build_skill_catalog_base, + resources_discover, +}; +pub use snapshot::PluginActiveSnapshot; +pub use tools::{ + ToolContributionCatalog, builtin_collaboration_tools_descriptor, builtin_tools_descriptor, + tool_contribution_catalog, +}; +pub use transport::PluginStdioTransport; diff --git a/crates/plugin-host/src/loader.rs b/crates/plugin-host/src/loader.rs new file mode 100644 index 00000000..eb87d8cd --- /dev/null +++ b/crates/plugin-host/src/loader.rs @@ -0,0 +1,323 @@ +use std::path::{Path, PathBuf}; + +use astrcode_core::{AstrError, Result}; + +use crate::{ + CommandManifestEntry, PluginDescriptor, PluginManifest, PromptManifestEntry, + ProviderManifestEntry, ResourceManifestEntry, SkillManifestEntry, ThemeManifestEntry, + descriptor::{ + CommandDescriptor, PluginSourceKind, PromptDescriptor, ProviderDescriptor, + ResourceDescriptor, SkillDescriptor, ThemeDescriptor, + }, +}; + +pub fn parse_plugin_manifest_toml(raw: &str) -> Result { + toml::from_str(raw).map_err(|error| { + AstrError::Validation(format!("failed to parse plugin manifest TOML: {error}")) + }) +} + +#[derive(Debug, Default, Clone)] +pub struct PluginLoader { + pub search_paths: Vec, +} + +fn resolve_relative_path( + path_field: &mut Option, + manifest_path: &Path, + search_path: &Path, + require_components_gt_1: bool, +) { + let Some(value) = path_field.clone() else { + return; + }; + let path = PathBuf::from(&value); + if !path.is_relative() { + return; + } + if require_components_gt_1 && path.components().count() <= 1 { + return; + } + let resolved = manifest_path.parent().unwrap_or(search_path).join(path); + *path_field = Some(resolved.to_string_lossy().into_owned()); +} + +fn manifest_to_descriptor(manifest: PluginManifest, manifest_path: &Path) -> PluginDescriptor { + let source_ref = manifest + .executable + .clone() + .unwrap_or_else(|| manifest_path.to_string_lossy().into_owned()); + PluginDescriptor { + plugin_id: manifest.name.clone(), + display_name: manifest.name, + version: manifest.version, + source_kind: PluginSourceKind::Process, + source_ref, + enabled: true, + priority: 0, + launch_command: manifest.executable, + launch_args: manifest.args, + working_dir: manifest.working_dir, + repository: manifest.repository, + tools: manifest.capabilities, + hooks: Vec::new(), + providers: manifest + .providers + .into_iter() + .map( + |ProviderManifestEntry { id, api_kind }| ProviderDescriptor { + provider_id: id, + api_kind, + }, + ) + .collect(), + resources: manifest + .resources + .into_iter() + .map( + |ResourceManifestEntry { id, kind, locator }| ResourceDescriptor { + resource_id: id, + kind, + locator, + }, + ) + .collect(), + commands: manifest + .commands + .into_iter() + .map(|CommandManifestEntry { id, entry_ref }| CommandDescriptor { + command_id: id, + entry_ref, + }) + .collect(), + themes: manifest + .themes + .into_iter() + .map(|ThemeManifestEntry { id }| ThemeDescriptor { theme_id: id }) + .collect(), + prompts: manifest + .prompts + .into_iter() + .map(|PromptManifestEntry { id, body }| PromptDescriptor { + prompt_id: id, + body, + }) + .collect(), + skills: manifest + .skills + .into_iter() + .map(|SkillManifestEntry { id, entry_ref }| SkillDescriptor { + skill_id: id, + entry_ref, + }) + .collect(), + modes: Vec::new(), + } +} + +impl PluginLoader { + pub fn discover_descriptors(&self) -> Result> { + let mut descriptors = Vec::new(); + for search_path in &self.search_paths { + if !search_path.exists() { + continue; + } + + let entries = match std::fs::read_dir(search_path) { + Ok(entries) => entries, + Err(error) => { + log::warn!( + "skipping plugin directory '{}' because it could not be read: {}", + search_path.display(), + error + ); + continue; + }, + }; + + for entry in entries { + let entry = match entry { + Ok(entry) => entry, + Err(error) => { + log::warn!( + "skipping plugin entry in '{}' because it could not be inspected: {}", + search_path.display(), + error + ); + continue; + }, + }; + let path = entry.path(); + if path.extension().and_then(|ext| ext.to_str()) != Some("toml") { + continue; + } + let raw = match std::fs::read_to_string(&path) { + Ok(raw) => raw, + Err(error) => { + log::warn!( + "skipping plugin manifest '{}' because it could not be read: {}", + path.display(), + error + ); + continue; + }, + }; + let mut manifest = match parse_plugin_manifest_toml(&raw) { + Ok(manifest) => manifest, + Err(error) => { + log::warn!( + "skipping plugin manifest '{}' because it could not be parsed: {}", + path.display(), + error + ); + continue; + }, + }; + resolve_relative_path(&mut manifest.working_dir, &path, search_path, false); + resolve_relative_path(&mut manifest.executable, &path, search_path, true); + descriptors.push(manifest_to_descriptor(manifest, &path)); + } + } + + descriptors.sort_by(|left, right| { + left.plugin_id + .cmp(&right.plugin_id) + .then_with(|| left.version.cmp(&right.version)) + .then_with(|| left.launch_command.cmp(&right.launch_command)) + }); + Ok(descriptors) + } +} + +#[cfg(test)] +mod tests { + use std::{ + fs, + path::PathBuf, + time::{SystemTime, UNIX_EPOCH}, + }; + + use super::{PluginLoader, parse_plugin_manifest_toml}; + + fn unique_temp_dir(name: &str) -> PathBuf { + let suffix = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should be monotonic enough") + .as_nanos(); + std::env::temp_dir().join(format!("astrcode-plugin-host-{name}-{suffix}")) + } + + #[test] + fn parse_plugin_manifest_toml_reads_manifest() { + let manifest = parse_plugin_manifest_toml( + r#" +name = "repo-inspector" +version = "0.1.0" +description = "inspect repo" +plugin_type = ["Tool"] +capabilities = [] +executable = "./bin/repo-inspector" +args = ["--stdio"] +working_dir = "." +repository = "https://example.com/repo-inspector" +"#, + ) + .expect("manifest should parse"); + + assert_eq!(manifest.name, "repo-inspector"); + assert_eq!(manifest.args, vec!["--stdio".to_string()]); + assert_eq!(manifest.working_dir.as_deref(), Some(".")); + } + + #[test] + fn parse_plugin_manifest_toml_reads_provider_contributions() { + let manifest = parse_plugin_manifest_toml( + r#" +name = "corp-provider" +version = "0.1.0" +description = "corp provider" +plugin_type = ["Provider"] +capabilities = [] +executable = "./bin/corp-provider" +repository = "https://example.com/corp-provider" + +[[providers]] +id = "corp-ai" +api_kind = "openai-compatible" +"#, + ) + .expect("manifest should parse"); + + assert_eq!(manifest.providers.len(), 1); + assert_eq!(manifest.providers[0].id, "corp-ai"); + assert_eq!(manifest.providers[0].api_kind, "openai-compatible"); + } + + #[test] + fn discover_descriptors_resolves_relative_paths_and_sorts() { + let root = unique_temp_dir("discover"); + fs::create_dir_all(root.join("alpha")).expect("temp dir should create"); + fs::create_dir_all(root.join("beta")).expect("temp dir should create"); + fs::write( + root.join("beta").join("beta.toml"), + r#" +name = "beta" +version = "0.1.0" +description = "beta" +plugin_type = ["Tool"] +capabilities = [] +executable = "./bin/beta" +args = ["--serve"] +working_dir = "." +repository = "https://example.com/beta" +"#, + ) + .expect("beta manifest should write"); + fs::write( + root.join("alpha").join("alpha.toml"), + r#" +name = "alpha" +version = "0.1.0" +description = "alpha" +plugin_type = ["Tool"] +capabilities = [] +executable = "./bin/alpha" +args = [] +working_dir = "." +repository = "https://example.com/alpha" +"#, + ) + .expect("alpha manifest should write"); + + let loader = PluginLoader { + search_paths: vec![root.join("alpha"), root.join("beta")], + }; + let descriptors = loader + .discover_descriptors() + .expect("descriptors should be discovered"); + + assert_eq!( + descriptors + .iter() + .map(|descriptor| descriptor.plugin_id.as_str()) + .collect::>(), + vec!["alpha", "beta"] + ); + assert!( + descriptors[0] + .launch_command + .as_deref() + .expect("launch command should resolve") + .contains("bin") + ); + assert!( + descriptors[0] + .working_dir + .as_deref() + .expect("working dir should resolve") + .contains("alpha") + ); + + let _ = fs::remove_dir_all(root); + } +} diff --git a/crates/plugin-host/src/manifest.rs b/crates/plugin-host/src/manifest.rs new file mode 100644 index 00000000..acf4a8f1 --- /dev/null +++ b/crates/plugin-host/src/manifest.rs @@ -0,0 +1,80 @@ +//! # 插件清单 +//! +//! 插件清单从 `Plugin.toml` 文件解析而来，描述插件的名称、版本、能力声明和启动方式。 + +use astrcode_core::CapabilitySpec; +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct ResourceManifestEntry { + pub id: String, + pub kind: String, + pub locator: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct CommandManifestEntry { + pub id: String, + pub entry_ref: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct ThemeManifestEntry { + pub id: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct ProviderManifestEntry { + pub id: String, + pub api_kind: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct PromptManifestEntry { + pub id: String, + pub body: String, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +pub struct SkillManifestEntry { + pub id: String, + pub entry_ref: String, +} + +/// 插件类型。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub enum PluginType { + Tool, + Orchestrator, + Provider, + Hook, +} + +/// 插件清单。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct PluginManifest { + pub name: String, + pub version: String, + pub description: String, + pub plugin_type: Vec, + pub capabilities: Vec, + pub executable: Option, + #[serde(default)] + pub args: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub working_dir: Option, + pub repository: Option, + #[serde(default)] + pub resources: Vec, + #[serde(default)] + pub commands: Vec, + #[serde(default)] + pub themes: Vec, + #[serde(default)] + pub providers: Vec, + #[serde(default)] + pub prompts: Vec, + #[serde(default)] + pub skills: Vec, +} diff --git a/crates/plugin-host/src/modes.rs b/crates/plugin-host/src/modes.rs new file mode 100644 index 00000000..594387ff --- /dev/null +++ b/crates/plugin-host/src/modes.rs @@ -0,0 +1,13 @@ +use astrcode_core::GovernanceModeSpec; + +use crate::PluginDescriptor; + +pub fn builtin_modes_descriptor( + plugin_id: impl Into, + display_name: impl Into, + modes: Vec, +) -> PluginDescriptor { + let mut descriptor = PluginDescriptor::builtin(plugin_id, display_name); + descriptor.modes = modes; + descriptor +} diff --git a/crates/plugin-host/src/protocol.rs b/crates/plugin-host/src/protocol.rs new file mode 100644 index 00000000..dc15acf1 --- /dev/null +++ b/crates/plugin-host/src/protocol.rs @@ -0,0 +1,272 @@ +use std::time::{SystemTime, UNIX_EPOCH}; + +use astrcode_protocol::plugin::{ + CapabilityWireDescriptor, InitializeMessage, InitializeResultData, PROTOCOL_VERSION, + PeerDescriptor, PeerRole, ProfileDescriptor, +}; + +/// `plugin-host` 持有的最小握手状态。 +/// +/// 第一阶段只固化： +/// - 宿主发给插件的 initialize 载荷 +/// - 插件回传的 initialize 结果 +/// - 最终协商出的协议版本 +/// +/// 这样后续迁入 `peer/supervisor` 时，不需要再把握手真相塞回旧 crate。 +#[derive(Debug, Clone, PartialEq)] +pub struct PluginInitializeState { + pub local_initialize: InitializeMessage, + pub remote_initialize: Option, +} + +/// 宿主可直接消费的远端握手摘要。 +/// +/// 它不是协议原文，而是 `plugin-host` 对远端 initialize 结果的只读稳定视图， +/// 用于后续统一装配 active runtime surface。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RemotePluginHandshakeSummary { + pub protocol_version: String, + pub peer_id: String, + pub peer_name: String, + pub capability_names: Vec, + pub profile_names: Vec, + pub skill_ids: Vec, + pub mode_ids: Vec, +} + +impl PluginInitializeState { + pub fn new(local_initialize: InitializeMessage) -> Self { + Self { + local_initialize, + remote_initialize: None, + } + } + + pub fn with_defaults( + local_peer: PeerDescriptor, + capabilities: Vec, + ) -> Self { + Self::new(default_initialize_message( + local_peer, + capabilities, + default_profiles(), + )) + } + + pub fn record_remote_initialize( + &mut self, + remote_initialize: InitializeResultData, + ) -> &InitializeResultData { + self.remote_initialize = Some(remote_initialize); + self.remote_initialize + .as_ref() + .expect("remote initialize should exist immediately after record") + } + + pub fn negotiated_protocol_version(&self) -> &str { + self.remote_initialize + .as_ref() + .map(|remote| remote.protocol_version.as_str()) + .unwrap_or_else(|| self.local_initialize.protocol_version.as_str()) + } + + pub fn remote_handshake_summary(&self) -> Option { + self.remote_initialize + .as_ref() + .map(RemotePluginHandshakeSummary::from_remote_initialize) + } +} + +impl RemotePluginHandshakeSummary { + pub fn from_remote_initialize(remote: &InitializeResultData) -> Self { + Self { + protocol_version: remote.protocol_version.clone(), + peer_id: remote.peer.id.clone(), + peer_name: remote.peer.name.clone(), + capability_names: remote + .capabilities + .iter() + .map(|capability| capability.name.to_string()) + .collect(), + profile_names: remote + .profiles + .iter() + .map(|profile| profile.name.clone()) + .collect(), + skill_ids: remote + .skills + .iter() + .map(|skill| skill.name.clone()) + .collect(), + mode_ids: remote + .modes + .iter() + .map(|mode| mode.id.to_string()) + .collect(), + } + } +} + +/// 构建 `plugin-host` 默认使用的 initialize 载荷。 +/// +/// 这里只保留最小稳态： +/// - 单一协议版本入口 +/// - 空 handlers +/// - `stdio` transport metadata +pub fn default_initialize_message( + local_peer: PeerDescriptor, + capabilities: Vec, + profiles: Vec, +) -> InitializeMessage { + InitializeMessage { + id: format!("plugin-host-init-{}", now_unix_ms()), + protocol_version: PROTOCOL_VERSION.to_string(), + supported_protocol_versions: vec![PROTOCOL_VERSION.to_string()], + peer: local_peer, + capabilities, + handlers: Vec::new(), + profiles, + metadata: serde_json::json!({ "transport": "stdio" }), + } +} + +/// 构建 `plugin-host` 默认使用的本地 peer 描述。 +/// +/// 第一阶段先给新宿主一个稳定、可测试的身份， +/// 避免 external runtime handle 在 reload 后还没有本地握手上下文。 +pub fn default_local_peer_descriptor() -> PeerDescriptor { + PeerDescriptor { + id: "plugin-host".to_string(), + name: "plugin-host".to_string(), + role: PeerRole::Supervisor, + version: env!("CARGO_PKG_VERSION").to_string(), + supported_profiles: vec!["coding".to_string()], + metadata: serde_json::json!({ + "owner": "plugin-host", + "transport": "stdio" + }), + } +} + +/// `plugin-host` 当前默认暴露的 profile。 +/// +/// 暂时只保留 `coding`，和旧插件 supervisor 的最小默认值一致， +/// 但 owner 已经迁到 `plugin-host`。 +pub fn default_profiles() -> Vec { + vec![ProfileDescriptor { + name: "coding".to_string(), + version: "1".to_string(), + description: "Coding workflow profile".to_string(), + context_schema: serde_json::json!({ + "type": "object", + "properties": { + "workingDir": { "type": "string" }, + "repoRoot": { "type": "string" }, + "openFiles": { "type": "array", "items": { "type": "string" } }, + "activeFile": { "type": "string" }, + "selection": { "type": "object" }, + "approvalMode": { "type": "string" } + } + }), + metadata: serde_json::Value::Null, + }] +} + +fn now_unix_ms() -> u128 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() +} + +#[cfg(test)] +mod tests { + use astrcode_protocol::plugin::{CapabilityKind, PeerRole}; + use serde_json::json; + + use super::{ + PluginInitializeState, default_initialize_message, default_local_peer_descriptor, + default_profiles, + }; + + fn sample_peer() -> astrcode_protocol::plugin::PeerDescriptor { + let mut peer = default_local_peer_descriptor(); + peer.id = "host-1".to_string(); + peer + } + + #[test] + fn default_initialize_message_uses_protocol_defaults() { + let capability = astrcode_protocol::plugin::CapabilityWireDescriptor::builder( + "tool.echo", + CapabilityKind::tool(), + ) + .description("Echo the input") + .schema(json!({ "type": "object" }), json!({ "type": "object" })) + .build() + .expect("capability should build"); + + let message = + default_initialize_message(sample_peer(), vec![capability.clone()], default_profiles()); + + assert!(message.id.starts_with("plugin-host-init-")); + assert_eq!(message.protocol_version, "5"); + assert_eq!(message.supported_protocol_versions, vec!["5".to_string()]); + assert_eq!(message.capabilities, vec![capability]); + assert!(message.handlers.is_empty()); + assert_eq!(message.metadata["transport"], "stdio"); + } + + #[test] + fn default_profiles_exposes_single_coding_profile() { + let profiles = default_profiles(); + + assert_eq!(profiles.len(), 1); + assert_eq!(profiles[0].name, "coding"); + assert_eq!(profiles[0].version, "1"); + assert_eq!(profiles[0].context_schema["type"], "object"); + } + + #[test] + fn initialize_state_records_remote_handshake() { + let local_peer = sample_peer(); + let local = default_initialize_message(local_peer.clone(), Vec::new(), default_profiles()); + let mut state = PluginInitializeState::new(local.clone()); + + assert_eq!(state.negotiated_protocol_version(), "5"); + + let recorded = + state.record_remote_initialize(astrcode_protocol::plugin::InitializeResultData { + protocol_version: "5".to_string(), + peer: local_peer, + capabilities: Vec::new(), + handlers: Vec::new(), + profiles: default_profiles(), + skills: Vec::new(), + modes: Vec::new(), + metadata: serde_json::Value::Null, + }); + + assert_eq!(recorded.protocol_version, "5"); + assert_eq!(state.negotiated_protocol_version(), "5"); + assert!(state.remote_initialize.is_some()); + assert_eq!(state.local_initialize, local); + let summary = state + .remote_handshake_summary() + .expect("remote handshake summary should exist"); + assert_eq!(summary.peer_id, "host-1"); + assert_eq!(summary.profile_names, vec!["coding".to_string()]); + } + + #[test] + fn default_local_peer_descriptor_marks_plugin_host_owner() { + let peer = default_local_peer_descriptor(); + + assert_eq!(peer.id, "plugin-host"); + assert_eq!(peer.name, "plugin-host"); + assert_eq!(peer.role, PeerRole::Supervisor); + assert_eq!(peer.supported_profiles, vec!["coding".to_string()]); + assert_eq!(peer.metadata["owner"], "plugin-host"); + assert_eq!(peer.metadata["transport"], "stdio"); + } +} diff --git a/crates/plugin-host/src/providers.rs b/crates/plugin-host/src/providers.rs new file mode 100644 index 00000000..be22dcdb --- /dev/null +++ b/crates/plugin-host/src/providers.rs @@ -0,0 +1,105 @@ +use astrcode_core::Result; + +use crate::{PluginDescriptor, ProviderDescriptor, descriptor::validate_descriptors}; + +pub const OPENAI_PROVIDER_ID: &str = "openai"; +pub const OPENAI_API_KIND: &str = "openai"; + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ProviderContributionCatalog { + pub providers: Vec, +} + +pub fn builtin_openai_provider_descriptor() -> PluginDescriptor { + let mut descriptor = PluginDescriptor::builtin("builtin-provider-openai", "Builtin OpenAI"); + descriptor.providers.push(ProviderDescriptor { + provider_id: OPENAI_PROVIDER_ID.to_string(), + api_kind: OPENAI_API_KIND.to_string(), + }); + descriptor +} + +impl ProviderContributionCatalog { + pub fn from_descriptors(descriptors: &[PluginDescriptor]) -> Result { + validate_descriptors(descriptors)?; + Ok(Self { + providers: descriptors + .iter() + .flat_map(|descriptor| descriptor.providers.iter().cloned()) + .collect(), + }) + } + + pub fn provider(&self, provider_id: &str) -> Option<&ProviderDescriptor> { + self.providers + .iter() + .find(|provider| provider.provider_id == provider_id) + } + + pub fn provider_for_api_kind(&self, api_kind: &str) -> Option<&ProviderDescriptor> { + self.providers + .iter() + .find(|provider| provider.api_kind == api_kind) + } +} + +#[cfg(test)] +mod tests { + use super::{ + OPENAI_API_KIND, OPENAI_PROVIDER_ID, ProviderContributionCatalog, + builtin_openai_provider_descriptor, + }; + use crate::{PluginDescriptor, ProviderDescriptor}; + + #[test] + fn builtin_openai_provider_is_registered_through_descriptor() { + let descriptor = builtin_openai_provider_descriptor(); + let catalog = ProviderContributionCatalog::from_descriptors(&[descriptor]) + .expect("provider catalog should build"); + + let provider = catalog + .provider(OPENAI_PROVIDER_ID) + .expect("openai provider should exist"); + + assert_eq!(provider.api_kind, OPENAI_API_KIND); + } + + #[test] + fn provider_catalog_accepts_plugin_provider_descriptors() { + let mut descriptor = PluginDescriptor::builtin("corp-provider", "Corp Provider"); + descriptor.providers.push(ProviderDescriptor { + provider_id: "corp-ai".to_string(), + api_kind: "openai-compatible".to_string(), + }); + + let catalog = ProviderContributionCatalog::from_descriptors(&[descriptor]) + .expect("provider catalog should build"); + + assert_eq!( + catalog + .provider_for_api_kind("openai-compatible") + .expect("provider should be indexed") + .provider_id, + "corp-ai" + ); + } + + #[test] + fn provider_catalog_rejects_duplicate_provider_ids() { + let mut first = PluginDescriptor::builtin("first", "First"); + first.providers.push(ProviderDescriptor { + provider_id: "shared".to_string(), + api_kind: "openai".to_string(), + }); + let mut second = PluginDescriptor::builtin("second", "Second"); + second.providers.push(ProviderDescriptor { + provider_id: "shared".to_string(), + api_kind: "anthropic".to_string(), + }); + + let error = ProviderContributionCatalog::from_descriptors(&[first, second]) + .expect_err("duplicate provider ids should fail"); + + assert!(error.to_string().contains("provider 'shared'")); + } +} diff --git a/crates/plugin-host/src/registry.rs b/crates/plugin-host/src/registry.rs new file mode 100644 index 00000000..e12973dd --- /dev/null +++ b/crates/plugin-host/src/registry.rs @@ -0,0 +1,414 @@ +use std::{collections::BTreeMap, sync::RwLock}; + +use astrcode_core::{CapabilitySpec, Result}; + +use crate::{ + PluginActiveSnapshot, PluginDescriptor, PluginManifest, descriptor::validate_descriptors, +}; + +/// 插件生命周期状态。 +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum PluginState { + Discovered, + Initialized, + Failed, +} + +/// 插件健康状态。 +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum PluginHealth { + Unknown, + Healthy, + Degraded, + Unavailable, +} + +/// 插件注册表条目。 +#[derive(Debug, Clone)] +pub struct PluginEntry { + pub manifest: PluginManifest, + pub state: PluginState, + pub health: PluginHealth, + pub failure_count: u32, + pub capabilities: Vec, + pub failure: Option, + pub warnings: Vec, + pub last_checked_at: Option, +} + +/// plugin-host 的最小注册表。 +/// +/// 第一阶段只负责三件事： +/// - 接收一组 descriptor 并构建 candidate snapshot +/// - 原子提交 candidate 成为 active snapshot +/// - 在提交失败或显式放弃时回滚 candidate +/// +/// 发现、进程管理和健康检查会在后续阶段继续补进来， +/// 但不应该重新把 registry 扩成旧 `core::plugin::registry` 那种生命周期大全。 +#[derive(Debug, Default)] +pub struct PluginRegistry { + state: RwLock, +} + +#[derive(Debug, Default)] +struct PluginRegistryState { + next_revision: u64, + active: Option, + candidate: Option, + plugins: BTreeMap, +} + +impl PluginRegistry { + /// 读取当前 active snapshot。 + pub fn active_snapshot(&self) -> Option { + self.state + .read() + .expect("plugin registry lock poisoned") + .active + .clone() + } + + /// 读取当前 candidate snapshot。 + pub fn candidate_snapshot(&self) -> Option { + self.state + .read() + .expect("plugin registry lock poisoned") + .candidate + .clone() + } + + /// 使用给定 descriptors 构建下一版 candidate snapshot。 + /// + /// candidate 只对后续 commit 生效，不影响当前 active turn。 + pub fn stage_candidate( + &self, + descriptors: impl IntoIterator, + ) -> Result { + let mut state = self.state.write().expect("plugin registry lock poisoned"); + state.next_revision = state.next_revision.saturating_add(1); + let descriptors = descriptors.into_iter().collect::>(); + validate_descriptors(&descriptors)?; + let snapshot = PluginActiveSnapshot::from_descriptors( + state.next_revision, + format!("plugin-snapshot-{}", state.next_revision), + &descriptors, + ); + state.candidate = Some(snapshot.clone()); + Ok(snapshot) + } + + /// 提交 candidate snapshot。 + /// + /// 成功后 active 被替换，candidate 被清空。 + pub fn commit_candidate(&self) -> Option { + let mut state = self.state.write().expect("plugin registry lock poisoned"); + let candidate = state.candidate.take()?; + state.active = Some(candidate.clone()); + Some(candidate) + } + + /// 丢弃当前 candidate snapshot。 + pub fn rollback_candidate(&self) -> Option { + self.state + .write() + .expect("plugin registry lock poisoned") + .candidate + .take() + } + + /// 直接替换 active snapshot。 + /// + /// 这个入口保留给测试和后续 reload 恢复流程使用， + /// 避免 host 在回放持久化状态时必须走 staging 再 commit。 + pub fn replace_active(&self, snapshot: PluginActiveSnapshot) { + let mut state = self.state.write().expect("plugin registry lock poisoned"); + state.next_revision = state.next_revision.max(snapshot.revision); + state.active = Some(snapshot); + state.candidate = None; + } + + /// 记录一个新发现的插件。 + pub fn record_discovered(&self, manifest: PluginManifest) { + self.upsert_plugin(PluginEntry { + manifest, + state: PluginState::Discovered, + health: PluginHealth::Unknown, + failure_count: 0, + capabilities: Vec::new(), + failure: None, + warnings: Vec::new(), + last_checked_at: None, + }); + } + + /// 记录插件初始化成功，将状态推进到 `Initialized`。 + pub fn record_initialized( + &self, + manifest: PluginManifest, + capabilities: Vec, + warnings: Vec, + ) { + self.upsert_plugin(PluginEntry { + manifest, + state: PluginState::Initialized, + health: PluginHealth::Healthy, + failure_count: 0, + capabilities, + failure: None, + warnings, + last_checked_at: None, + }); + } + + /// 记录插件初始化失败，将状态标记为 `Failed`。 + pub fn record_failed( + &self, + manifest: PluginManifest, + failure: impl Into, + capabilities: Vec, + warnings: Vec, + ) { + self.upsert_plugin(PluginEntry { + manifest, + state: PluginState::Failed, + health: PluginHealth::Unavailable, + failure_count: 1, + capabilities, + failure: Some(failure.into()), + warnings, + last_checked_at: None, + }); + } + + /// 按名称查询插件条目。 + pub fn get(&self, name: &str) -> Option { + self.state + .read() + .expect("plugin registry lock poisoned") + .plugins + .get(name) + .cloned() + } + + /// 获取所有插件条目的快照。 + pub fn snapshot(&self) -> Vec { + self.state + .read() + .expect("plugin registry lock poisoned") + .plugins + .values() + .cloned() + .collect() + } + + /// 原子替换整个插件生命周期快照。 + pub fn replace_snapshot(&self, entries: Vec) { + let mut state = self.state.write().expect("plugin registry lock poisoned"); + state.plugins.clear(); + for entry in entries { + state.plugins.insert(entry.manifest.name.clone(), entry); + } + } + + /// 记录插件运行时成功事件。 + pub fn record_runtime_success(&self, name: &str, checked_at: String) { + self.mutate_plugin(name, |entry| { + if entry.state == PluginState::Initialized { + entry.health = PluginHealth::Healthy; + } + entry.failure_count = 0; + entry.failure = None; + entry.last_checked_at = Some(checked_at); + }); + } + + /// 记录插件运行时失败事件。 + pub fn record_runtime_failure( + &self, + name: &str, + failure: impl Into, + checked_at: String, + ) { + let failure = failure.into(); + self.mutate_plugin(name, |entry| { + entry.failure_count = entry.failure_count.saturating_add(1); + entry.failure = Some(failure.clone()); + entry.last_checked_at = Some(checked_at); + if entry.state == PluginState::Initialized { + entry.health = if entry.failure_count >= 3 { + PluginHealth::Unavailable + } else { + PluginHealth::Degraded + }; + } else { + entry.health = PluginHealth::Unavailable; + } + }); + } + + /// 记录一次主动健康探测结果。 + pub fn record_health_probe( + &self, + name: &str, + health: PluginHealth, + failure: Option, + checked_at: String, + ) { + self.mutate_plugin(name, |entry| { + entry.health = health.clone(); + if matches!(health, PluginHealth::Healthy) { + entry.failure_count = 0; + entry.failure = None; + } else if let Some(message) = failure.clone() { + entry.failure = Some(message); + } + entry.last_checked_at = Some(checked_at.clone()); + }); + } + + fn upsert_plugin(&self, entry: PluginEntry) { + self.state + .write() + .expect("plugin registry lock poisoned") + .plugins + .insert(entry.manifest.name.clone(), entry); + } + + fn mutate_plugin(&self, name: &str, update: impl FnOnce(&mut PluginEntry)) { + if let Some(entry) = self + .state + .write() + .expect("plugin registry lock poisoned") + .plugins + .get_mut(name) + { + update(entry); + } + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; + + use super::PluginRegistry; + use crate::{PluginDescriptor, descriptor::PluginSourceKind}; + + fn capability(name: &str) -> CapabilitySpec { + CapabilitySpec { + name: name.into(), + kind: CapabilityKind::Tool, + description: format!("{name} capability"), + input_schema: Default::default(), + output_schema: Default::default(), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: false, + profiles: vec!["coding".to_string()], + tags: Vec::new(), + permissions: Vec::new(), + side_effect: SideEffect::None, + stability: Stability::Stable, + metadata: Default::default(), + max_result_inline_size: None, + } + } + + fn builtin(plugin_id: &str, tool_name: &str) -> PluginDescriptor { + let mut descriptor = PluginDescriptor::builtin(plugin_id, format!("{plugin_id} display")); + descriptor.source_kind = PluginSourceKind::Builtin; + descriptor.tools.push(capability(tool_name)); + descriptor + } + + #[test] + fn stage_candidate_does_not_replace_active_snapshot() { + let registry = PluginRegistry::default(); + + let staged = registry + .stage_candidate(vec![builtin("alpha", "tool.alpha")]) + .expect("candidate should stage"); + + assert_eq!(staged.revision, 1); + assert!(registry.active_snapshot().is_none()); + assert_eq!( + registry + .candidate_snapshot() + .expect("candidate should exist") + .plugin_ids, + vec!["alpha".to_string()] + ); + } + + #[test] + fn commit_candidate_promotes_snapshot_and_clears_candidate() { + let registry = PluginRegistry::default(); + registry + .stage_candidate(vec![builtin("alpha", "tool.alpha")]) + .expect("candidate should stage"); + + let committed = registry + .commit_candidate() + .expect("candidate should commit"); + + assert_eq!(committed.revision, 1); + assert!(registry.candidate_snapshot().is_none()); + assert_eq!( + registry + .active_snapshot() + .expect("active snapshot should exist") + .tools + .into_iter() + .map(|tool| tool.name.to_string()) + .collect::>(), + vec!["tool.alpha".to_string()] + ); + } + + #[test] + fn rollback_candidate_preserves_previous_active_snapshot() { + let registry = PluginRegistry::default(); + registry + .stage_candidate(vec![builtin("alpha", "tool.alpha")]) + .expect("first candidate should stage"); + let active = registry + .commit_candidate() + .expect("first candidate should commit"); + + registry + .stage_candidate(vec![builtin("beta", "tool.beta")]) + .expect("second candidate should stage"); + let rolled_back = registry + .rollback_candidate() + .expect("candidate should roll back"); + + assert_eq!(rolled_back.revision, 2); + assert_eq!( + registry + .active_snapshot() + .expect("active snapshot should be preserved") + .plugin_ids, + active.plugin_ids + ); + assert!(registry.candidate_snapshot().is_none()); + } + + #[test] + fn stage_candidate_rejects_invalid_descriptor_sets() { + let registry = PluginRegistry::default(); + let duplicate = vec![ + builtin("alpha", "tool.alpha"), + builtin("alpha", "tool.beta"), + ]; + + let error = registry + .stage_candidate(duplicate) + .expect_err("duplicate plugin ids should fail"); + + assert!(error.to_string().contains("plugin_id 'alpha' 重复")); + assert!(registry.active_snapshot().is_none()); + assert!(registry.candidate_snapshot().is_none()); + } +} diff --git a/crates/plugin-host/src/resource_provider.rs b/crates/plugin-host/src/resource_provider.rs new file mode 100644 index 00000000..214456c1 --- /dev/null +++ b/crates/plugin-host/src/resource_provider.rs @@ -0,0 +1,64 @@ +use astrcode_core::{Result, SessionId, TurnId}; +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +/// plugin-host owner 的资源读取请求上下文。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ResourceRequestContext { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub session_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub turn_id: Option, + #[serde(default)] + pub profile: Option, + #[serde(default)] + pub metadata: Value, +} + +/// plugin-host owner 的资源读取结果。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ResourceReadResult { + pub uri: String, + pub content: Value, + #[serde(default)] + pub metadata: Value, +} + +#[async_trait] +pub trait ResourceProvider: Send + Sync { + async fn read_resource( + &self, + uri: &str, + context: &ResourceRequestContext, + ) -> Result; +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::{ResourceReadResult, ResourceRequestContext}; + + #[test] + fn resource_context_defaults_to_empty_metadata() { + let context = ResourceRequestContext::default(); + + assert!(context.session_id.is_none()); + assert_eq!(context.metadata, serde_json::Value::Null); + } + + #[test] + fn resource_read_result_preserves_uri_and_content() { + let result = ResourceReadResult { + uri: "skill://review".to_string(), + content: json!({"name": "review"}), + metadata: serde_json::Value::Null, + }; + + assert_eq!(result.uri, "skill://review"); + assert_eq!(result.content["name"], "review"); + } +} diff --git a/crates/plugin-host/src/resources.rs b/crates/plugin-host/src/resources.rs new file mode 100644 index 00000000..90b3a634 --- /dev/null +++ b/crates/plugin-host/src/resources.rs @@ -0,0 +1,347 @@ +use std::collections::BTreeSet; + +use astrcode_core::{AstrError, Result, SkillSpec}; + +use crate::descriptor::{ + CommandDescriptor, PluginDescriptor, PromptDescriptor, ResourceDescriptor, SkillDescriptor, + ThemeDescriptor, validate_descriptors, +}; + +/// plugin-host 聚合出的统一资源目录。 +/// +/// 这一层先只做只读聚合，不负责发现源本身的 watch/reload。 +/// 后续 `resources_discover` hooks 接进来时，仍然可以把结果归并到这个 catalog。 +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ResourceCatalog { + pub plugin_ids: Vec, + pub resources: Vec, + pub commands: Vec, + pub themes: Vec, + pub prompts: Vec, + pub skills: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ResourceDiscoverReport { + pub descriptor_count: usize, + pub plugin_ids: Vec, + pub catalog: ResourceCatalog, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SkillCatalogBaseBuild { + pub base_skills: Vec, + pub plugin_skill_count: usize, + pub descriptor_skill_ids: Vec, +} + +pub fn resources_discover(descriptors: &[PluginDescriptor]) -> Result { + validate_descriptors(descriptors)?; + let mut catalog = ResourceCatalog::default(); + catalog.extend_from_descriptors(descriptors)?; + Ok(ResourceDiscoverReport { + descriptor_count: descriptors.len(), + plugin_ids: catalog.plugin_ids.clone(), + catalog, + }) +} + +pub fn build_skill_catalog_base( + mut builtin_skills: Vec, + mut plugin_skills: Vec, + resource_catalog: &ResourceCatalog, +) -> SkillCatalogBaseBuild { + let plugin_skill_count = plugin_skills.len(); + builtin_skills.append(&mut plugin_skills); + SkillCatalogBaseBuild { + base_skills: builtin_skills, + plugin_skill_count, + descriptor_skill_ids: resource_catalog + .skills + .iter() + .map(|skill| skill.skill_id.clone()) + .collect(), + } +} + +impl ResourceCatalog { + pub fn from_descriptors(descriptors: &[PluginDescriptor]) -> Self { + resources_discover(descriptors) + .expect("resource discovery should stay consistent for validated descriptors") + .catalog + } + + pub fn extend_from_descriptors(&mut self, descriptors: &[PluginDescriptor]) -> Result<()> { + let mut plugin_ids = self.plugin_ids.iter().cloned().collect::>(); + let mut resource_ids = self + .resources + .iter() + .map(|resource| resource.resource_id.clone()) + .collect::>(); + let mut command_ids = self + .commands + .iter() + .map(|command| command.command_id.clone()) + .collect::>(); + let mut theme_ids = self + .themes + .iter() + .map(|theme| theme.theme_id.clone()) + .collect::>(); + let mut prompt_ids = self + .prompts + .iter() + .map(|prompt| prompt.prompt_id.clone()) + .collect::>(); + let mut skill_ids = self + .skills + .iter() + .map(|skill| skill.skill_id.clone()) + .collect::>(); + + for descriptor in descriptors { + plugin_ids.insert(descriptor.plugin_id.clone()); + + for resource in &descriptor.resources { + if !resource_ids.insert(resource.resource_id.clone()) { + return Err(AstrError::Validation(format!( + "resource '{}' 在统一资源目录中重复注册", + resource.resource_id + ))); + } + self.resources.push(resource.clone()); + } + + for command in &descriptor.commands { + if !command_ids.insert(command.command_id.clone()) { + return Err(AstrError::Validation(format!( + "command '{}' 在统一资源目录中重复注册", + command.command_id + ))); + } + self.commands.push(command.clone()); + } + + for theme in &descriptor.themes { + if !theme_ids.insert(theme.theme_id.clone()) { + return Err(AstrError::Validation(format!( + "theme '{}' 在统一资源目录中重复注册", + theme.theme_id + ))); + } + self.themes.push(theme.clone()); + } + + for prompt in &descriptor.prompts { + if !prompt_ids.insert(prompt.prompt_id.clone()) { + return Err(AstrError::Validation(format!( + "prompt '{}' 在统一资源目录中重复注册", + prompt.prompt_id + ))); + } + self.prompts.push(prompt.clone()); + } + + for skill in &descriptor.skills { + if !skill_ids.insert(skill.skill_id.clone()) { + return Err(AstrError::Validation(format!( + "skill '{}' 在统一资源目录中重复注册", + skill.skill_id + ))); + } + self.skills.push(skill.clone()); + } + } + + self.plugin_ids = plugin_ids.into_iter().collect(); + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{SkillSource, SkillSpec}; + + use super::{ResourceCatalog, build_skill_catalog_base, resources_discover}; + use crate::descriptor::{ + CommandDescriptor, PluginDescriptor, PromptDescriptor, ResourceDescriptor, SkillDescriptor, + ThemeDescriptor, + }; + + #[test] + fn catalog_flattens_resource_like_contributions() { + let mut descriptor = PluginDescriptor::builtin("core-resources", "Core Resources"); + descriptor.resources.push(ResourceDescriptor { + resource_id: "resource.docs".to_string(), + kind: "docs".to_string(), + locator: ".codex/resources/docs".to_string(), + }); + descriptor.commands.push(CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + descriptor.themes.push(ThemeDescriptor { + theme_id: "graphite".to_string(), + }); + descriptor.prompts.push(PromptDescriptor { + prompt_id: "review".to_string(), + body: "Review the selected change".to_string(), + }); + descriptor.skills.push(SkillDescriptor { + skill_id: "skill.review".to_string(), + entry_ref: ".codex/skills/review/SKILL.md".to_string(), + }); + + let catalog = ResourceCatalog::from_descriptors(&[descriptor.clone()]); + + assert_eq!(catalog.plugin_ids, vec![descriptor.plugin_id]); + assert_eq!(catalog.resources.len(), 1); + assert_eq!(catalog.commands.len(), 1); + assert_eq!(catalog.themes.len(), 1); + assert_eq!(catalog.prompts.len(), 1); + assert_eq!(catalog.skills.len(), 1); + } + + #[test] + fn catalog_can_merge_multiple_descriptor_batches() { + let mut builtin = PluginDescriptor::builtin("core-resources", "Core Resources"); + builtin.commands.push(CommandDescriptor { + command_id: "review".to_string(), + entry_ref: ".codex/commands/review.md".to_string(), + }); + + let mut discovered = PluginDescriptor::builtin("project-prompts", "Project Prompts"); + discovered.source_ref = ".codex".to_string(); + discovered.prompts.push(PromptDescriptor { + prompt_id: "prompt.review".to_string(), + body: "Review the selected change".to_string(), + }); + discovered.skills.push(SkillDescriptor { + skill_id: "skill.review".to_string(), + entry_ref: ".codex/skills/review/SKILL.md".to_string(), + }); + + let mut catalog = ResourceCatalog::default(); + catalog + .extend_from_descriptors(&[builtin.clone()]) + .expect("builtin batch should merge"); + catalog + .extend_from_descriptors(&[discovered.clone()]) + .expect("discovered batch should merge"); + + assert_eq!( + catalog.plugin_ids, + vec![builtin.plugin_id.clone(), discovered.plugin_id.clone()] + ); + assert_eq!(catalog.commands.len(), 1); + assert_eq!(catalog.prompts.len(), 1); + assert_eq!(catalog.skills.len(), 1); + } + + #[test] + fn catalog_rejects_duplicate_resource_like_ids_across_batches() { + let mut first = PluginDescriptor::builtin("first", "First"); + first.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "a".to_string(), + }); + + let mut second = PluginDescriptor::builtin("second", "Second"); + second.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "b".to_string(), + }); + + let mut catalog = ResourceCatalog::default(); + catalog + .extend_from_descriptors(&[first]) + .expect("first batch should merge"); + let error = catalog + .extend_from_descriptors(&[second]) + .expect_err("duplicate prompt ids should fail"); + assert!(error.to_string().contains("prompt 'prompt.shared'")); + } + + #[test] + fn resources_discover_reports_single_catalog_owner() { + let mut descriptor = PluginDescriptor::builtin("project-resources", "Project Resources"); + descriptor.commands.push(CommandDescriptor { + command_id: "apply-change".to_string(), + entry_ref: ".codex/commands/apply-change.md".to_string(), + }); + descriptor.prompts.push(PromptDescriptor { + prompt_id: "prompt.apply-change".to_string(), + body: "Apply the selected OpenSpec change".to_string(), + }); + descriptor.skills.push(SkillDescriptor { + skill_id: "openspec-apply-change".to_string(), + entry_ref: ".codex/skills/openspec-apply-change/SKILL.md".to_string(), + }); + + let report = resources_discover(&[descriptor]).expect("resource discovery should succeed"); + + assert_eq!(report.descriptor_count, 1); + assert_eq!(report.plugin_ids, vec!["project-resources".to_string()]); + assert_eq!(report.catalog.commands.len(), 1); + assert_eq!(report.catalog.prompts.len(), 1); + assert_eq!(report.catalog.skills.len(), 1); + } + + #[test] + fn resources_discover_rejects_duplicate_prompt_ids_before_reload_commit() { + let mut first = PluginDescriptor::builtin("first", "First"); + first.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "first".to_string(), + }); + let mut second = PluginDescriptor::builtin("second", "Second"); + second.prompts.push(PromptDescriptor { + prompt_id: "prompt.shared".to_string(), + body: "second".to_string(), + }); + + let error = + resources_discover(&[first, second]).expect_err("duplicate prompt ids should fail"); + + assert!(error.to_string().contains("prompt 'prompt.shared'")); + } + + #[test] + fn skill_catalog_base_build_keeps_descriptor_skill_ids_under_resource_owner() { + let builtin = SkillSpec { + id: "builtin-skill".to_string(), + name: "builtin-skill".to_string(), + description: "builtin".to_string(), + guide: "guide".to_string(), + skill_root: None, + asset_files: Vec::new(), + allowed_tools: Vec::new(), + source: SkillSource::Builtin, + }; + let plugin = SkillSpec { + id: "plugin-skill".to_string(), + name: "plugin-skill".to_string(), + description: "plugin".to_string(), + guide: "guide".to_string(), + skill_root: None, + asset_files: Vec::new(), + allowed_tools: Vec::new(), + source: SkillSource::Plugin, + }; + let mut descriptor = PluginDescriptor::builtin("plugin-resources", "Plugin Resources"); + descriptor.skills.push(SkillDescriptor { + skill_id: "descriptor-skill".to_string(), + entry_ref: ".codex/skills/descriptor/SKILL.md".to_string(), + }); + let catalog = ResourceCatalog::from_descriptors(&[descriptor]); + + let build = build_skill_catalog_base(vec![builtin], vec![plugin], &catalog); + + assert_eq!(build.base_skills.len(), 2); + assert_eq!(build.plugin_skill_count, 1); + assert_eq!( + build.descriptor_skill_ids, + vec!["descriptor-skill".to_string()] + ); + } +} diff --git a/crates/plugin-host/src/snapshot.rs b/crates/plugin-host/src/snapshot.rs new file mode 100644 index 00000000..d31b6e0e --- /dev/null +++ b/crates/plugin-host/src/snapshot.rs @@ -0,0 +1,79 @@ +use astrcode_core::{CapabilitySpec, GovernanceModeSpec}; + +use crate::descriptor::{ + CommandDescriptor, HookDescriptor, PluginDescriptor, PromptDescriptor, ProviderDescriptor, + ResourceDescriptor, SkillDescriptor, ThemeDescriptor, +}; + +#[derive(Debug, Clone, PartialEq, Default)] +pub struct PluginActiveSnapshot { + pub snapshot_id: String, + pub revision: u64, + pub plugin_ids: Vec, + pub tools: Vec, + pub hooks: Vec, + pub providers: Vec, + pub resources: Vec, + pub commands: Vec, + pub themes: Vec, + pub prompts: Vec, + pub skills: Vec, + pub modes: Vec, +} + +impl PluginActiveSnapshot { + pub fn from_descriptors( + revision: u64, + snapshot_id: impl Into, + descriptors: &[PluginDescriptor], + ) -> Self { + let mut snapshot = Self { + snapshot_id: snapshot_id.into(), + revision, + plugin_ids: descriptors + .iter() + .map(|item| item.plugin_id.clone()) + .collect(), + ..Self::default() + }; + + for descriptor in descriptors { + snapshot.tools.extend(descriptor.tools.clone()); + snapshot.hooks.extend(descriptor.hooks.clone()); + snapshot.providers.extend(descriptor.providers.clone()); + snapshot.resources.extend(descriptor.resources.clone()); + snapshot.commands.extend(descriptor.commands.clone()); + snapshot.themes.extend(descriptor.themes.clone()); + snapshot.prompts.extend(descriptor.prompts.clone()); + snapshot.skills.extend(descriptor.skills.clone()); + snapshot.modes.extend(descriptor.modes.clone()); + } + + snapshot + } +} + +#[cfg(test)] +mod tests { + use crate::{ + descriptor::{HookDescriptor, PluginDescriptor}, + snapshot::PluginActiveSnapshot, + }; + + #[test] + fn snapshot_flattens_plugin_contributions() { + let mut descriptor = PluginDescriptor::builtin("core-tools", "Core Tools"); + descriptor.hooks.push(HookDescriptor { + hook_id: "turn-start".to_string(), + event: "turn_start".to_string(), + }); + + let snapshot = + PluginActiveSnapshot::from_descriptors(7, "snapshot-7", &[descriptor.clone()]); + + assert_eq!(snapshot.revision, 7); + assert_eq!(snapshot.snapshot_id, "snapshot-7"); + assert_eq!(snapshot.plugin_ids, vec![descriptor.plugin_id]); + assert_eq!(snapshot.hooks.len(), 1); + } +} diff --git a/crates/plugin-host/src/tools.rs b/crates/plugin-host/src/tools.rs new file mode 100644 index 00000000..2903c140 --- /dev/null +++ b/crates/plugin-host/src/tools.rs @@ -0,0 +1,169 @@ +use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; + +use crate::PluginDescriptor; + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct ToolContributionCatalog { + pub tool_names: Vec, +} + +pub fn builtin_tools_descriptor( + plugin_id: impl Into, + display_name: impl Into, + tools: Vec, +) -> PluginDescriptor { + let mut descriptor = PluginDescriptor::builtin(plugin_id, display_name); + descriptor.tools = tools; + descriptor +} + +pub fn builtin_collaboration_tools_descriptor() -> PluginDescriptor { + builtin_tools_descriptor( + "builtin-collaboration-tools", + "Builtin Collaboration Tools", + vec![ + host_session_tool( + "spawn_agent", + "Spawn a child session and record parent/child lineage through host-session.", + ), + host_session_tool( + "send_to_child", + "Deliver an input from a parent session to a direct child session.", + ), + host_session_tool( + "send_to_parent", + "Deliver a typed result from a child session back to its direct parent.", + ), + host_session_tool( + "observe_subtree", + "Read the host-session collaboration subtree projection.", + ), + host_session_tool( + "terminate_subtree", + "Terminate a session subtree through the host-session owner.", + ), + ], + ) +} + +fn host_session_tool(name: &str, description: &str) -> CapabilitySpec { + CapabilitySpec { + name: name.into(), + kind: CapabilityKind::Tool, + description: description.to_string(), + input_schema: Default::default(), + output_schema: Default::default(), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: true, + profiles: vec!["coding".to_string()], + tags: vec!["collaboration".to_string(), "host-session".to_string()], + permissions: Vec::new(), + side_effect: SideEffect::Workspace, + stability: Stability::Experimental, + metadata: Default::default(), + max_result_inline_size: None, + } +} + +pub fn tool_contribution_catalog(descriptors: &[PluginDescriptor]) -> ToolContributionCatalog { + ToolContributionCatalog { + tool_names: descriptors + .iter() + .flat_map(|descriptor| descriptor.tools.iter()) + .map(|tool| tool.name.to_string()) + .collect(), + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; + + use super::{ + builtin_collaboration_tools_descriptor, builtin_tools_descriptor, tool_contribution_catalog, + }; + + fn capability(name: &str) -> CapabilitySpec { + CapabilitySpec { + name: name.into(), + kind: CapabilityKind::Tool, + description: format!("{name} capability"), + input_schema: Default::default(), + output_schema: Default::default(), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: false, + profiles: vec!["coding".to_string()], + tags: Vec::new(), + permissions: Vec::new(), + side_effect: SideEffect::None, + stability: Stability::Stable, + metadata: Default::default(), + max_result_inline_size: None, + } + } + + #[test] + fn builtin_tools_are_represented_as_plugin_descriptor_tools() { + let descriptor = builtin_tools_descriptor( + "builtin-core-tools", + "Builtin Core Tools", + vec![capability("readFile"), capability("writeFile")], + ); + + assert_eq!(descriptor.plugin_id, "builtin-core-tools"); + assert_eq!( + descriptor + .tools + .iter() + .map(|tool| tool.name.to_string()) + .collect::>(), + vec!["readFile".to_string(), "writeFile".to_string()] + ); + } + + #[test] + fn tool_catalog_flattens_mcp_and_builtin_descriptor_tools() { + let builtin = builtin_tools_descriptor( + "builtin-core-tools", + "Builtin Core Tools", + vec![capability("readFile")], + ); + let mcp = builtin_tools_descriptor("mcp-tools", "MCP Tools", vec![capability("mcp.echo")]); + + let catalog = tool_contribution_catalog(&[builtin, mcp]); + + assert_eq!( + catalog.tool_names, + vec!["readFile".to_string(), "mcp.echo".to_string()] + ); + } + + #[test] + fn collaboration_entrypoints_are_declared_as_builtin_plugin_tools() { + let descriptor = builtin_collaboration_tools_descriptor(); + + assert_eq!(descriptor.plugin_id, "builtin-collaboration-tools"); + assert_eq!( + descriptor + .tools + .iter() + .map(|tool| tool.name.to_string()) + .collect::>(), + vec![ + "spawn_agent".to_string(), + "send_to_child".to_string(), + "send_to_parent".to_string(), + "observe_subtree".to_string(), + "terminate_subtree".to_string(), + ] + ); + assert!( + descriptor + .tools + .iter() + .all(|tool| tool.tags.iter().any(|tag| tag == "host-session")) + ); + } +} diff --git a/crates/plugin-host/src/transport.rs b/crates/plugin-host/src/transport.rs new file mode 100644 index 00000000..ba6e0f60 --- /dev/null +++ b/crates/plugin-host/src/transport.rs @@ -0,0 +1,506 @@ +use std::{fmt, pin::Pin}; + +use astrcode_core::{AstrError, Result}; +use astrcode_protocol::plugin::{ + EventMessage, EventPhase, InitializeMessage, InitializeResultData, InvokeMessage, + PluginMessage, ResultMessage, +}; +use tokio::{ + io::{AsyncBufRead, AsyncBufReadExt, AsyncWrite, AsyncWriteExt, BufReader}, + process::{ChildStdin, ChildStdout}, + sync::Mutex, +}; + +/// `plugin-host` 的最小 stdio 协议传输。 +/// +/// 它只负责 line-delimited JSON 消息收发，不承担 peer/read-loop。 +/// 这样可以先把真实 transport owner 接到新边界里，再逐步补更复杂的并发协议语义。 +pub struct PluginStdioTransport { + writer: Mutex>>, + reader: Mutex>>, +} + +impl fmt::Debug for PluginStdioTransport { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PluginStdioTransport") + .finish_non_exhaustive() + } +} + +impl PluginStdioTransport { + pub fn from_child(stdin: ChildStdin, stdout: ChildStdout) -> Self { + Self::from_streams(stdin, BufReader::new(stdout)) + } + + pub fn from_streams(writer: W, reader: R) -> Self + where + W: AsyncWrite + Send + 'static, + R: AsyncBufRead + Send + 'static, + { + Self { + writer: Mutex::new(Box::pin(writer)), + reader: Mutex::new(Box::pin(reader)), + } + } + + pub async fn initialize(&self, request: &InitializeMessage) -> Result { + self.send_message(&PluginMessage::Initialize(request.clone())) + .await?; + let response = self + .recv_result_message(&request.id, Some("initialize")) + .await?; + if !response.success { + return Err(result_message_error(response)); + } + response.parse_output().map_err(|error| { + AstrError::Validation(format!("failed to parse initialize result: {error}")) + }) + } + + pub async fn invoke_unary(&self, request: &InvokeMessage) -> Result { + self.send_message(&PluginMessage::Invoke(request.clone())) + .await?; + self.recv_result_message(&request.id, None).await + } + + pub async fn invoke_stream(&self, request: &InvokeMessage) -> Result> { + self.send_message(&PluginMessage::Invoke(request.clone())) + .await?; + self.recv_stream_events(&request.id).await + } + + async fn send_message(&self, message: &PluginMessage) -> Result<()> { + let payload = serde_json::to_string(message).map_err(|error| { + AstrError::Validation(format!("failed to serialize plugin message: {error}")) + })?; + let mut writer = self.writer.lock().await; + writer + .write_all(payload.as_bytes()) + .await + .map_err(|error| AstrError::io("failed to write plugin payload", error))?; + writer + .write_all(b"\n") + .await + .map_err(|error| AstrError::io("failed to terminate plugin payload", error))?; + writer + .flush() + .await + .map_err(|error| AstrError::io("failed to flush plugin payload", error)) + } + + async fn recv_message(&self) -> Result> { + let mut reader = self.reader.lock().await; + let mut line = String::new(); + let bytes = reader + .read_line(&mut line) + .await + .map_err(|error| AstrError::io("failed to read plugin payload", error))?; + if bytes == 0 { + return Ok(None); + } + let payload = line.trim_end_matches(['\r', '\n']); + serde_json::from_str(payload).map(Some).map_err(|error| { + AstrError::Validation(format!("failed to decode plugin payload: {error}")) + }) + } + + async fn recv_result_message( + &self, + request_id: &str, + expected_kind: Option<&str>, + ) -> Result { + let message = self.recv_message().await?.ok_or_else(|| { + AstrError::Internal(format!( + "plugin transport closed before result for request '{request_id}'" + )) + })?; + match message { + PluginMessage::Result(result) if result.id == request_id => { + if let Some(kind) = expected_kind { + if result.kind.as_deref() != Some(kind) { + return Err(AstrError::Internal(format!( + "expected result kind '{kind}' for request '{request_id}', got {:?}", + result.kind + ))); + } + } + Ok(result) + }, + PluginMessage::Event(event) if event.id == request_id => { + Err(AstrError::Internal(format!( + "received event phase {:?} for unary request '{request_id}'", + event.phase + ))) + }, + PluginMessage::Result(result) => Err(AstrError::Internal(format!( + "received result for unexpected request '{}' while waiting for '{}'", + result.id, request_id + ))), + PluginMessage::Event(event) => Err(AstrError::Internal(format!( + "received event for unexpected request '{}' while waiting for '{}'", + event.id, request_id + ))), + other => Err(AstrError::Internal(format!( + "received unexpected plugin message {:?} while waiting for result '{}'", + other, request_id + ))), + } + } + + async fn recv_stream_events(&self, request_id: &str) -> Result> { + let mut events = Vec::new(); + loop { + let message = self.recv_message().await?.ok_or_else(|| { + AstrError::Internal(format!( + "plugin transport closed before stream request '{request_id}' completed" + )) + })?; + match message { + PluginMessage::Event(event) if event.id == request_id => { + let terminal = + matches!(event.phase, EventPhase::Completed | EventPhase::Failed); + events.push(event); + if terminal { + return Ok(events); + } + }, + PluginMessage::Result(result) if result.id == request_id => { + return Err(AstrError::Internal(format!( + "received unary result for streaming request '{request_id}'" + ))); + }, + PluginMessage::Result(result) => { + return Err(AstrError::Internal(format!( + "received result for unexpected request '{}' while waiting for stream '{}'", + result.id, request_id + ))); + }, + PluginMessage::Event(event) => { + return Err(AstrError::Internal(format!( + "received event for unexpected request '{}' while waiting for stream '{}'", + event.id, request_id + ))); + }, + other => { + return Err(AstrError::Internal(format!( + "received unexpected plugin message {:?} while waiting for stream '{}'", + other, request_id + ))); + }, + } + } + } +} + +fn result_message_error(result: ResultMessage) -> AstrError { + let message = result + .error + .map(|error| error.message) + .unwrap_or_else(|| "plugin invocation failed".to_string()); + AstrError::Validation(message) +} + +#[cfg(test)] +mod tests { + use astrcode_protocol::plugin::{ + CallerRef, CapabilityWireDescriptor, ErrorPayload, EventMessage, EventPhase, + HandlerDescriptor, InitializeMessage, InitializeResultData, InvokeMessage, PeerDescriptor, + PeerRole, PluginMessage, ProfileDescriptor, ResultMessage, TriggerDescriptor, + }; + use serde_json::json; + use tokio::io::{BufReader, duplex}; + + use super::PluginStdioTransport; + + fn sample_initialize() -> InitializeMessage { + InitializeMessage { + id: "init-1".to_string(), + protocol_version: "5".to_string(), + supported_protocol_versions: vec!["5".to_string()], + peer: PeerDescriptor { + id: "host-1".to_string(), + name: "plugin-host".to_string(), + role: PeerRole::Supervisor, + version: "0.1.0".to_string(), + supported_profiles: vec!["coding".to_string()], + metadata: json!({ "owner": "plugin-host" }), + }, + capabilities: vec![ + CapabilityWireDescriptor::builder( + "tool.search", + astrcode_core::CapabilityKind::tool(), + ) + .description("search workspace") + .input_schema(json!({ "type": "object" })) + .output_schema(json!({ "type": "object" })) + .build() + .expect("capability should build"), + ], + handlers: vec![HandlerDescriptor { + id: "observe-tool-call".to_string(), + trigger: TriggerDescriptor { + kind: "event".to_string(), + value: "tool_call".to_string(), + metadata: json!({ "source": "transport-test" }), + }, + input_schema: json!({ "type": "object" }), + profiles: vec!["coding".to_string()], + filters: Vec::new(), + permissions: Vec::new(), + }], + profiles: vec![ProfileDescriptor { + name: "coding".to_string(), + version: "1".to_string(), + description: "coding profile".to_string(), + context_schema: serde_json::Value::Null, + metadata: serde_json::Value::Null, + }], + metadata: json!({ "test": true }), + } + } + + fn sample_invoke(stream: bool) -> InvokeMessage { + InvokeMessage { + id: "req-1".to_string(), + capability: if stream { + "tool.patch_stream".to_string() + } else { + "tool.search".to_string() + }, + input: json!({ "query": "plugin-host" }), + context: astrcode_protocol::plugin::InvocationContext { + request_id: if stream { + "req-1-stream".to_string() + } else { + "req-1-unary".to_string() + }, + trace_id: None, + session_id: Some("session-1".to_string()), + caller: Some(CallerRef { + id: "test".to_string(), + role: "integration-test".to_string(), + metadata: serde_json::Value::Null, + }), + workspace: None, + deadline_ms: None, + budget: None, + profile: "coding".to_string(), + profile_context: serde_json::Value::Null, + metadata: serde_json::Value::Null, + }, + stream, + } + } + + async fn write_message(writer: &mut (impl AsyncWrite + Unpin), message: &PluginMessage) { + let payload = serde_json::to_string(message).expect("message should serialize"); + writer + .write_all(payload.as_bytes()) + .await + .expect("write should succeed"); + writer + .write_all(b"\n") + .await + .expect("newline should succeed"); + writer.flush().await.expect("flush should succeed"); + } + + async fn read_message(reader: &mut (impl AsyncBufRead + Unpin)) -> PluginMessage { + let mut line = String::new(); + reader + .read_line(&mut line) + .await + .expect("read should succeed"); + serde_json::from_str(line.trim_end()).expect("message should deserialize") + } + + use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncWrite, AsyncWriteExt}; + + #[tokio::test] + async fn stdio_transport_initializes_against_real_line_protocol() { + let (client_side, server_side) = duplex(4096); + let (client_reader, client_writer) = tokio::io::split(client_side); + let (server_reader, server_writer) = tokio::io::split(server_side); + let transport = + PluginStdioTransport::from_streams(client_writer, BufReader::new(client_reader)); + + let server = tokio::spawn(async move { + let mut reader = BufReader::new(server_reader); + let mut writer = server_writer; + let message = read_message(&mut reader).await; + let PluginMessage::Initialize(request) = message else { + panic!("expected initialize message"); + }; + assert_eq!(request.id, "init-1"); + write_message( + &mut writer, + &PluginMessage::Result(ResultMessage { + id: request.id, + kind: Some("initialize".to_string()), + success: true, + output: serde_json::to_value(InitializeResultData { + protocol_version: "5".to_string(), + peer: PeerDescriptor { + id: "worker-1".to_string(), + name: "fixture".to_string(), + role: PeerRole::Worker, + version: "0.1.0".to_string(), + supported_profiles: vec!["coding".to_string()], + metadata: json!({ "fixture": true }), + }, + capabilities: Vec::new(), + handlers: Vec::new(), + profiles: vec![ProfileDescriptor { + name: "coding".to_string(), + version: "1".to_string(), + description: "coding".to_string(), + context_schema: serde_json::Value::Null, + metadata: serde_json::Value::Null, + }], + skills: Vec::new(), + modes: Vec::new(), + metadata: serde_json::Value::Null, + }) + .expect("initialize result should serialize"), + error: None, + metadata: serde_json::Value::Null, + }), + ) + .await; + }); + + let negotiated = transport + .initialize(&sample_initialize()) + .await + .expect("initialize should succeed"); + assert_eq!(negotiated.peer.id, "worker-1"); + server.await.expect("server should finish"); + } + + #[tokio::test] + async fn stdio_transport_invokes_unary_request() { + let (client_side, server_side) = duplex(4096); + let (client_reader, client_writer) = tokio::io::split(client_side); + let (server_reader, server_writer) = tokio::io::split(server_side); + let transport = + PluginStdioTransport::from_streams(client_writer, BufReader::new(client_reader)); + + let server = tokio::spawn(async move { + let mut reader = BufReader::new(server_reader); + let mut writer = server_writer; + let message = read_message(&mut reader).await; + let PluginMessage::Invoke(request) = message else { + panic!("expected invoke message"); + }; + assert!(!request.stream); + write_message( + &mut writer, + &PluginMessage::Result(ResultMessage { + id: request.id, + kind: Some("tool_result".to_string()), + success: true, + output: json!({ "matches": 9 }), + error: None, + metadata: json!({ "transport": "stdio" }), + }), + ) + .await; + }); + + let result = transport + .invoke_unary(&sample_invoke(false)) + .await + .expect("unary invoke should succeed"); + assert!(result.success); + assert_eq!(result.output, json!({ "matches": 9 })); + server.await.expect("server should finish"); + } + + #[tokio::test] + async fn stdio_transport_collects_stream_events_until_terminal() { + let (client_side, server_side) = duplex(4096); + let (client_reader, client_writer) = tokio::io::split(client_side); + let (server_reader, server_writer) = tokio::io::split(server_side); + let transport = + PluginStdioTransport::from_streams(client_writer, BufReader::new(client_reader)); + + let server = tokio::spawn(async move { + let mut reader = BufReader::new(server_reader); + let mut writer = server_writer; + let message = read_message(&mut reader).await; + let PluginMessage::Invoke(request) = message else { + panic!("expected invoke message"); + }; + assert!(request.stream); + for (seq, phase, payload) in [ + (0, EventPhase::Started, json!({ "status": "started" })), + (1, EventPhase::Delta, json!({ "chunk": 1 })), + (2, EventPhase::Completed, json!({ "status": "done" })), + ] { + write_message( + &mut writer, + &PluginMessage::Event(EventMessage { + id: request.id.clone(), + phase, + event: "artifact.patch".to_string(), + payload, + seq, + error: None, + }), + ) + .await; + } + }); + + let events = transport + .invoke_stream(&sample_invoke(true)) + .await + .expect("stream invoke should succeed"); + assert_eq!(events.len(), 3); + assert_eq!(events[1].phase, EventPhase::Delta); + assert_eq!(events[2].phase, EventPhase::Completed); + server.await.expect("server should finish"); + } + + #[tokio::test] + async fn stdio_transport_rejects_mismatched_request_ids() { + let (client_side, server_side) = duplex(4096); + let (client_reader, client_writer) = tokio::io::split(client_side); + let (server_reader, server_writer) = tokio::io::split(server_side); + let transport = + PluginStdioTransport::from_streams(client_writer, BufReader::new(client_reader)); + + let server = tokio::spawn(async move { + let mut reader = BufReader::new(server_reader); + let mut writer = server_writer; + let message = read_message(&mut reader).await; + let PluginMessage::Invoke(_) = message else { + panic!("expected invoke message"); + }; + write_message( + &mut writer, + &PluginMessage::Result(ResultMessage { + id: "other-request".to_string(), + kind: Some("tool_result".to_string()), + success: false, + output: serde_json::Value::Null, + error: Some(ErrorPayload { + code: "unexpected".to_string(), + message: "wrong request".to_string(), + details: serde_json::Value::Null, + retriable: false, + }), + metadata: serde_json::Value::Null, + }), + ) + .await; + }); + + let error = transport + .invoke_unary(&sample_invoke(false)) + .await + .expect_err("mismatched request id should fail"); + assert!(error.to_string().contains("unexpected request")); + server.await.expect("server should finish"); + } +} diff --git a/crates/plugin/src/bin/fixture_worker.rs b/crates/plugin/src/bin/fixture_worker.rs deleted file mode 100644 index 840437fc..00000000 --- a/crates/plugin/src/bin/fixture_worker.rs +++ /dev/null @@ -1,142 +0,0 @@ -use std::time::Duration; - -use astrcode_core::{ - AstrError, CancelToken, CapabilityKind, CapabilitySpec, InvocationMode, Result, SideEffect, -}; -use astrcode_plugin::{CapabilityHandler, CapabilityRouter, EventEmitter, Worker}; -use astrcode_protocol::plugin::{InvocationContext, PeerDescriptor, PeerRole}; -use async_trait::async_trait; -use serde_json::{Value, json}; -use tokio::time::sleep; - -struct EchoHandler; - -#[async_trait] -impl CapabilityHandler for EchoHandler { - fn capability_spec(&self) -> CapabilitySpec { - CapabilitySpec::builder("tool.echo", CapabilityKind::Tool) - .description("Echo the input") - .schema(json!({ "type": "object" }), json!({ "type": "object" })) - .profiles(["coding"]) - .tags(["fixture"]) - .build() - .expect("fixture capability spec should build") - } - - async fn invoke( - &self, - input: Value, - _context: InvocationContext, - _events: EventEmitter, - _cancel: CancelToken, - ) -> Result { - Ok(input) - } -} - -struct PatchStreamHandler; - -#[async_trait] -impl CapabilityHandler for PatchStreamHandler { - fn capability_spec(&self) -> CapabilitySpec { - CapabilitySpec::builder("tool.patch_stream", CapabilityKind::Tool) - .description("Emit patch deltas") - .schema(json!({ "type": "object" }), json!({ "type": "object" })) - .invocation_mode(InvocationMode::Streaming) - .profiles(["coding"]) - .tags(["fixture", "stream"]) - .side_effect(SideEffect::Workspace) - .build() - .expect("fixture capability spec should build") - } - - async fn invoke( - &self, - input: Value, - _context: InvocationContext, - events: EventEmitter, - cancel: CancelToken, - ) -> Result { - let path = input - .get("path") - .and_then(Value::as_str) - .unwrap_or("src/main.rs"); - for chunk in 0..3_u64 { - if cancel.is_cancelled() { - return Err(AstrError::Cancelled); - } - events - .delta( - "artifact.patch", - json!({ - "path": path, - "chunk": chunk, - "patch": format!("@@ chunk {chunk} @@"), - }), - ) - .await?; - sleep(Duration::from_millis(40)).await; - } - - if cancel.is_cancelled() { - return Err(AstrError::Cancelled); - } - - Ok(json!({ - "path": path, - "chunks": 3, - "status": "applied" - })) - } -} - -struct DelayedEchoHandler; - -#[async_trait] -impl CapabilityHandler for DelayedEchoHandler { - fn capability_spec(&self) -> CapabilitySpec { - CapabilitySpec::builder("tool.delayed_echo", CapabilityKind::Tool) - .description("Delay before returning") - .schema(json!({ "type": "object" }), json!({ "type": "object" })) - .profiles(["coding"]) - .tags(["fixture", "delayed"]) - .build() - .expect("fixture capability spec should build") - } - - async fn invoke( - &self, - input: Value, - _context: InvocationContext, - _events: EventEmitter, - cancel: CancelToken, - ) -> Result { - sleep(Duration::from_millis(300)).await; - if cancel.is_cancelled() { - return Err(AstrError::Cancelled); - } - Ok(input) - } -} - -#[tokio::main] -async fn main() -> Result<()> { - let mut router = CapabilityRouter::default(); - router.register(EchoHandler)?; - router.register(PatchStreamHandler)?; - router.register(DelayedEchoHandler)?; - - let worker = Worker::from_stdio( - PeerDescriptor { - id: "fixture-worker".to_string(), - name: "fixture-worker".to_string(), - role: PeerRole::Worker, - version: env!("CARGO_PKG_VERSION").to_string(), - supported_profiles: vec!["coding".to_string()], - metadata: json!({ "fixture": true }), - }, - router, - None, - )?; - worker.run().await -} diff --git a/crates/plugin/src/capability_mapping.rs b/crates/plugin/src/capability_mapping.rs deleted file mode 100644 index 35b595b6..00000000 --- a/crates/plugin/src/capability_mapping.rs +++ /dev/null @@ -1,66 +0,0 @@ -//! 插件协议描述符与宿主内部 `CapabilitySpec` 的边界映射。 -//! -//! Why: `protocol` crate 只承载 wire types，不负责宿主内部模型转换。 -//! `CapabilitySpec` 是宿主内部语义真相，`CapabilityWireDescriptor` -//! 只是握手/传输使用的 DTO 名称。 - -use astrcode_core::{CapabilitySpec, CapabilitySpecBuildError}; -use astrcode_protocol::plugin::CapabilityWireDescriptor; -use thiserror::Error; - -#[derive(Debug, Error)] -pub enum CapabilityMappingError { - #[error("invalid capability payload: {0}")] - InvalidCapability(#[from] CapabilitySpecBuildError), -} - -pub fn wire_descriptor_to_spec( - descriptor: &CapabilityWireDescriptor, -) -> std::result::Result { - descriptor.validate()?; - Ok(descriptor.clone()) -} - -pub fn spec_to_wire_descriptor( - spec: &CapabilitySpec, -) -> std::result::Result { - spec.validate()?; - Ok(spec.clone()) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; - use serde_json::json; - - use super::{spec_to_wire_descriptor, wire_descriptor_to_spec}; - - fn sample_spec() -> CapabilitySpec { - CapabilitySpec { - name: "tool.echo".into(), - kind: CapabilityKind::Tool, - description: "echo".to_string(), - input_schema: json!({ "type": "object" }), - output_schema: json!({ "type": "object" }), - invocation_mode: InvocationMode::Unary, - concurrency_safe: true, - compact_clearable: true, - profiles: vec!["coding".to_string()], - tags: vec!["builtin".to_string()], - permissions: vec![], - side_effect: SideEffect::None, - stability: Stability::Stable, - metadata: json!({ "prompt": { "summary": "x" } }), - max_result_inline_size: Some(1024), - } - } - - #[test] - fn round_trip_between_spec_and_descriptor() { - let spec = sample_spec(); - let descriptor = spec_to_wire_descriptor(&spec).expect("spec->wire descriptor should pass"); - let mapped = - wire_descriptor_to_spec(&descriptor).expect("wire descriptor->spec should pass"); - assert_eq!(mapped, spec); - } -} diff --git a/crates/plugin/src/capability_router.rs b/crates/plugin/src/capability_router.rs deleted file mode 100644 index 6892b7eb..00000000 --- a/crates/plugin/src/capability_router.rs +++ /dev/null @@ -1,308 +0,0 @@ -//! 能力路由与权限检查。 -//! -//! 本模块负责将能力调用请求路由到对应的处理器，并在执行前进行权限验证。 -//! -//! ## 核心组件 -//! -//! - `CapabilityHandler`: 能力处理器的 trait，每个实现代表一个可被调用的能力 -//! - `PermissionChecker`: 权限检查 trait，决定是否允许某个能力在特定上下文中执行 -//! - `CapabilityRouter`: 能力路由器，维护能力注册表并执行路由+权限检查 -//! -//! ## 调用流程 -//! -//! 1. 调用方通过 `router.invoke(capability_name, ...)` 发起调用 -//! 2. 路由器查找对应的 handler -//! 3. 验证 profile 兼容性（能力的 profiles 必须包含上下文的 profile） -//! 4. 执行权限检查 -//! 5. 调用 handler.invoke() 执行实际逻辑 - -use std::{collections::BTreeMap, sync::Arc}; - -use astrcode_core::{AstrError, CancelToken, CapabilitySpec, Result}; -use astrcode_protocol::plugin::{CapabilityWireDescriptor, InvocationContext}; -use async_trait::async_trait; -use serde_json::Value; - -use crate::{EventEmitter, capability_mapping::spec_to_wire_descriptor}; - -/// 能力处理器 trait。 -/// -/// 每个实现代表一个可被插件或宿主调用的能力。 -/// 能力通过 `capability_spec()` 声明元数据（名称、类型、输入输出 schema 等）， -/// 通过 `invoke()` 执行实际逻辑。 -/// -/// # 线程安全 -/// -/// 需要 `Send + Sync`，因为路由器可能在多线程环境中并发调用。 -#[async_trait] -pub trait CapabilityHandler: Send + Sync { - fn capability_spec(&self) -> CapabilitySpec; - - async fn invoke( - &self, - input: Value, - context: InvocationContext, - events: EventEmitter, - cancel: CancelToken, - ) -> Result; -} - -/// 权限检查器 trait。 -/// -/// 在能力执行前进行权限验证。实现可以根据能力描述和调用上下文 -/// 决定是否允许执行。例如：检查用户是否授权了文件系统访问、 -/// 是否在沙箱环境中运行等。 -/// -/// 默认实现 `AllowAllPermissionChecker` 允许所有请求， -/// 生产环境应替换为更严格的检查器。 -pub trait PermissionChecker: Send + Sync { - fn check(&self, capability: &CapabilitySpec, context: &InvocationContext) -> Result<()>; -} - -/// 允许所有请求的权限检查器。 -/// -/// 用于开发环境或不需要权限隔离的场景。 -/// 生产环境应使用更严格的实现。 -#[derive(Debug, Default)] -pub struct AllowAllPermissionChecker; - -impl PermissionChecker for AllowAllPermissionChecker { - fn check(&self, _capability: &CapabilitySpec, _context: &InvocationContext) -> Result<()> { - Ok(()) - } -} - -/// 能力路由器——维护能力注册表并执行路由+权限检查。 -/// -/// # 职责 -/// -/// - 注册能力处理器（通过 `register` 或 `register_arc`） -/// - 查询已注册的能力列表 -/// - 根据能力名称路由调用请求 -/// - 验证 profile 兼容性 -/// - 执行权限检查 -/// -/// # 内部实现 -/// -/// 使用 `BTreeMap` 存储处理器以保证确定性遍历顺序， -/// 这对于能力列表的序列化一致性很重要。 -pub struct CapabilityRouter { - handlers: BTreeMap>, - permission_checker: Arc, -} - -impl Default for CapabilityRouter { - /// 创建使用 `AllowAllPermissionChecker` 的默认路由器。 - fn default() -> Self { - Self::new(Arc::new(AllowAllPermissionChecker)) - } -} - -impl CapabilityRouter { - /// 创建使用指定权限检查器的路由器。 - pub fn new(permission_checker: Arc) -> Self { - Self { - handlers: BTreeMap::new(), - permission_checker, - } - } - - /// 注册一个能力处理器。 - /// - /// # 验证 - /// - /// - 检查 `CapabilitySpec` 的合法性（名称格式、必填字段等） - /// - 检查是否已有同名能力（不允许重复注册） - /// - /// # 错误 - /// - /// - descriptor 验证失败返回 `Validation` 错误 - /// - 重复注册返回 `Validation` 错误 - pub fn register(&mut self, handler: H) -> Result<()> - where - H: CapabilityHandler + 'static, - { - self.register_arc(Arc::new(handler)) - } - - /// 注册一个 `Arc` 包装的能力处理器。 - /// - /// 与 `register()` 功能相同，但允许调用方自行管理 handler 的 `Arc`， - /// 适用于需要在多处共享同一个 handler 实例的场景。 - pub fn register_arc(&mut self, handler: Arc) -> Result<()> { - let spec = handler.capability_spec(); - spec.validate().map_err(|error| { - AstrError::Validation(format!( - "invalid capability spec '{}': {}", - spec.name, error - )) - })?; - if self.handlers.contains_key(spec.name.as_str()) { - return Err(AstrError::Validation(format!( - "duplicate capability registration: {}", - spec.name - ))); - } - self.handlers.insert(spec.name.to_string(), handler); - Ok(()) - } - - /// 获取所有已注册能力的描述符列表。 - /// - /// 返回顺序由内部 `BTreeMap` 的键顺序决定（按能力名称字典序）。 - pub fn capabilities(&self) -> Result> { - self.handlers - .values() - .map(|handler| { - let spec = handler.capability_spec(); - spec_to_wire_descriptor(&spec).map_err(|error| { - AstrError::Validation(format!( - "failed to project capability spec '{}' to wire descriptor: {}", - spec.name, error - )) - }) - }) - .collect() - } - - /// 调用指定能力。 - /// - /// # 执行流程 - /// - /// 1. 查找能力 handler，不存在则返回 `Validation` 错误 - /// 2. 验证 profile 兼容性（能力的 profiles 必须包含上下文的 profile） - /// 3. 执行权限检查 - /// 4. 调用 handler.invoke() 执行实际逻辑 - /// - /// # 参数 - /// - /// * `capability` - 能力名称（如 `tool.echo`） - /// * `input` - 输入参数，需符合能力的 `input_schema` - /// * `context` - 调用上下文，包含 session、workspace、profile 等信息 - /// * `events` - 事件发射器，用于流式输出 - /// * `cancel` - 取消令牌，用于中途取消 - pub async fn invoke( - &self, - capability: &str, - input: Value, - context: InvocationContext, - events: EventEmitter, - cancel: CancelToken, - ) -> Result { - let handler = self - .handlers - .get(capability) - .ok_or_else(|| AstrError::Validation(format!("unknown capability '{capability}'")))?; - let spec = handler.capability_spec(); - self.validate_profile(&spec, &context)?; - self.permission_checker.check(&spec, &context)?; - handler.invoke(input, context, events, cancel).await - } - - /// 验证能力是否支持调用上下文的 profile。 - /// - /// 如果能力没有声明任何 profiles（空列表），则认为支持所有 profile。 - /// 否则，上下文的 profile 必须在能力的 profiles 列表中。 - fn validate_profile(&self, spec: &CapabilitySpec, context: &InvocationContext) -> Result<()> { - if spec.profiles.is_empty() || spec.profiles.contains(&context.profile) { - return Ok(()); - } - Err(AstrError::Validation(format!( - "capability '{}' does not support profile '{}'", - spec.name, context.profile - ))) - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::CapabilityKind; - use serde_json::json; - - use super::*; - - struct SampleHandler; - - #[async_trait] - impl CapabilityHandler for SampleHandler { - fn capability_spec(&self) -> CapabilitySpec { - CapabilitySpec::builder("tool.sample", CapabilityKind::Tool) - .description("sample") - .schema(json!({ "type": "object" }), json!({ "type": "object" })) - .profiles(["coding"]) - .build() - .expect("sample capability spec should build") - } - - async fn invoke( - &self, - input: Value, - _context: InvocationContext, - _events: EventEmitter, - _cancel: CancelToken, - ) -> Result { - Ok(input) - } - } - - struct DenyChecker; - - impl PermissionChecker for DenyChecker { - fn check(&self, _capability: &CapabilitySpec, _context: &InvocationContext) -> Result<()> { - Err(AstrError::Validation("denied by checker".to_string())) - } - } - - fn context(profile: &str) -> InvocationContext { - InvocationContext { - request_id: "req-1".to_string(), - trace_id: None, - session_id: None, - caller: None, - workspace: None, - deadline_ms: None, - budget: None, - profile: profile.to_string(), - profile_context: Value::Null, - metadata: Value::Null, - } - } - - #[tokio::test] - async fn router_rejects_unsupported_profile() { - let mut router = CapabilityRouter::default(); - router.register(SampleHandler).expect("register handler"); - - let error = router - .invoke( - "tool.sample", - json!({}), - context("workflow"), - EventEmitter::noop(), - CancelToken::new(), - ) - .await - .expect_err("unsupported profile should fail"); - assert!(matches!(error, AstrError::Validation(_))); - assert!(error.to_string().contains("does not support profile")); - } - - #[tokio::test] - async fn router_applies_permission_checker_before_invocation() { - let mut router = CapabilityRouter::new(Arc::new(DenyChecker)); - router.register(SampleHandler).expect("register handler"); - - let error = router - .invoke( - "tool.sample", - json!({}), - context("coding"), - EventEmitter::noop(), - CancelToken::new(), - ) - .await - .expect_err("permission checker should fail"); - assert!(matches!(error, AstrError::Validation(_))); - assert!(error.to_string().contains("denied by checker")); - } -} diff --git a/crates/plugin/src/invoker.rs b/crates/plugin/src/invoker.rs deleted file mode 100644 index 00d0fafe..00000000 --- a/crates/plugin/src/invoker.rs +++ /dev/null @@ -1,280 +0,0 @@ -//! 插件能力调用器。 -//! -//! 本模块实现 `CapabilityInvoker` trait 的插件版本， -//! 将 core 层的能力调用请求转换为插件协议的 `InvokeMessage`。 -//! -//! ## 职责 -//! -//! - 将 `CapabilityContext` 转换为插件协议的 `InvocationContext` -//! - 根据能力是否支持流式选择 `invoke` 或 `invoke_stream` -//! - 将插件返回的结果转换为 `CapabilityExecutionResult` - -use std::{sync::Arc, time::Instant}; - -use astrcode_core::{ - AstrError, CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, - InvocationMode, Result, -}; -use astrcode_protocol::plugin::{ - CapabilityWireDescriptor, EventPhase, InvocationContext, WorkspaceRef, -}; -use async_trait::async_trait; -use serde_json::{Value, json}; -use uuid::Uuid; - -use crate::{Peer, StreamExecution, Supervisor, capability_mapping::wire_descriptor_to_spec}; - -/// 插件能力的调用器实现。 -/// -/// 将 `core::CapabilityInvoker` trait 适配到插件协议的 `Peer`。 -/// 每个实例对应一个远程插件能力。 -/// -/// # 架构位置 -/// -/// ```text -/// Runtime → CapabilityInvoker (此结构体) → Peer → Transport → 插件进程 -/// ``` -#[derive(Clone)] -pub struct PluginCapabilityInvoker { - peer: Peer, - capability_spec: CapabilitySpec, - remote_name: String, -} - -impl PluginCapabilityInvoker { - /// 从协议描述符创建调用器。 - /// - /// `remote_name` 保存原始的能力名称，因为 `descriptor.name` 可能在 - /// 适配过程中被修改（如添加命名空间前缀）。 - pub fn from_wire_descriptor(peer: Peer, descriptor: CapabilityWireDescriptor) -> Result { - let capability_spec = wire_descriptor_to_spec(&descriptor).map_err(|error| { - AstrError::Validation(format!( - "invalid protocol capability wire descriptor '{}': {}", - descriptor.name, error - )) - })?; - Ok(Self { - remote_name: descriptor.name.to_string(), - capability_spec, - peer, - }) - } -} - -#[async_trait] -impl CapabilityInvoker for PluginCapabilityInvoker { - fn capability_spec(&self) -> CapabilitySpec { - self.capability_spec.clone() - } - - /// 执行能力调用。 - /// - /// 根据能力的 `streaming` 标志选择调用模式： - /// - 流式模式：通过 `invoke_stream` 获取 `StreamExecution`， 然后收集所有 delta - /// 事件直到终端事件 - /// - 一元模式：通过 `invoke` 等待完整结果 - /// - /// # 返回 - /// - /// 总是返回 `Ok(CapabilityExecutionResult)`，即使插件调用失败。 - /// 成功与否通过 `CapabilityExecutionResult::success` 字段判断。 - /// 只有在传输层错误时才返回 `Err`。 - async fn invoke( - &self, - payload: Value, - ctx: &CapabilityContext, - ) -> Result { - let started_at = Instant::now(); - let invocation = to_invocation_context(ctx); - - if matches!( - self.capability_spec.invocation_mode, - InvocationMode::Streaming - ) { - let mut stream = self - .peer - .invoke_stream(astrcode_protocol::plugin::InvokeMessage { - id: invocation.request_id.clone(), - capability: self.remote_name.clone(), - input: payload, - context: invocation, - stream: true, - }) - .await?; - finish_stream_invocation( - self.capability_spec.name.to_string(), - &mut stream, - started_at, - ) - .await - } else { - let result = self - .peer - .invoke(astrcode_protocol::plugin::InvokeMessage { - id: invocation.request_id.clone(), - capability: self.remote_name.clone(), - input: payload, - context: invocation, - stream: false, - }) - .await?; - let (success, error) = if result.success { - (true, None) - } else { - let error = result - .error - .map(|value| value.message) - .unwrap_or_else(|| "plugin invocation failed".to_string()); - (false, Some(error)) - }; - Ok(CapabilityExecutionResult::from_common( - self.capability_spec.name.to_string(), - success, - result.output, - None, - astrcode_core::ExecutionResultCommon { - error, - metadata: Some(result.metadata), - duration_ms: started_at.elapsed().as_millis() as u64, - truncated: false, - }, - )) - } - } -} - -impl Supervisor { - /// 获取此插件所有能力的调用器列表。 - /// - /// 每个调用器封装了一个远程插件能力，实现了 `core::CapabilityInvoker` trait， - /// 可以被 runtime 统一调度。 - pub fn capability_invokers(&self) -> Vec> { - self.remote_initialize() - .capabilities - .iter() - .cloned() - .filter_map(|descriptor| { - match PluginCapabilityInvoker::from_wire_descriptor(self.peer(), descriptor) { - Ok(invoker) => Some(Arc::new(invoker) as Arc), - Err(error) => { - log::error!("failed to adapt plugin capability wire descriptor: {error}"); - None - }, - } - }) - .collect() - } - - /// 获取此插件声明的 wire 能力描述符列表。 - /// - /// 与 `capability_invokers()` 不同，此方法返回原始的描述符， - /// 不包装为调用器。用于向宿主展示插件提供了哪些能力。 - pub fn wire_capabilities(&self) -> Vec { - self.remote_initialize().capabilities.clone() - } - - /// 获取此插件声明的 skill 列表。 - /// - /// 返回插件在握手阶段通过 `InitializeResultData.skills` 声明的 skill。 - /// 调用方负责将这些声明转换为内部的 `SkillSpec`。 - pub fn declared_skills(&self) -> Vec { - self.remote_initialize().skills.clone() - } - - /// 获取此插件声明的治理 mode 列表。 - /// - /// 返回插件在握手阶段通过 `InitializeResultData.modes` 声明的 mode。 - /// 调用方负责决定如何校验并注册这些 mode。 - pub fn declared_modes(&self) -> Vec { - self.remote_initialize().modes.clone() - } -} - -/// 完成流式调用并收集结果。 -/// -/// 从 `StreamExecution` 中读取所有事件，收集 delta 事件到 `streamEvents` 元数据中， -/// 直到收到终端事件（Completed 或 Failed）。 -/// -/// # 错误处理 -/// -/// 如果 channel 关闭但未收到终端事件，返回 `Internal` 错误。 -/// 这通常意味着插件异常退出或传输层断裂。 -async fn finish_stream_invocation( - capability_name: String, - stream: &mut StreamExecution, - started_at: Instant, -) -> Result { - let mut deltas = Vec::new(); - - while let Some(event) = stream.recv().await { - match event.phase { - EventPhase::Started => {}, - EventPhase::Delta => { - deltas.push(json!({ - "event": event.event, - "payload": event.payload, - "seq": event.seq, - })); - }, - EventPhase::Completed => { - return Ok(CapabilityExecutionResult::from_common( - capability_name, - true, - event.payload, - None, - astrcode_core::ExecutionResultCommon::success( - Some(json!({ "streamEvents": deltas })), - started_at.elapsed().as_millis() as u64, - false, - ), - )); - }, - EventPhase::Failed => { - let error = event - .error - .map(|value| value.message) - .unwrap_or_else(|| "stream invocation failed".to_string()); - return Ok(CapabilityExecutionResult::from_common( - capability_name, - false, - Value::Null, - None, - astrcode_core::ExecutionResultCommon::failure( - error, - Some(json!({ "streamEvents": deltas })), - started_at.elapsed().as_millis() as u64, - false, - ), - )); - }, - } - } - - Err(AstrError::Internal( - "plugin stream ended without terminal event".to_string(), - )) -} - -fn to_invocation_context(ctx: &CapabilityContext) -> InvocationContext { - let working_dir = ctx.working_dir.to_string_lossy().into_owned(); - InvocationContext { - request_id: ctx - .request_id - .clone() - .unwrap_or_else(|| Uuid::new_v4().to_string()), - trace_id: ctx.trace_id.clone(), - session_id: Some(ctx.session_id.to_string()), - caller: None, - workspace: Some(WorkspaceRef { - working_dir: Some(working_dir.clone()), - repo_root: Some(working_dir), - branch: None, - metadata: Value::Null, - }), - deadline_ms: None, - budget: None, - profile: ctx.profile.clone(), - profile_context: ctx.profile_context.clone(), - metadata: ctx.metadata.clone(), - } -} diff --git a/crates/plugin/src/lib.rs b/crates/plugin/src/lib.rs deleted file mode 100644 index 15e42704..00000000 --- a/crates/plugin/src/lib.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! # Astrcode 插件系统 -//! -//! 本库实现了插件进程的管理和 JSON-RPC 通信，是 Astrcode 可扩展架构的核心。 -//! -//! ## 架构概览 -//! -//! ```text -//! Runtime / Server 插件宿主 (本 crate) 插件进程 -//! ────────────── ────────────────── ────────── -//! CapabilityInvoker ──────────────► Supervisor Worker -//! ├─ PluginProcess (子进程管理) ├─ CapabilityRouter -//! ├─ Peer (JSON-RPC 通信) ├─ StdioTransport -//! └─ CapabilityRouter (反向调用) └─ 能力处理器 -//! ``` -//! -//! ## 核心组件 -//! -//! - **进程管理** (`process`): 启动、监控、重启插件子进程 -//! - **通信** (`peer`, `transport`): 基于 stdio 的 JSON-RPC 双向通信 -//! - **生命周期** (`supervisor`): 处理插件进程的握手、健康检查和优雅关闭 -//! - **流式执行** (`streaming`): 支持插件的流式响应（增量事件） -//! - **能力路由** (`capability_router`): 路由能力调用并执行权限检查 -//! - **插件加载** (`loader`): 发现、解析和启动插件 -//! - **Worker** (`worker`): 插件进程侧的入口，用于编写插件二进制 -//! -//! ## 通信协议 -//! -//! 插件通过 stdio 与宿主进行 JSON-RPC 通信，消息类型包括： -//! -//! - `InitializeMessage` / `InitializeResultData` — 握手协商 -//! - `InvokeMessage` / `ResultMessage` — 能力调用与结果 -//! - `EventMessage` — 流式增量事件（started → delta × N → completed/failed） -//! - `CancelMessage` — 取消请求 -//! -//! ## 使用方式 -//! -//! ### 宿主侧 -//! -//! ```ignore -//! let loader = PluginLoader { search_paths: vec!["plugins/".into()] }; -//! let manifests = loader.discover()?; -//! for manifest in manifests { -//! let supervisor = loader.start(&manifest, local_peer, None).await?; -//! let invokers = supervisor.capability_invokers(); -//! // 注册到 runtime... -//! } -//! ``` -//! -//! ### 插件侧 -//! -//! ```ignore -//! let mut router = CapabilityRouter::default(); -//! router.register(MyHandler)?; -//! -//! let worker = Worker::from_stdio(peer_descriptor, router, None); -//! worker.run().await?; -//! ``` - -mod capability_mapping; -mod capability_router; -mod invoker; -mod loader; -mod peer; -mod process; -mod streaming; -mod supervisor; -pub mod transport; -mod worker; - -pub use capability_mapping::{spec_to_wire_descriptor, wire_descriptor_to_spec}; -pub use capability_router::{ - AllowAllPermissionChecker, CapabilityHandler, CapabilityRouter, PermissionChecker, -}; -pub use invoker::PluginCapabilityInvoker; -pub use loader::{PluginLoader, parse_plugin_manifest_toml}; -pub use peer::Peer; -pub use process::{PluginProcess, PluginProcessStatus}; -pub use streaming::{EventEmitter, StreamExecution}; -pub use supervisor::{ - Supervisor, SupervisorHealth, SupervisorHealthReport, default_initialize_message, - default_profiles, -}; -pub use worker::Worker; diff --git a/crates/plugin/src/loader.rs b/crates/plugin/src/loader.rs deleted file mode 100644 index da2f0341..00000000 --- a/crates/plugin/src/loader.rs +++ /dev/null @@ -1,190 +0,0 @@ -//! 插件加载器—— 发现、解析和启动插件。 -//! -//! 本模块负责： -//! -//! - **发现**: 在配置的搜索路径中扫描 `.toml` 插件清单文件 -//! - **解析**: 解析 `PluginManifest` 并处理相对路径 -//! - **启动**: 启动插件进程并完成握手 -//! -//! ## 插件发现流程 -//! -//! 1. 遍历所有 `search_paths` -//! 2. 读取目录中的 `.toml` 文件 -//! 3. 解析为 `PluginManifest` -//! 4. 将相对路径（`working_dir`、`executable`）解析为绝对路径 -//! 5. 按名称、版本、可执行文件路径排序以保证确定性 - -use std::path::PathBuf; - -use astrcode_core::{AstrError, PluginManifest, Result}; -use astrcode_protocol::plugin::{InitializeMessage, PeerDescriptor}; - -use crate::{PluginProcess, Supervisor}; - -pub fn parse_plugin_manifest_toml(raw: &str) -> Result { - toml::from_str(raw).map_err(|error| { - AstrError::Validation(format!("failed to parse plugin manifest TOML: {error}")) - }) -} - -/// 插件加载器。 -/// -/// 维护插件搜索路径列表，提供发现、解析和启动插件的功能。 -/// -/// # 搜索路径 -/// -/// 每个搜索路径是一个目录，加载器会扫描其中的 `.toml` 文件作为插件清单。 -/// 路径不存在或无法读取时会记录警告并跳过，不会导致整体失败。 -#[derive(Debug, Default, Clone)] -pub struct PluginLoader { - pub search_paths: Vec, -} - -/// Resolve a relative path field in place. -/// -/// If `require_components_gt_1` is true, only resolve paths that contain -/// directory separators (e.g. `./bin/plugin`), avoiding bare executable names. -fn resolve_relative_path( - path_field: &mut Option, - manifest_path: &std::path::Path, - search_path: &std::path::Path, - require_components_gt_1: bool, -) { - let Some(value) = path_field.clone() else { - return; - }; - let path = PathBuf::from(&value); - if !path.is_relative() { - return; - } - if require_components_gt_1 && path.components().count() <= 1 { - return; - } - let resolved = manifest_path.parent().unwrap_or(search_path).join(path); - *path_field = Some(resolved.to_string_lossy().into_owned()); -} - -impl PluginLoader { - /// 在所有搜索路径中发现插件清单。 - /// - /// # 容错设计 - /// - /// 此方法采用"尽力而为"策略： - /// - 目录不存在或无法读取 → 记录警告，跳过 - /// - 单个条目无法检查 → 记录警告，跳过 - /// - 文件不是 `.toml` → 静默跳过 - /// - 清单解析失败 → 记录警告，跳过 - /// - /// 这样确保单个插件的问题不会影响其他插件的加载。 - /// - /// # 路径解析 - /// - /// 清单中的 `working_dir` 和 `executable` 如果是相对路径， - /// 会相对于清单文件所在目录进行解析。 - /// `executable` 只有在包含路径分隔符（`components().count() > 1`）时才解析， - /// 这是为了避免将简单的可执行文件名（如 `my-plugin`）错误地解析为相对路径。 - /// - /// # 排序 - /// - /// 返回结果按名称、版本、可执行文件路径排序， - /// 确保能力冲突解析的确定性，不受文件系统枚举顺序影响。 - pub fn discover(&self) -> Result> { - let mut manifests = Vec::new(); - for search_path in &self.search_paths { - if !search_path.exists() { - continue; - } - - let entries = match std::fs::read_dir(search_path) { - Ok(entries) => entries, - Err(error) => { - log::warn!( - "skipping plugin directory '{}' because it could not be read: {}", - search_path.display(), - error - ); - continue; - }, - }; - - for entry in entries { - let entry = match entry { - Ok(entry) => entry, - Err(error) => { - log::warn!( - "skipping plugin entry in '{}' because it could not be inspected: {}", - search_path.display(), - error - ); - continue; - }, - }; - let path = entry.path(); - if path.extension().and_then(|ext| ext.to_str()) != Some("toml") { - continue; - } - let raw = match std::fs::read_to_string(&path) { - Ok(raw) => raw, - Err(error) => { - log::warn!( - "skipping plugin manifest '{}' because it could not be read: {}", - path.display(), - error - ); - continue; - }, - }; - let mut manifest = match parse_plugin_manifest_toml(&raw) { - Ok(manifest) => manifest, - Err(error) => { - log::warn!( - "skipping plugin manifest '{}' because it could not be parsed: {}", - path.display(), - error - ); - continue; - }, - }; - resolve_relative_path(&mut manifest.working_dir, &path, search_path, false); - resolve_relative_path(&mut manifest.executable, &path, search_path, true); - manifests.push(manifest); - } - } - // Keep discovery deterministic so capability conflicts always resolve against the same - // plugin order regardless of filesystem enumeration order. - manifests.sort_by(|left, right| { - left.name - .cmp(&right.name) - .then_with(|| left.version.cmp(&right.version)) - .then_with(|| left.executable.cmp(&right.executable)) - }); - Ok(manifests) - } - - /// 启动插件进程但不进行握手。 - /// - /// 仅创建子进程和传输层，不调用 `initialize()`。 - pub async fn start_process(&self, manifest: &PluginManifest) -> Result { - PluginProcess::start(manifest).await - } - - /// 启动插件进程并完成握手。 - /// - /// 这是加载插件的完整流程：启动进程 → 创建 Peer → 发送 InitializeMessage → - /// 等待 InitializeResultData → 返回 Supervisor。 - /// - /// # 参数 - /// - /// * `manifest` - 插件清单 - /// * `local_peer` - 本地（宿主）的 peer 描述 - /// * `local_initialize` - 可选的自定义初始化消息；为 `None` 时使用默认值 - pub async fn start( - &self, - manifest: &PluginManifest, - local_peer: PeerDescriptor, - local_initialize: Option, - ) -> Result { - let process = self.start_process(manifest).await?; - Supervisor::from_process(process, local_peer, local_initialize).await - } -} diff --git a/crates/plugin/src/peer.rs b/crates/plugin/src/peer.rs deleted file mode 100644 index 4178b912..00000000 --- a/crates/plugin/src/peer.rs +++ /dev/null @@ -1,916 +0,0 @@ -//! 插件对等体（Peer）—— 管理与插件进程的双向 JSON-RPC 通信。 -//! -//! ## 核心职责 -//! -//! `Peer` 是宿主进程与插件进程之间的通信桥梁，负责： -//! - 发送 `InitializeMessage` 完成握手协商 -//! - 发送 `InvokeMessage` 调用插件能力并等待 `ResultMessage` -//! - 发送 `InvokeMessage(stream=true)` 获取流式 `StreamExecution` -//! - 接收插件主动发起的能力调用（host-to-plugin 反向调用） -//! - 处理 `CancelMessage` 取消请求 -//! - 管理后台读循环和所有活跃请求的生命周期 -//! -//! ## 消息流 -//! -//! ```text -//! 宿主 (Peer) 插件进程 -//! ────────────── ────────────── -//! InitializeMessage ──────────────────► -//! ◄────────────────────── ResultMessage (initialize) -//! -//! InvokeMessage ─────────────────────► -//! ◄────────────────────── ResultMessage (unary) -//! -//! InvokeMessage(stream=true) ────────► -//! ◄────────────────────── EventMessage (started) -//! ◄────────────────────── EventMessage (delta) × N -//! ◄────────────────────── EventMessage (completed/failed) -//! -//! ◄────────────────────── InvokeMessage (插件→宿主) -//! InvokeMessage ─────────────────────► (宿主处理) -//! ◄────────────────────── ResultMessage -//! -//! CancelMessage ─────────────────────► -//! ``` -//! -//! ## 同步原语选择 -//! -//! `read_loop_handle` 和 `invoke_handles` 使用 `std::sync::Mutex`（非 tokio Mutex）， -//! 因为这些字段只在短时间内持有锁（插入/取出 HashMap 条目），不需要跨 await 点。 -//! 使用 `std::sync::Mutex` 避免了 tokio Mutex 的额外开销和潜在的 "mutex held across await" 警告。 - -use std::{ - collections::HashMap, - sync::{ - Arc, - atomic::{AtomicU64, Ordering}, - }, -}; - -use astrcode_core::{AstrError, CancelToken, Result}; -use astrcode_protocol::plugin::{ - CancelMessage, ErrorPayload, EventMessage, EventPhase, InitializeMessage, InitializeResultData, - InvokeMessage, PROTOCOL_VERSION, PluginMessage, ResultMessage, -}; -use serde_json::{Value, json}; -use tokio::sync::{Mutex, Notify, mpsc, oneshot}; - -use crate::{CapabilityRouter, EventEmitter, StreamExecution, transport::Transport}; - -/// 与插件进程的双向通信端。 -/// -/// `Peer` 封装了与单个插件进程的完整 JSON-RPC 生命周期，包括握手、 -/// 请求-响应、流式事件、取消和优雅关闭。 -/// -/// ## 架构概览 -/// -/// ```text -/// Host (本进程) Plugin (子进程) -/// ────────────── ────────────── -/// invoke() ─── InvokeMessage ──────► 处理请求 -/// ◄──── ResultMessage ─────── 返回结果 -/// ◄──── EventMessage ──────── 流式增量 -/// -/// read_loop ◄──── PluginMessage ─────── 所有入站消息 -/// ─── CancelMessage ──────► 取消请求 -/// ``` -/// -/// ## 关键状态 -/// -/// - `pending_results`: 等待结果的一次性 channel，invoke 时插入，收到 ResultMessage 时取出 -/// - `pending_streams`: 流式调用的增量 channel，invoke(stream=true) 时插入 -/// - `inbound_cancellations`: 插件调用 host 能力时的取消令牌，host 可以取消 -/// - `read_loop_handle`: 后台读循环的 JoinHandle，abort() 时用于取消 -/// - `invoke_handles`: 每个入站 invoke 对应的处理任务，abort() 时批量取消 -/// -/// ## 同步原语选择 -/// -/// `read_loop_handle` 和 `invoke_handles` 使用 `std::sync::Mutex`（非 tokio Mutex）， -/// 因为这些字段只在短时间内持有锁（插入/取出 HashMap 条目），不需要跨 await 点。 -#[derive(Clone)] -pub struct Peer { - inner: Arc, -} - -struct PeerInner { - transport: Arc, - local_initialize: InitializeMessage, - router: Arc, - pending_results: Mutex>>, - pending_streams: Mutex>>, - inbound_cancellations: Mutex>, - remote_initialize: Mutex>, - closed_reason: Mutex>, - closed_notify: Notify, - read_loop_handle: std::sync::Mutex>>, - invoke_handles: std::sync::Mutex>>, -} - -impl Peer { - /// 创建新的 Peer 并启动后台读循环。 - /// - /// # 参数 - /// - /// * `transport` - 底层传输层（通常是 stdio），负责序列化和发送/接收 JSON-RPC 消息 - /// * `local_initialize` - 本地初始化信息，包含本端支持的能力和配置 - /// * `router` - 能力路由器，用于处理插件反向调用宿主能力的请求 - /// - /// # 注意 - /// - /// 构造完成后立即启动后台读循环（`spawn_read_loop`）， - /// 该循环会持续监听来自插件的入站消息。 - pub fn new( - transport: Arc, - local_initialize: InitializeMessage, - router: Arc, - ) -> Self { - let inner = Arc::new(PeerInner { - transport, - local_initialize, - router, - pending_results: Mutex::new(HashMap::new()), - pending_streams: Mutex::new(HashMap::new()), - inbound_cancellations: Mutex::new(HashMap::new()), - remote_initialize: Mutex::new(None), - closed_reason: Mutex::new(None), - closed_notify: Notify::new(), - read_loop_handle: std::sync::Mutex::new(None), - invoke_handles: std::sync::Mutex::new(HashMap::new()), - }); - - let peer = Self { inner }; - peer.spawn_read_loop(); - peer - } - - /// 发送初始化请求并等待插件响应，完成协议版本协商。 - /// - /// 这是与插件通信的第一步。发送 `InitializeMessage` 后等待 `ResultMessage`， - /// 解析返回的 `InitializeResultData` 并验证协议版本兼容性。 - /// - /// # 返回 - /// - /// 返回协商后的 `InitializeResultData`，包含插件声明的能力列表、 - /// 支持的 profiles 和元数据。 - /// - /// # 错误 - /// - /// - 返回的消息类型不是 `initialize` 时返回内部错误 - /// - 插件返回 `success: false` 时返回对应的错误载荷 - /// - 解析 JSON 失败时返回验证错误 - pub async fn initialize(&self) -> Result { - let request = self.inner.local_initialize.clone(); - let response = self.await_result(request).await?; - if response.kind.as_deref() != Some("initialize") { - return Err(AstrError::Internal(format!( - "expected initialize result for '{}', received kind {:?}", - response.id, response.kind - ))); - } - if !response.success { - return Err(result_error_to_astr(response)); - } - let negotiated: InitializeResultData = response.parse_output().map_err(|error| { - AstrError::Validation(format!("failed to parse initialize result: {error}")) - })?; - *self.inner.remote_initialize.lock().await = Some(negotiated.clone()); - Ok(negotiated) - } - - /// 调用插件的某个能力并等待完整结果。 - /// - /// 发送 `InvokeMessage`（`stream=false`），注册一个 oneshot channel 到 - /// `pending_results`，然后等待对应的 `ResultMessage` 返回。 - /// - /// # 参数 - /// - /// * `request` - 调用请求，包含能力名称、输入参数和上下文 - /// - /// # 返回 - /// - /// 返回 `ResultMessage`，调用者需自行检查 `success` 字段判断成功与否。 - pub async fn invoke(&self, request: InvokeMessage) -> Result { - self.await_result(request).await - } - - /// 以流式模式调用插件的某个能力。 - /// - /// 与 `invoke()` 不同，此方法不会等待完整结果，而是返回一个 `StreamExecution`， - /// 调用者可以通过 `recv()` 逐步接收 `EventMessage` 增量事件。 - /// - /// # 流程 - /// - /// 1. 创建无界 channel，将 sender 注册到 `pending_streams` - /// 2. 发送 `InvokeMessage(stream=true)` - /// 3. 如果发送失败，清理已注册的 channel 并返回错误 - /// 4. 发送成功则返回 `StreamExecution`，包含 receiver 和 request_id - /// - /// # 注意 - /// - /// 流式事件（started → delta × N → completed/failed）会通过 - /// `handle_event` 路由到对应的 channel。终端事件（completed/failed） - /// 到达后会自动从 `pending_streams` 中移除。 - pub async fn invoke_stream(&self, request: InvokeMessage) -> Result { - let request_id = request.id.clone(); - let (sender, receiver) = mpsc::unbounded_channel(); - self.inner - .pending_streams - .lock() - .await - .insert(request_id.clone(), sender); - let send_result = self.send_message(&PluginMessage::Invoke(request)).await; - if let Err(error) = send_result { - self.inner.pending_streams.lock().await.remove(&request_id); - return Err(error); - } - Ok(StreamExecution::new(request_id, receiver)) - } - - /// 取消一个正在进行的请求。 - /// - /// 发送 `CancelMessage` 到插件进程。插件收到后应停止当前操作 - /// 并返回一个 failed 的终端事件。 - /// - /// # 参数 - /// - /// * `request_id` - 要取消的请求 ID - /// * `reason` - 可选的取消原因，用于日志和调试 - pub async fn cancel( - &self, - request_id: impl Into, - reason: Option, - ) -> Result<()> { - self.send_message(&PluginMessage::Cancel(CancelMessage { - id: request_id.into(), - reason, - })) - .await - } - - /// 获取插件在握手时返回的初始化结果。 - /// - /// 返回 `None` 表示尚未完成 `initialize()` 调用。 - pub async fn remote_initialize(&self) -> Option { - self.inner.remote_initialize.lock().await.clone() - } - - /// 获取 Peer 关闭的原因。 - /// - /// 返回 `None` 表示 Peer 仍在正常运行。 - /// 一旦关闭原因被设置，Peer 将不再处理任何新消息。 - pub async fn closed_reason(&self) -> Option { - self.inner.closed_reason.lock().await.clone() - } - - /// 等待 Peer 关闭。 - /// - /// 异步阻塞直到 `closed_reason` 被设置。使用 `Notify` 避免忙等待， - /// 每次被唤醒后重新检查条件以处理虚假唤醒。 - pub async fn wait_closed(&self) { - loop { - let notified = self.inner.closed_notify.notified(); - if self.inner.closed_reason.lock().await.is_some() { - return; - } - notified.await; - } - } - - /// 启动后台读循环，持续监听来自插件的入站消息。 - /// - /// 读循环在独立的 tokio task 中运行，负责： - /// - 从传输层读取原始 JSON 字符串 - /// - 反序列化为 `PluginMessage` - /// - 分发到对应的处理器（handle_*） - /// - /// 如果读循环因任何原因退出（传输关闭、解析错误等）， - /// 会触发 `close()` 并通知所有等待方。 - fn spawn_read_loop(&self) { - let inner = Arc::clone(&self.inner); - let handle = tokio::spawn(async move { - inner.read_loop().await; - }); - // Store the handle so we can abort the read loop during shutdown. - // Using std::sync::Mutex is safe here: the write happens synchronously - // during Peer::new, and abort() reads it from an async context with - // negligible contention. - astrcode_core::support::with_lock_recovery( - &self.inner.read_loop_handle, - "peer.read_loop_handle", - |guard| *guard = Some(handle), - ); - } - - /// 中止读循环和所有活跃的入站 invoke 处理器。 - /// - /// 由 `Supervisor` 在关闭时调用，确保 peer 的后台任务不会在进程终止后继续运行。 - /// - /// # 清理顺序 - /// - /// 1. 中止读循环（停止接收新消息） - /// 2. 中止所有入站 invoke 处理器（插件→宿主的调用） - /// 3. 取消所有入站请求的取消令牌 - /// 4. 设置关闭原因，通知所有等待方 - pub async fn abort(&self) { - // 使用 into_inner() 处理可能的 poison，避免在清理路径中 panic - if let Some(handle) = self - .inner - .read_loop_handle - .lock() - .unwrap_or_else(|poisoned| poisoned.into_inner()) - .take() - { - handle.abort(); - } - let handles = std::mem::take( - &mut *self - .inner - .invoke_handles - .lock() - .unwrap_or_else(|poisoned| poisoned.into_inner()), - ); - for (_, handle) in handles { - handle.abort(); - } - let cancellations = std::mem::take(&mut *self.inner.inbound_cancellations.lock().await); - for (_, cancel) in cancellations { - cancel.cancel(); - } - self.inner - .close("peer aborted during shutdown".to_string()) - .await; - } - - /// 发送请求并等待对应的结果。 - /// - /// 这是 `invoke()` 和 `initialize()` 的底层实现。 - /// - /// # 流程 - /// - /// 1. 将请求转换为 `PluginMessage` - /// 2. 创建 oneshot channel，将 sender 注册到 `pending_results` - /// 3. 发送消息到插件 - /// 4. 如果发送失败，清理已注册的 channel 并返回错误 - /// 5. 等待 receiver 收到 `ResultMessage` - /// - /// # 注意 - /// - /// 如果 peer 在读循环中关闭，所有 pending 的 oneshot sender 会被 - /// 发送一个失败的结果，因此 `receiver.await` 会返回 `Err`（channel 关闭）。 - async fn await_result(&self, request: T) -> Result - where - T: Into, - { - let request = request.into(); - let request_id = request.id().to_string(); - let (sender, receiver) = oneshot::channel(); - self.inner - .pending_results - .lock() - .await - .insert(request_id.clone(), sender); - if let Err(error) = self.send_message(&request.into_message()).await { - self.inner.pending_results.lock().await.remove(&request_id); - return Err(error); - } - receiver.await.map_err(|_| { - AstrError::Internal(format!( - "peer dropped pending result channel '{}'", - request_id - )) - }) - } - - /// 通过底层传输发送一条 JSON-RPC 消息。 - async fn send_message(&self, message: &PluginMessage) -> Result<()> { - self.inner.send_message(message).await - } -} - -/// 统一封装 `InitializeMessage` 和 `InvokeMessage`。 -/// -/// 两种消息都遵循请求-响应模式：发送后等待 `ResultMessage`。 -/// 此枚举允许 `await_result` 泛型处理两种请求类型，避免代码重复。 -enum InvokeOrInitialize { - Initialize(InitializeMessage), - Invoke(InvokeMessage), -} - -impl InvokeOrInitialize { - fn id(&self) -> &str { - match self { - Self::Initialize(message) => &message.id, - Self::Invoke(message) => &message.id, - } - } - - fn into_message(self) -> PluginMessage { - match self { - Self::Initialize(message) => PluginMessage::Initialize(message), - Self::Invoke(message) => PluginMessage::Invoke(message), - } - } -} - -impl From for InvokeOrInitialize { - fn from(value: InitializeMessage) -> Self { - Self::Initialize(value) - } -} - -impl From for InvokeOrInitialize { - fn from(value: InvokeMessage) -> Self { - Self::Invoke(value) - } -} - -impl PeerInner { - /// 后台读循环——持续监听来自插件的入站消息。 - /// - /// # 退出条件 - /// - /// - 传输层返回 `None`（管道关闭）→ 标记 "transport closed" - /// - 传输层返回错误 → 标记错误信息 - /// - JSON 反序列化失败 → 标记 "failed to decode plugin message" - /// - 消息处理器返回错误 → 标记 "peer message handling failed" - /// - /// 任何退出都会调用 `close()` 通知所有等待方。 - async fn read_loop(self: Arc) { - loop { - match self.transport.recv().await { - Ok(Some(payload)) => { - let message = match serde_json::from_str::(&payload) { - Ok(message) => message, - Err(error) => { - self.close(format!("failed to decode plugin message: {error}")) - .await; - break; - }, - }; - if let Err(error) = Arc::clone(&self).handle_message(message).await { - self.close(format!("peer message handling failed: {error}")) - .await; - break; - } - }, - Ok(None) => { - self.close("transport closed".to_string()).await; - break; - }, - Err(error) => { - self.close(error).await; - break; - }, - } - } - } - - /// 分发入站消息到对应的处理器。 - /// - /// # 注意 - /// - /// `Invoke` 消息的处理器返回 `Ok(())` 因为实际的异步处理在 - /// 独立的 tokio task 中进行，这里只负责 spawn 并立即返回。 - /// 如果 spawn 或后续处理失败，会在 task 内部调用 `close()`。 - async fn handle_message(self: Arc, message: PluginMessage) -> Result<()> { - match message { - PluginMessage::Initialize(message) => self.handle_initialize(message).await, - PluginMessage::Invoke(message) => { - self.handle_invoke(message).await; - Ok(()) - }, - PluginMessage::Result(message) => self.handle_result(message).await, - PluginMessage::Event(message) => self.handle_event(message).await, - PluginMessage::Cancel(message) => self.handle_cancel(message).await, - } - } - - /// 处理插件发起的初始化请求（插件→宿主的反向握手）。 - /// - /// 验证协议版本兼容性：如果插件声明的版本中包含 `PROTOCOL_VERSION`， - /// 则协商成功并返回本地能力信息；否则返回版本不匹配错误。 - /// - /// # 成功响应 - /// - /// 包含本地声明的能力、handlers、profiles 和元数据。 - /// - /// # 失败响应 - /// - /// 错误码为 `unsupported_version`，`retriable: false` 表示不应重试。 - async fn handle_initialize(&self, message: InitializeMessage) -> Result<()> { - let InitializeMessage { - id, - protocol_version, - supported_protocol_versions, - peer, - capabilities, - handlers, - profiles, - metadata, - } = message; - let supported = protocol_version == PROTOCOL_VERSION - || supported_protocol_versions - .iter() - .any(|version| version == PROTOCOL_VERSION); - let response = if supported { - let negotiated = InitializeResultData { - protocol_version: PROTOCOL_VERSION.to_string(), - peer, - capabilities, - handlers, - profiles, - skills: vec![], - modes: vec![], - metadata, - }; - *self.remote_initialize.lock().await = Some(negotiated.clone()); - ResultMessage { - id, - kind: Some("initialize".to_string()), - success: true, - output: serde_json::to_value(self.local_result()).map_err(|error| { - AstrError::Validation(format!( - "failed to serialize local initialize result: {error}" - )) - })?, - error: None, - metadata: json!({ "acceptedVersion": PROTOCOL_VERSION }), - } - } else { - ResultMessage { - id, - kind: Some("initialize".to_string()), - success: false, - output: Value::Null, - error: Some(ErrorPayload { - code: "unsupported_version".to_string(), - message: format!( - "peer version '{}' does not support '{}'", - protocol_version, PROTOCOL_VERSION - ), - details: json!({ "supportedProtocolVersions": supported_protocol_versions }), - retriable: false, - }), - metadata: Value::Null, - } - }; - self.send_message(&PluginMessage::Result(response)).await - } - - /// 处理插件发起的能力调用请求（插件→宿主）。 - /// - /// 此方法在独立的 tokio task 中执行，不阻塞读循环。 - /// - /// # 生命周期管理 - /// - /// 1. 创建 `CancelToken` 并注册到 `inbound_cancellations` - /// 2. 根据 `stream` 标志选择流式或一元处理 - /// 3. 完成后清理取消令牌和 invoke handle - /// 4. 如果处理失败，关闭整个 peer（因为插件可能处于不一致状态） - /// - /// # 为什么失败时关闭 peer？ - /// - /// 入站 invoke 是插件主动调用宿主能力，如果处理失败通常意味着 - /// 宿主侧出现了严重问题（如能力未注册、权限拒绝等）， - /// 继续运行可能导致更严重的不一致。 - async fn handle_invoke(self: Arc, message: InvokeMessage) { - let request_id = message.id.clone(); - let track_id = request_id.clone(); - let handle = tokio::spawn({ - let this = Arc::clone(&self); - async move { - let cancel = CancelToken::new(); - this.inbound_cancellations - .lock() - .await - .insert(request_id.clone(), cancel.clone()); - - let result = if message.stream { - this.handle_streaming_invoke(message, cancel).await - } else { - this.handle_unary_invoke(message, cancel).await - }; - - this.inbound_cancellations.lock().await.remove(&request_id); - this.invoke_handles - .lock() - .unwrap_or_else(|poisoned| poisoned.into_inner()) - .remove(&request_id); - if let Err(error) = result { - this.close(format!("failed to process inbound invoke: {error}")) - .await; - } - } - }); - - // Track the handle so shutdown cannot miss an in-flight invoke. - self.invoke_handles - .lock() - .unwrap_or_else(|poisoned| poisoned.into_inner()) - .insert(track_id, handle); - } - - /// 处理一元（非流式）入站调用。 - /// - /// 通过 `CapabilityRouter` 调用本地能力，将结果封装为 `ResultMessage` - /// 发送回插件。流式调用使用 `EventEmitter::noop()` 因为一元调用不需要增量输出。 - async fn handle_unary_invoke(&self, message: InvokeMessage, cancel: CancelToken) -> Result<()> { - let result = self - .router - .invoke( - &message.capability, - message.input, - message.context, - EventEmitter::noop(), - cancel, - ) - .await; - let response = match result { - Ok(output) => ResultMessage::success(message.id, output), - Err(error) => ResultMessage::failure(message.id, error_to_payload(&error)), - }; - self.send_message(&PluginMessage::Result(response)).await - } - - /// 处理流式入站调用。 - /// - /// 与一元调用不同，流式调用通过 `EventEmitter` 将增量事件 - /// 实时发送回插件。 - /// - /// # 流程 - /// - /// 1. 发送 `Started` 事件，告知插件调用已开始 - /// 2. 创建 `EventEmitter`，每个 `delta()` 调用都会通过传输层发送 `EventMessage` - /// 3. 调用 `CapabilityRouter` 执行实际能力 - /// 4. 根据结果发送 `Completed` 或 `Failed` 终端事件 - /// - /// # 取消处理 - /// - /// 如果能力执行成功但 `cancel.is_cancelled()` 为 true， - /// 发送 `Failed` 事件（错误码 `cancelled`），因为结果可能不完整。 - async fn handle_streaming_invoke( - self: &Arc, - message: InvokeMessage, - cancel: CancelToken, - ) -> Result<()> { - let request_id = message.id.clone(); - let sequence = Arc::new(AtomicU64::new(1)); - self.send_message(&PluginMessage::Event(EventMessage { - id: request_id.clone(), - phase: EventPhase::Started, - event: "invoke.started".to_string(), - payload: json!({ "capability": message.capability }), - seq: 0, - error: None, - })) - .await?; - - let transport = Arc::clone(&self.transport); - let emit_request_id = request_id.clone(); - let emit_sequence = Arc::clone(&sequence); - let emitter = EventEmitter::new(move |event, payload| { - let transport = Arc::clone(&transport); - let emit_request_id = emit_request_id.clone(); - let emit_sequence = Arc::clone(&emit_sequence); - async move { - let event_message = PluginMessage::Event(EventMessage { - id: emit_request_id, - phase: EventPhase::Delta, - event, - payload, - seq: emit_sequence.fetch_add(1, Ordering::SeqCst), - error: None, - }); - send_message_via_transport(transport, &event_message).await - } - }); - - let result = self - .router - .invoke( - &message.capability, - message.input, - message.context, - emitter, - cancel.clone(), - ) - .await; - - let terminal = match result { - Ok(_output) if cancel.is_cancelled() => EventMessage { - id: request_id, - phase: EventPhase::Failed, - event: "invoke.cancelled".to_string(), - payload: Value::Null, - seq: sequence.fetch_add(1, Ordering::SeqCst), - error: Some(ErrorPayload { - code: "cancelled".to_string(), - message: "request was cancelled".to_string(), - details: Value::Null, - retriable: false, - }), - }, - Ok(output) => EventMessage { - id: request_id, - phase: EventPhase::Completed, - event: "invoke.completed".to_string(), - payload: output, - seq: sequence.fetch_add(1, Ordering::SeqCst), - error: None, - }, - Err(error) => EventMessage { - id: request_id, - phase: EventPhase::Failed, - event: "invoke.failed".to_string(), - payload: Value::Null, - seq: sequence.fetch_add(1, Ordering::SeqCst), - error: Some(error_to_payload(&error)), - }, - }; - - self.send_message(&PluginMessage::Event(terminal)).await - } - - /// 处理插件返回的结果消息。 - /// - /// 从 `pending_results` 中取出对应的 oneshot sender 并发送结果。 - /// 如果没有匹配的 sender（可能是重复消息或已超时），则静默忽略。 - async fn handle_result(&self, message: ResultMessage) -> Result<()> { - if let Some(sender) = self.pending_results.lock().await.remove(&message.id) { - // 故意忽略：接收端已关闭表示请求已被取消/超时 - let _ = sender.send(message); - } - Ok(()) - } - - /// 处理插件发送的事件消息。 - /// - /// 将事件转发到 `pending_streams` 中对应的 channel。 - /// 如果是终端事件（Completed/Failed），处理完后从 map 中移除， - /// 避免后续消息丢失时 channel 泄漏。 - async fn handle_event(&self, message: EventMessage) -> Result<()> { - let is_terminal = matches!(message.phase, EventPhase::Completed | EventPhase::Failed); - let request_id = message.id.clone(); - let mut streams = self.pending_streams.lock().await; - if let Some(sender) = streams.get(&request_id) { - // 故意忽略：流已关闭表示订阅者已离开 - let _ = sender.send(message); - } - if is_terminal { - streams.remove(&request_id); - } - Ok(()) - } - - /// 处理插件发送的取消请求。 - /// - /// 从 `inbound_cancellations` 中取出对应的 `CancelToken` 并触发取消。 - /// 如果没有匹配的 token（可能已处理完或从未注册），则静默忽略。 - async fn handle_cancel(&self, message: CancelMessage) -> Result<()> { - if let Some(cancel) = self - .inbound_cancellations - .lock() - .await - .get(&message.id) - .cloned() - { - cancel.cancel(); - } - Ok(()) - } - - /// 将本地初始化信息转换为 `InitializeResultData`。 - /// - /// 用于响应插件的 `InitializeMessage`，告知插件本端支持的能力。 - fn local_result(&self) -> InitializeResultData { - InitializeResultData { - protocol_version: self.local_initialize.protocol_version.clone(), - peer: self.local_initialize.peer.clone(), - capabilities: self.local_initialize.capabilities.clone(), - handlers: self.local_initialize.handlers.clone(), - profiles: self.local_initialize.profiles.clone(), - skills: vec![], - modes: vec![], - metadata: self.local_initialize.metadata.clone(), - } - } - - /// 通过底层传输发送一条 JSON-RPC 消息。 - /// - /// 将 `PluginMessage` 序列化为 JSON 字符串后发送。 - async fn send_message(&self, message: &PluginMessage) -> Result<()> { - send_message_via_transport(Arc::clone(&self.transport), message).await - } - - /// 关闭 Peer 并通知所有等待方。 - /// - /// 这是一个幂等操作：如果已经关闭过，则直接返回。 - /// - /// # 清理流程 - /// - /// 1. 设置 `closed_reason`（防止重复关闭） - /// 2. 向所有 `pending_results` 发送失败结果 - /// 3. 向所有 `pending_streams` 发送 failed 终端事件 - /// 4. 唤醒所有等待 `closed_notify` 的异步任务 - async fn close(&self, reason: String) { - let mut closed_reason = self.closed_reason.lock().await; - if closed_reason.is_some() { - return; - } - *closed_reason = Some(reason.clone()); - drop(closed_reason); - - let error = ErrorPayload { - code: "transport_closed".to_string(), - message: reason.clone(), - details: Value::Null, - retriable: false, - }; - - let pending_results = std::mem::take(&mut *self.pending_results.lock().await); - for (request_id, sender) in pending_results { - // 故意忽略：发送失败响应时接收端可能已关闭 - let _ = sender.send(ResultMessage::failure(request_id, error.clone())); - } - - let pending_streams = std::mem::take(&mut *self.pending_streams.lock().await); - for (request_id, sender) in pending_streams { - // 故意忽略：广播关闭事件时接收端可能已关闭 - let _ = sender.send(EventMessage { - id: request_id, - phase: EventPhase::Failed, - event: "transport.closed".to_string(), - payload: Value::Null, - seq: 0, - error: Some(error.clone()), - }); - } - - self.closed_notify.notify_waiters(); - } -} - -/// 将 JSON-RPC 消息序列化并通过传输层发送。 -/// -/// # 错误处理 -/// -/// - 序列化失败返回 `Validation` 错误（通常是消息结构问题） -/// - 发送失败返回 `Internal` 错误（通常是传输层问题，如管道断裂） -async fn send_message_via_transport( - transport: Arc, - message: &PluginMessage, -) -> Result<()> { - let payload = serde_json::to_string(message).map_err(|error| { - AstrError::Validation(format!("failed to serialize plugin message: {error}")) - })?; - transport - .send(&payload) - .await - .map_err(|error| AstrError::Internal(format!("failed to send plugin message: {error}"))) -} - -/// 将 `AstrError` 转换为 JSON-RPC 错误载荷。 -/// -/// 根据错误类型映射到对应的错误码： -/// - `Cancelled` / `LlmInterrupted` → `cancelled` -/// - `Validation` → `validation_error` -/// - `Io` → `io_error` -/// - `Parse` → `parse_error` -/// - 其他 → `internal_error` -/// -/// `retriable` 字段继承自 `AstrError::is_retryable()`， -/// 告知调用方是否应该重试。 -fn error_to_payload(error: &AstrError) -> ErrorPayload { - ErrorPayload { - code: match error { - AstrError::Cancelled | AstrError::LlmInterrupted => "cancelled", - AstrError::Validation(_) => "validation_error", - AstrError::Io { .. } => "io_error", - AstrError::Parse { .. } => "parse_error", - _ => "internal_error", - } - .to_string(), - message: error.to_string(), - details: Value::Null, - retriable: error.is_retryable(), - } -} - -/// 将 `ResultMessage` 的错误载荷转换回 `AstrError`。 -/// -/// 特殊处理 `cancelled` 错误码，将其映射为 `AstrError::Cancelled`， -/// 其他错误统一映射为 `Internal` 并保留原始错误信息。 -fn result_error_to_astr(result: ResultMessage) -> AstrError { - let request_id = result.id; - match result.error { - Some(error) if error.code == "cancelled" => AstrError::Cancelled, - Some(error) => AstrError::Internal(format!( - "plugin request '{}' failed: {}", - request_id, error.message - )), - None => AstrError::Internal(format!( - "plugin request '{}' failed without error payload", - request_id - )), - } -} diff --git a/crates/plugin/src/process.rs b/crates/plugin/src/process.rs deleted file mode 100644 index b0544d46..00000000 --- a/crates/plugin/src/process.rs +++ /dev/null @@ -1,130 +0,0 @@ -//! 插件进程管理。 -//! -//! 本模块负责启动、监控和关闭插件子进程。 -//! -//! ## 进程生命周期 -//! -//! 1. `PluginProcess::start()` — 根据 manifest 启动子进程，创建 stdio 传输 -//! 2. `status()` — 非阻塞检查进程状态 -//! 3. `shutdown()` — 终止子进程 -//! -//! ## 传输层 -//! -//! 进程启动后立即创建 `StdioTransport`，将子进程的 stdin/stdout -//! 包装为异步传输层，供 `Peer` 使用。 - -use std::{process::Stdio, sync::Arc}; - -use astrcode_core::{AstrError, PluginManifest, Result}; -use tokio::process::{Child, Command}; - -use crate::transport::{StdioTransport, Transport}; - -/// 插件子进程。 -/// -/// 封装了 tokio 子进程和对应的 stdio 传输层。 -/// 由 `PluginProcess::start()` 创建，由 `Supervisor` 管理生命周期。 -pub struct PluginProcess { - pub manifest: PluginManifest, - pub child: Child, - transport: Arc, -} - -/// 插件进程的运行状态。 -/// -/// 由 `PluginProcess::status()` 返回，通过 `try_wait()` 非阻塞获取。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct PluginProcessStatus { - pub running: bool, - pub exit_code: Option, -} - -impl PluginProcess { - /// 根据清单启动插件子进程。 - /// - /// # 流程 - /// - /// 1. 从 manifest 获取可执行文件路径（必须存在） - /// 2. 配置命令参数和工作目录 - /// 3. 设置 stdin/stdout 为管道模式（用于 JSON-RPC 通信） - /// 4. 生成子进程 - /// 5. 取出 stdin/stdout 句柄创建 `StdioTransport` - /// - /// # 错误 - /// - /// - manifest 没有 `executable` → `Validation` 错误 - /// - 子进程生成失败 → `Io` 错误 - /// - stdin/stdout 不可用 → `Internal` 错误（理论上不应发生） - pub async fn start(manifest: &PluginManifest) -> Result { - let executable = manifest.executable.as_ref().ok_or_else(|| { - AstrError::Validation(format!("plugin '{}' has no executable", manifest.name)) - })?; - let mut command = Command::new(executable); - command - .args(&manifest.args) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()); - if let Some(working_dir) = &manifest.working_dir { - command.current_dir(working_dir); - } - let mut child = command.spawn().map_err(|error| { - AstrError::io(format!("failed to spawn plugin '{executable}'"), error) - })?; - let stdin = child.stdin.take().ok_or_else(|| { - AstrError::Internal(format!("plugin '{}' did not expose stdin", manifest.name)) - })?; - let stdout = child.stdout.take().ok_or_else(|| { - AstrError::Internal(format!("plugin '{}' did not expose stdout", manifest.name)) - })?; - let transport: Arc = Arc::new(StdioTransport::from_child(stdin, stdout)); - - Ok(Self { - manifest: manifest.clone(), - child, - transport, - }) - } - - /// 获取传输层的引用。 - /// - /// 返回 `Arc` 克隆，可与 `Peer` 共享。 - pub fn transport(&self) -> Arc { - Arc::clone(&self.transport) - } - - /// 非阻塞检查进程状态。 - /// - /// 使用 `try_wait()` 检查进程是否已退出，不会阻塞等待。 - pub fn status(&mut self) -> Result { - let exit_status = self - .child - .try_wait() - .map_err(|error| AstrError::io("failed to poll plugin process", error))?; - Ok(match exit_status { - Some(status) => PluginProcessStatus { - running: false, - exit_code: status.code(), - }, - None => PluginProcessStatus { - running: true, - exit_code: None, - }, - }) - } - - /// 终止插件子进程。 - /// - /// 调用 `kill()` 强制终止进程。 - /// - /// # 容错 - /// - /// 如果进程已经退出（`InvalidInput` 错误），视为成功。 - /// 这是为了避免在进程已退出的情况下重复关闭导致错误。 - pub async fn shutdown(&mut self) -> Result<()> { - match self.child.kill().await { - Ok(()) => Ok(()), - Err(error) if error.kind() == std::io::ErrorKind::InvalidInput => Ok(()), - Err(error) => Err(AstrError::io("failed to terminate plugin process", error)), - } - } -} diff --git a/crates/plugin/src/streaming.rs b/crates/plugin/src/streaming.rs deleted file mode 100644 index 0c5a4529..00000000 --- a/crates/plugin/src/streaming.rs +++ /dev/null @@ -1,117 +0,0 @@ -//! 流式执行与事件发射。 -//! -//! 本模块提供流式能力调用的基础设施： -//! -//! - `EventEmitter`: 异步事件发射器，用于在能力执行过程中发送增量事件 -//! - `StreamExecution`: 流式执行的接收端，封装了 `mpsc::UnboundedReceiver` -//! -//! ## 使用场景 -//! -//! 当插件能力需要逐步输出结果（如代码生成的增量 patch、搜索工具的逐步结果）时， -//! 通过 `EventEmitter::delta()` 发送事件，调用方通过 `StreamExecution::recv()` 接收。 - -use std::{future::Future, pin::Pin, sync::Arc}; - -use astrcode_core::Result; -use astrcode_protocol::plugin::EventMessage; -use serde_json::Value; -use tokio::sync::mpsc; - -type EmitFuture = Pin> + Send>>; -type EmitFn = dyn Fn(String, Value) -> EmitFuture + Send + Sync; - -/// 异步事件发射器。 -/// -/// 用于在能力执行过程中发送增量事件（delta events）。 -/// 内部使用类型擦除（type erasure）存储异步闭包，避免泛型污染 API。 -/// -/// # 设计选择 -/// -/// - 使用 `Option>` 而非直接存储闭包，使得 `Default` 实现为 no-op -/// - `Clone` 实现共享同一个 emit 函数，适合在多个地方传递 -/// - `noop()` 构造函数创建一个不执行任何操作的发射器，用于一元调用场景 -#[derive(Clone, Default)] -pub struct EventEmitter { - emit: Option>, -} - -impl EventEmitter { - /// 创建新的事件发射器。 - /// - /// 接受一个异步闭包 `(event_name, payload) -> Future>`， - /// 每次调用 `delta()` 时执行该闭包。 - pub fn new(emit: F) -> Self - where - F: Fn(String, Value) -> Fut + Send + Sync + 'static, - Fut: Future> + Send + 'static, - { - Self { - emit: Some(Arc::new(move |event, payload| { - Box::pin(emit(event, payload)) - })), - } - } - - /// 创建不执行任何操作的事件发射器。 - /// - /// 用于一元调用场景，能力处理器不需要发送增量事件。 - pub fn noop() -> Self { - Self { emit: None } - } - - /// 发送一个增量事件。 - /// - /// 如果发射器是 no-op 模式（通过 `Default` 或 `noop()` 创建）， - /// 则直接返回 `Ok(())`，不执行任何操作。 - pub async fn delta(&self, event: impl Into, payload: Value) -> Result<()> { - match &self.emit { - Some(emit) => emit(event.into(), payload).await, - None => Ok(()), - } - } -} - -/// 流式执行的接收端。 -/// -/// 封装了 `mpsc::UnboundedReceiver`，提供类型安全的 -/// 流式事件接收接口。由 `Peer::invoke_stream()` 创建并返回。 -/// -/// # 事件序列 -/// -/// 典型的流式执行会产生以下事件序列： -/// 1. `EventPhase::Started` — 调用开始 -/// 2. `EventPhase::Delta` × N — 增量输出 -/// 3. `EventPhase::Completed` 或 `EventPhase::Failed` — 终端事件 -/// -/// 收到终端事件后，channel 可能还会关闭（返回 `None`）， -/// 调用方应同时处理终端事件和 channel 关闭两种情况。 -pub struct StreamExecution { - request_id: String, - receiver: mpsc::UnboundedReceiver, -} - -impl StreamExecution { - /// 创建新的流式执行实例。 - pub fn new( - request_id: impl Into, - receiver: mpsc::UnboundedReceiver, - ) -> Self { - Self { - request_id: request_id.into(), - receiver, - } - } - - /// 获取关联的请求 ID。 - pub fn request_id(&self) -> &str { - &self.request_id - } - - /// 接收下一个事件。 - /// - /// 异步阻塞直到有新事件到达或 channel 关闭。 - /// 返回 `None` 表示 channel 已关闭（发送端已丢弃）。 - pub async fn recv(&mut self) -> Option { - self.receiver.recv().await - } -} diff --git a/crates/plugin/src/supervisor.rs b/crates/plugin/src/supervisor.rs deleted file mode 100644 index ef53df5a..00000000 --- a/crates/plugin/src/supervisor.rs +++ /dev/null @@ -1,313 +0,0 @@ -//! 插件 Supervisor—— 管理插件的完整生命周期。 -//! -//! `Supervisor` 是插件系统的核心门面（facade），组合了： -//! -//! - `PluginProcess` — 子进程管理 -//! - `Peer` — JSON-RPC 通信 -//! - `InitializeResultData` — 握手协商结果 -//! -//! ## 职责 -//! -//! - 启动插件进程并完成握手 -//! - 提供能力调用接口（一元和流式） -//! - 健康检查 -//! - 优雅关闭（先中止 peer 后台任务，再终止进程） -//! -//! ## 与 Runtime 的集成 -//! -//! `Supervisor` 实现了 `ManagedRuntimeComponent` trait， -//! 可以被 runtime 统一管理生命周期。 - -use std::sync::Arc; - -use astrcode_core::{ManagedRuntimeComponent, PluginManifest, Result}; -use astrcode_protocol::plugin::{ - CapabilityWireDescriptor, InitializeMessage, InitializeResultData, InvokeMessage, - PROTOCOL_VERSION, PeerDescriptor, ProfileDescriptor, ResultMessage, -}; -use async_trait::async_trait; -use serde_json::{Value, json}; -use tokio::sync::Mutex; -use uuid::Uuid; - -use crate::{CapabilityRouter, Peer, PluginProcess, StreamExecution}; - -/// 插件健康状态。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum SupervisorHealth { - /// 插件正常运行 - Healthy, - /// 插件不可用（进程退出或 peer 关闭） - Unavailable, -} - -/// 插件健康检查报告。 -/// -/// 包含健康状态和可选的描述信息。 -/// 当状态为 `Unavailable` 时，`message` 通常包含具体原因。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SupervisorHealthReport { - pub health: SupervisorHealth, - pub message: Option, -} - -/// 插件 Supervisor—— 管理插件的完整生命周期。 -/// -/// 作为插件系统的门面，封装了进程管理、通信和握手协商的所有细节。 -/// 调用方只需与 `Supervisor` 交互，无需直接操作 `PluginProcess` 或 `Peer`。 -pub struct Supervisor { - manifest_name: String, - process: Mutex>, - peer: Peer, - remote_initialize: InitializeResultData, -} - -impl Supervisor { - /// 启动插件并完成握手的便捷方法。 - /// - /// 等价于 `PluginProcess::start()` + `from_process()`。 - pub async fn start(manifest: &PluginManifest, local_peer: PeerDescriptor) -> Result { - let process = PluginProcess::start(manifest).await?; - Self::from_process(process, local_peer, None).await - } - - /// 从已有的进程创建 Supervisor 并完成握手。 - /// - /// # 流程 - /// - /// 1. 创建默认的 `CapabilityRouter`（用于处理插件→宿主的反向调用） - /// 2. 构建 `InitializeMessage`（使用默认值或自定义值） - /// 3. 创建 `Peer` 并启动读循环 - /// 4. 发送 `InitializeMessage` 并等待响应 - /// 5. 如果握手失败，终止进程并返回错误 - /// - /// # 错误处理 - /// - /// 如果 `initialize()` 失败，会先尝试终止进程再返回错误， - /// 避免留下僵尸进程。 - pub async fn from_process( - process: PluginProcess, - local_peer: PeerDescriptor, - local_initialize: Option, - ) -> Result { - let mut process = process; - let manifest_name = process.manifest.name.clone(); - let router = Arc::new(CapabilityRouter::default()); - let initialize = local_initialize.unwrap_or_else(|| { - default_initialize_message(local_peer, Vec::new(), default_profiles()) - }); - let peer = Peer::new(process.transport(), initialize, router); - let remote_initialize = match peer.initialize().await { - Ok(remote_initialize) => remote_initialize, - Err(error) => { - if let Err(shutdown_error) = process.shutdown().await { - log::warn!( - "failed to terminate plugin '{}' after initialize error: {}", - manifest_name, - shutdown_error - ); - } - return Err(error); - }, - }; - Ok(Self { - manifest_name, - process: Mutex::new(Some(process)), - peer, - remote_initialize, - }) - } - - /// 获取握手协商结果。 - /// - /// 返回插件声明的能力列表、支持的 profiles 和元数据。 - pub fn remote_initialize(&self) -> &InitializeResultData { - &self.remote_initialize - } - - /// 获取 Peer 的克隆。 - /// - /// 仅供内部使用（`pub(crate)`），外部应通过 `invoke()` 等方法间接使用。 - pub(crate) fn peer(&self) -> Peer { - self.peer.clone() - } - - /// 调用插件的某个能力（一元模式）。 - /// - /// 自动生成 UUID 作为请求 ID，设置 `stream: false`。 - pub async fn invoke( - &self, - capability: impl Into, - input: Value, - context: astrcode_protocol::plugin::InvocationContext, - ) -> Result { - self.peer - .invoke(InvokeMessage { - id: Uuid::new_v4().to_string(), - capability: capability.into(), - input, - context, - stream: false, - }) - .await - } - - /// 调用插件的某个能力（流式模式）。 - /// - /// 自动生成 UUID 作为请求 ID，设置 `stream: true`。 - /// 返回 `StreamExecution` 用于接收增量事件。 - pub async fn invoke_stream( - &self, - capability: impl Into, - input: Value, - context: astrcode_protocol::plugin::InvocationContext, - ) -> Result { - self.peer - .invoke_stream(InvokeMessage { - id: Uuid::new_v4().to_string(), - capability: capability.into(), - input, - context, - stream: true, - }) - .await - } - - /// 取消一个正在进行的请求。 - pub async fn cancel( - &self, - request_id: impl Into, - reason: Option, - ) -> Result<()> { - self.peer.cancel(request_id, reason).await - } - - /// 优雅关闭插件。 - /// - /// # 关闭顺序 - /// - /// 1. 中止 peer 的读循环和所有活跃的 invoke 处理器 - /// 2. 终止子进程 - /// - /// 这个顺序很重要：如果先终止进程，peer 的后台任务可能因为 - /// 传输层管道断裂而产生不可预期的行为。 - pub async fn shutdown(&self) -> Result<()> { - // Abort the read loop and any in-flight invoke handlers first, then - // terminate the child process. This order ensures the peer's background - // tasks don't linger after the process exits (which could cause the - // transport to hang if stdin/stdout pipes don't close promptly). - self.peer.abort().await; - // 持锁 await 修复：先 take() 出 PluginProcess 再 await shutdown， - // 避免在 MutexGuard 跨越 .await 期间持锁。 - if let Some(mut process) = self.process.lock().await.take() { - process.shutdown().await - } else { - Ok(()) - } - } - - /// 检查插件健康状态。 - /// - /// # 检查顺序 - /// - /// 1. 首先检查 peer 是否已关闭（协议层异常） - /// 2. 然后检查进程是否仍在运行（进程层异常） - /// - /// # 返回 - /// - /// - `Healthy` — 进程运行中且 peer 未关闭 - /// - `Unavailable` — peer 已关闭或进程已退出，`message` 包含具体原因 - pub async fn health_report(&self) -> Result { - if let Some(reason) = self.peer.closed_reason().await { - return Ok(SupervisorHealthReport { - health: SupervisorHealth::Unavailable, - message: Some(format!("protocol peer closed: {reason}")), - }); - } - - // process 为 None 表示已 shutdown，直接返回 Unavailable。 - let mut guard = self.process.lock().await; - let Some(process) = guard.as_mut() else { - return Ok(SupervisorHealthReport { - health: SupervisorHealth::Unavailable, - message: Some("plugin process has been shut down".to_string()), - }); - }; - let status = process.status()?; - if status.running { - Ok(SupervisorHealthReport { - health: SupervisorHealth::Healthy, - message: None, - }) - } else { - Ok(SupervisorHealthReport { - health: SupervisorHealth::Unavailable, - message: Some(match status.exit_code { - Some(code) => format!("plugin process exited with code {code}"), - None => "plugin process exited".to_string(), - }), - }) - } - } -} - -#[async_trait] -impl ManagedRuntimeComponent for Supervisor { - fn component_name(&self) -> String { - format!("plugin supervisor '{}'", self.manifest_name) - } - - async fn shutdown_component(&self) -> Result<()> { - self.shutdown().await - } -} - -/// 构建默认的 `InitializeMessage`。 -/// -/// 用于宿主向插件发送初始化请求。 -/// 包含本地 peer 信息、支持的能力、profiles 和传输元数据。 -/// -/// # 参数 -/// -/// * `local_peer` - 本地 peer 描述 -/// * `capabilities` - 本地支持的能力列表（宿主→插件的反向调用） -/// * `profiles` - 支持的 profile 列表 -pub fn default_initialize_message( - local_peer: PeerDescriptor, - capabilities: Vec, - profiles: Vec, -) -> InitializeMessage { - InitializeMessage { - id: Uuid::new_v4().to_string(), - protocol_version: PROTOCOL_VERSION.to_string(), - supported_protocol_versions: vec![PROTOCOL_VERSION.to_string()], - peer: local_peer, - capabilities, - handlers: Vec::new(), - profiles, - metadata: json!({ "transport": "stdio" }), - } -} - -/// 构建默认的 profiles 列表。 -/// -/// 当前只支持 `coding` profile，包含编码工作流的上下文 schema。 -pub fn default_profiles() -> Vec { - vec![ProfileDescriptor { - name: "coding".to_string(), - version: "1".to_string(), - description: "Coding workflow profile".to_string(), - context_schema: json!({ - "type": "object", - "properties": { - "workingDir": { "type": "string" }, - "repoRoot": { "type": "string" }, - "openFiles": { "type": "array", "items": { "type": "string" } }, - "activeFile": { "type": "string" }, - "selection": { "type": "object" }, - "approvalMode": { "type": "string" } - } - }), - metadata: Value::Null, - }] -} diff --git a/crates/plugin/src/transport/mod.rs b/crates/plugin/src/transport/mod.rs deleted file mode 100644 index 3484edb5..00000000 --- a/crates/plugin/src/transport/mod.rs +++ /dev/null @@ -1,27 +0,0 @@ -//! 插件传输层。 -//! -//! 本模块定义了插件宿主与插件进程之间的传输抽象。 -//! -//! ## 架构 -//! -//! `Transport` trait 定义了最基本的发送/接收接口， -//! 当前唯一的实现是 `StdioTransport`，通过标准输入输出进行 JSON-RPC 通信。 -//! -//! ## 扩展性 -//! -//! 未来可以添加其他传输实现（如 TCP、Unix socket 等）， -//! 只需实现 `Transport` trait 即可与现有的 `Peer` 兼容。 - -mod stdio; - -use async_trait::async_trait; -pub use stdio::StdioTransport; - -/// 插件宿主与插件进程之间的传输抽象。 -/// -/// Why: 传输是插件宿主实现细节，不属于协议 wire types。 -#[async_trait] -pub trait Transport: Send + Sync { - async fn send(&self, payload: &str) -> Result<(), String>; - async fn recv(&self) -> Result, String>; -} diff --git a/crates/plugin/src/transport/stdio.rs b/crates/plugin/src/transport/stdio.rs deleted file mode 100644 index 6657cb59..00000000 --- a/crates/plugin/src/transport/stdio.rs +++ /dev/null @@ -1,108 +0,0 @@ -//! 标准输入输出传输实现。 -//! -//! 通过 stdio 管道在宿主进程和插件进程之间传输 JSON-RPC 消息。 -//! -//! ## 协议 -//! -//! 每条消息是一个 JSON 字符串，以换行符（`\n`）结尾。 -//! 接收端按行读取，自动去除行尾的 `\r` 和 `\n`。 -//! -//! ## 线程安全 -//! -//! `writer` 和 `reader` 分别使用独立的 `Mutex` 保护， -//! 允许并发发送和接收（但不能同时有多个发送或接收）。 - -use std::pin::Pin; - -use async_trait::async_trait; -use tokio::{ - io::{self, AsyncBufRead, AsyncBufReadExt, AsyncWrite, AsyncWriteExt, BufReader}, - process::{ChildStdin, ChildStdout}, - sync::Mutex, -}; - -use super::Transport; - -/// 基于标准输入输出的传输实现。 -/// -/// 支持两种模式： -/// - **子进程模式** (`from_child`): 宿主进程管理子进程的 stdin/stdout -/// - **进程内模式** (`from_process_stdio`): 插件进程使用自己的 stdin/stdout 与宿主通信 -/// -/// # 注意 -/// -/// `writer` 和 `reader` 使用 `Pin>` 而非具体类型， -/// 因为两种模式使用的底层类型不同（`ChildStdin` vs `io::stdout`）。 -pub struct StdioTransport { - writer: Mutex>>, - reader: Mutex>>, -} - -impl StdioTransport { - /// 从子进程的 stdin/stdout 创建传输。 - /// - /// 用于宿主进程模式：宿主拥有子进程的 stdin/stdout 句柄， - /// 通过写入 stdin 发送消息，从 stdout 读取消息。 - pub fn from_child(stdin: ChildStdin, stdout: ChildStdout) -> Self { - Self { - writer: Mutex::new(Box::pin(stdin)), - reader: Mutex::new(Box::pin(BufReader::new(stdout))), - } - } - - /// 从当前进程的标准输入输出创建传输。 - /// - /// 用于插件进程模式：插件作为子进程运行，使用自己的 stdin/stdout - /// 与宿主通信。写入 stdout 发送消息给宿主，从 stdin 读取宿主消息。 - /// - /// # 注意 - /// - /// 方向是反直觉的：插件写入 stdout → 宿主从 stdout 读取， - /// 这是因为 stdout 是管道的一端，另一端由宿主持有。 - pub fn from_process_stdio() -> Self { - Self { - writer: Mutex::new(Box::pin(io::stdout())), - reader: Mutex::new(Box::pin(BufReader::new(io::stdin()))), - } - } -} - -#[async_trait] -impl Transport for StdioTransport { - /// 发送一条消息。 - /// - /// 将 payload 写入底层输出，追加换行符并 flush。 - /// flush 确保消息立即通过管道传递到对端。 - async fn send(&self, payload: &str) -> Result<(), String> { - let mut writer = self.writer.lock().await; - writer - .write_all(payload.as_bytes()) - .await - .map_err(|error| format!("failed to write plugin payload: {error}"))?; - writer - .write_all(b"\n") - .await - .map_err(|error| format!("failed to terminate plugin payload: {error}"))?; - writer - .flush() - .await - .map_err(|error| format!("failed to flush plugin payload: {error}")) - } - - /// 接收一条消息。 - /// - /// 按行读取，自动去除行尾的 `\r` 和 `\n`。 - /// 返回 `None` 表示输入流已关闭（对端退出或管道断裂）。 - async fn recv(&self) -> Result, String> { - let mut reader = self.reader.lock().await; - let mut line = String::new(); - let bytes = reader - .read_line(&mut line) - .await - .map_err(|error| format!("failed to read plugin payload: {error}"))?; - if bytes == 0 { - return Ok(None); - } - Ok(Some(line.trim_end_matches(['\r', '\n']).to_string())) - } -} diff --git a/crates/plugin/src/worker.rs b/crates/plugin/src/worker.rs deleted file mode 100644 index fa4ed248..00000000 --- a/crates/plugin/src/worker.rs +++ /dev/null @@ -1,84 +0,0 @@ -//! 插件 Worker—— 插件进程侧的入口。 -//! -//! 本模块提供 `Worker` 结构体，用于插件二进制文件的 main 函数。 -//! -//! ## 使用方式 -//! -//! 插件开发者在 `main()` 中： -//! 1. 创建 `CapabilityRouter` 并注册能力处理器 -//! 2. 调用 `Worker::from_stdio()` 创建 worker -//! 3. 调用 `worker.run()` 进入事件循环 -//! -//! ## 生命周期 -//! -//! `run()` 会阻塞直到宿主关闭连接（通过 `Peer::wait_closed()`）。 -//! 在此期间，worker 持续接收宿主的调用请求并返回结果。 - -use std::sync::Arc; - -use astrcode_core::Result; -use astrcode_protocol::plugin::{InitializeMessage, PeerDescriptor}; - -use crate::{CapabilityRouter, Peer, transport::StdioTransport}; - -/// 进程内插件 Worker—— 通过 stdio 与宿主进程通信。 -/// -/// 通常用于子进程模式下，插件二进制通过 `Worker::from_stdio()` 创建连接， -/// 然后进入 `run()` 循环直到连接关闭。 -/// -/// # 示例 -/// -/// ```ignore -/// let mut router = CapabilityRouter::default(); -/// router.register(MyHandler)?; -/// -/// let worker = Worker::from_stdio( -/// PeerDescriptor { /* ... */ }, -/// router, -/// None, -/// ); -/// worker.run().await?; -/// ``` -pub struct Worker { - peer: Peer, -} - -impl Worker { - /// 从标准输入输出创建 Worker。 - /// - /// # 参数 - /// - /// * `local_peer` - 本插件的描述信息（ID、名称、版本等） - /// * `router` - 能力路由器，包含所有已注册的能力处理器 - /// * `local_initialize` - 可选的自定义初始化消息；为 `None` 时使用默认值 - /// - /// # 注意 - /// - /// 此方法会自动将 router 中已注册的能力包含在初始化消息中， - /// 无需手动指定。 - pub fn from_stdio( - local_peer: PeerDescriptor, - router: CapabilityRouter, - local_initialize: Option, - ) -> Result { - let capabilities = router.capabilities()?; - let initialize = local_initialize.unwrap_or_else(|| { - crate::supervisor::default_initialize_message( - local_peer, - capabilities, - crate::supervisor::default_profiles(), - ) - }); - let transport = Arc::new(StdioTransport::from_process_stdio()); - let peer = Peer::new(transport, initialize, Arc::new(router)); - Ok(Self { peer }) - } - - /// 进入事件循环，持续处理宿主的调用请求。 - /// - /// 此方法会阻塞直到宿主关闭连接。通常作为插件 `main()` 的最后一个调用。 - pub async fn run(&self) -> Result<()> { - self.peer.wait_closed().await; - Ok(()) - } -} diff --git a/crates/plugin/tests/v4_stdio_e2e.rs b/crates/plugin/tests/v4_stdio_e2e.rs deleted file mode 100644 index 3ff9b4b6..00000000 --- a/crates/plugin/tests/v4_stdio_e2e.rs +++ /dev/null @@ -1,295 +0,0 @@ -use std::{sync::Arc, time::Duration}; - -use astrcode_core::{PluginManifest, PluginType, Result}; -use astrcode_plugin::{ - CapabilityRouter, Peer, PluginProcess, Supervisor, default_initialize_message, default_profiles, -}; -use astrcode_protocol::plugin::{ - EventPhase, InvocationContext, PeerDescriptor, PeerRole, WorkspaceRef, -}; -use serde_json::{Value, json}; -use tokio::time::{sleep, timeout}; - -fn fixture_manifest() -> PluginManifest { - PluginManifest { - name: "fixture-worker".to_string(), - version: "0.1.0".to_string(), - description: "Fixture worker for stdio e2e tests".to_string(), - plugin_type: vec![PluginType::Tool], - capabilities: vec![], - executable: Some(env!("CARGO_BIN_EXE_fixture_worker").to_string()), - args: Vec::new(), - working_dir: None, - repository: None, - } -} - -fn local_peer() -> PeerDescriptor { - PeerDescriptor { - id: "astrcode-supervisor".to_string(), - name: "astrcode-supervisor".to_string(), - role: PeerRole::Supervisor, - version: env!("CARGO_PKG_VERSION").to_string(), - supported_profiles: vec!["coding".to_string()], - metadata: json!({ "transport": "stdio" }), - } -} - -fn coding_context(request_id: &str) -> InvocationContext { - InvocationContext { - request_id: request_id.to_string(), - trace_id: Some(format!("trace-{request_id}")), - session_id: Some("session-1".to_string()), - caller: None, - workspace: Some(WorkspaceRef { - working_dir: Some("D:/workspace/project".to_string()), - repo_root: Some("D:/workspace/project".to_string()), - branch: Some("main".to_string()), - metadata: Value::Null, - }), - deadline_ms: Some(10_000), - budget: None, - profile: "coding".to_string(), - profile_context: json!({ - "workingDir": "D:/workspace/project", - "repoRoot": "D:/workspace/project", - "openFiles": ["D:/workspace/project/src/main.rs"], - "activeFile": "D:/workspace/project/src/main.rs", - "selection": { - "startLine": 1, - "startColumn": 1, - "endLine": 2, - "endColumn": 1 - }, - "approvalMode": "never" - }), - metadata: Value::Null, - } -} - -#[tokio::test] -async fn stdio_supervisor_initializes_and_invokes_unary_capability() -> Result<()> { - let manifest = fixture_manifest(); - let supervisor = Supervisor::start(&manifest, local_peer()).await?; - - assert_eq!(supervisor.remote_initialize().peer.role, PeerRole::Worker); - assert!( - supervisor - .remote_initialize() - .capabilities - .iter() - .any(|capability| capability.name.as_str() == "tool.echo") - ); - - let response = supervisor - .invoke( - "tool.echo", - json!({ "message": "hello" }), - coding_context("req-unary"), - ) - .await?; - assert!(response.success); - assert_eq!(response.output["message"], "hello"); - - supervisor.shutdown().await -} - -#[tokio::test] -async fn stdio_supervisor_streams_started_delta_completed_lifecycle() -> Result<()> { - let manifest = fixture_manifest(); - let supervisor = Supervisor::start(&manifest, local_peer()).await?; - let mut stream = supervisor - .invoke_stream( - "tool.patch_stream", - json!({ "path": "src/main.rs" }), - coding_context("req-stream"), - ) - .await?; - - let mut phases = Vec::new(); - let mut delta_events = Vec::new(); - while let Some(event) = stream.recv().await { - phases.push(event.phase.clone()); - if event.phase == EventPhase::Delta { - delta_events.push(event.event.clone()); - } - if matches!(event.phase, EventPhase::Completed | EventPhase::Failed) { - assert_eq!(event.payload["status"], "applied"); - break; - } - } - - assert_eq!(phases.first(), Some(&EventPhase::Started)); - assert!(delta_events.iter().all(|event| event == "artifact.patch")); - assert!(matches!(phases.last(), Some(EventPhase::Completed))); - - supervisor.shutdown().await -} - -#[tokio::test] -async fn stdio_supervisor_propagates_cancel_to_streaming_worker() -> Result<()> { - let manifest = fixture_manifest(); - let supervisor = Supervisor::start(&manifest, local_peer()).await?; - let mut stream = supervisor - .invoke_stream( - "tool.patch_stream", - json!({ "path": "src/lib.rs" }), - coding_context("req-cancel"), - ) - .await?; - let request_id = stream.request_id().to_string(); - - let mut saw_delta = false; - while let Some(event) = stream.recv().await { - if event.phase == EventPhase::Delta { - saw_delta = true; - supervisor - .cancel(request_id.clone(), Some("user interrupted".to_string())) - .await?; - } - if event.phase == EventPhase::Failed { - let error = event - .error - .expect("cancel failed event should include error"); - assert_eq!(error.code, "cancelled"); - break; - } - } - - assert!(saw_delta); - supervisor.shutdown().await -} - -#[tokio::test] -async fn stdio_peer_closes_pending_request_and_stream_when_process_dies() -> Result<()> { - let manifest = fixture_manifest(); - let mut process = PluginProcess::start(&manifest).await?; - let peer = Peer::new( - process.transport(), - default_initialize_message(local_peer(), Vec::new(), default_profiles()), - Arc::new(CapabilityRouter::default()), - ); - let remote = peer.initialize().await?; - assert_eq!(remote.peer.role, PeerRole::Worker); - - let unary_peer = peer.clone(); - let unary_task = tokio::spawn(async move { - unary_peer - .invoke(astrcode_protocol::plugin::InvokeMessage { - id: "req-close-unary".to_string(), - capability: "tool.delayed_echo".to_string(), - input: json!({ "message": "wait" }), - context: coding_context("req-close-unary"), - stream: false, - }) - .await - }); - - let mut stream = peer - .invoke_stream(astrcode_protocol::plugin::InvokeMessage { - id: "req-close-stream".to_string(), - capability: "tool.patch_stream".to_string(), - input: json!({ "path": "src/main.rs" }), - context: coding_context("req-close-stream"), - stream: true, - }) - .await?; - - sleep(Duration::from_millis(80)).await; - process.shutdown().await?; - - let unary = unary_task - .await - .expect("join unary") - .expect("invoke result"); - assert!(!unary.success); - assert_eq!( - unary.error.as_ref().expect("transport close error").code, - "transport_closed" - ); - - let mut terminal = None; - while let Some(event) = stream.recv().await { - if matches!(event.phase, EventPhase::Completed | EventPhase::Failed) { - terminal = Some(event); - break; - } - } - let terminal = terminal.expect("terminal stream event"); - assert_eq!(terminal.phase, EventPhase::Failed); - assert_eq!( - terminal.error.as_ref().expect("stream close error").code, - "transport_closed" - ); - - Ok(()) -} - -#[tokio::test] -async fn stdio_peer_abort_closes_pending_request_and_stream() -> Result<()> { - let manifest = fixture_manifest(); - let mut process = PluginProcess::start(&manifest).await?; - let peer = Peer::new( - process.transport(), - default_initialize_message(local_peer(), Vec::new(), default_profiles()), - Arc::new(CapabilityRouter::default()), - ); - let remote = peer.initialize().await?; - assert_eq!(remote.peer.role, PeerRole::Worker); - - let unary_peer = peer.clone(); - let unary_task = tokio::spawn(async move { - unary_peer - .invoke(astrcode_protocol::plugin::InvokeMessage { - id: "req-abort-unary".to_string(), - capability: "tool.delayed_echo".to_string(), - input: json!({ "message": "wait" }), - context: coding_context("req-abort-unary"), - stream: false, - }) - .await - }); - - let mut stream = peer - .invoke_stream(astrcode_protocol::plugin::InvokeMessage { - id: "req-abort-stream".to_string(), - capability: "tool.patch_stream".to_string(), - input: json!({ "path": "src/main.rs" }), - context: coding_context("req-abort-stream"), - stream: true, - }) - .await?; - - sleep(Duration::from_millis(80)).await; - peer.abort().await; - - let unary = timeout(Duration::from_secs(2), unary_task) - .await - .expect("unary invoke should resolve after peer abort") - .expect("join unary") - .expect("invoke result"); - assert!(!unary.success); - assert_eq!( - unary.error.as_ref().expect("transport close error").code, - "transport_closed" - ); - - let terminal = timeout(Duration::from_secs(2), async { - loop { - if let Some(event) = stream.recv().await { - if matches!(event.phase, EventPhase::Completed | EventPhase::Failed) { - return event; - } - } - } - }) - .await - .expect("stream should terminate after peer abort"); - assert_eq!(terminal.phase, EventPhase::Failed); - assert_eq!( - terminal.error.as_ref().expect("stream close error").code, - "transport_closed" - ); - - process.shutdown().await -} diff --git a/crates/protocol/src/http/composer.rs b/crates/protocol/src/http/composer.rs index e52c3da7..89f5cb40 100644 --- a/crates/protocol/src/http/composer.rs +++ b/crates/protocol/src/http/composer.rs @@ -1,14 +1,44 @@ //! 输入候选（composer options）相关 DTO。 //! -//! 单个候选项已经是跨层共享的 canonical 读模型，协议层直接复用 `core`； -//! 外层响应壳仍由 protocol 拥有。 +//! 单个候选项由 host-session 拥有；协议层保留同构 wire DTO， +//! 避免 protocol 反向依赖 runtime owner crate。 -pub use astrcode_core::{ - ComposerOption as ComposerOptionDto, ComposerOptionActionKind as ComposerOptionActionKindDto, - ComposerOptionKind as ComposerOptionKindDto, -}; use serde::{Deserialize, Serialize}; +/// 输入候选项的来源类别。 +#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)] +#[serde(rename_all = "snake_case")] +pub enum ComposerOptionKindDto { + Command, + Skill, + Capability, +} + +/// 输入候选项被选择后的动作类型。 +#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)] +#[serde(rename_all = "snake_case")] +pub enum ComposerOptionActionKindDto { + InsertText, + ExecuteCommand, +} + +/// 单个输入候选项的 wire DTO。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +pub struct ComposerOptionDto { + pub kind: ComposerOptionKindDto, + pub id: String, + pub title: String, + pub description: String, + pub insert_text: String, + pub action_kind: ComposerOptionActionKindDto, + pub action_value: String, + #[serde(default)] + pub badges: Vec, + #[serde(default)] + pub keywords: Vec, +} + /// 输入候选列表响应。 /// /// 预留响应外层对象而非直接返回数组，是为了后续在不破坏协议的前提下 diff --git a/crates/protocol/src/http/event.rs b/crates/protocol/src/http/event.rs index 2cedd7cf..915106b3 100644 --- a/crates/protocol/src/http/event.rs +++ b/crates/protocol/src/http/event.rs @@ -24,12 +24,19 @@ pub use astrcode_core::{ ParentDeliveryPayload as ParentDeliveryPayloadDto, ParentDeliveryTerminalSemantics as ParentDeliveryTerminalSemanticsDto, Phase as PhaseDto, ProgressParentDeliveryPayload as ProgressParentDeliveryPayloadDto, - ResolvedExecutionLimitsSnapshot as ResolvedExecutionLimitsDto, ResolvedSubagentContextOverrides as ResolvedSubagentContextOverridesDto, SubRunFailure as SubRunFailureDto, SubRunFailureCode as SubRunFailureCodeDto, SubRunHandoff as SubRunHandoffDto, ToolOutputStream as ToolOutputStreamDto, }; +/// `resolvedLimits` 是 presence marker。 +/// +/// 不能直接复用 unit struct，否则 `Option` 会被序列化成 `null`， +/// 反序列化后无法区分 `Some` 与 `None`。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +#[serde(rename_all = "camelCase")] +pub struct ResolvedExecutionLimitsDto {} + #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum SubRunOutcomeDto { diff --git a/crates/protocol/src/http/runtime.rs b/crates/protocol/src/http/runtime.rs index 8de733f0..9f0c67f5 100644 --- a/crates/protocol/src/http/runtime.rs +++ b/crates/protocol/src/http/runtime.rs @@ -6,13 +6,31 @@ pub use astrcode_core::{ AgentCollaborationScorecardSnapshot as AgentCollaborationScorecardDto, ExecutionDiagnosticsSnapshot as ExecutionDiagnosticsDto, - OperationMetricsSnapshot as OperationMetricsDto, PluginHealth as PluginHealthDto, - PluginState as PluginRuntimeStateDto, ReplayMetricsSnapshot as ReplayMetricsDto, + OperationMetricsSnapshot as OperationMetricsDto, ReplayMetricsSnapshot as ReplayMetricsDto, RuntimeObservabilitySnapshot as RuntimeMetricsDto, SubRunExecutionMetricsSnapshot as SubRunExecutionMetricsDto, }; use serde::{Deserialize, Serialize}; +/// 插件生命周期状态 wire DTO。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum PluginRuntimeStateDto { + Discovered, + Initialized, + Failed, +} + +/// 插件健康状态 wire DTO。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum PluginHealthDto { + Unknown, + Healthy, + Degraded, + Unavailable, +} + /// 运行时能力的摘要信息。 /// /// 用于 `GET /api/runtime/status` 响应中列出 runtime 暴露的所有能力。 diff --git a/crates/protocol/src/http/session_event.rs b/crates/protocol/src/http/session_event.rs index 1fe04370..05f4fde8 100644 --- a/crates/protocol/src/http/session_event.rs +++ b/crates/protocol/src/http/session_event.rs @@ -1,13 +1,31 @@ //! 会话目录事件 DTO。 //! -//! 目录事件载荷已经是共享语义，协议层直接复用 `core`； -//! 外层信封仍由 protocol 拥有。 +//! 目录事件载荷由 host-session 拥有；协议层保留同构 wire DTO， +//! 避免 protocol 反向依赖 runtime owner crate。 -pub use astrcode_core::SessionCatalogEvent as SessionCatalogEventPayload; use serde::{Deserialize, Serialize}; use crate::http::PROTOCOL_VERSION; +/// 会话目录事件 wire DTO。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase", tag = "event", content = "data")] +pub enum SessionCatalogEventPayload { + SessionCreated { + session_id: String, + }, + SessionDeleted { + session_id: String, + }, + ProjectDeleted { + working_dir: String, + }, + SessionBranched { + session_id: String, + source_session_id: String, + }, +} + /// 会话目录事件信封。 /// /// 为事件载荷添加协议版本号，确保前端可以验证兼容性。 diff --git a/crates/sdk/Cargo.toml b/crates/sdk/Cargo.toml deleted file mode 100644 index 706592ef..00000000 --- a/crates/sdk/Cargo.toml +++ /dev/null @@ -1,13 +0,0 @@ -[package] -name = "astrcode-sdk" -version = "0.1.0" -edition.workspace = true -license-file.workspace = true -authors.workspace = true - -[dependencies] -astrcode-core = { path = "../core" } -astrcode-protocol = { path = "../protocol" } -serde.workspace = true -serde_json.workspace = true -thiserror.workspace = true diff --git a/crates/sdk/src/context.rs b/crates/sdk/src/context.rs deleted file mode 100644 index 882d92b5..00000000 --- a/crates/sdk/src/context.rs +++ /dev/null @@ -1,190 +0,0 @@ -//! 插件上下文数据模型。 -//! -//! 本模块定义了插件在执行工具或钩子时可访问的上下文信息， -//! 包括工作区状态、编码配置文件（coding profile）以及请求追踪元数据。 -//! -//! ## 设计意图 -//! -//! 插件不应直接访问宿主运行时内部状态，而是通过 `PluginContext` 获取 -//! 与当前调用相关的快照。这保证了插件的可测试性和隔离性。 -//! -//! ## 上下文层次 -//! -//! - **WorkspaceContext**: 文件系统级别的工作区信息（工作目录、仓库根目录、分支） -//! - **CodingProfileContext**: 编辑器状态（打开的文件、选中区域、审批模式） -//! - **PluginContext**: 顶层上下文，聚合上述信息并附加请求/会话/追踪 ID - -use serde::{Deserialize, Serialize}; -use serde_json::Value; - -/// 工作区级别的上下文信息。 -/// -/// 提供插件执行时所需的文件系统环境快照， -/// 使工具能够正确解析相对路径或感知当前 Git 状态。 -#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct WorkspaceContext { - /// 当前工作目录的绝对路径。 - /// - /// 工具应以此为基础解析相对路径，而非依赖进程 CWD。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub working_dir: Option, - /// Git 仓库根目录的绝对路径。 - /// - /// 当工作区不在 Git 仓库中时为 `None`。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub repo_root: Option, - /// 当前 Git 分支名称。 - /// - /// 非 Git 仓库或 detached HEAD 状态下为 `None`。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub branch: Option, -} - -/// 编辑器中的文本选区。 -/// -/// 用于标识用户在编辑器中选中了哪段代码， -/// 行号从 1 开始，列号从 1 开始（如果提供）。 -#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct TextSelection { - /// 选区起始行号（1-based）。 - pub start_line: u64, - /// 选区起始列号（1-based），未指定时表示整行。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub start_column: Option, - /// 选区结束行号（1-based）。 - pub end_line: u64, - /// 选区结束列号（1-based），未指定时表示整行。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub end_column: Option, -} - -/// 编码配置文件（coding profile）的上下文信息。 -/// -/// 当插件在 "coding" 模式下被调用时，此结构体包含编辑器当前的状态快照， -/// 使工具能够感知用户正在查看的文件、选中的代码段等上下文。 -/// -/// ## 为什么使用 `extras: Value` -/// -/// 编码配置文件可能随版本演进增加新字段，`extras` 作为扩展点 -/// 容纳未显式建模的字段，避免反序列化失败。 -#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct CodingProfileContext { - /// 当前工作目录的绝对路径。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub working_dir: Option, - /// Git 仓库根目录的绝对路径。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub repo_root: Option, - /// 当前在编辑器中打开的文件路径列表。 - #[serde(default)] - pub open_files: Vec, - /// 当前活动（焦点所在）的文件路径。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub active_file: Option, - /// 用户在活动文件中的文本选区（如果有）。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub selection: Option, - /// 当前的审批模式（如 "auto", "approve-each" 等）。 - #[serde(default, skip_serializing_if = "Option::is_none")] - pub approval_mode: Option, - /// 扩展字段，容纳未来可能新增的配置文件属性。 - #[serde(default)] - pub extras: Value, -} - -/// 插件调用上下文。 -/// -/// 这是插件在执行工具或钩子时接收到的完整上下文快照， -/// 包含请求追踪信息、工作区状态和当前配置文件。 -/// -/// ## 生命周期 -/// -/// 每次工具调用都会创建一个新的 `PluginContext` 实例， -/// 插件不应跨调用缓存此结构体，因为其中的状态可能已过期。 -/// -/// ## 从协议类型转换 -/// -/// 实现了 `From`，由运行时在调用插件前自动转换， -/// 插件作者无需关心协议层细节。 -#[derive(Debug, Clone, PartialEq)] -pub struct PluginContext { - /// 本次请求的唯一标识符。 - /// - /// 用于日志关联和调试，贯穿整个请求链路。 - pub request_id: String, - /// 会话 ID（如果存在）。 - /// - /// 标识本次调用所属的对话会话，可用于会话级别的缓存或状态管理。 - pub session_id: Option, - /// 分布式追踪 ID（如果存在）。 - /// - /// 用于跨服务追踪，将插件调用与 LLM 请求、工具执行等关联起来。 - pub trace_id: Option, - /// 工作区上下文快照。 - /// - /// 当调用不涉及工作区时（如纯计算工具）可能为 `None`。 - pub workspace: Option, - /// 当前配置文件名称（如 "coding"、"planning" 等）。 - /// - /// 插件可据此调整行为，例如在 "coding" 模式下感知编辑器状态。 - pub profile: String, - /// 配置文件的原始 JSON 上下文。 - /// - /// 通过 `coding_profile()` 方法可尝试解析为 `CodingProfileContext`。 - pub profile_context: Value, -} - -impl Default for PluginContext { - /// 创建空的插件上下文。 - /// - /// 主要用于测试和默认值场景，实际调用中上下文由运行时注入。 - fn default() -> Self { - Self { - request_id: String::new(), - session_id: None, - trace_id: None, - workspace: None, - profile: "coding".to_string(), - profile_context: Value::Null, - } - } -} - -impl PluginContext { - /// 尝试将配置文件上下文解析为 `CodingProfileContext`。 - /// - /// 仅当 `profile` 字段为 `"coding"` 时返回 `Some`， - /// 其他配置文件模式（如 "planning"）返回 `None`。 - /// - /// ## 为什么返回 Option 而不是 Result - /// - /// 配置文件不匹配不是错误，而是正常的业务分支。 - /// 反序列化失败也被静默吞掉，因为 `extras` 字段已容纳未知数据， - /// 真正的结构不匹配意味着协议版本不一致，应由上层处理。 - pub fn coding_profile(&self) -> Option { - if self.profile != "coding" { - return None; - } - serde_json::from_value(self.profile_context.clone()).ok() - } -} - -impl From for PluginContext { - fn from(value: astrcode_protocol::plugin::InvocationContext) -> Self { - Self { - request_id: value.request_id, - session_id: value.session_id, - trace_id: value.trace_id, - workspace: value.workspace.map(|workspace| WorkspaceContext { - working_dir: workspace.working_dir, - repo_root: workspace.repo_root, - branch: workspace.branch, - }), - profile: value.profile, - profile_context: value.profile_context, - } - } -} diff --git a/crates/sdk/src/error.rs b/crates/sdk/src/error.rs deleted file mode 100644 index c1a4d84e..00000000 --- a/crates/sdk/src/error.rs +++ /dev/null @@ -1,340 +0,0 @@ -//! SDK 错误类型体系。 -//! -//! 本模块定义了插件 SDK 的统一错误类型 `SdkError`， -//! 覆盖工具执行生命周期中可能出现的所有错误场景。 -//! -//! ## 设计原则 -//! -//! - **分类明确**: 每种错误变体对应一种失败模式，调用方可据此决定重试或降级策略 -//! - **可序列化**: 所有错误都能转换为 `ErrorPayload` 发送给前端或协议层 -//! - **便捷构造**: 提供语义化的构造函数（如 `SdkError::validation()`），避免手动拼凑变体 -//! -//! ## 错误分类 -//! -//! | 变体 | 触发场景 | 可重试 | -//! |------|---------|--------| -//! | `Serde` | 输入解码或输出编码失败 | 否 | -//! | `Validation` | 工具输入校验不通过 | 否 | -//! | `PermissionDenied` | 策略钩子拒绝执行 | 否 | -//! | `Cancelled` | 请求被取消 | 否 | -//! | `Io` | 文件系统或网络 I/O 失败 | 视情况 | -//! | `StreamEmit` | 流式事件发送失败 | 视情况 | -//! | `Internal` | 插件内部未预期错误 | 由 `retriable` 标记 | - -use astrcode_protocol::plugin::ErrorPayload; -use serde_json::Value; -use thiserror::Error; - -/// 标识序列化/反序列化失败发生在工具执行的哪个阶段。 -/// -/// 用于错误消息中准确描述是"解码输入"还是"编码输出"出了问题， -/// 帮助插件作者快速定位问题方向。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ToolSerdeStage { - /// 将 JSON 输入反序列化为工具期望的 Rust 类型时失败。 - DecodeInput, - /// 将工具返回的 Rust 类型序列化为 JSON 输出时失败。 - EncodeOutput, -} - -impl ToolSerdeStage { - /// 返回该阶段的人类可读描述，用于错误消息拼接。 - pub fn action(self) -> &'static str { - match self { - Self::DecodeInput => "decode input", - Self::EncodeOutput => "encode output", - } - } -} - -/// SDK 统一错误类型。 -/// -/// 覆盖插件工具执行生命周期中的所有错误场景， -/// 每个变体都携带足够的上下文信息用于调试和前端展示。 -/// -/// ## 错误码映射 -/// -/// 通过 `code()` 方法可获取机器可读的错误码， -/// 用于前端根据错误类型采取不同的 UI 展示策略。 -#[derive(Debug, Clone, PartialEq, Error)] -pub enum SdkError { - /// 序列化/反序列化失败。 - /// - /// 发生在工具输入解码或输出编码阶段， - /// 通常意味着插件定义的输入/输出类型与实际传输的 JSON 不匹配。 - #[error( - "tool '{capability}' failed to {action} as {rust_type}: {message}", - action = .stage.action() - )] - Serde { - /// 工具/能力名称。 - capability: String, - /// 失败发生的阶段。 - stage: ToolSerdeStage, - /// 涉及的 Rust 类型名称。 - rust_type: &'static str, - /// 底层 serde_json 的错误消息。 - message: String, - }, - /// 输入校验失败。 - /// - /// 工具在执行业务逻辑前发现输入不符合预期， - /// 例如必填字段缺失、值超出合法范围等。 - #[error("validation failed: {message}")] - Validation { - /// 人类可读的错误描述。 - message: String, - /// 结构化的错误详情，可包含字段级错误等信息。 - details: Value, - }, - /// 权限被策略钩子拒绝。 - /// - /// 插件注册的 `PolicyHook` 在工具执行前返回了 deny 决策。 - #[error("permission denied: {message}")] - PermissionDenied { - /// 拒绝原因。 - message: String, - /// 策略钩子附加的额外信息。 - details: Value, - }, - /// 请求被取消。 - /// - /// 用户主动取消或超时导致工具执行被中止。 - #[error("request cancelled")] - Cancelled, - /// I/O 操作失败。 - /// - /// 文件读写、网络请求等底层 I/O 错误。 - #[error("i/o error: {message}")] - Io { - /// 底层 I/O 错误的描述。 - message: String, - }, - /// 流式事件发送失败。 - /// - /// 通过 `StreamWriter` 发送增量输出时发生错误， - /// 可能是回调函数返回错误或内部状态异常。 - #[error("stream emission failed for event '{event}': {message}")] - StreamEmit { - /// 事件名称。 - event: String, - /// 错误描述。 - message: String, - /// 附加的错误上下文。 - details: Value, - }, - /// 插件内部未预期的错误。 - /// - /// 不属于以上分类的兜底错误，通常表示代码中的 bug 或 - /// 未处理的边界情况。可通过 `retriable` 标记建议是否重试。 - #[error("internal error: {message}")] - Internal { - /// 错误描述。 - message: String, - /// 结构化的错误详情。 - details: Value, - /// 是否建议重试。 - retriable: bool, - }, -} - -impl SdkError { - /// 构造输入解码失败的错误。 - /// - /// 当工具无法将传入的 JSON 解析为期望的 Rust 类型时调用。 - pub fn decode_input( - capability: impl Into, - rust_type: &'static str, - source: serde_json::Error, - ) -> Self { - Self::Serde { - capability: capability.into(), - stage: ToolSerdeStage::DecodeInput, - rust_type, - message: source.to_string(), - } - } - - /// 构造输出编码失败的错误。 - /// - /// 当工具返回的 Rust 值无法序列化为 JSON 时调用。 - pub fn encode_output( - capability: impl Into, - rust_type: &'static str, - source: serde_json::Error, - ) -> Self { - Self::Serde { - capability: capability.into(), - stage: ToolSerdeStage::EncodeOutput, - rust_type, - message: source.to_string(), - } - } - - /// 构造输入校验失败的错误。 - /// - /// 用于工具在业务逻辑执行前发现输入不合法的场景， - /// 例如参数超出范围、必填字段缺失等。 - pub fn validation(message: impl Into) -> Self { - Self::Validation { - message: message.into(), - details: Value::Null, - } - } - - /// 构造权限拒绝的错误。 - /// - /// 通常由策略钩子调用，表示当前操作不被允许。 - pub fn permission_denied(message: impl Into) -> Self { - Self::PermissionDenied { - message: message.into(), - details: Value::Null, - } - } - - /// 构造请求取消的错误。 - /// - /// 表示用户主动取消或超时导致工具执行被中止。 - pub fn cancelled() -> Self { - Self::Cancelled - } - - /// 从 `std::io::Error` 构造 I/O 错误。 - pub fn io(error: std::io::Error) -> Self { - Self::Io { - message: error.to_string(), - } - } - - /// 构造内部错误。 - /// - /// 用于不属于其他分类的兜底错误，通常表示未预期的异常。 - /// 默认 `retriable` 为 `false`，如需标记为可重试请使用 `details` 变体。 - pub fn internal(message: impl Into) -> Self { - Self::Internal { - message: message.into(), - details: Value::Null, - retriable: false, - } - } - - /// 构造流式事件发送失败的错误。 - /// - /// 当通过 `StreamWriter` 发送增量输出失败时调用。 - pub fn stream_emit(event: impl Into, message: impl Into) -> Self { - Self::StreamEmit { - event: event.into(), - message: message.into(), - details: Value::Null, - } - } - - /// 返回机器可读的错误码。 - /// - /// 用于前端或协议层根据错误类型采取不同的处理策略， - /// 例如 `validation_error` 显示表单错误，`io_error` 提示重试等。 - pub fn code(&self) -> &'static str { - match self { - Self::Serde { stage, .. } => match stage { - ToolSerdeStage::DecodeInput => "invalid_input", - ToolSerdeStage::EncodeOutput => "invalid_output", - }, - Self::Validation { .. } => "validation_error", - Self::PermissionDenied { .. } => "permission_denied", - Self::Cancelled => "cancelled", - Self::Io { .. } => "io_error", - Self::StreamEmit { .. } => "stream_error", - Self::Internal { .. } => "internal_error", - } - } - - /// 返回该错误是否建议重试。 - /// - /// 仅 `Internal` 变体可标记为可重试，其他错误类型默认不可重试， - /// 因为重试相同输入大概率会得到相同结果。 - pub fn retriable(&self) -> bool { - match self { - Self::Internal { retriable, .. } => *retriable, - _ => false, - } - } - - /// 返回结构化的错误详情。 - /// - /// 对于 `Serde` 错误，详情包含 capability、stage、rustType 等诊断信息； - /// 对于其他变体，返回构造时传入的 `details` 字段。 - pub fn details(&self) -> Value { - match self { - Self::Serde { - capability, - stage, - rust_type, - message, - } => Value::Object(serde_json::Map::from_iter([ - ("capability".to_string(), Value::String(capability.clone())), - ( - "stage".to_string(), - Value::String( - match stage { - ToolSerdeStage::DecodeInput => "decode_input", - ToolSerdeStage::EncodeOutput => "encode_output", - } - .to_string(), - ), - ), - ( - "rustType".to_string(), - Value::String((*rust_type).to_string()), - ), - ("message".to_string(), Value::String(message.clone())), - ])), - Self::Validation { details, .. } - | Self::PermissionDenied { details, .. } - | Self::StreamEmit { details, .. } - | Self::Internal { details, .. } => details.clone(), - Self::Cancelled | Self::Io { .. } => Value::Null, - } - } - - /// 将错误转换为协议层的 `ErrorPayload`。 - /// - /// 用于将 SDK 内部错误序列化为可传输的格式， - /// 发送给前端或写入事件日志。 - pub fn to_error_payload(&self) -> ErrorPayload { - ErrorPayload { - code: self.code().to_string(), - message: self.to_string(), - details: self.details(), - retriable: self.retriable(), - } - } -} - -impl From for SdkError { - fn from(value: std::io::Error) -> Self { - Self::io(value) - } -} - -impl From for SdkError { - fn from(value: serde_json::Error) -> Self { - Self::Serde { - capability: "unknown".to_string(), - stage: ToolSerdeStage::DecodeInput, - rust_type: "unknown", - message: value.to_string(), - } - } -} - -impl From for SdkError { - fn from(value: String) -> Self { - Self::internal(value) - } -} - -impl From<&str> for SdkError { - fn from(value: &str) -> Self { - Self::internal(value) - } -} diff --git a/crates/sdk/src/hook.rs b/crates/sdk/src/hook.rs deleted file mode 100644 index 0308a24d..00000000 --- a/crates/sdk/src/hook.rs +++ /dev/null @@ -1,298 +0,0 @@ -//! # 插件策略钩子 (Plugin Policy Hooks) -//! -//! 提供插件内策略决策工具函数，用于编写可复用的允许/拒绝检查。 -//! -//! ## 核心类型 -//! - `PolicyDecision`: 策略决策结果，包含允许/拒绝标志、原因和附加元数据 -//! - `PolicyHook`: 策略钩子接口，包含 `before_invoke` 决策点和可选的短路语义 -//! -//! ## 与运行时策略的区别 -//! -//! 这些钩子有意设计得比宿主运行时全局策略更窄，只关注插件本地的 allow/deny 检查。 -//! 全局策略还覆盖审批流程、上下文压力和模型请求重写等能力。 - -use std::sync::Arc; - -use astrcode_core::CapabilitySpec; -use serde_json::Value; - -use crate::{PluginContext, SdkError}; - -/// 策略决策结果。 -/// -/// 由 `PolicyHook::before_invoke` 返回， -/// 决定工具是否被允许执行。 -/// -/// ## 默认语义 -/// -/// 多个钩子串联时，最后一个钩子的决策为最终结果（除非配置了短路）。 -/// 短路模式下，第一个 deny 会立即终止后续钩子执行。 -#[derive(Debug, Clone, PartialEq)] -pub struct PolicyDecision { - /// 是否允许执行。 - /// - /// `true` 表示放行，`false` 表示拒绝。 - pub allowed: bool, - /// 拒绝原因（仅在 `allowed = false` 时有意义）。 - pub reason: Option, - /// 附加的元数据，可包含结构化信息供前端展示或日志记录。 - pub metadata: Value, -} - -impl PolicyDecision { - /// 构造允许的决策。 - /// - /// 默认不带原因和元数据，钩子可在后续链中附加信息。 - pub fn allow() -> Self { - Self { - allowed: true, - reason: None, - metadata: Value::Null, - } - } - - /// 构造拒绝的决策。 - /// - /// `reason` 会展示给用户或记录到日志中， - /// 应清晰说明拒绝的具体原因。 - pub fn deny(reason: impl Into) -> Self { - Self { - allowed: false, - reason: Some(reason.into()), - metadata: Value::Null, - } - } -} - -/// A lightweight pre-invocation guard around plugin-owned capabilities. -/// -/// Use this for plugin-local validation and gating. Host-level approval, sandbox, or runtime -/// policy should stay in the host runtime rather than being reimplemented here. -pub trait PolicyHook: Send + Sync { - fn before_invoke(&self, capability: &CapabilitySpec, context: &PluginContext) - -> PolicyDecision; -} - -/// 钩子短路策略。 -/// -/// 控制 `PolicyHookChain` 在遇到 deny 决策时的行为。 -#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] -pub enum HookShortCircuit { - /// 永不短路，始终执行所有钩子。 - /// - /// 适用于需要收集所有钩子诊断信息的场景。 - Never, - /// 遇到第一个 deny 时立即停止。 - /// - /// 默认行为，因为策略检查通常采用"一票否决"原则， - /// 一旦有钩子拒绝，后续检查无意义且浪费资源。 - #[default] - OnDeny, -} - -/// 已注册的策略钩子包装器。 -/// -/// 将钩子名称与实现绑定，使用 `Arc` 包装以支持 -/// 在 `PolicyHookChain` 中共享而无需克隆实现。 -#[derive(Clone)] -pub struct RegisteredPolicyHook { - name: String, - hook: Arc, -} - -impl RegisteredPolicyHook { - /// 返回钩子名称。 - /// - /// 用于日志记录和错误消息中标识是哪个钩子做出的决策。 - pub fn name(&self) -> &str { - &self.name - } - - /// 返回钩子实现的引用。 - pub fn hook(&self) -> &dyn PolicyHook { - self.hook.as_ref() - } -} - -/// 策略钩子注册表。 -/// -/// 管理插件内注册的所有策略钩子， -/// 提供 builder 风格（`with_policy_hook`）和可变风格（`register_policy_hook`）两种 API。 -/// -/// ## 为什么需要注册表 -/// -/// 插件可能有多个工具需要共享同一组策略检查（如路径白名单、 -/// 权限验证）。注册表允许一次注册、多处复用， -/// 并通过 `policy_hook_chain()` 快速构建执行链。 -#[derive(Clone, Default)] -pub struct HookRegistry { - policy_hooks: Vec, -} - -impl HookRegistry { - /// 注册一个策略钩子。 - /// - /// ## 参数 - /// - /// - `name`: 钩子名称，用于日志和错误消息标识 - /// - `hook`: 策略钩子实现 - /// - /// ## 错误 - /// - /// 如果名称已存在或为空，返回 `SdkError::Validation`。 - pub fn register_policy_hook( - &mut self, - name: impl Into, - hook: H, - ) -> Result<&mut Self, SdkError> - where - H: PolicyHook + 'static, - { - let name = normalize_hook_name(name)?; - if self - .policy_hooks - .iter() - .any(|registered| registered.name == name) - { - return Err(SdkError::validation(format!( - "duplicate policy hook registration '{name}'" - ))); - } - self.policy_hooks.push(RegisteredPolicyHook { - name, - hook: Arc::new(hook), - }); - Ok(self) - } - - /// 以 builder 风格注册策略钩子。 - /// - /// 与 `register_policy_hook` 功能相同， - /// 但返回 `Self` 而非 `&mut Self`，支持链式调用。 - pub fn with_policy_hook(mut self, name: impl Into, hook: H) -> Result - where - H: PolicyHook + 'static, - { - self.register_policy_hook(name, hook)?; - Ok(self) - } - - /// 返回所有已注册的策略钩子。 - pub fn policy_hooks(&self) -> &[RegisteredPolicyHook] { - &self.policy_hooks - } - - /// 从当前注册表构建策略钩子执行链。 - /// - /// 返回的 `PolicyHookChain` 包含所有已注册钩子的克隆引用， - /// 可独立配置短路策略而不影响原始注册表。 - pub fn policy_hook_chain(&self) -> PolicyHookChain { - // Registry owns hooks by Arc so plugin authors can build reusable chains - // without moving or reconstructing the original registrations. - PolicyHookChain { - hooks: self.policy_hooks.clone(), - short_circuit: HookShortCircuit::default(), - } - } -} - -/// 策略钩子执行链。 -/// -/// 将多个 `PolicyHook` 组合为一个可顺序执行的链， -/// 每个钩子依次对工具调用进行前置检查。 -/// -/// ## 执行语义 -/// -/// - 默认短路模式：第一个 deny 立即终止链，返回该 deny 决策 -/// - 非短路模式：执行所有钩子，返回最后一个钩子的决策 -/// -/// `PolicyHookChain` 自身也实现 `PolicyHook`，因此可以嵌套组合。 -#[derive(Clone, Default)] -pub struct PolicyHookChain { - hooks: Vec, - short_circuit: HookShortCircuit, -} - -impl PolicyHookChain { - /// 配置短路策略。 - /// - /// 返回新的 `PolicyHookChain`（builder 风格）， - /// 不影响原实例。 - pub fn with_short_circuit(mut self, short_circuit: HookShortCircuit) -> Self { - self.short_circuit = short_circuit; - self - } - - /// 注册一个策略钩子到此链。 - /// - /// 与 `HookRegistry::register_policy_hook` 类似， - /// 但钩子仅加入此链，不影响注册表。 - pub fn register(&mut self, name: impl Into, hook: H) -> Result<&mut Self, SdkError> - where - H: PolicyHook + 'static, - { - let name = normalize_hook_name(name)?; - if self.hooks.iter().any(|registered| registered.name == name) { - return Err(SdkError::validation(format!( - "duplicate policy hook registration '{name}'" - ))); - } - self.hooks.push(RegisteredPolicyHook { - name, - hook: Arc::new(hook), - }); - Ok(self) - } - - /// 以 builder 风格注册钩子。 - pub fn with_hook(mut self, name: impl Into, hook: H) -> Result - where - H: PolicyHook + 'static, - { - self.register(name, hook)?; - Ok(self) - } - - /// 返回链中所有已注册的钩子。 - pub fn hooks(&self) -> &[RegisteredPolicyHook] { - &self.hooks - } - - /// 返回当前的短路策略。 - pub fn short_circuit(&self) -> HookShortCircuit { - self.short_circuit - } -} - -impl PolicyHook for PolicyHookChain { - fn before_invoke( - &self, - capability: &CapabilitySpec, - context: &PluginContext, - ) -> PolicyDecision { - let mut final_decision = PolicyDecision::allow(); - for registered in &self.hooks { - let decision = registered.hook.before_invoke(capability, context); - // Policies default to fail-fast on deny so a guard hook can veto the - // invocation before later hooks add more permissive behavior. - let should_stop = - matches!(self.short_circuit, HookShortCircuit::OnDeny) && !decision.allowed; - final_decision = decision; - if should_stop { - break; - } - } - final_decision - } -} - -fn normalize_hook_name(name: impl Into) -> Result { - let name = name.into(); - let trimmed = name.trim(); - if trimmed.is_empty() { - return Err(SdkError::validation( - "policy hook registration requires a non-empty name", - )); - } - Ok(trimmed.to_string()) -} diff --git a/crates/sdk/src/lib.rs b/crates/sdk/src/lib.rs deleted file mode 100644 index fed4d5c8..00000000 --- a/crates/sdk/src/lib.rs +++ /dev/null @@ -1,84 +0,0 @@ -//! # Astrcode 插件 SDK -//! -//! 本库为插件开发者提供 Rust SDK，用于编写 Astrcode 插件。 -//! -//! ## 架构定位 -//! -//! SDK 是插件与 Astrcode 运行时之间的桥梁。插件通过 SDK 注册工具、 -//! 定义策略钩子、访问调用上下文和发送流式响应，而无需直接依赖 -//! `core` 或 `runtime` crate。 -//! -//! ## 核心功能 -//! -//! - **ToolHandler**: 定义工具的处理逻辑，支持类型安全的输入/输出 -//! - **HookRegistry**: 注册策略钩子（如权限检查、路径白名单） -//! - **PluginContext**: 访问插件调用上下文（工作目录、编辑器状态等） -//! - **StreamWriter**: 流式响应写入，支持增量输出到前端 -//! -//! ## 快速开始 -//! -//! ```ignore -//! use astrcode_sdk::{ToolHandler, ToolRegistration, ToolFuture, PluginContext, StreamWriter}; -//! use astrcode_sdk::{CapabilityKind, CapabilitySpec, SideEffect}; -//! use serde::{Deserialize, Serialize}; -//! -//! // 1. 定义工具的输入/输出类型 -//! #[derive(Deserialize)] -//! struct GreetInput { name: String } -//! -//! #[derive(Serialize)] -//! struct GreetOutput { message: String } -//! -//! // 2. 实现 ToolHandler -//! struct GreetTool; -//! -//! impl ToolHandler for GreetTool { -//! fn descriptor(&self) -> CapabilitySpec { -//! CapabilitySpec::builder("greet", CapabilityKind::Tool) -//! .description("向指定用户打招呼") -//! .schema(serde_json::json!({ "type": "object" }), serde_json::json!({ "type": "object" })) -//! .side_effect(SideEffect::None) -//! .build() -//! .unwrap() -//! } -//! -//! fn execute(&self, input: GreetInput, _ctx: PluginContext, _stream: StreamWriter) -> ToolFuture<'_, GreetOutput> { -//! Box::pin(async move { -//! Ok(GreetOutput { message: format!("Hello, {}!", input.name) }) -//! }) -//! } -//! } -//! -//! // 3. 注册工具 -//! let registration = ToolRegistration::new(GreetTool); -//! ``` -//! -//! ## Crate 依赖 -//! -//! SDK 依赖 `protocol`（DTO 类型）和 `core`（接口定义）， -//! 但插件作者无需关心这些内部依赖，SDK 会 re-export 必要的类型。 - -mod context; -mod error; -mod hook; -mod stream; -#[cfg(test)] -mod tests; -mod tool; - -// Re-export canonical capability types for plugin authors. -pub use astrcode_core::{ - CapabilityKind, CapabilitySpec, CapabilitySpecBuildError, CapabilitySpecBuilder, - InvocationMode, PermissionSpec, SideEffect, Stability, -}; -// Re-export SDK-local types. -pub use context::PluginContext; -pub use error::{SdkError, ToolSerdeStage}; -pub use hook::{ - HookRegistry, HookShortCircuit, PolicyDecision, PolicyHook, PolicyHookChain, - RegisteredPolicyHook, -}; -// Re-export serde for convenience, so plugin authors don't need a separate dependency. -pub use serde::{Serialize, de::DeserializeOwned}; -pub use stream::{StreamChunk, StreamWriter}; -pub use tool::{DynToolHandler, ToolFuture, ToolHandler, ToolRegistration, ToolResult}; diff --git a/crates/sdk/src/stream.rs b/crates/sdk/src/stream.rs deleted file mode 100644 index 02dcc044..00000000 --- a/crates/sdk/src/stream.rs +++ /dev/null @@ -1,177 +0,0 @@ -//! 流式响应写入器。 -//! -//! 本模块提供 `StreamWriter`，用于工具在执行过程中向客户端发送增量输出。 -//! -//! ## 使用场景 -//! -//! - **长耗时工具**: shell 命令的 stdout/stderr 逐行输出 -//! - **LLM 流式响应**: token 级别的文本增量 -//! - **文件编辑**: diff 补丁的逐步应用 -//! -//! ## 设计意图 -//! -//! 工具不应等到全部完成才返回结果，而是通过流式输出让用户 -//! 实时看到进度。`StreamWriter` 将每个增量事件持久化并广播， -//! 确保断线重连后可通过 replay 恢复。 -//! -//! ## 线程安全 -//! -//! `StreamWriter` 是 `Clone` 且线程安全的，可在 async 任务中 -//! 跨多个 future 共享，适合并发发送多个流式事件。 - -use std::sync::{Arc, Mutex}; - -use serde_json::{Value, json}; - -use crate::SdkError; - -type StreamResult = Result; -type StreamCallback = dyn Fn(StreamChunk) -> StreamResult<()> + Send + Sync; - -/// 单个流式事件块。 -/// -/// 表示工具执行过程中产生的一个增量输出事件， -/// 包含事件类型（如 "message.delta"）和负载数据。 -/// -/// ## 事件命名约定 -/// -/// 事件名使用点分格式，如 `message.delta`、`artifact.patch`， -/// 前端据此选择对应的渲染组件。 -#[derive(Debug, Clone, PartialEq)] -pub struct StreamChunk { - /// 事件类型名称。 - pub event: String, - /// 事件负载，结构由事件类型决定。 - pub payload: Value, -} - -/// 流式响应写入器。 -/// -/// 工具通过此对象在执行过程中发送增量输出到客户端。 -/// -/// ## 线程安全与克隆 -/// -/// `StreamWriter` 内部使用 `Arc>` 共享状态， -/// 因此 `Clone` 是廉价的引用计数增加，可在 async 任务间安全共享。 -/// -/// ## 回调机制 -/// -/// 可通过 `with_callback` 注册回调函数，每次 `emit` 时触发。 -/// 回调用于将事件推送到运行时广播通道或持久化层。 -/// 如果不设置回调，`emit` 仅记录到内部缓冲区（可通过 `records()` 读取）。 -/// -/// ## 为什么同时有 records 和 callback -/// -/// - `records`: 用于测试断言和断线重连时的历史回放 -/// - `callback`: 用于实时推送到运行时广播通道 -/// -/// 两者互补，不是冗余设计。 -#[derive(Clone, Default)] -pub struct StreamWriter { - records: Arc>>, - callback: Option>, -} - -impl StreamWriter { - /// 创建带回调的流式写入器。 - /// - /// 回调函数会在每次 `emit` 时被调用， - /// 通常用于将事件推送到运行时的广播通道。 - pub fn with_callback(callback: F) -> Self - where - F: Fn(StreamChunk) -> StreamResult<()> + Send + Sync + 'static, - { - Self { - records: Arc::new(Mutex::new(Vec::new())), - callback: Some(Arc::new(callback)), - } - } - - /// 发送一个流式事件。 - /// - /// 事件会被记录到内部缓冲区（可通过 `records()` 读取）， - /// 如果设置了回调，还会调用回调函数进行实时推送。 - /// - /// ## 错误处理 - /// - /// 如果回调返回错误，`emit` 会将其包装为 `SdkError::StreamEmit` 返回， - /// 工具应据此决定是否中止执行。 - pub fn emit(&self, event: impl Into, payload: Value) -> StreamResult<()> { - let event = event.into(); - let chunk = StreamChunk { - event: event.clone(), - payload, - }; - self.records - .lock() - .map_err(|_| SdkError::internal("stream records lock poisoned"))? - .push(chunk.clone()); - if let Some(callback) = &self.callback { - callback(chunk).map_err(|error| SdkError::StreamEmit { - event, - message: error.to_string(), - details: error.details(), - })?; - } - Ok(()) - } - - /// 发送文本增量事件。 - /// - /// 便捷方法，等价于 `emit("message.delta", { "text": ... })`， - /// 用于 LLM 流式响应等场景的逐段文本输出。 - pub fn message_delta(&self, text: impl Into) -> StreamResult<()> { - self.emit("message.delta", json!({ "text": text.into() })) - } - - /// 发送文件补丁事件。 - /// - /// 便捷方法，等价于 `emit("artifact.patch", { "path": ..., "patch": ... })`， - /// 用于工具逐步应用文件修改时向前端发送 diff。 - pub fn artifact_patch( - &self, - path: impl Into, - patch: impl Into, - ) -> StreamResult<()> { - self.emit( - "artifact.patch", - json!({ - "path": path.into(), - "patch": patch.into(), - }), - ) - } - - /// 发送诊断信息事件。 - /// - /// 便捷方法，等价于 `emit("diagnostic", { "severity": ..., "message": ... })`， - /// 用于工具在执行过程中向前端报告警告、错误等诊断信息。 - pub fn diagnostic( - &self, - severity: impl Into, - message: impl Into, - ) -> StreamResult<()> { - self.emit( - "diagnostic", - json!({ - "severity": severity.into(), - "message": message.into(), - }), - ) - } - - /// 返回所有已记录的流式事件。 - /// - /// 用于测试断言、断线重连时的历史回放， - /// 或工具执行完成后审计发送了哪些事件。 - /// - /// ## 线程安全 - /// - /// 获取锁时会短暂阻塞，如果锁被毒化（panic）则返回错误。 - pub fn records(&self) -> StreamResult> { - self.records - .lock() - .map_err(|_| SdkError::internal("stream records lock poisoned")) - .map(|guard| guard.clone()) - } -} diff --git a/crates/sdk/src/tests.rs b/crates/sdk/src/tests.rs deleted file mode 100644 index 4ffdad66..00000000 --- a/crates/sdk/src/tests.rs +++ /dev/null @@ -1,245 +0,0 @@ -use std::{ - future::Future, - pin::pin, - sync::{Arc, Mutex}, - task::{Context, Poll, RawWaker, RawWakerVTable, Waker}, -}; - -use serde::{Deserialize, Serialize}; -use serde_json::json; - -use crate::{ - CapabilityKind, CapabilitySpec, HookRegistry, InvocationMode, PluginContext, PolicyDecision, - PolicyHook, PolicyHookChain, SdkError, SideEffect, StreamWriter, ToolFuture, ToolHandler, - ToolRegistration, ToolSerdeStage, -}; - -/// Minimal synchronous executor for tests. -fn block_on(future: F) -> F::Output { - fn noop_raw_waker() -> RawWaker { - fn clone(_: *const ()) -> RawWaker { - noop_raw_waker() - } - fn wake(_: *const ()) {} - fn wake_by_ref(_: *const ()) {} - fn drop(_: *const ()) {} - RawWaker::new( - std::ptr::null(), - &RawWakerVTable::new(clone, wake, wake_by_ref, drop), - ) - } - let waker = unsafe { Waker::from_raw(noop_raw_waker()) }; - let mut future = pin!(future); - let mut context = Context::from_waker(&waker); - loop { - match future.as_mut().poll(&mut context) { - Poll::Ready(output) => return output, - Poll::Pending => std::thread::yield_now(), - } - } -} - -#[derive(Default)] -struct SampleTool; - -#[derive(Debug, Deserialize, PartialEq, Eq)] -struct SampleInput { - value: String, -} - -#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)] -struct SampleOutput { - echoed: String, -} - -impl ToolHandler for SampleTool { - fn descriptor(&self) -> CapabilitySpec { - CapabilitySpec::builder("tool.sample", CapabilityKind::tool()) - .description("Sample tool") - .schema(json!({ "type": "object" }), json!({ "type": "object" })) - .invocation_mode(InvocationMode::Streaming) - .profile("coding") - .tag("sample") - .side_effect(SideEffect::None) - .build() - .expect("sample capability spec should build") - } - - fn execute( - &self, - input: SampleInput, - _context: PluginContext, - stream: StreamWriter, - ) -> ToolFuture<'_, SampleOutput> { - Box::pin(async move { - stream.message_delta("running")?; - Ok(SampleOutput { - echoed: input.value, - }) - }) - } -} - -struct TrackingPolicyHook { - name: &'static str, - allowed: bool, - calls: Arc>>, -} - -impl PolicyHook for TrackingPolicyHook { - fn before_invoke( - &self, - _capability: &CapabilitySpec, - _context: &PluginContext, - ) -> PolicyDecision { - self.calls - .lock() - .expect("tracking policy calls") - .push(self.name); - if self.allowed { - PolicyDecision::allow() - } else { - PolicyDecision::deny(format!("{} denied the request", self.name)) - } - } -} - -// --- Critical contract: type-erased tool execution --- - -#[test] -fn tool_registration_decodes_input_and_encodes_output_automatically() { - let registration = ToolRegistration::new(SampleTool); - let output = block_on(registration.handler().execute_value( - json!({ "value": "hello" }), - PluginContext::default(), - StreamWriter::default(), - )) - .expect("typed tool execution should succeed"); - - assert_eq!(output, json!({ "echoed": "hello" })); -} - -#[test] -fn tool_registration_reports_typed_decode_errors() { - let registration = ToolRegistration::new(SampleTool); - let error = block_on(registration.handler().execute_value( - json!({ "value": 42 }), - PluginContext::default(), - StreamWriter::default(), - )) - .expect_err("invalid typed payload should fail"); - - let payload = error.to_error_payload(); - match error { - SdkError::Serde { - capability, - stage, - rust_type, - .. - } => { - assert_eq!(capability, "tool.sample"); - assert_eq!(stage, ToolSerdeStage::DecodeInput); - assert!(rust_type.contains("SampleInput")); - }, - other => panic!("expected serde decode error, got {other:?}"), - } - assert_eq!(payload.code, "invalid_input"); - assert!(!payload.retriable); -} - -// --- Critical contract: hook chain composition and short-circuit --- - -#[test] -fn hook_registry_composes_policy_hooks_in_order() { - let calls = Arc::new(Mutex::new(Vec::new())); - let registry = HookRegistry::default() - .with_policy_hook( - "first", - TrackingPolicyHook { - name: "first", - allowed: true, - calls: Arc::clone(&calls), - }, - ) - .and_then(|registry| { - registry.with_policy_hook( - "second", - TrackingPolicyHook { - name: "second", - allowed: true, - calls: Arc::clone(&calls), - }, - ) - }) - .expect("policy hooks should register"); - - let decision = registry - .policy_hook_chain() - .before_invoke(&SampleTool.descriptor(), &PluginContext::default()); - - assert!(decision.allowed); - assert_eq!( - calls.lock().expect("tracking policy calls").as_slice(), - ["first", "second"] - ); -} - -#[test] -fn policy_hook_chain_short_circuits_after_first_deny() { - let calls = Arc::new(Mutex::new(Vec::new())); - let chain = PolicyHookChain::default() - .with_hook( - "allow", - TrackingPolicyHook { - name: "allow", - allowed: true, - calls: Arc::clone(&calls), - }, - ) - .and_then(|chain| { - chain.with_hook( - "deny", - TrackingPolicyHook { - name: "deny", - allowed: false, - calls: Arc::clone(&calls), - }, - ) - }) - .and_then(|chain| { - chain.with_hook( - "never-runs", - TrackingPolicyHook { - name: "never-runs", - allowed: true, - calls: Arc::clone(&calls), - }, - ) - }) - .expect("policy chain should register"); - - let decision = chain.before_invoke(&SampleTool.descriptor(), &PluginContext::default()); - - assert!(!decision.allowed); - assert_eq!(decision.reason.as_deref(), Some("deny denied the request")); - assert_eq!( - calls.lock().expect("tracking policy calls").as_slice(), - ["allow", "deny"] - ); -} - -// --- Critical contract: error to protocol payload mapping --- - -#[test] -fn sdk_error_maps_to_protocol_payload() { - let error = SdkError::permission_denied("filesystem.write requires approval"); - let payload = error.to_error_payload(); - - assert_eq!(payload.code, "permission_denied"); - assert_eq!( - payload.message, - "permission denied: filesystem.write requires approval" - ); - assert_eq!(payload.details, serde_json::Value::Null); - assert!(!payload.retriable); -} diff --git a/crates/sdk/src/tool.rs b/crates/sdk/src/tool.rs deleted file mode 100644 index 651bbc12..00000000 --- a/crates/sdk/src/tool.rs +++ /dev/null @@ -1,267 +0,0 @@ -//! 工具处理器 SDK。 -//! -//! 本模块提供插件作者注册和实现工具的核心接口。 -//! -//! ## 核心抽象 -//! -//! - **`ToolHandler`**: 类型安全的工具处理 trait，插件作者实现此 trait 来定义工具逻辑 -//! - **`ToolRegistration`**: 将 `ToolHandler` 包装为可被运行时调用的注册项 -//! - **`DynToolHandler`**: 类型擦除后的动态分发 trait，由运行时内部使用 -//! -//! ## 类型擦除设计 -//! -//! 插件作者实现的是泛型 `ToolHandler`（输入/输出为具体 Rust 类型）， -//! 但运行时只知道 `Value`（JSON）。`ErasedToolHandler` 在中间层负责 -//! `Value <-> I/O` 的 serde 转换，并统一错误处理。 -//! -//! 这样插件作者只需关注业务逻辑，无需手动处理 JSON 编解码。 -//! -//! ## 使用示例 -//! -//! ```ignore -//! struct MyTool; -//! -//! impl ToolHandler for MyTool { -//! fn descriptor(&self) -> CapabilitySpec { /* ... */ } -//! -//! fn execute(&self, input: MyInput, context: PluginContext, stream: StreamWriter) -> ToolFuture<'_, MyOutput> { -//! Box::pin(async move { -//! // 业务逻辑 -//! Ok(MyOutput { result: input.value }) -//! }) -//! } -//! } -//! -//! let registration = ToolRegistration::new(MyTool); -//! ``` - -use std::{future::Future, pin::Pin}; - -use astrcode_core::CapabilitySpec; -use serde::{Serialize, de::DeserializeOwned}; -use serde_json::Value; - -use crate::{PluginContext, SdkError, StreamWriter, ToolSerdeStage}; - -/// 工具执行的返回类型别名。 -/// -/// 所有工具执行结果都包装在此 Result 中， -/// 成功时返回输出类型 `T`，失败时返回 `SdkError`。 -pub type ToolResult = Result; - -/// 工具执行返回的 Future 类型。 -/// -/// 使用 `Pin>` 是因为 `ToolHandler::execute` -/// 需要返回 trait object，而 async trait 在稳定 Rust 中 -/// 需要通过这种方式实现类型擦除。 -pub type ToolFuture<'a, T> = Pin> + Send + 'a>>; - -/// 类型安全的工具处理 trait。 -/// -/// 插件作者实现此 trait 来定义工具的行为。 -/// 泛型参数 `I` 和 `O` 分别是工具的输入和输出类型， -/// 由 serde 自动处理 JSON 编解码。 -/// -/// ## 生命周期 -/// -/// `ToolHandler` 实例通常被 `Arc` 或 `Box` 包装后注册到运行时， -/// 因此需要 `Send + Sync`。`execute` 返回的 future 生命周期 -/// 绑定在 `&self` 上，因为工具实例在调用期间保持存活。 -/// -/// ## 为什么 `execute` 返回 `ToolFuture` 而不是 `async fn` -/// -/// trait 中的 `async fn` 在稳定 Rust 中需要 `async_trait` crate， -/// 此处手动返回 `Pin>` 避免额外依赖， -/// 同时保持与 `async fn` 相同的语义。 -pub trait ToolHandler: Send + Sync { - /// 返回工具的能力描述。 - /// - /// 描述包含工具名称、文档、副作用级别等元数据， - /// 用于 LLM 决定是否调用此工具，以及前端如何渲染工具卡片。 - fn descriptor(&self) -> CapabilitySpec; - - /// 执行工具逻辑。 - /// - /// ## 参数 - /// - /// - `input`: 已反序列化的工具输入，类型由泛型 `I` 决定 - /// - `context`: 当前调用的插件上下文（工作区、会话、追踪信息等） - /// - `stream`: 流式写入器，用于发送增量输出 - /// - /// ## 返回值 - /// - /// 返回 `ToolFuture<'_, O>`，即一个产出 `ToolResult` 的 future。 - /// 成功时返回输出值，失败时返回 `SdkError`。 - fn execute(&self, input: I, context: PluginContext, stream: StreamWriter) -> ToolFuture<'_, O>; -} - -/// 为 `Box` 实现 `ToolHandler`，允许工具处理器被装箱。 -/// -/// 这在工具需要动态分发或存储在集合中时很有用， -/// 确保装箱后的工具仍然保持类型安全的 `ToolHandler` 接口。 -impl ToolHandler for Box -where - T: ToolHandler + ?Sized, -{ - fn descriptor(&self) -> CapabilitySpec { - (**self).descriptor() - } - - fn execute(&self, input: I, context: PluginContext, stream: StreamWriter) -> ToolFuture<'_, O> { - (**self).execute(input, context, stream) - } -} - -/// 类型擦除后的动态分发工具处理 trait。 -/// -/// 运行时内部使用此 trait 调用工具，不关心工具的具体输入/输出类型。 -/// 所有输入/输出都通过 `Value`（JSON）传递，serde 转换由 `ErasedToolHandler` 处理。 -/// -/// ## 为什么需要这个 trait -/// -/// 运行时维护一个 `Vec>` 集合， -/// 如果直接用 `ToolHandler`，集合中的每个元素类型都不同， -/// 无法统一存储。类型擦除后所有工具都实现同一个 trait，可放入同一集合。 -pub trait DynToolHandler: Send + Sync { - /// 返回工具的能力描述。 - fn descriptor(&self) -> CapabilitySpec; - - /// 以 `Value` 作为输入/输出执行工具。 - /// - /// 内部实现会先将 `Value` 反序列化为具体类型， - /// 调用类型安全的 `ToolHandler::execute`， - /// 再将结果序列化为 `Value` 返回。 - fn execute_value( - &self, - input: Value, - context: PluginContext, - stream: StreamWriter, - ) -> ToolFuture<'_, Value>; -} - -/// 类型擦除适配器，将 `ToolHandler` 包装为 `DynToolHandler`。 -/// -/// 此结构体不公开，插件作者无需直接与之交互。 -/// 它由 `ToolRegistration::new` 内部创建，负责： -/// 1. 将输入的 `Value` 反序列化为 `I` -/// 2. 调用内部 `ToolHandler::execute` -/// 3. 将输出的 `O` 序列化为 `Value` -/// 4. 统一处理 serde 错误为 `SdkError::Serde` -struct ErasedToolHandler { - inner: H, - _marker: std::marker::PhantomData O>, -} - -impl ErasedToolHandler { - fn new(inner: H) -> Self { - Self { - inner, - _marker: std::marker::PhantomData, - } - } -} - -impl DynToolHandler for ErasedToolHandler -where - H: ToolHandler + Send + Sync, - I: DeserializeOwned + Send + 'static, - O: Serialize + Send + 'static, -{ - fn descriptor(&self) -> CapabilitySpec { - ToolHandler::::descriptor(&self.inner) - } - - fn execute_value( - &self, - input: Value, - context: PluginContext, - stream: StreamWriter, - ) -> ToolFuture<'_, Value> { - let capability_spec = ToolHandler::::descriptor(&self.inner); - let capability_name = capability_spec.name.to_string(); - let typed_input = serde_json::from_value::(input).map_err(|source| SdkError::Serde { - capability: capability_name.clone(), - stage: ToolSerdeStage::DecodeInput, - rust_type: std::any::type_name::(), - message: source.to_string(), - }); - - // The registration stores an erased handler so plugin authors only implement - // typed logic once while the SDK owns serde conversion and consistent errors. - Box::pin(async move { - let typed_input = typed_input?; - let output = - ToolHandler::::execute(&self.inner, typed_input, context, stream).await?; - serde_json::to_value(output).map_err(|source| SdkError::Serde { - capability: capability_name, - stage: ToolSerdeStage::EncodeOutput, - rust_type: std::any::type_name::(), - message: source.to_string(), - }) - }) - } -} - -/// 工具注册项。 -/// -/// 将 `ToolHandler` 与其能力描述打包， -/// 是插件向运行时注册工具的最小单元。 -/// -/// ## 使用方式 -/// -/// 插件作者通过 `ToolRegistration::new(handler)` 创建注册项， -/// 然后将其传递给运行时。运行时通过 `descriptor()` 获取工具元数据， -/// 通过 `handler()` 进行动态分发调用。 -/// -/// ## 类型擦除 -/// -/// 构造函数内部创建 `ErasedToolHandler` 包装器， -/// 将泛型 `ToolHandler` 转换为 `dyn DynToolHandler`， -/// 使运行时可用统一接口调用所有工具。 -pub struct ToolRegistration { - descriptor: CapabilitySpec, - handler: Box, -} - -impl ToolRegistration { - /// 从 `ToolHandler` 创建工具注册项。 - /// - /// 此方法会自动： - /// 1. 从 handler 提取能力描述 - /// 2. 创建类型擦除包装器 - /// 3. 打包为 `ToolRegistration` - /// - /// ## 泛型约束 - /// - /// - `I: DeserializeOwned`: 输入类型必须可从 JSON 反序列化 - /// - `O: Serialize`: 输出类型必须可序列化为 JSON - /// - `'static`: handler 必须拥有所有数据，不能有非静态引用 - pub fn new(handler: H) -> Self - where - H: ToolHandler + 'static, - I: DeserializeOwned + Send + 'static, - O: Serialize + Send + 'static, - { - let descriptor = handler.descriptor(); - Self { - descriptor, - handler: Box::new(ErasedToolHandler::::new(handler)), - } - } - - /// 返回工具的能力描述引用。 - /// - /// 运行时用此信息向 LLM 暴露工具列表， - /// 前端用此信息渲染工具卡片。 - pub fn descriptor(&self) -> &CapabilitySpec { - &self.descriptor - } - - /// 返回类型擦除后的处理器引用。 - /// - /// 运行时通过此接口以 `Value` 为输入/输出调用工具， - /// serde 转换由内部的 `ErasedToolHandler` 处理。 - pub fn handler(&self) -> &dyn DynToolHandler { - self.handler.as_ref() - } -} diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml index 3b68085e..c81750d8 100644 --- a/crates/server/Cargo.toml +++ b/crates/server/Cargo.toml @@ -6,7 +6,6 @@ license-file.workspace = true authors.workspace = true [dependencies] -astrcode-application = { path = "../application" } astrcode-adapter-agents = { path = "../adapter-agents" } astrcode-adapter-llm = { path = "../adapter-llm" } astrcode-adapter-mcp = { path = "../adapter-mcp" } @@ -14,11 +13,11 @@ astrcode-adapter-prompt = { path = "../adapter-prompt" } astrcode-adapter-skills = { path = "../adapter-skills" } astrcode-adapter-storage = { path = "../adapter-storage" } astrcode-adapter-tools = { path = "../adapter-tools" } +astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } -astrcode-kernel = { path = "../kernel" } -astrcode-plugin = { path = "../plugin" } +astrcode-host-session = { path = "../host-session" } +astrcode-plugin-host = { path = "../plugin-host" } astrcode-protocol = { path = "../protocol" } -astrcode-session-runtime = { path = "../session-runtime" } astrcode-support = { path = "../support" } async-stream.workspace = true anyhow.workspace = true @@ -38,6 +37,7 @@ thiserror.workspace = true tokio.workspace = true tower.workspace = true tower-http.workspace = true +uuid.workspace = true [dev-dependencies] astrcode-core = { path = "../core", features = ["test-support"] } diff --git a/crates/application/src/agent/context.rs b/crates/server/src/agent/context.rs similarity index 94% rename from crates/application/src/agent/context.rs rename to crates/server/src/agent/context.rs index 557ad976..b1c16f38 100644 --- a/crates/application/src/agent/context.rs +++ b/crates/server/src/agent/context.rs @@ -9,8 +9,9 @@ use std::path::Path; use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, AgentCollaborationPolicyContext, AgentEventContext, ChildExecutionIdentity, InvocationKind, - ModeId, ResolvedExecutionLimitsSnapshot, Result, SubRunHandle, ToolContext, + ModeId, ResolvedExecutionLimitsSnapshot, Result, ToolContext, }; +use astrcode_host_session::SubRunHandle; use super::{ AgentOrchestrationError, AgentOrchestrationService, IMPLICIT_ROOT_PROFILE_ID, @@ -205,9 +206,7 @@ pub(crate) fn implicit_session_root_agent_id(session_id: &str) -> String { format!("root-agent:{}", normalize_external_session_id(session_id)) } -fn default_resolved_limits_for_gateway( - _gateway: &astrcode_kernel::KernelGateway, -) -> ResolvedExecutionLimitsSnapshot { +fn default_resolved_limits() -> ResolvedExecutionLimitsSnapshot { ResolvedExecutionLimitsSnapshot } @@ -217,19 +216,13 @@ fn default_resolved_limits_for_gateway( /// 此函数统一补上空快照，避免旧事件缺口影响后续状态投影。 async fn ensure_handle_has_resolved_limits( kernel: &dyn crate::AgentKernelPort, - gateway: &astrcode_kernel::KernelGateway, handle: SubRunHandle, ) -> std::result::Result { if handle.resolved_limits == ResolvedExecutionLimitsSnapshot { return Ok(handle); } - super::persist_resolved_limits_for_handle( - kernel, - handle, - default_resolved_limits_for_gateway(gateway), - ) - .await + super::persist_resolved_limits_for_handle(kernel, handle, default_resolved_limits()).await } impl AgentOrchestrationService { @@ -448,13 +441,9 @@ impl AgentOrchestrationService { if let Some(agent_id) = explicit_agent_id { if let Some(handle) = self.kernel.get_handle(&agent_id).await { if handle.depth == 0 && handle.resolved_limits != ResolvedExecutionLimitsSnapshot { - return ensure_handle_has_resolved_limits( - self.kernel.as_ref(), - &self.kernel.gateway(), - handle, - ) - .await - .map_err(AgentOrchestrationError::Internal); + return ensure_handle_has_resolved_limits(self.kernel.as_ref(), handle) + .await + .map_err(AgentOrchestrationError::Internal); } return Ok(handle); } @@ -479,13 +468,9 @@ impl AgentOrchestrationService { "failed to register root agent for parent context: {error}" )) })?; - return ensure_handle_has_resolved_limits( - self.kernel.as_ref(), - &self.kernel.gateway(), - handle, - ) - .await - .map_err(AgentOrchestrationError::Internal); + return ensure_handle_has_resolved_limits(self.kernel.as_ref(), handle) + .await + .map_err(AgentOrchestrationError::Internal); } return Err(AgentOrchestrationError::NotFound(format!( @@ -495,13 +480,9 @@ impl AgentOrchestrationService { } if let Some(handle) = self.kernel.find_root_handle_for_session(&session_id).await { - return ensure_handle_has_resolved_limits( - self.kernel.as_ref(), - &self.kernel.gateway(), - handle, - ) - .await - .map_err(AgentOrchestrationError::Internal); + return ensure_handle_has_resolved_limits(self.kernel.as_ref(), handle) + .await + .map_err(AgentOrchestrationError::Internal); } let handle = self @@ -517,7 +498,7 @@ impl AgentOrchestrationService { "failed to register implicit root agent for session parent context: {error}" )) })?; - ensure_handle_has_resolved_limits(self.kernel.as_ref(), &self.kernel.gateway(), handle) + ensure_handle_has_resolved_limits(self.kernel.as_ref(), handle) .await .map_err(AgentOrchestrationError::Internal) } diff --git a/crates/application/src/agent/mod.rs b/crates/server/src/agent/mod.rs similarity index 98% rename from crates/application/src/agent/mod.rs rename to crates/server/src/agent/mod.rs index 50eba2e2..7094f328 100644 --- a/crates/application/src/agent/mod.rs +++ b/crates/server/src/agent/mod.rs @@ -31,8 +31,9 @@ use astrcode_core::{ DelegationMetadata, ObserveParams, ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ProgressParentDeliveryPayload, QueuedInputEnvelope, ResolvedExecutionLimitsSnapshot, Result, RuntimeMetricsRecorder, SendAgentParams, - SpawnAgentParams, SubRunHandle, SubRunHandoff, SubRunResult, ToolContext, + SpawnAgentParams, SubRunHandoff, SubRunResult, ToolContext, }; +use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor, SubRunHandle}; use async_trait::async_trait; pub(crate) use context::{ CollaborationFactRecord, ToolCollaborationContext, ToolCollaborationContextInput, @@ -430,7 +431,7 @@ impl ObserveGuardState { // ── 实现 SubAgentExecutor（供 spawn 工具使用）────────────────────── #[async_trait] -impl astrcode_core::SubAgentExecutor for AgentOrchestrationService { +impl SubAgentExecutor for AgentOrchestrationService { async fn launch(&self, params: SpawnAgentParams, ctx: &ToolContext) -> Result { let parent_handle = self .ensure_parent_agent_handle(ctx) @@ -559,7 +560,7 @@ impl astrcode_core::SubAgentExecutor for AgentOrchestrationService { // ── 实现 CollaborationExecutor（供 send/close/observe 工具使用）───── #[async_trait] -impl astrcode_core::CollaborationExecutor for AgentOrchestrationService { +impl CollaborationExecutor for AgentOrchestrationService { async fn send( &self, params: SendAgentParams, @@ -598,12 +599,13 @@ mod tests { CancelToken, ChildAgentRef, ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNotification, ChildSessionNotificationKind, ParentExecutionRef, ResolvedExecutionLimitsSnapshot, SessionId, SpawnAgentParams, StorageEventPayload, - ToolContext, agent::executor::SubAgentExecutor, + ToolContext, }; + use astrcode_host_session::SubAgentExecutor; use super::{ IMPLICIT_ROOT_PROFILE_ID, build_delegation_metadata, child_delivery_input_queue_envelope, - implicit_session_root_agent_id, root_execution_event_context, + context::implicit_session_root_agent_id, root_execution_event_context, terminal_notification_message, terminal_notification_turn_outcome, }; use crate::{ @@ -809,7 +811,7 @@ mod tests { assert_eq!(parent_agent_artifact.id, expected_parent_agent_id); let root_status = harness - .kernel + .session_runtime .agent() .query_root_status(&parent.session_id) .await @@ -831,7 +833,7 @@ mod tests { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -877,7 +879,7 @@ mod tests { .expect("child session artifact should exist"); let child_handle = harness - .kernel + .session_runtime .agent() .get_handle(&child_agent_id) .await @@ -958,7 +960,7 @@ mod tests { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -1003,7 +1005,7 @@ mod tests { .find(|artifact| artifact.kind == "subRun") .expect("subRun artifact should exist"); let child_handle = harness - .kernel + .session_runtime .agent() .get_handle(&child_agent_id) .await @@ -1071,7 +1073,7 @@ mod tests { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), diff --git a/crates/application/src/agent/observe.rs b/crates/server/src/agent/observe.rs similarity index 98% rename from crates/application/src/agent/observe.rs rename to crates/server/src/agent/observe.rs index c203435c..9e8f33fe 100644 --- a/crates/application/src/agent/observe.rs +++ b/crates/server/src/agent/observe.rs @@ -7,6 +7,7 @@ use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationOutcomeKind, AgentLifecycleStatus, CollaborationResult, ObserveParams, ObserveSnapshot, }; +use astrcode_host_session::SubRunHandle; use super::{AgentOrchestrationService, ObserveSnapshotSignature}; @@ -126,7 +127,7 @@ impl AgentOrchestrationService { fn observe_snapshot_is_unchanged( &self, - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, collaboration: &super::ToolCollaborationContext, signature: &ObserveSnapshotSignature, ) -> std::result::Result { @@ -139,7 +140,7 @@ impl AgentOrchestrationService { fn remember_observe_snapshot( &self, - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, collaboration: &super::ToolCollaborationContext, signature: ObserveSnapshotSignature, ) -> std::result::Result<(), super::AgentOrchestrationError> { @@ -153,7 +154,7 @@ impl AgentOrchestrationService { } fn observe_guard_key( - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, collaboration: &super::ToolCollaborationContext, ) -> String { format!( @@ -211,8 +212,8 @@ mod tests { use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationOutcomeKind, CancelToken, ObserveParams, SessionId, StorageEventPayload, ToolContext, - agent::executor::{CollaborationExecutor, SubAgentExecutor}, }; + use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; use tokio::time::sleep; use super::format_observe_summary; @@ -282,7 +283,7 @@ mod tests { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -327,7 +328,7 @@ mod tests { .expect("child agent artifact should exist"); for _ in 0..20 { if harness - .kernel + .session_runtime .agent() .get_lifecycle(&child_agent_id) .await @@ -386,7 +387,7 @@ mod tests { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -431,7 +432,7 @@ mod tests { .expect("child agent artifact should exist"); for _ in 0..20 { if harness - .kernel + .session_runtime .agent() .get_lifecycle(&child_agent_id) .await diff --git a/crates/application/src/agent/routing.rs b/crates/server/src/agent/routing.rs similarity index 99% rename from crates/application/src/agent/routing.rs rename to crates/server/src/agent/routing.rs index c26902bb..755bc9b4 100644 --- a/crates/application/src/agent/routing.rs +++ b/crates/server/src/agent/routing.rs @@ -9,8 +9,9 @@ use astrcode_core::{ AgentLifecycleStatus, ChildAgentRef, ChildSessionNotification, CloseAgentParams, CollaborationResult, InboxEnvelopeKind, InputDiscardedPayload, InputQueuedPayload, ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, SendAgentParams, - SendToChildParams, SendToParentParams, SubRunHandle, + SendToChildParams, SendToParentParams, }; +use astrcode_host_session::SubRunHandle; use collaboration_flow::parent_delivery_label; use super::{ diff --git a/crates/application/src/agent/routing/child_send.rs b/crates/server/src/agent/routing/child_send.rs similarity index 98% rename from crates/application/src/agent/routing/child_send.rs rename to crates/server/src/agent/routing/child_send.rs index 4bfbc80c..c6c3586a 100644 --- a/crates/application/src/agent/routing/child_send.rs +++ b/crates/server/src/agent/routing/child_send.rs @@ -142,10 +142,7 @@ impl AgentOrchestrationService { context: params.context.clone(), busy_policy: GovernanceBusyPolicy::RejectOnBusy, }; - let surface = match self - .governance_surface - .resumed_child_surface(self.kernel.as_ref(), resumed_input) - { + let surface = match self.governance_surface.resumed_child_surface(resumed_input) { Ok(surface) => surface, Err(error) => { return self diff --git a/crates/application/src/agent/routing/parent_delivery.rs b/crates/server/src/agent/routing/parent_delivery.rs similarity index 100% rename from crates/application/src/agent/routing/parent_delivery.rs rename to crates/server/src/agent/routing/parent_delivery.rs diff --git a/crates/application/src/agent/routing/tests.rs b/crates/server/src/agent/routing/tests.rs similarity index 98% rename from crates/application/src/agent/routing/tests.rs rename to crates/server/src/agent/routing/tests.rs index 8bd849f9..efade784 100644 --- a/crates/application/src/agent/routing/tests.rs +++ b/crates/server/src/agent/routing/tests.rs @@ -5,13 +5,12 @@ use astrcode_core::{ CompletedParentDeliveryPayload, ObserveParams, ParentDeliveryPayload, SendAgentParams, SendToChildParams, SendToParentParams, SessionId, SpawnAgentParams, StorageEventPayload, ToolContext, - agent::executor::{CollaborationExecutor, SubAgentExecutor}, }; +use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; use tokio::time::sleep; use super::super::{root_execution_event_context, subrun_event_context}; use crate::{ - AgentKernelPort, AppKernelPort, agent::test_support::{TestLlmBehavior, build_agent_test_harness}, lifecycle::governance::ObservabilitySnapshotProvider, }; @@ -22,7 +21,7 @@ async fn spawn_direct_child( working_dir: &std::path::Path, ) -> (String, String) { harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -64,7 +63,7 @@ async fn spawn_direct_child( .expect("child agent artifact should exist"); for _ in 0..20 { if harness - .kernel + .session_runtime .get_lifecycle(&child_agent_id) .await .is_some_and(|lifecycle| lifecycle == astrcode_core::AgentLifecycleStatus::Idle) @@ -98,7 +97,7 @@ async fn collaboration_calls_reject_non_direct_child() { .await .expect("parent session B should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "other-root".to_string(), @@ -223,8 +222,8 @@ async fn send_to_idle_child_reports_resume_semantics() { "resumed child projection should expose resume lineage instead of masquerading as spawn" ); let resumed_child = harness - .kernel - .get_handle( + .session_runtime + .get_agent_handle( result .child_agent_ref() .map(|child_ref| child_ref.agent_id().as_str()) @@ -262,7 +261,7 @@ async fn send_to_running_child_reports_input_queue_semantics() { .with_agent_context(root_execution_event_context("root-agent", "root-profile")); let _ = harness - .kernel + .session_runtime .agent_control() .set_lifecycle( &child_agent_id, @@ -304,7 +303,7 @@ async fn send_to_parent_rejects_root_execution_without_direct_parent() { .await .expect("parent session should be created"); harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -388,8 +387,8 @@ async fn send_to_parent_from_resumed_child_routes_to_current_parent_turn() { .expect("send should resume idle child"); let resumed_child = harness - .kernel - .get_handle(&child_agent_id) + .session_runtime + .get_agent_handle(&child_agent_id) .await .expect("resumed child handle should exist"); let child_ctx = ToolContext::new( @@ -514,13 +513,13 @@ async fn send_to_parent_rejects_when_direct_parent_is_terminated() { let (child_agent_id, _) = spawn_direct_child(&harness, &parent.session_id, project.path()).await; let child_handle = harness - .kernel - .get_handle(&child_agent_id) + .session_runtime + .get_agent_handle(&child_agent_id) .await .expect("child handle should exist"); let _ = harness - .kernel + .session_runtime .agent_control() .set_lifecycle( "root-agent", @@ -585,7 +584,7 @@ async fn close_reports_cascade_scope_for_descendants() { spawn_direct_child(&harness, &parent.session_id, project.path()).await; let child_handle = harness - .kernel + .session_runtime .agent() .get_handle(&child_agent_id) .await diff --git a/crates/application/src/agent/routing_collaboration_flow.rs b/crates/server/src/agent/routing_collaboration_flow.rs similarity index 99% rename from crates/application/src/agent/routing_collaboration_flow.rs rename to crates/server/src/agent/routing_collaboration_flow.rs index 63af7f9c..045f8a36 100644 --- a/crates/application/src/agent/routing_collaboration_flow.rs +++ b/crates/server/src/agent/routing_collaboration_flow.rs @@ -113,7 +113,7 @@ pub(super) fn parent_delivery_label(payload: &ParentDeliveryPayload) -> &'static /// 将 live 控制面的 lifecycle + outcome 投影回 `ChildAgentRef` 的 lifecycle。 /// /// `Idle` + `None` outcome 的含义是：agent 已空闲但还没有完成过一轮 turn， -/// 此时保留调用方传入的 fallback 状态（通常是 handle 上的旧 lifecycle）。 +/// 此时保留调用方传入的 fallback 状态（通常是 handle 上当前记录的 lifecycle）。 /// 这避免了把刚 spawn 还没执行过 turn 的 agent 误标为 Idle。 fn project_collaboration_lifecycle( lifecycle: AgentLifecycleStatus, diff --git a/crates/application/src/agent/terminal.rs b/crates/server/src/agent/terminal.rs similarity index 98% rename from crates/application/src/agent/terminal.rs rename to crates/server/src/agent/terminal.rs index 4df17255..c4274ead 100644 --- a/crates/application/src/agent/terminal.rs +++ b/crates/server/src/agent/terminal.rs @@ -14,6 +14,7 @@ use astrcode_core::{ StorageEventPayload, SubRunFailure, SubRunFailureCode, SubRunHandoff, SubRunResult, SubRunStatus, }; +use astrcode_host_session::SubRunHandle; use super::{ AgentOrchestrationError, AgentOrchestrationService, child_collaboration_artifacts, @@ -38,7 +39,7 @@ struct ChildTerminalDeliveryProjection { /// 禁止再从 `child_ref.session_id` 反推父侧 notification 的落点。 /// 所有 notification 必须通过显式传入的 `parent_session_id` + `parent_turn_id` 路由。 pub(super) struct ChildTurnTerminalContext { - child: astrcode_core::SubRunHandle, + child: SubRunHandle, execution_session_id: String, execution_turn_id: String, parent_session_id: String, @@ -49,7 +50,7 @@ pub(super) struct ChildTurnTerminalContext { impl ChildTurnTerminalContext { pub(super) fn new( - child: astrcode_core::SubRunHandle, + child: SubRunHandle, execution_session_id: String, execution_turn_id: String, parent_session_id: String, @@ -75,7 +76,7 @@ impl AgentOrchestrationService { /// watcher 完成后执行：终态映射 → fallback delivery → 父级 reactivation。 pub(super) fn spawn_child_turn_terminal_watcher( &self, - child: astrcode_core::SubRunHandle, + child: SubRunHandle, execution_session_id: String, execution_turn_id: String, parent_session_id: String, @@ -216,7 +217,7 @@ impl AgentOrchestrationService { pub(super) async fn append_child_session_notification( &self, - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, parent_session_id: &str, parent_turn_id: &str, notification: &ChildSessionNotification, @@ -260,7 +261,7 @@ impl AgentOrchestrationService { /// 将子会话 turn 终态映射为 `SubRunResult`。 fn build_child_subrun_result( - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, parent_session_id: &str, source_turn_id: &str, outcome: &SessionTurnOutcomeSummary, @@ -313,7 +314,7 @@ fn build_child_subrun_result( } fn child_handoff_artifacts( - child: &astrcode_core::SubRunHandle, + child: &SubRunHandle, parent_session_id: &str, ) -> Vec { child_collaboration_artifacts(child, parent_session_id, true) @@ -408,13 +409,12 @@ mod tests { use astrcode_core::{ AgentEventContext, AgentLifecycleStatus, ChildAgentRef, ChildExecutionIdentity, - ChildSessionNotificationKind, ParentExecutionRef, Phase, SessionId, StorageEvent, - StorageEventPayload, SubRunStorageMode, + ChildSessionLineageKind, ChildSessionNotificationKind, ParentExecutionRef, Phase, + SessionId, StorageEvent, StorageEventPayload, SubRunStorageMode, }; use super::*; use crate::{ - ChildSessionLineageKind, agent::test_support::{TestLlmBehavior, build_agent_test_harness, sample_profile}, lifecycle::governance::ObservabilitySnapshotProvider, }; @@ -471,7 +471,7 @@ mod tests { .await .expect("child session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -481,7 +481,7 @@ mod tests { .await .expect("root agent should register"); let child_handle = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("reviewer"), @@ -494,7 +494,7 @@ mod tests { .await .expect("child handle should spawn"); harness - .kernel + .session_runtime .agent_control() .set_lifecycle(&child_handle.agent_id, AgentLifecycleStatus::Running) .await @@ -530,7 +530,7 @@ mod tests { let deadline = Instant::now() + Duration::from_secs(5); loop { if harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&parent.session_id) .await @@ -611,7 +611,7 @@ mod tests { .await .expect("child session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -621,7 +621,7 @@ mod tests { .await .expect("root agent should register"); let child_handle = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("reviewer"), @@ -634,7 +634,7 @@ mod tests { .await .expect("child handle should spawn"); harness - .kernel + .session_runtime .agent_control() .set_lifecycle(&child_handle.agent_id, AgentLifecycleStatus::Running) .await @@ -719,7 +719,7 @@ mod tests { #[test] fn cancelled_child_turn_preserves_interrupted_failure_details() { - let child = astrcode_core::SubRunHandle { + let child = SubRunHandle { sub_run_id: "subrun-1".to_string().into(), agent_id: "agent-child".to_string().into(), session_id: "session-parent".to_string().into(), @@ -802,7 +802,7 @@ mod tests { .await .expect("child session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -812,7 +812,7 @@ mod tests { .await .expect("root agent should register"); let child_handle = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("reviewer"), @@ -921,7 +921,7 @@ mod tests { .await .expect("leaf session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -931,7 +931,7 @@ mod tests { .await .expect("root agent should register"); let middle = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("reviewer"), @@ -944,7 +944,7 @@ mod tests { .await .expect("middle handle should spawn"); let leaf = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("explore"), @@ -957,13 +957,13 @@ mod tests { .await .expect("leaf handle should spawn"); harness - .kernel + .session_runtime .agent_control() .set_lifecycle(&middle.agent_id, AgentLifecycleStatus::Running) .await .expect("middle lifecycle should update"); harness - .kernel + .session_runtime .agent_control() .set_lifecycle(&leaf.agent_id, AgentLifecycleStatus::Running) .await @@ -1012,7 +1012,7 @@ mod tests { running" ); let leaf_status = harness - .kernel + .session_runtime .agent() .get_lifecycle(&leaf.agent_id) .await diff --git a/crates/application/src/agent/test_support.rs b/crates/server/src/agent/test_support.rs similarity index 66% rename from crates/application/src/agent/test_support.rs rename to crates/server/src/agent/test_support.rs index 4ef875af..9bd5561b 100644 --- a/crates/application/src/agent/test_support.rs +++ b/crates/server/src/agent/test_support.rs @@ -9,17 +9,19 @@ use std::{ sync::{Arc, Mutex}, }; +use astrcode_agent_runtime::{ + LlmEvent, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, +}; use astrcode_core::{ - AgentMode, AgentProfile, AstrError, Config, ConfigOverlay, DeleteProjectResult, EventStore, - LlmEvent, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, Phase, - PromptBuildOutput, PromptBuildRequest, PromptFacts, PromptFactsProvider, PromptProvider, - ReasoningContent, ResourceProvider, ResourceReadResult, ResourceRequestContext, Result, - SessionId, SessionMeta, SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, - StorageEvent, StoredEvent, + AgentLifecycleStatus, AgentMode, AgentProfile, AstrError, Config, ConfigOverlay, + DeleteProjectResult, Phase, ReasoningContent, Result, SessionId, SessionMeta, + SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StorageEvent, StoredEvent, + SubRunStorageMode, ports::{ConfigStore, McpConfigFileScope}, }; -use astrcode_kernel::{CapabilityRouter, Kernel}; -use astrcode_session_runtime::{SessionRuntime, display_name_from_working_dir}; +use astrcode_host_session::{ + EventStore, SessionCatalog, SubRunHandle, catalog::display_name_from_working_dir, +}; use async_trait::async_trait; use chrono::Utc; use serde_json::Value; @@ -27,44 +29,197 @@ use serde_json::Value; use crate::{ AgentKernelPort, AgentOrchestrationService, AgentSessionPort, ApplicationError, ConfigService, GovernanceSurfaceAssembler, ProfileResolutionService, RuntimeObservabilityCollector, - execution::ProfileProvider, lifecycle::TaskRegistry, + agent_control_bridge::ServerLiveSubRunStatus, + execution::ProfileProvider, + lifecycle::TaskRegistry, + mode::builtin_mode_catalog, + mode_catalog_service::ServerModeCatalog, + session_runtime_owner_bridge::{ + ServerAgentControlLimits, ServerRuntimeTestSupport, ServerSessionRuntimeBootstrapInput, + bootstrap_session_runtime, + }, }; pub(crate) struct AgentTestHarness { pub(crate) _guard: AgentTestEnvGuard, - pub(crate) kernel: Arc, - pub(crate) session_runtime: Arc, + pub(crate) session_runtime: AgentTestRuntimeHandle, pub(crate) service: AgentOrchestrationService, pub(crate) metrics: Arc, + _runtime_keepalive: Arc, +} + +#[derive(Clone)] +pub(crate) struct AgentTestRuntimeHandle { + session_catalog: Arc, + test_support: Arc, + agent_kernel: Arc, +} + +impl AgentTestRuntimeHandle { + pub(crate) fn agent(&self) -> &Self { + self + } + + pub(crate) fn agent_control(&self) -> &Self { + self + } + + pub(crate) async fn create_session(&self, working_dir: String) -> Result { + self.session_catalog.create_session(working_dir).await + } + + pub(crate) async fn replay_stored_events( + &self, + session_id: &SessionId, + ) -> Result> { + self.test_support + .replay_stored_events(session_id.as_str()) + .await + } + + pub(crate) async fn list_session_metas(&self) -> Result> { + self.session_catalog.list_session_metas().await + } + + pub(crate) async fn list_session_ids(&self) -> Result> { + Ok(self + .session_catalog + .list_session_metas() + .await? + .into_iter() + .map(|meta| SessionId::from(meta.session_id)) + .collect()) + } + + pub(crate) async fn get_lifecycle( + &self, + sub_run_or_agent_id: &str, + ) -> Option { + self.agent_kernel.get_lifecycle(sub_run_or_agent_id).await + } + + pub(crate) async fn get_agent_handle(&self, sub_run_or_agent_id: &str) -> Option { + self.agent_kernel.get_handle(sub_run_or_agent_id).await + } + + pub(crate) async fn get_handle(&self, sub_run_or_agent_id: &str) -> Option { + self.get_agent_handle(sub_run_or_agent_id).await + } + + pub(crate) async fn register_root_agent( + &self, + agent_id: impl Into, + session_id: impl Into, + profile_id: impl Into, + ) -> Result { + self.test_support + .register_root_agent(agent_id.into(), session_id.into(), profile_id.into()) + .await + .map_err(|error| AstrError::Validation(error.to_string())) + } + + pub(crate) async fn spawn_independent_child( + &self, + profile: &AgentProfile, + session_id: impl Into, + child_session_id: impl Into, + parent_turn_id: impl Into, + parent_agent_id: impl Into, + ) -> Result { + self.test_support + .spawn_independent_child( + profile, + session_id.into(), + child_session_id.into(), + parent_turn_id.into(), + parent_agent_id.into(), + ) + .await + .map_err(|error| AstrError::Validation(error.to_string())) + } + + pub(crate) async fn spawn_with_storage( + &self, + profile: &AgentProfile, + session_id: String, + child_session_id: Option, + parent_turn_id: String, + parent_agent_id: Option, + storage_mode: SubRunStorageMode, + ) -> Result { + if !matches!(storage_mode, SubRunStorageMode::IndependentSession) { + return Err(AstrError::Validation(format!( + "agent test runtime only supports independent child storage, got {storage_mode:?}" + ))); + } + let child_session_id = child_session_id.ok_or_else(|| { + AstrError::Validation( + "agent test runtime requires an explicit child session id for spawn".to_string(), + ) + })?; + let parent_agent_id = parent_agent_id.ok_or_else(|| { + AstrError::Validation( + "agent test runtime requires an explicit parent agent id for spawn".to_string(), + ) + })?; + self.spawn_independent_child( + profile, + session_id, + child_session_id, + parent_turn_id, + parent_agent_id, + ) + .await + } + + pub(crate) async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + lifecycle: AgentLifecycleStatus, + ) -> Result<()> { + self.test_support + .set_lifecycle(sub_run_or_agent_id, lifecycle) + .await + .ok_or_else(|| { + AstrError::Internal(format!( + "agent '{sub_run_or_agent_id}' disappeared before lifecycle update" + )) + }) + } - pub(crate) config_service: Arc, - pub(crate) profiles: Arc, + pub(crate) async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { + self.test_support + .pending_parent_delivery_count(parent_session_id) + .await + } + + pub(crate) async fn query_root_status( + &self, + session_id: &str, + ) -> Option { + self.test_support.query_root_status(session_id).await + } } impl AgentTestHarness { pub(crate) async fn append_events_to_session( &self, session_id: &str, - phase: Phase, + _phase: Phase, events: &[StorageEvent], ) -> Result<()> { - let state = self - .session_runtime - .get_session_state(&SessionId::from(session_id.to_string())) - .await?; - let mut translator = astrcode_core::EventTranslator::new(phase); for event in events { - let stored = state.writer.clone().append(event.clone()).await?; - let records = state.translate_store_and_cache(&stored, &mut translator)?; - for record in records { - let _ = state.broadcaster.send(record); - } + self.session_runtime + .test_support + .append_event(session_id, event.clone()) + .await?; } Ok(()) } pub(crate) async fn prepare_busy_turn(&self, session_id: &str, turn_id: &str) -> Result { self.session_runtime + .test_support .prepare_test_turn_runtime(session_id, turn_id) .await } @@ -76,6 +231,7 @@ impl AgentTestHarness { _phase: Phase, ) -> Result<()> { self.session_runtime + .test_support .complete_test_turn_runtime(session_id, generation) .await } @@ -90,23 +246,9 @@ pub(crate) fn build_agent_test_harness_with_agent_config( agent_config: Option, ) -> Result { let guard = AgentTestEnvGuard::new(); - let kernel = Arc::new( - Kernel::builder() - .with_capabilities(CapabilityRouter::empty()) - .with_llm_provider(Arc::new(TestLlmProvider::new(llm_behavior))) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .map_err(|error| AstrError::Internal(error.to_string()))?, - ); let metrics = Arc::new(RuntimeObservabilityCollector::new()); let event_store = Arc::new(InMemoryEventStore::default()); - let session_runtime = Arc::new(SessionRuntime::new( - Arc::clone(&kernel), - Arc::new(TestPromptFactsProvider), - event_store.clone(), - metrics.clone(), - )); + let session_catalog = Arc::new(SessionCatalog::new(event_store.clone())); let config_store = Arc::new(TestConfigStore::default()); if let Some(agent_config) = agent_config { config_store @@ -121,8 +263,27 @@ pub(crate) fn build_agent_test_harness_with_agent_config( StaticProfileProvider::default(), ))); let task_registry = Arc::new(TaskRegistry::new()); - let kernel_port: Arc = kernel.clone(); - let session_port: Arc = session_runtime.clone(); + let builtin_catalog = builtin_mode_catalog()?; + let builtin_mode_specs = builtin_catalog + .list() + .into_iter() + .filter_map(|summary| builtin_catalog.get(&summary.id)) + .collect::>(); + let bootstrapped_runtime = bootstrap_session_runtime(ServerSessionRuntimeBootstrapInput { + capability_invokers: Vec::new(), + llm_provider: Arc::new(TestLlmProvider::new(llm_behavior)), + session_catalog: Arc::clone(&session_catalog), + mode_catalog: ServerModeCatalog::from_mode_specs(builtin_mode_specs, Vec::new())?, + agent_limits: ServerAgentControlLimits { + max_depth: 8, + max_concurrent: 8, + finalized_retain_limit: 64, + inbox_capacity: 64, + parent_delivery_capacity: 64, + }, + })?; + let kernel_port: Arc = bootstrapped_runtime.agent_kernel.clone(); + let session_port: Arc = bootstrapped_runtime.agent_sessions.clone(); let service = AgentOrchestrationService::new( kernel_port, session_port, @@ -135,12 +296,14 @@ pub(crate) fn build_agent_test_harness_with_agent_config( Ok(AgentTestHarness { _guard: guard, - kernel, - session_runtime, + session_runtime: AgentTestRuntimeHandle { + session_catalog, + test_support: bootstrapped_runtime.test_support, + agent_kernel: bootstrapped_runtime.agent_kernel.clone(), + }, service, metrics, - config_service, - profiles, + _runtime_keepalive: bootstrapped_runtime.keepalive, }) } @@ -236,6 +399,7 @@ pub(crate) enum TestLlmBehavior { Succeed { content: String, }, + #[allow(dead_code)] Stream { reasoning_chunks: Vec, text_chunks: Vec, @@ -263,7 +427,7 @@ impl LlmProvider for TestLlmProvider { async fn generate( &self, _request: LlmRequest, - sink: Option, + sink: Option, ) -> Result { match &self.behavior { TestLlmBehavior::Succeed { content } => Ok(LlmOutput { @@ -314,53 +478,6 @@ impl LlmProvider for TestLlmProvider { } } -#[derive(Debug)] -struct TestPromptProvider; - -#[async_trait] -impl PromptProvider for TestPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "test".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: Value::Null, - }) - } -} - -#[derive(Debug)] -struct TestPromptFactsProvider; - -#[async_trait] -impl PromptFactsProvider for TestPromptFactsProvider { - async fn resolve_prompt_facts( - &self, - _request: &astrcode_core::PromptFactsRequest, - ) -> Result { - Ok(PromptFacts::default()) - } -} - -#[derive(Debug)] -struct TestResourceProvider; - -#[async_trait] -impl ResourceProvider for TestResourceProvider { - async fn read_resource( - &self, - uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: uri.to_string(), - content: Value::Null, - metadata: Value::Null, - }) - } -} - struct StaticProfileProvider { profiles: Vec, } diff --git a/crates/application/src/agent/wake.rs b/crates/server/src/agent/wake.rs similarity index 98% rename from crates/application/src/agent/wake.rs rename to crates/server/src/agent/wake.rs index 9ad51473..db2b1c94 100644 --- a/crates/application/src/agent/wake.rs +++ b/crates/server/src/agent/wake.rs @@ -686,7 +686,7 @@ mod tests { .await .expect("parent session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -712,7 +712,7 @@ mod tests { assert_eq!( harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&parent.session_id) .await, @@ -720,7 +720,12 @@ mod tests { "busy parent should keep delivery queued for retry" ); assert_eq!( - harness.session_runtime.list_sessions().len(), + harness + .session_runtime + .list_session_ids() + .await + .expect("session ids should list") + .len(), 1, "busy wake should not branch a new session" ); @@ -739,7 +744,7 @@ mod tests { let deadline = Instant::now() + Duration::from_secs(5); loop { if harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&parent.session_id) .await @@ -787,7 +792,7 @@ mod tests { .await .expect("middle session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -797,7 +802,7 @@ mod tests { .await .expect("root agent should register"); let middle = harness - .kernel + .session_runtime .agent_control() .spawn_with_storage( &sample_profile("reviewer"), @@ -810,7 +815,7 @@ mod tests { .await .expect("middle handle should spawn"); harness - .kernel + .session_runtime .agent_control() .set_lifecycle(&middle.agent_id, AgentLifecycleStatus::Running) .await @@ -861,12 +866,12 @@ mod tests { let deadline = Instant::now() + Duration::from_secs(5); loop { let middle_pending = harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&middle_session.session_id) .await; let root_pending = harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&root_session.session_id) .await; @@ -908,7 +913,7 @@ mod tests { .await .expect("parent session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -932,7 +937,7 @@ mod tests { loop { let metrics = harness.metrics.snapshot(); if harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&parent.session_id) .await @@ -971,7 +976,7 @@ mod tests { .await .expect("parent session should be created"); let root = harness - .kernel + .session_runtime .agent_control() .register_root_agent( "root-agent".to_string(), @@ -1016,7 +1021,7 @@ mod tests { let deadline = Instant::now() + Duration::from_secs(5); loop { if harness - .kernel + .session_runtime .agent_control() .pending_parent_delivery_count(&parent.session_id) .await @@ -1175,7 +1180,7 @@ mod tests { }, ]; - let recovered = astrcode_session_runtime::recoverable_parent_deliveries(&events); + let recovered = crate::ports::recoverable_parent_deliveries(&events); assert_eq!(recovered.len(), 1); assert_eq!(recovered[0].delivery_id, failed.notification_id.to_string()); diff --git a/crates/server/src/agent_control_bridge.rs b/crates/server/src/agent_control_bridge.rs new file mode 100644 index 00000000..e71e2bf1 --- /dev/null +++ b/crates/server/src/agent_control_bridge.rs @@ -0,0 +1,56 @@ +//! server-owned agent control bridge。 +//! +//! 收敛 agent 路由和 root execute 需要的 live status / close / root register 能力， +//! 让协议层和 server 状态面只暴露 server-owned DTO。 + +use astrcode_core::{AgentLifecycleStatus, AgentTurnOutcome, ResolvedExecutionLimitsSnapshot}; +use async_trait::async_trait; + +use crate::application_error_bridge::ServerRouteError; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerAgentHandleSummary { + pub agent_id: String, + pub session_id: String, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerLiveSubRunStatus { + pub sub_run_id: String, + pub agent_id: String, + pub agent_profile: String, + pub session_id: String, + pub child_session_id: Option, + pub depth: usize, + pub parent_agent_id: Option, + pub lifecycle: AgentLifecycleStatus, + pub last_turn_outcome: Option, + pub resolved_limits: ResolvedExecutionLimitsSnapshot, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerCloseAgentSummary { + pub closed_agent_ids: Vec, +} + +#[async_trait] +pub(crate) trait ServerAgentControlPort: Send + Sync { + async fn query_subrun_status(&self, agent_id: &str) -> Option; + async fn query_root_status(&self, session_id: &str) -> Option; + async fn get_handle(&self, agent_id: &str) -> Option; + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result; + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> bool; + async fn close_subtree( + &self, + agent_id: &str, + ) -> Result; +} diff --git a/crates/kernel/src/agent_tree/delivery_queue.rs b/crates/server/src/agent_control_registry/delivery_queue.rs similarity index 61% rename from crates/kernel/src/agent_tree/delivery_queue.rs rename to crates/server/src/agent_control_registry/delivery_queue.rs index 7229a698..1ad98567 100644 --- a/crates/kernel/src/agent_tree/delivery_queue.rs +++ b/crates/server/src/agent_control_registry/delivery_queue.rs @@ -8,14 +8,13 @@ use super::{ }, }; -/// 将指定 delivery_ids 的状态从 WakingParent 重置为 Queued（requeue 批量场景）。 fn mark_parent_deliveries_queued( queue: &mut ParentDeliveryQueue, delivery_ids: &HashSet<&String>, ) -> usize { let mut updated = 0usize; for entry in &mut queue.deliveries { - if delivery_ids.contains(&entry.delivery.delivery_id.to_string()) { + if delivery_ids.contains(&entry.delivery.delivery_id) { entry.state = PendingParentDeliveryState::Queued; updated += 1; } @@ -23,8 +22,6 @@ fn mark_parent_deliveries_queued( updated } -/// 从队列头部依次消费指定 delivery_ids，要求严格按 FIFO 顺序匹配。 -/// 如果队列头部的 delivery_id 与期望不符（顺序错乱），返回 false。 fn consume_front_deliveries(queue: &mut ParentDeliveryQueue, delivery_ids: &[String]) -> bool { for delivery_id in delivery_ids { let Some(front) = queue.deliveries.front() else { @@ -42,8 +39,6 @@ fn consume_front_deliveries(queue: &mut ParentDeliveryQueue, delivery_ids: &[Str true } -/// 入队一条 delivery，带去重（delivery_id）和容量保护。 -/// 返回 true 表示入队成功，false 表示重复或队列已满。 pub(super) fn enqueue_parent_delivery_locked( state: &mut AgentRegistryState, parent_delivery_capacity: usize, @@ -60,12 +55,6 @@ pub(super) fn enqueue_parent_delivery_locked( return false; } if queue.deliveries.len() >= parent_delivery_capacity { - log::warn!( - "parent_delivery_queue 已满 ({}/{}), 丢弃交付 {}", - queue.deliveries.len(), - parent_delivery_capacity, - delivery_id - ); queue.known_delivery_ids.remove(delivery_id.as_str()); return false; } @@ -85,22 +74,6 @@ pub(super) fn enqueue_parent_delivery_locked( true } -/// 单条 checkout：取队列头部的 Queued delivery，状态转为 WakingParent。 -pub(super) fn checkout_parent_delivery_locked( - state: &mut AgentRegistryState, - parent_session_id: &str, -) -> Option { - let queue = state.parent_delivery_queues.get_mut(parent_session_id)?; - let entry = queue.deliveries.front_mut()?; - if !matches!(entry.state, PendingParentDeliveryState::Queued) { - return None; - } - entry.state = PendingParentDeliveryState::WakingParent; - Some(entry.delivery.clone()) -} - -/// 批量 checkout：从队列头部连续取出同一 parent_agent_id 的 Queued delivery。 -/// 只包含连续且同父的 delivery，确保一个 wake turn 不会混合不同父 agent 的投递。 pub(super) fn checkout_parent_delivery_batch_locked( state: &mut AgentRegistryState, parent_session_id: &str, @@ -147,28 +120,6 @@ pub(super) fn checkout_parent_delivery_batch_locked( Some(deliveries) } -/// 单条 requeue：将指定 delivery 重置为 Queued 状态（wake 失败时回退）。 -pub(super) fn requeue_parent_delivery_locked( - state: &mut AgentRegistryState, - parent_session_id: &str, - delivery_id: &str, -) -> bool { - let Some(queue) = state.parent_delivery_queues.get_mut(parent_session_id) else { - return false; - }; - let Some(entry) = queue - .deliveries - .iter_mut() - .find(|entry| entry.delivery.delivery_id.as_str() == delivery_id) - else { - return false; - }; - entry.state = PendingParentDeliveryState::Queued; - true -} - -/// 批量 requeue：将指定 delivery_ids 的状态重置为 Queued。 -/// 返回实际重置的条目数。 pub(super) fn requeue_parent_delivery_batch_locked( state: &mut AgentRegistryState, parent_session_id: &str, @@ -177,34 +128,10 @@ pub(super) fn requeue_parent_delivery_batch_locked( let Some(queue) = state.parent_delivery_queues.get_mut(parent_session_id) else { return 0; }; - let target_ids = delivery_ids.iter().collect::>(); mark_parent_deliveries_queued(queue, &target_ids) } -/// 单条消费：从队列头部移除指定 delivery。队列为空时同步清理 session 的 queue 条目。 -pub(super) fn consume_parent_delivery_locked( - state: &mut AgentRegistryState, - parent_session_id: &str, - delivery_id: &str, -) -> bool { - let should_remove = { - let Some(queue) = state.parent_delivery_queues.get_mut(parent_session_id) else { - return false; - }; - if !consume_front_deliveries(queue, &[delivery_id.to_string()]) { - return false; - } - queue.deliveries.is_empty() - }; - - if should_remove { - state.parent_delivery_queues.remove(parent_session_id); - } - true -} - -/// 批量消费：按 FIFO 顺序从队列头部依次移除指定 delivery_ids。队列为空时清理 session 条目。 pub(super) fn consume_parent_delivery_batch_locked( state: &mut AgentRegistryState, parent_session_id: &str, @@ -226,7 +153,6 @@ pub(super) fn consume_parent_delivery_batch_locked( true } -/// 查询指定 session 的待投递 delivery 数量。 pub(super) fn pending_parent_delivery_count_locked( state: &AgentRegistryState, parent_session_id: &str, diff --git a/crates/server/src/agent_control_registry/mod.rs b/crates/server/src/agent_control_registry/mod.rs new file mode 100644 index 00000000..ba2b53f8 --- /dev/null +++ b/crates/server/src/agent_control_registry/mod.rs @@ -0,0 +1,533 @@ +mod delivery_queue; +mod state; +mod tree_ops; + +use std::{ + collections::{BTreeSet, HashSet, VecDeque}, + sync::{ + Arc, + atomic::{AtomicU64, Ordering}, + }, +}; + +use astrcode_core::{ + AgentInboxEnvelope, AgentLifecycleStatus, AgentProfile, AgentTurnOutcome, CancelToken, + ChildSessionLineageKind, DelegationMetadata, ResolvedExecutionLimitsSnapshot, + SubRunStorageMode, +}; +use astrcode_host_session::SubRunHandle; +use delivery_queue::{ + checkout_parent_delivery_batch_locked, consume_parent_delivery_batch_locked, + enqueue_parent_delivery_locked, pending_parent_delivery_count_locked, + requeue_parent_delivery_batch_locked, +}; +use state::{AgentRegistryEntry, AgentRegistryState, resolve_entry_key}; +use thiserror::Error; +use tokio::sync::{RwLock, watch}; +use tree_ops::{ + discard_parent_deliveries_locked, prune_finalized_agents_locked, terminate_tree_collect, +}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct PendingParentDelivery { + pub(crate) delivery_id: String, + pub(crate) parent_session_id: String, + pub(crate) parent_turn_id: String, + pub(crate) queued_at_ms: i64, + pub(crate) notification: astrcode_core::ChildSessionNotification, +} + +#[derive(Debug, Clone, PartialEq, Eq, Error)] +pub(crate) enum AgentControlError { + #[error("parent agent '{agent_id}' does not exist")] + ParentAgentNotFound { agent_id: String }, + #[error("agent depth {current} exceeds max depth {max}")] + MaxDepthExceeded { current: usize, max: usize }, + #[error("active agent count {current} exceeds max concurrent {max}")] + MaxConcurrentExceeded { current: usize, max: usize }, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct AgentControlLimits { + pub(crate) max_depth: usize, + pub(crate) max_concurrent: usize, + pub(crate) finalized_retain_limit: usize, + pub(crate) inbox_capacity: usize, + pub(crate) parent_delivery_capacity: usize, +} + +#[derive(Clone)] +pub(crate) struct AgentControlRegistry { + next_id: Arc, + next_finalized_seq: Arc, + max_depth: usize, + max_concurrent: usize, + finalized_retain_limit: usize, + inbox_capacity: usize, + parent_delivery_capacity: usize, + state: Arc>, +} + +impl AgentControlRegistry { + pub(crate) fn from_limits(limits: AgentControlLimits) -> Self { + Self { + next_id: Arc::new(AtomicU64::new(0)), + next_finalized_seq: Arc::new(AtomicU64::new(0)), + max_depth: limits.max_depth, + max_concurrent: limits.max_concurrent, + finalized_retain_limit: limits.finalized_retain_limit, + inbox_capacity: limits.inbox_capacity, + parent_delivery_capacity: limits.parent_delivery_capacity, + state: Arc::new(RwLock::new(AgentRegistryState::default())), + } + } + + pub(crate) async fn get(&self, sub_run_or_agent_id: &str) -> Option { + let state = self.state.read().await; + let key = resolve_entry_key(&state, sub_run_or_agent_id)?; + state.entries.get(key).map(|entry| entry.handle.clone()) + } + + pub(crate) async fn find_root_agent_for_session( + &self, + session_id: &str, + ) -> Option { + let state = self.state.read().await; + state + .entries + .values() + .find(|entry| entry.handle.depth == 0 && entry.handle.session_id.as_str() == session_id) + .map(|entry| entry.handle.clone()) + } + + pub(crate) async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result { + let mut state = self.state.write().await; + if let Some(existing_key) = state.agent_index.get(&agent_id) { + if let Some(entry) = state.entries.get(existing_key) { + return Ok(entry.handle.clone()); + } + } + let sub_run_id = format!("root-{agent_id}"); + let handle = SubRunHandle { + sub_run_id: sub_run_id.clone().into(), + agent_id: agent_id.clone().into(), + session_id: session_id.into(), + child_session_id: None, + depth: 0, + parent_turn_id: String::new().into(), + parent_agent_id: None, + parent_sub_run_id: None, + lineage_kind: ChildSessionLineageKind::Spawn, + agent_profile: profile_id, + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: AgentLifecycleStatus::Running, + last_turn_outcome: None, + resolved_limits: ResolvedExecutionLimitsSnapshot, + delegation: None, + }; + let cancel = CancelToken::new(); + let (status_tx, _status_rx) = watch::channel(handle.lifecycle); + state.entries.insert( + sub_run_id.clone(), + AgentRegistryEntry { + handle: handle.clone(), + cancel, + status_tx, + parent_agent_id: None, + children: BTreeSet::new(), + finalized_seq: None, + inbox: VecDeque::new(), + inbox_version: watch::channel(0).0, + lifecycle_status: AgentLifecycleStatus::Running, + last_turn_outcome: None, + }, + ); + state.agent_index.insert(agent_id, sub_run_id); + state.active_count += 1; + Ok(handle) + } + + pub(crate) async fn spawn_with_storage( + &self, + profile: &AgentProfile, + session_id: String, + child_session_id: Option, + parent_turn_id: String, + parent_agent_id: Option, + storage_mode: SubRunStorageMode, + ) -> Result { + let mut state = self.state.write().await; + let depth = match parent_agent_id.as_ref() { + Some(parent_agent_id) => { + let Some(parent_sub_run_id) = state.agent_index.get(parent_agent_id) else { + return Err(AgentControlError::ParentAgentNotFound { + agent_id: parent_agent_id.clone(), + }); + }; + let Some(parent) = state.entries.get(parent_sub_run_id) else { + return Err(AgentControlError::ParentAgentNotFound { + agent_id: parent_agent_id.clone(), + }); + }; + parent.handle.depth + 1 + }, + None => 1, + }; + if depth > self.max_depth { + return Err(AgentControlError::MaxDepthExceeded { + current: depth, + max: self.max_depth, + }); + } + if state.active_count >= self.max_concurrent { + return Err(AgentControlError::MaxConcurrentExceeded { + current: state.active_count, + max: self.max_concurrent, + }); + } + + let next_id = self.next_id.fetch_add(1, Ordering::SeqCst) + 1; + let agent_id = format!("agent-{next_id}"); + let sub_run_id = format!("subrun-{next_id}"); + let parent_sub_run_id = parent_agent_id + .as_ref() + .and_then(|parent_agent_id| state.agent_index.get(parent_agent_id)) + .cloned(); + let handle = SubRunHandle { + sub_run_id: sub_run_id.clone().into(), + agent_id: agent_id.clone().into(), + session_id: session_id.into(), + child_session_id: child_session_id.map(Into::into), + depth, + parent_turn_id: parent_turn_id.into(), + parent_agent_id: parent_agent_id.clone().map(Into::into), + parent_sub_run_id: parent_sub_run_id.map(Into::into), + lineage_kind: ChildSessionLineageKind::Spawn, + agent_profile: profile.id.clone(), + storage_mode, + lifecycle: AgentLifecycleStatus::Pending, + last_turn_outcome: None, + resolved_limits: ResolvedExecutionLimitsSnapshot, + delegation: None, + }; + let cancel = CancelToken::new(); + let (status_tx, _status_rx) = watch::channel(handle.lifecycle); + state.entries.insert( + sub_run_id.clone(), + AgentRegistryEntry { + handle: handle.clone(), + cancel, + status_tx, + parent_agent_id: parent_agent_id.clone(), + children: BTreeSet::new(), + finalized_seq: None, + inbox: VecDeque::new(), + inbox_version: watch::channel(0).0, + lifecycle_status: AgentLifecycleStatus::Pending, + last_turn_outcome: None, + }, + ); + state.agent_index.insert(agent_id, sub_run_id.clone()); + state.active_count += 1; + if let Some(parent_agent_id) = parent_agent_id { + if let Some(parent_sub_run_id) = state.agent_index.get(&parent_agent_id).cloned() { + if let Some(parent) = state.entries.get_mut(&parent_sub_run_id) { + parent.children.insert(sub_run_id); + } + } + } + prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); + Ok(handle) + } + + pub(crate) async fn get_lifecycle(&self, id: &str) -> Option { + let state = self.state.read().await; + let key = resolve_entry_key(&state, id)?; + state.entries.get(key).map(|entry| entry.lifecycle_status) + } + + pub(crate) async fn get_turn_outcome(&self, id: &str) -> Option> { + let state = self.state.read().await; + let key = resolve_entry_key(&state, id)?; + state.entries.get(key).map(|entry| entry.last_turn_outcome) + } + + pub(crate) async fn set_lifecycle( + &self, + id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()> { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, id)?.to_string(); + let entry = state.entries.get_mut(&key)?; + entry.lifecycle_status = new_status; + entry.handle.lifecycle = new_status; + entry.status_tx.send_replace(new_status); + Some(()) + } + + pub(crate) async fn complete_turn( + &self, + id: &str, + outcome: AgentTurnOutcome, + ) -> Option { + let next_seq = self.next_finalized_seq.fetch_add(1, Ordering::SeqCst); + let retain_limit = self.finalized_retain_limit; + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, id)?.to_string(); + let was_active = { + let entry = state.entries.get_mut(&key)?; + let was_active = entry.handle.lifecycle.occupies_slot(); + entry.last_turn_outcome = Some(outcome); + entry.lifecycle_status = AgentLifecycleStatus::Idle; + entry.handle.lifecycle = AgentLifecycleStatus::Idle; + entry.handle.last_turn_outcome = Some(outcome); + entry.finalized_seq = Some(next_seq); + entry.status_tx.send_replace(AgentLifecycleStatus::Idle); + was_active + }; + if was_active { + state.active_count = state.active_count.saturating_sub(1); + } + prune_finalized_agents_locked(&mut state, retain_limit); + Some(AgentLifecycleStatus::Idle) + } + + pub(crate) async fn set_resolved_limits( + &self, + id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> Option<()> { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, id)?.to_string(); + let entry = state.entries.get_mut(&key)?; + entry.handle.resolved_limits = resolved_limits; + Some(()) + } + + pub(crate) async fn set_delegation( + &self, + id: &str, + delegation: Option, + ) -> Option<()> { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, id)?.to_string(); + let entry = state.entries.get_mut(&key)?; + entry.handle.delegation = delegation; + Some(()) + } + + pub(crate) async fn list(&self) -> Vec { + let state = self.state.read().await; + let mut handles = state + .entries + .values() + .map(|entry| entry.handle.clone()) + .collect::>(); + handles.sort_by(|left, right| left.sub_run_id.cmp(&right.sub_run_id)); + handles + } + + pub(crate) async fn resume( + &self, + sub_run_or_agent_id: &str, + parent_turn_id: impl Into, + ) -> Option { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); + if state + .entries + .get(&key) + .is_none_or(|entry| entry.handle.lifecycle.occupies_slot()) + { + return None; + } + + let old_entry = state.entries.get(&key)?; + let old_handle = old_entry.handle.clone(); + let parent_agent_id = old_entry.parent_agent_id.clone(); + let children = old_entry.children.clone(); + + let next_id = self.next_id.fetch_add(1, Ordering::SeqCst) + 1; + let new_sub_run_id = format!("subrun-{next_id}"); + let mut new_handle = old_handle.clone(); + new_handle.sub_run_id = new_sub_run_id.clone().into(); + new_handle.parent_turn_id = parent_turn_id.into().into(); + new_handle.lineage_kind = ChildSessionLineageKind::Resume; + new_handle.lifecycle = AgentLifecycleStatus::Running; + new_handle.last_turn_outcome = None; + + let cancel = CancelToken::new(); + let (status_tx, _status_rx) = watch::channel(new_handle.lifecycle); + let inbox_version = watch::channel(0).0; + + state.active_count += 1; + state.entries.insert( + new_sub_run_id.clone(), + AgentRegistryEntry { + handle: new_handle.clone(), + cancel, + status_tx, + parent_agent_id: parent_agent_id.clone(), + children: children.clone(), + finalized_seq: None, + inbox: VecDeque::new(), + inbox_version, + lifecycle_status: AgentLifecycleStatus::Running, + last_turn_outcome: None, + }, + ); + state + .agent_index + .insert(new_handle.agent_id.to_string(), new_sub_run_id.clone()); + + if let Some(parent_agent_id) = parent_agent_id { + if let Some(parent_sub_run_id) = state.agent_index.get(&parent_agent_id).cloned() { + if let Some(parent) = state.entries.get_mut(&parent_sub_run_id) { + parent.children.remove(&key); + parent.children.insert(new_sub_run_id); + } + } + } + Some(new_handle) + } + + pub(crate) async fn push_inbox( + &self, + sub_run_or_agent_id: &str, + envelope: AgentInboxEnvelope, + ) -> Option<()> { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); + let entry = state.entries.get_mut(&key)?; + if entry.inbox.len() >= self.inbox_capacity { + return None; + } + entry.inbox.push_back(envelope); + let current = *entry.inbox_version.borrow(); + entry.inbox_version.send_replace(current + 1); + Some(()) + } + + pub(crate) async fn drain_inbox( + &self, + sub_run_or_agent_id: &str, + ) -> Option> { + let mut state = self.state.write().await; + let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); + let entry = state.entries.get_mut(&key)?; + Some(entry.inbox.drain(..).collect()) + } + + pub(crate) async fn enqueue_parent_delivery( + &self, + parent_session_id: String, + parent_turn_id: String, + notification: astrcode_core::ChildSessionNotification, + ) -> bool { + let mut state = self.state.write().await; + enqueue_parent_delivery_locked( + &mut state, + self.parent_delivery_capacity, + parent_session_id, + parent_turn_id, + notification, + ) + } + + pub(crate) async fn checkout_parent_delivery_batch( + &self, + parent_session_id: &str, + ) -> Option> { + let mut state = self.state.write().await; + checkout_parent_delivery_batch_locked(&mut state, parent_session_id) + } + + pub(crate) async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { + let state = self.state.read().await; + pending_parent_delivery_count_locked(&state, parent_session_id) + } + + pub(crate) async fn requeue_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) { + let mut state = self.state.write().await; + requeue_parent_delivery_batch_locked(&mut state, parent_session_id, delivery_ids); + } + + pub(crate) async fn consume_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) -> bool { + let mut state = self.state.write().await; + consume_parent_delivery_batch_locked(&mut state, parent_session_id, delivery_ids) + } + + pub(crate) async fn terminate_subtree_and_collect_handles( + &self, + sub_run_or_agent_id: &str, + ) -> Option> { + let mut state = self.state.write().await; + let mut visited = HashSet::new(); + let mut terminated = Vec::new(); + let key = resolve_entry_key(&state, sub_run_or_agent_id)?.to_string(); + terminate_tree_collect( + &mut state, + &key, + &mut visited, + &mut terminated, + &self.next_finalized_seq, + )?; + let terminated_agent_ids = terminated + .iter() + .map(|handle| handle.agent_id.clone()) + .collect::>(); + discard_parent_deliveries_locked(&mut state, &terminated_agent_ids); + prune_finalized_agents_locked(&mut state, self.finalized_retain_limit); + Some(terminated) + } + + pub(crate) async fn terminate_subtree( + &self, + sub_run_or_agent_id: &str, + ) -> Option { + self.terminate_subtree_and_collect_handles(sub_run_or_agent_id) + .await + .and_then(|mut handles| handles.drain(..).next()) + } + + pub(crate) async fn collect_subtree_handles( + &self, + sub_run_or_agent_id: &str, + ) -> Vec { + let state = self.state.read().await; + let mut result = Vec::new(); + let mut queue = std::collections::VecDeque::new(); + + if let Some(key) = resolve_entry_key(&state, sub_run_or_agent_id) { + if let Some(entry) = state.entries.get(key) { + for child_sub_run_id in &entry.children { + queue.push_back(child_sub_run_id.clone()); + } + } + } + + while let Some(child_key) = queue.pop_front() { + if let Some(entry) = state.entries.get(&child_key) { + result.push(entry.handle.clone()); + for grandchild in &entry.children { + queue.push_back(grandchild.clone()); + } + } + } + result + } +} diff --git a/crates/server/src/agent_control_registry/state.rs b/crates/server/src/agent_control_registry/state.rs new file mode 100644 index 00000000..731e2f6a --- /dev/null +++ b/crates/server/src/agent_control_registry/state.rs @@ -0,0 +1,66 @@ +use std::collections::{BTreeSet, HashMap, HashSet, VecDeque}; + +use astrcode_core::{AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, CancelToken}; +use astrcode_host_session::SubRunHandle; +use tokio::sync::watch; + +use super::PendingParentDelivery; + +#[derive(Default)] +pub(super) struct AgentRegistryState { + pub(super) entries: HashMap, + pub(super) agent_index: HashMap, + pub(super) active_count: usize, + pub(super) parent_delivery_queues: HashMap, +} + +pub(super) struct AgentRegistryEntry { + pub(super) handle: SubRunHandle, + pub(super) cancel: CancelToken, + pub(super) status_tx: watch::Sender, + pub(super) parent_agent_id: Option, + pub(super) children: BTreeSet, + pub(super) finalized_seq: Option, + pub(super) inbox: VecDeque, + pub(super) inbox_version: watch::Sender, + pub(super) lifecycle_status: AgentLifecycleStatus, + pub(super) last_turn_outcome: Option, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum PendingParentDeliveryState { + Queued, + WakingParent, +} + +#[derive(Debug, Clone)] +pub(super) struct PendingParentDeliveryEntry { + pub(super) delivery: PendingParentDelivery, + pub(super) state: PendingParentDeliveryState, +} + +#[derive(Default)] +pub(super) struct ParentDeliveryQueue { + pub(super) deliveries: VecDeque, + pub(super) known_delivery_ids: HashSet, +} + +pub(super) fn resolve_entry_key<'a>( + state: &'a AgentRegistryState, + sub_run_or_agent_id: &'a str, +) -> Option<&'a str> { + if state.entries.contains_key(sub_run_or_agent_id) { + return Some(sub_run_or_agent_id); + } + state + .agent_index + .get(sub_run_or_agent_id) + .map(String::as_str) +} + +pub(super) fn entry_children(state: &AgentRegistryState, sub_run_id: &str) -> Option> { + state + .entries + .get(sub_run_id) + .map(|entry| entry.children.iter().cloned().collect()) +} diff --git a/crates/kernel/src/agent_tree/tree_ops.rs b/crates/server/src/agent_control_registry/tree_ops.rs similarity index 67% rename from crates/kernel/src/agent_tree/tree_ops.rs rename to crates/server/src/agent_control_registry/tree_ops.rs index 9e9fc43c..310b8014 100644 --- a/crates/kernel/src/agent_tree/tree_ops.rs +++ b/crates/server/src/agent_control_registry/tree_ops.rs @@ -3,7 +3,8 @@ use std::{ sync::atomic::{AtomicU64, Ordering}, }; -use astrcode_core::{AgentLifecycleStatus, AgentTurnOutcome, SubRunHandle}; +use astrcode_core::{AgentId, AgentLifecycleStatus, AgentTurnOutcome}; +use astrcode_host_session::SubRunHandle; use super::state::{AgentRegistryState, entry_children}; @@ -14,10 +15,6 @@ struct TerminateTreePolicy { only_if_active: bool, } -/// 通用树遍历骨架，visitor 模式统一 cancel / terminate / collect 等操作。 -/// -/// 深度优先遍历以 `agent_id` 为根的子树，对每个节点调用 `visit` 闭包。 -/// `visited` 防止环形引用导致无限递归；已访问节点直接返回缓存的 handle 而不再 visit。 pub(super) fn traverse_tree( state: &mut AgentRegistryState, agent_id: &str, @@ -40,11 +37,6 @@ pub(super) fn traverse_tree( Some(handle) } -/// 将单个 agent entry 标记为 Terminated 并执行所有终态副作用。 -/// -/// 副作用包括：更新 lifecycle 状态、分配 finalized_seq、触发 cancel token、 -/// 递减 active_count（仅当之前占用 slot 时）。 -/// `clear_inbox` / `bump_inbox_version` 由调用方按场景决定是否清理 inbox。 pub(super) fn mark_entry_terminated( state: &mut AgentRegistryState, agent_id: &str, @@ -60,28 +52,23 @@ pub(super) fn mark_entry_terminated( entry.handle.last_turn_outcome = Some(AgentTurnOutcome::Cancelled); entry.last_turn_outcome = Some(AgentTurnOutcome::Cancelled); entry.finalized_seq = Some(next_finalized_seq.fetch_add(1, Ordering::SeqCst)); - // finalized_seq 保证全局递增，用于 GC 按终结顺序回收。 if clear_inbox { entry.inbox.clear(); } if bump_inbox_version { - let current_inbox_version = *entry.inbox_version.borrow(); - entry.inbox_version.send_replace(current_inbox_version + 1); + let current = *entry.inbox_version.borrow(); + entry.inbox_version.send_replace(current + 1); } entry .status_tx .send_replace(AgentLifecycleStatus::Terminated); entry.cancel.cancel(); - if was_active { state.active_count = state.active_count.saturating_sub(1); } - Some(entry.handle.clone()) } -/// 仅当 agent 当前占用活跃 slot 时才执行 terminate。 -/// 返回 `Some(Some(handle))` 表示已终止，`Some(None)` 表示无需操作，`None` 表示 agent 不存在。 pub(super) fn mark_entry_terminated_if_active( state: &mut AgentRegistryState, agent_id: &str, @@ -137,29 +124,6 @@ fn traverse_terminated_tree( ) } -/// 递归取消子树：不清理 inbox、不 bump inbox version（用于 cancel_for_parent_turn）。 -pub(super) fn cancel_tree( - state: &mut AgentRegistryState, - agent_id: &str, - visited: &mut HashSet, - next_finalized_seq: &AtomicU64, -) -> Option { - traverse_terminated_tree( - state, - agent_id, - visited, - next_finalized_seq, - TerminateTreePolicy { - clear_inbox: false, - bump_inbox_version: false, - only_if_active: false, - }, - |_| {}, - ) -} - -/// 递归终止子树并收集所有被终止的 handle（用于 close_child 级联关闭）。 -/// 会清理 inbox 并 bump inbox version，因为 close 是最终操作。 pub(super) fn terminate_tree_collect( state: &mut AgentRegistryState, agent_id: &str, @@ -181,34 +145,9 @@ pub(super) fn terminate_tree_collect( ) } -/// 递归取消子树中仍然活跃的 agent，仅收集实际被终止的 handle。 -/// 已处于 Terminated/Idle 的 agent 会被跳过（通过 mark_entry_terminated_if_active）。 -pub(super) fn cancel_tree_collect( - state: &mut AgentRegistryState, - agent_id: &str, - visited: &mut HashSet, - cancelled: &mut Vec, - next_finalized_seq: &AtomicU64, -) { - let _ = traverse_terminated_tree( - state, - agent_id, - visited, - next_finalized_seq, - TerminateTreePolicy { - clear_inbox: false, - bump_inbox_version: false, - only_if_active: true, - }, - |handle| cancelled.push(handle), - ); -} - -/// 清理已终止 agent 在父级 delivery queue 中残留的待投递条目。 -/// 如果 queue 被清空则移除整个 session 的 queue 条目，避免空 map 条目累积。 pub(super) fn discard_parent_deliveries_locked( state: &mut AgentRegistryState, - terminated_agent_ids: &HashSet, + terminated_agent_ids: &HashSet, ) -> usize { if terminated_agent_ids.is_empty() { return 0; @@ -242,16 +181,9 @@ pub(super) fn discard_parent_deliveries_locked( for session_id in empty_sessions { state.parent_delivery_queues.remove(&session_id); } - removed_count } -/// GC：回收已终结（finalized）且无子节点的叶子 agent。 -/// -/// 每轮迭代找到 finalized_seq 最小的叶子 agent（最早终结的优先回收）， -/// 从父节点的 children 集合中断开，然后从 registry 中移除。 -/// 循环直到叶子终结数量 ≤ `finalized_retain_limit`。 -/// `usize::MAX` 表示不执行任何回收。 pub(super) fn prune_finalized_agents_locked( state: &mut AgentRegistryState, finalized_retain_limit: usize, @@ -276,7 +208,6 @@ pub(super) fn prune_finalized_agents_locked( } finalized_leaf_agents.sort_by_key(|(seq, agent_id, _)| (*seq, agent_id.clone())); - // 取 finalized_seq 最小的叶子优先回收——最早终结的 agent 最不可能还需要回查。 let Some((_, agent_id, parent_agent_id)) = finalized_leaf_agents.into_iter().next() else { break; }; diff --git a/crates/server/src/agent_runtime_bridge.rs b/crates/server/src/agent_runtime_bridge.rs new file mode 100644 index 00000000..9c26c843 --- /dev/null +++ b/crates/server/src/agent_runtime_bridge.rs @@ -0,0 +1,211 @@ +//! server-owned agent runtime bridge builder。 +//! +//! 把 application orchestration / governance-surface 组装细节收敛到单独 +//! bridge 文件，避免组合根直接消费 app service 类型。 + +use std::{path::Path, sync::Arc}; + +use astrcode_core::ModeId; +use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; + +use crate::{ + AgentOrchestrationService, ApplicationError, GovernanceSurfaceAssembler, ModeCatalog, + ProfileProvider, ProfileResolutionService, ResolvedGovernanceSurface, RootGovernanceInput, + agent_api::ServerAgentApi, + agent_control_bridge::ServerAgentControlPort, + application_error_bridge::ServerRouteError, + config_service_bridge::ServerConfigService, + mode_catalog_service::ServerModeCatalog, + ports::{AgentKernelPort, AgentSessionPort, AppSessionPort}, + profile_service::ServerProfileService, + root_execute_service::ServerRootExecuteService, + runtime_owner_bridge::{ServerRuntimeObservability, ServerTaskRegistry}, +}; + +pub(crate) struct ServerAgentRuntimeBundle { + pub agent_api: Arc, + pub agent_control: Arc, + pub subagent_executor: Arc, + pub collaboration_executor: Arc, +} + +pub(crate) struct ServerAgentRuntimeBuildInput { + pub agent_kernel: Arc, + pub agent_sessions: Arc, + pub app_sessions: Arc, + pub agent_control: Arc, + pub config_service: Arc, + pub profiles: Arc, + pub mode_catalog: Arc, + pub task_registry: Arc, + pub observability: Arc, +} + +pub(crate) fn build_server_agent_runtime_bundle( + input: ServerAgentRuntimeBuildInput, +) -> ServerAgentRuntimeBundle { + let ServerAgentRuntimeBuildInput { + agent_kernel, + agent_sessions, + app_sessions, + agent_control, + config_service, + profiles, + mode_catalog, + task_registry, + observability, + } = input; + let profile_resolution = build_profile_resolution_service(profiles.clone()); + let governance_surface = Arc::new(GovernanceSurfaceAssembler::new( + build_governance_mode_catalog(mode_catalog.as_ref()), + )); + let agent_service = Arc::new(AgentOrchestrationService::new( + agent_kernel, + agent_sessions.clone(), + Arc::clone(config_service.inner()), + profile_resolution, + Arc::clone(&governance_surface), + task_registry.inner(), + observability, + )); + let agent_api = Arc::new(ServerAgentApi::new( + agent_control.clone(), + app_sessions.clone(), + profiles.clone(), + Arc::new(ServerRootExecuteService::new( + Arc::clone(&agent_control), + app_sessions, + profiles, + config_service, + Arc::new(ApplicationRootGovernancePort::new(governance_surface)), + )), + )); + let subagent_executor: Arc = agent_service.clone(); + let collaboration_executor: Arc = agent_service; + + ServerAgentRuntimeBundle { + agent_api, + agent_control, + subagent_executor, + collaboration_executor, + } +} + +fn build_governance_mode_catalog(mode_catalog: &ServerModeCatalog) -> ModeCatalog { + let snapshot = mode_catalog.snapshot(); + let builtin_modes = snapshot + .entries + .values() + .filter(|entry| entry.builtin) + .map(|entry| entry.spec.clone()) + .collect::>(); + let plugin_modes = snapshot + .entries + .values() + .filter(|entry| !entry.builtin) + .map(|entry| entry.spec.clone()) + .collect::>(); + ModeCatalog::new(builtin_modes, plugin_modes) + .expect("server mode catalog snapshot should stay valid for governance") +} + +fn build_profile_resolution_service( + profiles: Arc, +) -> Arc { + Arc::new(ProfileResolutionService::new(Arc::new( + ServerProfileProviderAdapter { profiles }, + ))) +} + +struct ApplicationRootGovernancePort { + assembler: Arc, +} + +struct ServerProfileProviderAdapter { + profiles: Arc, +} + +impl ApplicationRootGovernancePort { + fn new(assembler: Arc) -> Self { + Self { assembler } + } +} + +impl crate::root_execute_service::ServerRootGovernancePort for ApplicationRootGovernancePort { + fn prepare_root_submission( + &self, + input: crate::root_execute_service::ServerRootGovernanceInput, + ) -> Result { + let surface = self + .assembler + .root_surface(RootGovernanceInput { + session_id: input.session_id, + turn_id: input.turn_id, + working_dir: input.working_dir, + profile: input.profile_id.clone(), + mode_id: ModeId::default(), + runtime: input.runtime, + control: input.control, + }) + .map_err(application_error_to_server)?; + prepared_root_execution_from_surface(input.agent_id, input.profile_id, surface) + } +} + +impl ProfileProvider for ServerProfileProviderAdapter { + fn load_for_working_dir( + &self, + working_dir: &Path, + ) -> Result, ApplicationError> { + self.profiles + .resolve(working_dir) + .map(|profiles| profiles.as_ref().clone()) + .map_err(server_route_error_to_application_error) + } + + fn load_global(&self) -> Result, ApplicationError> { + self.profiles + .resolve_global() + .map(|profiles| profiles.as_ref().clone()) + .map_err(server_route_error_to_application_error) + } +} + +fn server_route_error_to_application_error(error: ServerRouteError) -> ApplicationError { + match error { + ServerRouteError::NotFound(message) => ApplicationError::NotFound(message), + ServerRouteError::Conflict(message) => ApplicationError::Conflict(message), + ServerRouteError::InvalidArgument(message) => ApplicationError::InvalidArgument(message), + ServerRouteError::PermissionDenied(message) => ApplicationError::PermissionDenied(message), + ServerRouteError::Internal(message) => ApplicationError::Internal(message), + } +} + +fn application_error_to_server(error: ApplicationError) -> ServerRouteError { + match error { + ApplicationError::NotFound(message) => ServerRouteError::NotFound(message), + ApplicationError::Conflict(message) => ServerRouteError::Conflict(message), + ApplicationError::InvalidArgument(message) => ServerRouteError::InvalidArgument(message), + ApplicationError::PermissionDenied(message) => ServerRouteError::PermissionDenied(message), + ApplicationError::Internal(message) => ServerRouteError::Internal(message), + } +} + +fn prepared_root_execution_from_surface( + agent_id: String, + profile_id: String, + surface: ResolvedGovernanceSurface, +) -> Result { + let runtime = surface.runtime.clone(); + let resolved_limits = surface.resolved_limits.clone(); + let submission = surface.into_submission( + astrcode_core::AgentEventContext::root_execution(agent_id, profile_id), + None, + ); + + Ok(crate::root_execute_service::ServerPreparedRootExecution { + runtime, + resolved_limits, + submission, + }) +} diff --git a/crates/server/src/application_error_bridge.rs b/crates/server/src/application_error_bridge.rs new file mode 100644 index 00000000..3ca4b0d2 --- /dev/null +++ b/crates/server/src/application_error_bridge.rs @@ -0,0 +1,67 @@ +//! server-owned application error bridge。 +//! +//! 定义 server 自己的 route-facing 错误枚举。 + +use astrcode_core::AstrError; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) enum ServerRouteError { + NotFound(String), + Conflict(String), + InvalidArgument(String), + PermissionDenied(String), + Internal(String), +} + +impl ServerRouteError { + pub(crate) fn not_found(message: impl Into) -> Self { + Self::NotFound(message.into()) + } + + pub(crate) fn invalid_argument(message: impl Into) -> Self { + Self::InvalidArgument(message.into()) + } + + pub(crate) fn permission_denied(message: impl Into) -> Self { + Self::PermissionDenied(message.into()) + } + + pub(crate) fn internal(message: impl Into) -> Self { + Self::Internal(message.into()) + } +} + +impl From for ServerRouteError { + fn from(value: AstrError) -> Self { + match value { + AstrError::SessionNotFound(_) + | AstrError::ProjectNotFound(_) + | AstrError::ModelNotFound { .. } => Self::NotFound(value.to_string()), + AstrError::TurnInProgress(_) | AstrError::Cancelled => { + Self::Conflict(value.to_string()) + }, + AstrError::InvalidSessionId(_) + | AstrError::ConfigError { .. } + | AstrError::MissingApiKey(_) + | AstrError::MissingBaseUrl(_) + | AstrError::NoProfilesConfigured + | AstrError::UnsupportedProvider(_) + | AstrError::Validation(_) => Self::InvalidArgument(value.to_string()), + _ => Self::Internal(value.to_string()), + } + } +} + +impl std::fmt::Display for ServerRouteError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + ServerRouteError::NotFound(message) + | ServerRouteError::Conflict(message) + | ServerRouteError::InvalidArgument(message) + | ServerRouteError::PermissionDenied(message) + | ServerRouteError::Internal(message) => f.write_str(message), + } + } +} + +impl std::error::Error for ServerRouteError {} diff --git a/crates/server/src/bootstrap/capabilities.rs b/crates/server/src/bootstrap/capabilities.rs index 1ef107c6..febbc654 100644 --- a/crates/server/src/bootstrap/capabilities.rs +++ b/crates/server/src/bootstrap/capabilities.rs @@ -32,19 +32,21 @@ use astrcode_adapter_tools::{ write_file::WriteFileTool, }, }; -use astrcode_application::AgentOrchestrationService; -use astrcode_core::{SkillCatalog, SkillSpec}; - -use super::deps::{ - core::{CapabilityInvoker, Result, Tool}, - kernel::{CapabilityRouter, Kernel, ToolCapabilityInvoker}, +use astrcode_core::{CapabilitySpec, SkillCatalog, SkillSpec}; +use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; +use astrcode_plugin_host::{ResourceCatalog, build_skill_catalog_base}; + +use super::deps::core::{CapabilityInvoker, Result, Tool}; +use crate::{ + session_runtime_owner_bridge::ServerCapabilitySurfacePort, + tool_capability_invoker::ToolCapabilityInvoker, }; /// 构建稳定本地层中的 core builtin tool invokers。 /// /// 这里的“builtin”是能力来源语义，不等同于“所有稳定能力”。 /// 例如 agent 四工具同样属于稳定本地能力，但不在本函数中构建， -/// 因为它们依赖 `AgentOrchestrationService`，必须在更晚的组合根阶段装配。 +/// 因为它们依赖协作执行 trait object，必须在更晚的组合根阶段装配。 pub(crate) fn build_core_tool_invokers( tool_search_index: Arc, skill_catalog: Arc, @@ -86,12 +88,16 @@ pub(crate) fn build_core_tool_invokers( /// 这样 catalog 才能在后续叠加 user/project 时保持正确优先级。 pub(crate) fn build_skill_catalog( home_dir: &Path, - mut external_base_skills: Vec, + external_base_skills: Vec, + resource_catalog: &ResourceCatalog, ) -> Arc { - let mut base_skills = load_builtin_skills(); - base_skills.append(&mut external_base_skills); + let base_build = build_skill_catalog_base( + load_builtin_skills(), + external_base_skills, + resource_catalog, + ); Arc::new(LayeredSkillCatalog::new_with_home_dir( - base_skills, + base_build.base_skills, home_dir, )) } @@ -111,32 +117,29 @@ pub(crate) fn sync_external_tool_search_index( tool_search_index.replace_from_specs(external_specs); } -pub(crate) fn build_server_capability_router( - invokers: Vec>, -) -> Result { - let router = CapabilityRouter::empty(); - router.register_invokers(invokers)?; - Ok(router) -} - #[derive(Clone)] pub(crate) struct CapabilitySurfaceSync { stable_local_invokers: Vec>, - router: CapabilityRouter, - kernel: Arc, + capability_surface: Arc, tool_search_index: Arc, + current_capabilities: Arc>>, current_external_invokers: Arc>>>, } impl CapabilitySurfaceSync { pub(crate) fn new( - kernel: Arc, + capability_surface: Arc, stable_local_invokers: Vec>, tool_search_index: Arc, ) -> Self { Self { - router: kernel.gateway().capabilities().clone(), - kernel, + capability_surface, + current_capabilities: Arc::new(RwLock::new( + stable_local_invokers + .iter() + .map(|invoker| invoker.capability_spec()) + .collect(), + )), stable_local_invokers, tool_search_index, current_external_invokers: Arc::new(RwLock::new(Vec::new())), @@ -154,16 +157,22 @@ impl CapabilitySurfaceSync { ) -> Result<()> { let mut invokers = self.stable_local_invokers.clone(); invokers.extend(external_invokers.clone()); - self.router.replace_invokers(invokers.clone())?; - self.kernel - .surface() - .replace_capabilities(&invokers, self.kernel.events()); + self.capability_surface + .replace_capability_invokers(invokers.clone())?; let external_specs = invokers .iter() .skip(self.stable_local_invokers.len()) .map(|invoker| invoker.capability_spec()) .collect(); self.tool_search_index.replace_from_specs(external_specs); + *self + .current_capabilities + .write() + .expect("capability surface sync current capabilities lock should not be poisoned") = + invokers + .iter() + .map(|invoker| invoker.capability_spec()) + .collect(); *self .current_external_invokers .write() @@ -172,8 +181,11 @@ impl CapabilitySurfaceSync { Ok(()) } - pub(crate) fn current_capabilities(&self) -> Vec { - self.kernel.surface().snapshot().capability_specs + pub(crate) fn current_capabilities(&self) -> Vec { + self.current_capabilities + .read() + .expect("capability surface sync current capabilities lock should not be poisoned") + .clone() } pub(crate) fn current_external_invokers(&self) -> Vec> { @@ -190,13 +202,14 @@ impl CapabilitySurfaceSync { /// 而 kernel 的 capability surface 又需要包含 agent 工具， /// 所以 agent 工具的注册必须在 kernel + session_runtime 构建之后单独完成。 pub(crate) fn build_agent_tool_invokers( - agent_service: Arc, + subagent_executor: Arc, + collaboration_executor: Arc, ) -> Result>> { let tools: Vec> = vec![ - Arc::new(SpawnAgentTool::new(agent_service.clone())), - Arc::new(SendAgentTool::new(agent_service.clone())), - Arc::new(CloseAgentTool::new(agent_service.clone())), - Arc::new(ObserveAgentTool::new(agent_service)), + Arc::new(SpawnAgentTool::new(subagent_executor)), + Arc::new(SendAgentTool::new(Arc::clone(&collaboration_executor))), + Arc::new(CloseAgentTool::new(Arc::clone(&collaboration_executor))), + Arc::new(ObserveAgentTool::new(collaboration_executor)), ]; Ok(tools .into_iter() @@ -226,9 +239,13 @@ pub(crate) fn build_stable_local_invokers( #[cfg(test)] mod tests { - use std::sync::Arc; + use std::{ + collections::HashSet, + sync::{Arc, RwLock}, + }; use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; + use astrcode_plugin_host::ResourceCatalog; use async_trait::async_trait; use serde_json::{Value, json}; @@ -236,18 +253,17 @@ mod tests { CapabilitySurfaceSync, build_core_tool_invokers, build_skill_catalog, build_stable_local_invokers, }; - use crate::bootstrap::{ - capabilities::sync_external_tool_search_index, - deps::{ - core::{ + use crate::{ + bootstrap::{ + capabilities::sync_external_tool_search_index, + deps::core::{ AstrError, CapabilityInvoker, CapabilityKind, CapabilitySpec, - CapabilitySpecBuildError, LlmEventSink, LlmOutput, LlmProvider, LlmRequest, - ModelLimits, PromptBuildOutput, PromptBuildRequest, PromptProvider, - ResourceProvider, ResourceReadResult, ResourceRequestContext, Result, Tool, - ToolContext, ToolDefinition, ToolExecutionResult, + CapabilitySpecBuildError, Result, Tool, ToolContext, ToolDefinition, + ToolExecutionResult, }, - kernel::{CapabilityRouter, Kernel, ToolCapabilityInvoker}, }, + session_runtime_owner_bridge::ServerCapabilitySurfacePort, + tool_capability_invoker::ToolCapabilityInvoker, }; #[derive(Debug)] @@ -294,63 +310,6 @@ mod tests { } } - #[derive(Debug)] - struct NoopLlmProvider; - - #[async_trait] - impl LlmProvider for NoopLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Err(AstrError::Validation( - "noop llm provider should not execute in this test".to_string(), - )) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 8192, - max_output_tokens: 4096, - } - } - } - - #[derive(Debug)] - struct NoopPromptProvider; - - #[async_trait] - impl PromptProvider for NoopPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: Value::Null, - }) - } - } - - #[derive(Debug)] - struct NoopResourceProvider; - - #[async_trait] - impl ResourceProvider for NoopResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: Value::Null, - metadata: Value::Null, - }) - } - } - fn invoker(name: &'static str, tags: &'static [&'static str]) -> Arc { Arc::new( ToolCapabilityInvoker::new(Arc::new(StaticTool { name, tags })) @@ -358,31 +317,53 @@ mod tests { ) as Arc } - fn test_kernel(builtin_invokers: &[Arc]) -> Arc { - let mut builder = CapabilityRouter::builder(); - for invoker in builtin_invokers { - builder = builder.register_invoker(Arc::clone(invoker)); + #[derive(Default)] + struct TestCapabilitySurface { + invokers: RwLock>>, + } + + impl TestCapabilitySurface { + fn capability_tool_names(&self) -> Vec { + self.invokers + .read() + .expect("test capability surface lock should not be poisoned") + .iter() + .map(|invoker| invoker.capability_spec().name.to_string()) + .collect() + } + } + + impl ServerCapabilitySurfacePort for TestCapabilitySurface { + fn replace_capability_invokers( + &self, + invokers: Vec>, + ) -> Result<()> { + let mut seen = HashSet::new(); + for invoker in &invokers { + let name = invoker.capability_spec().name.to_string(); + if !seen.insert(name.clone()) { + return Err(AstrError::Validation(format!( + "duplicate capability '{}'", + name + ))); + } + } + *self + .invokers + .write() + .expect("test capability surface lock should not be poisoned") = invokers; + Ok(()) } - let router = builder.build().expect("router should build"); - Arc::new( - Kernel::builder() - .with_capabilities(router) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"), - ) } #[test] fn apply_external_invokers_keeps_previous_surface_on_failure() { let builtin_invoker = invoker("read_file", &["source:builtin"]); let core_tool_invokers = vec![builtin_invoker]; - let kernel = test_kernel(&core_tool_invokers); + let capability_surface = Arc::new(TestCapabilitySurface::default()); let tool_search_index = Arc::new(ToolSearchIndex::new()); let sync = CapabilitySurfaceSync::new( - Arc::clone(&kernel), + capability_surface, core_tool_invokers.clone(), Arc::clone(&tool_search_index), ); @@ -446,10 +427,10 @@ mod tests { let agent_invoker = invoker("spawn", &["builtin", "agent"]); let stable_local_invokers = build_stable_local_invokers(vec![builtin_invoker], vec![agent_invoker]); - let kernel = test_kernel(&stable_local_invokers); + let capability_surface = Arc::new(TestCapabilitySurface::default()); let tool_search_index = Arc::new(ToolSearchIndex::new()); let sync = CapabilitySurfaceSync::new( - Arc::clone(&kernel), + capability_surface.clone(), stable_local_invokers, Arc::clone(&tool_search_index), ); @@ -457,7 +438,7 @@ mod tests { sync.apply_external_invokers(vec![invoker("mcp__demo__search", &["source:mcp"])]) .expect("replace should succeed"); - let names: Vec = kernel.gateway().capabilities().tool_names(); + let names = capability_surface.capability_tool_names(); assert!(names.iter().any(|name| name == "read_file")); assert!(names.iter().any(|name| name == "spawn")); assert!(names.iter().any(|name| name == "mcp__demo__search")); @@ -467,7 +448,8 @@ mod tests { fn build_core_tool_invokers_registers_task_write() { let temp = tempfile::tempdir().expect("tempdir should exist"); let tool_search_index = Arc::new(ToolSearchIndex::new()); - let skill_catalog = build_skill_catalog(temp.path(), Vec::new()); + let skill_catalog = + build_skill_catalog(temp.path(), Vec::new(), &ResourceCatalog::default()); let invokers = build_core_tool_invokers(tool_search_index, skill_catalog) .expect("core tool invokers should build"); diff --git a/crates/server/src/bootstrap/composer_skills.rs b/crates/server/src/bootstrap/composer_skills.rs deleted file mode 100644 index 0d142b03..00000000 --- a/crates/server/src/bootstrap/composer_skills.rs +++ /dev/null @@ -1,44 +0,0 @@ -use std::{path::Path, sync::Arc}; - -use astrcode_application::{ComposerResolvedSkill, ComposerSkillPort, ComposerSkillSummary}; -use astrcode_core::SkillCatalog; - -#[derive(Clone)] -pub(crate) struct RuntimeComposerSkillPort { - skill_catalog: Arc, -} - -impl RuntimeComposerSkillPort { - pub(crate) fn new(skill_catalog: Arc) -> Self { - Self { skill_catalog } - } -} - -impl std::fmt::Debug for RuntimeComposerSkillPort { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("RuntimeComposerSkillPort") - .finish_non_exhaustive() - } -} - -impl ComposerSkillPort for RuntimeComposerSkillPort { - fn list_skill_summaries(&self, working_dir: &Path) -> Vec { - self.skill_catalog - .resolve_for_working_dir(&working_dir.to_string_lossy()) - .into_iter() - .map(|skill| ComposerSkillSummary::new(skill.id, skill.description)) - .collect() - } - - fn resolve_skill(&self, working_dir: &Path, skill_id: &str) -> Option { - self.skill_catalog - .resolve_for_working_dir(&working_dir.to_string_lossy()) - .into_iter() - .find(|skill| skill.matches_requested_name(skill_id)) - .map(|skill| ComposerResolvedSkill { - id: skill.id, - description: skill.description, - guide: skill.guide, - }) - } -} diff --git a/crates/server/src/bootstrap/deps.rs b/crates/server/src/bootstrap/deps.rs index 631675c1..8d2a2635 100644 --- a/crates/server/src/bootstrap/deps.rs +++ b/crates/server/src/bootstrap/deps.rs @@ -1,9 +1,7 @@ //! bootstrap 内部底层依赖别名。 //! //! 为什么保留这一层： -//! 让 `core` / `kernel` / `session-runtime` 的直接依赖只集中在少数入口文件， +//! 让 `core` 的直接依赖只集中在少数入口文件， //! 其他装配模块统一通过本地 facade 引用，避免 import 散点继续扩散。 pub(crate) use astrcode_core as core; -pub(crate) use astrcode_kernel as kernel; -pub(crate) use astrcode_session_runtime as session_runtime; diff --git a/crates/server/src/bootstrap/governance.rs b/crates/server/src/bootstrap/governance.rs index 02660af8..5ae71492 100644 --- a/crates/server/src/bootstrap/governance.rs +++ b/crates/server/src/bootstrap/governance.rs @@ -3,87 +3,146 @@ //! 负责把底层 `RuntimeCoordinator` 适配成应用层治理端口， //! 并为治理入口接入真实 reload/observability 组合根。 -use std::{collections::HashSet, path::PathBuf, sync::Arc}; +use std::{ + collections::HashSet, + path::PathBuf, + sync::{Arc, RwLock}, +}; use astrcode_adapter_mcp::{ config::McpServerConfig, manager::{McpConnectionManager, McpReloadSnapshot}, }; use astrcode_adapter_skills::{LayeredSkillCatalog, load_builtin_skills}; -use astrcode_application::{ - AppGovernance, ApplicationError, ModeCatalog, RuntimeGovernancePort, RuntimeGovernanceSnapshot, - RuntimeObservabilityCollector, RuntimeReloader, SessionInfoProvider, config::ConfigService, - lifecycle::TaskRegistry, mode::ModeCatalogSnapshot, +use astrcode_core::{CapabilityInvoker, SkillSpec}; +use astrcode_plugin_host::{ + PluginEntry, ProviderContributionCatalog, ResourceCatalog, build_skill_catalog_base, + builtin_openai_provider_descriptor, }; -use astrcode_core::{CapabilityInvoker, SkillSpec, plugin::PluginEntry}; -use astrcode_plugin::Supervisor; use async_trait::async_trait; use super::{ capabilities::CapabilitySurfaceSync, - deps::{ - core::{AstrError, ManagedRuntimeComponent, RuntimeHandle}, - session_runtime::SessionRuntime, - }, + deps::core::{AstrError, ManagedRuntimeComponent, RuntimeHandle}, mcp::load_declared_configs, plugins::bootstrap_plugins_with_skill_root, runtime_coordinator::RuntimeCoordinator, }; +use crate::{ + AppGovernance, ApplicationError, GovernanceSnapshot, RuntimeGovernancePort, + RuntimeGovernanceSnapshot, RuntimeReloader, SessionInfoProvider, + application_error_bridge::ServerRouteError, + config_service_bridge::ServerConfigService, + governance_service::{ + ServerGovernancePort, ServerGovernanceReloadResult, ServerGovernanceService, + ServerGovernanceSnapshot, + }, + mode_catalog_service::{ServerModeCatalog, ServerModeCatalogSnapshot}, + runtime_owner_bridge::{ServerRuntimeObservability, ServerTaskRegistry}, +}; pub(crate) struct GovernanceBuildInput { - pub session_runtime: Arc, - pub config_service: Arc, + pub sessions: Arc, + pub config_service: Arc, pub coordinator: Arc, - pub task_registry: Arc, - pub observability: Arc, + pub task_registry: Arc, + pub observability: Arc, pub mcp_manager: Arc, pub capability_sync: CapabilitySurfaceSync, pub skill_catalog: Arc, + pub resource_catalog: Arc>, + pub provider_catalog: Arc>, pub plugin_search_paths: Vec, pub plugin_skill_root: PathBuf, - pub plugin_supervisors: Vec>, + pub managed_plugin_components: Vec>, pub working_dir: PathBuf, - pub mode_catalog: Option>, + pub mode_catalog: Option>, } -pub(crate) fn build_app_governance(input: GovernanceBuildInput) -> Arc { +pub(crate) fn build_server_governance_service( + input: GovernanceBuildInput, +) -> Arc { let runtime_port = Arc::new(CoordinatorGovernancePort { coordinator: Arc::clone(&input.coordinator), }); - let sessions = Arc::new(SessionRuntimeInfo { - session_runtime: Arc::clone(&input.session_runtime), - }); let reloader: Arc = Arc::new(ServerRuntimeReloader { config_service: Arc::clone(&input.config_service), coordinator: Arc::clone(&input.coordinator), mcp_manager: Arc::clone(&input.mcp_manager), capability_sync: input.capability_sync.clone(), skill_catalog: Arc::clone(&input.skill_catalog), + resource_catalog: Arc::clone(&input.resource_catalog), + provider_catalog: Arc::clone(&input.provider_catalog), plugin_search_paths: input.plugin_search_paths.clone(), plugin_skill_root: input.plugin_skill_root.clone(), working_dir: input.working_dir.clone(), mode_catalog: input.mode_catalog, }); - let managed_components: Vec> = input - .plugin_supervisors - .into_iter() - .map(|supervisor| supervisor as Arc) - .collect(); + let managed_components: Vec> = input.managed_plugin_components; input.coordinator.replace_runtime_surface( input.coordinator.plugin_registry().snapshot(), input.capability_sync.current_capabilities(), managed_components, ); - Arc::new( + let governance = Arc::new( AppGovernance::new( runtime_port, - input.task_registry, + input.task_registry.inner(), input.observability, - sessions, + input.sessions, ) .with_reloader(reloader), - ) + ); + Arc::new(ServerGovernanceService::new(Arc::new( + ApplicationGovernancePort { inner: governance }, + ))) +} + +struct ApplicationGovernancePort { + inner: Arc, +} + +const SERVER_RUNTIME_NAME: &str = "astrcode-server"; +const SERVER_RUNTIME_KIND: &str = "server"; + +#[async_trait] +impl ServerGovernancePort for ApplicationGovernancePort { + fn capabilities(&self) -> Vec { + self.inner.runtime().snapshot().capabilities + } + + async fn reload(&self) -> Result { + let reloaded = self + .inner + .reload() + .await + .map_err(application_error_to_server)?; + Ok(ServerGovernanceReloadResult { + snapshot: server_snapshot_from_application(reloaded.snapshot), + reloaded_at: reloaded.reloaded_at, + }) + } + + async fn shutdown(&self, timeout_secs: u64) -> Result<(), ServerRouteError> { + self.inner + .shutdown(timeout_secs) + .await + .map_err(application_error_to_server) + } +} + +fn server_snapshot_from_application(snapshot: GovernanceSnapshot) -> ServerGovernanceSnapshot { + ServerGovernanceSnapshot { + runtime_name: snapshot.runtime_name, + runtime_kind: snapshot.runtime_kind, + loaded_session_count: snapshot.loaded_session_count, + running_session_ids: snapshot.running_session_ids, + plugin_search_paths: snapshot.plugin_search_paths, + metrics: snapshot.metrics, + capabilities: snapshot.capabilities, + plugins: snapshot.plugins, + } } #[derive(Debug)] @@ -125,11 +184,11 @@ pub(crate) struct AppRuntimeHandle; #[async_trait] impl RuntimeHandle for AppRuntimeHandle { fn runtime_name(&self) -> &'static str { - "astrcode-application" + SERVER_RUNTIME_NAME } fn runtime_kind(&self) -> &'static str { - "application" + SERVER_RUNTIME_KIND } async fn shutdown(&self, _timeout_secs: u64) -> std::result::Result<(), AstrError> { @@ -137,41 +196,19 @@ impl RuntimeHandle for AppRuntimeHandle { } } -struct SessionRuntimeInfo { - session_runtime: Arc, -} - -impl SessionInfoProvider for SessionRuntimeInfo { - fn loaded_session_count(&self) -> usize { - self.session_runtime.list_sessions().len() - } - - fn running_session_ids(&self) -> Vec { - self.session_runtime - .list_running_sessions() - .into_iter() - .map(|id| id.to_string()) - .collect() - } -} - -impl std::fmt::Debug for SessionRuntimeInfo { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("SessionRuntimeInfo").finish_non_exhaustive() - } -} - #[derive(Clone)] struct ServerRuntimeReloader { - config_service: Arc, + config_service: Arc, coordinator: Arc, mcp_manager: Arc, capability_sync: CapabilitySurfaceSync, skill_catalog: Arc, + resource_catalog: Arc>, + provider_catalog: Arc>, plugin_search_paths: Vec, plugin_skill_root: PathBuf, working_dir: PathBuf, - mode_catalog: Option>, + mode_catalog: Option>, } impl std::fmt::Debug for ServerRuntimeReloader { @@ -186,8 +223,10 @@ impl std::fmt::Debug for ServerRuntimeReloader { struct PreparedGovernanceReload { search_paths: Vec, mcp_configs: Vec, - mode_snapshot: Option, + mode_snapshot: Option, base_skills: Vec, + resource_catalog: ResourceCatalog, + provider_catalog: ProviderContributionCatalog, plugin_invokers: Vec>, plugin_entries: Vec, managed_components: Vec>, @@ -241,8 +280,9 @@ impl GovernanceReloadRollback { impl ServerRuntimeReloader { async fn prepare_reload_candidate(&self) -> Result { - let mcp_configs = - load_declared_configs(&self.config_service, self.working_dir.as_path()).await?; + let mcp_configs = load_declared_configs(&self.config_service, self.working_dir.as_path()) + .await + .map_err(server_error_to_application)?; let plugin_bootstrap = bootstrap_plugins_with_skill_root( self.plugin_search_paths.clone(), self.plugin_skill_root.clone(), @@ -257,23 +297,26 @@ impl ServerRuntimeReloader { None => None, }; - let mut base_skills = load_builtin_skills(); - base_skills.extend(plugin_bootstrap.skills.clone()); - let managed_components: Vec> = plugin_bootstrap - .supervisors - .iter() - .cloned() - .map(|supervisor| supervisor as Arc) - .collect(); - + let base_skills = build_skill_catalog_base( + load_builtin_skills(), + plugin_bootstrap.skills.clone(), + &plugin_bootstrap.resource_catalog, + ) + .base_skills; + let mut provider_descriptors = vec![builtin_openai_provider_descriptor()]; + provider_descriptors.extend(plugin_bootstrap.descriptors.clone()); + let provider_catalog = ProviderContributionCatalog::from_descriptors(&provider_descriptors) + .map_err(ApplicationError::from)?; Ok(PreparedGovernanceReload { search_paths: plugin_bootstrap.search_paths, mcp_configs, mode_snapshot, base_skills, + resource_catalog: plugin_bootstrap.resource_catalog, + provider_catalog, plugin_invokers: plugin_bootstrap.invokers, plugin_entries: plugin_bootstrap.registry.snapshot(), - managed_components, + managed_components: plugin_bootstrap.managed_components, }) } @@ -300,7 +343,10 @@ impl RuntimeReloader for ServerRuntimeReloader { Box, ApplicationError>> + Send + '_>, > { Box::pin(async move { - self.config_service.reload_from_disk().await?; + self.config_service + .reload_from_disk() + .await + .map_err(server_error_to_application)?; let candidate = self.prepare_reload_candidate().await?; let rollback = GovernanceReloadRollback::capture(&self.mcp_manager, &self.capability_sync).await; @@ -338,6 +384,14 @@ impl RuntimeReloader for ServerRuntimeReloader { self.skill_catalog .replace_base_skills(candidate.base_skills); + *self + .resource_catalog + .write() + .expect("plugin resource catalog lock poisoned") = candidate.resource_catalog; + *self + .provider_catalog + .write() + .expect("provider catalog lock poisoned") = candidate.provider_catalog; if let (Some(mode_catalog), Some(mode_snapshot)) = (&self.mode_catalog, candidate.mode_snapshot) { @@ -362,23 +416,44 @@ impl RuntimeReloader for ServerRuntimeReloader { } } +fn server_error_to_application(error: ServerRouteError) -> ApplicationError { + match error { + ServerRouteError::NotFound(message) => ApplicationError::NotFound(message), + ServerRouteError::Conflict(message) => ApplicationError::Conflict(message), + ServerRouteError::InvalidArgument(message) => ApplicationError::InvalidArgument(message), + ServerRouteError::PermissionDenied(message) => ApplicationError::PermissionDenied(message), + ServerRouteError::Internal(message) => ApplicationError::Internal(message), + } +} + +fn application_error_to_server(error: ApplicationError) -> ServerRouteError { + match error { + ApplicationError::NotFound(message) => ServerRouteError::NotFound(message), + ApplicationError::Conflict(message) => ServerRouteError::Conflict(message), + ApplicationError::InvalidArgument(message) => ServerRouteError::InvalidArgument(message), + ApplicationError::PermissionDenied(message) => ServerRouteError::PermissionDenied(message), + ApplicationError::Internal(message) => ServerRouteError::Internal(message), + } +} + #[cfg(test)] mod tests { - use std::{collections::HashMap, sync::Arc}; + use std::{ + collections::{HashMap, HashSet}, + sync::{Arc, RwLock}, + }; + use astrcode_plugin_host::PluginRegistry; use async_trait::async_trait; use serde_json::{Value, json}; use super::*; - use crate::bootstrap::deps::{ - core::{ + use crate::{ + bootstrap::deps::core::{ AstrError, CapabilityInvoker, CapabilityKind, CapabilitySpec, CapabilitySpecBuildError, - LlmEventSink, LlmOutput, LlmProvider, LlmRequest, ModelLimits, PluginRegistry, - PromptBuildOutput, PromptBuildRequest, PromptProvider, ResourceProvider, - ResourceReadResult, ResourceRequestContext, Result, Tool, ToolContext, ToolDefinition, - ToolExecutionResult, + Result, Tool, ToolContext, ToolDefinition, ToolExecutionResult, }, - kernel::{CapabilityRouter, Kernel, ToolCapabilityInvoker}, + tool_capability_invoker::ToolCapabilityInvoker, }; #[derive(Debug)] @@ -425,63 +500,6 @@ mod tests { } } - #[derive(Debug)] - struct NoopLlmProvider; - - #[async_trait] - impl LlmProvider for NoopLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Err(AstrError::Validation( - "noop llm provider should not execute in this test".to_string(), - )) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 8192, - max_output_tokens: 4096, - } - } - } - - #[derive(Debug)] - struct NoopPromptProvider; - - #[async_trait] - impl PromptProvider for NoopPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: Value::Null, - }) - } - } - - #[derive(Debug)] - struct NoopResourceProvider; - - #[async_trait] - impl ResourceProvider for NoopResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: Value::Null, - metadata: Value::Null, - }) - } - } - fn invoker(name: &'static str, tags: &'static [&'static str]) -> Arc { Arc::new( ToolCapabilityInvoker::new(Arc::new(StaticTool { name, tags })) @@ -489,21 +507,32 @@ mod tests { ) as Arc } - fn test_kernel(builtin_invokers: &[Arc]) -> Arc { - let mut builder = CapabilityRouter::builder(); - for invoker in builtin_invokers { - builder = builder.register_invoker(Arc::clone(invoker)); + #[derive(Default)] + struct TestCapabilitySurface { + invokers: RwLock>>, + } + + impl crate::session_runtime_owner_bridge::ServerCapabilitySurfacePort for TestCapabilitySurface { + fn replace_capability_invokers( + &self, + invokers: Vec>, + ) -> Result<()> { + let mut seen = HashSet::new(); + for invoker in &invokers { + let name = invoker.capability_spec().name.to_string(); + if !seen.insert(name.clone()) { + return Err(AstrError::Validation(format!( + "duplicate capability '{}'", + name + ))); + } + } + *self + .invokers + .write() + .expect("test capability surface lock should not be poisoned") = invokers; + Ok(()) } - let router = builder.build().expect("router should build"); - Arc::new( - Kernel::builder() - .with_capabilities(router) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"), - ) } #[tokio::test] @@ -525,8 +554,8 @@ mod tests { let port = CoordinatorGovernancePort { coordinator }; let snapshot = port.snapshot(); - assert_eq!(snapshot.runtime_name, "astrcode-application"); - assert_eq!(snapshot.runtime_kind, "application"); + assert_eq!(snapshot.runtime_name, SERVER_RUNTIME_NAME); + assert_eq!(snapshot.runtime_kind, SERVER_RUNTIME_KIND); assert_eq!(snapshot.capabilities.len(), 1); assert!(snapshot.plugins.is_empty()); @@ -559,11 +588,11 @@ mod tests { .expect("alpha config should apply"); let stable_local_invokers = vec![invoker("read_file", &["source:builtin"])]; - let kernel = test_kernel(&stable_local_invokers); + let capability_surface = Arc::new(TestCapabilitySurface::default()); let tool_search_index = Arc::new(astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex::new()); let capability_sync = CapabilitySurfaceSync::new( - kernel, + capability_surface, stable_local_invokers, Arc::clone(&tool_search_index), ); diff --git a/crates/server/src/bootstrap/mcp.rs b/crates/server/src/bootstrap/mcp.rs index a659d973..0e5fe720 100644 --- a/crates/server/src/bootstrap/mcp.rs +++ b/crates/server/src/bootstrap/mcp.rs @@ -15,16 +15,21 @@ use astrcode_adapter_mcp::{ manager::McpConnectionManager, }; use astrcode_adapter_storage::mcp_settings_store::FileMcpSettingsStore; -use astrcode_application::{ - ApplicationError, McpPort, McpServerStatusView, RegisterMcpServerInput, - config::{ConfigService, McpConfigFileScope}, -}; +use astrcode_core::ports::McpConfigFileScope; use async_trait::async_trait; use super::{ capabilities::CapabilitySurfaceSync, deps::core::{AstrError, CapabilityInvoker, Result as CoreResult}, }; +use crate::{ + application_error_bridge::ServerRouteError, + config_service_bridge::ServerConfigService, + mcp_service::{ + ServerMcpConfigScope, ServerMcpPort, ServerMcpServerStatusSummary, ServerMcpService, + ServerRegisterMcpServerInput, + }, +}; /// 构建并初始化 MCP 连接管理器。 pub(crate) async fn bootstrap_mcp_manager( @@ -45,7 +50,7 @@ pub(crate) async fn bootstrap_mcp_manager( /// MCP 作为外部能力面可在后台预热，失败只影响对应能力，不应拖垮桌面端启动。 pub(crate) async fn warmup_mcp_manager( manager: Arc, - config_service: Arc, + config_service: Arc, working_dir: PathBuf, capability_sync: CapabilitySurfaceSync, plugin_invokers: Vec>, @@ -75,23 +80,21 @@ pub(crate) async fn warmup_mcp_manager( /// 构建 MCP 服务，使用 `McpConnectionManager` 作为实际端口实现。 pub(crate) fn build_mcp_service( - config_service: Arc, + config_service: Arc, working_dir: PathBuf, manager: Arc, capability_sync: CapabilitySurfaceSync, -) -> Arc { - Arc::new(astrcode_application::McpService::new(Arc::new( - ManagerMcpPort { - config_service, - working_dir, - manager, - capability_sync, - }, - ))) +) -> Arc { + Arc::new(ServerMcpService::new(Arc::new(ManagerMcpPort { + config_service, + working_dir, + manager, + capability_sync, + }))) } struct ManagerMcpPort { - config_service: Arc, + config_service: Arc, working_dir: PathBuf, manager: Arc, capability_sync: CapabilitySurfaceSync, @@ -104,66 +107,60 @@ impl std::fmt::Debug for ManagerMcpPort { } #[async_trait] -impl McpPort for ManagerMcpPort { - async fn list_server_status(&self) -> Vec { +impl ServerMcpPort for ManagerMcpPort { + async fn list_server_status_summary(&self) -> Vec { self.manager .list_status() .await .into_iter() - .map(snapshot_to_view) + .map(snapshot_to_summary) .collect() } - async fn approve_server( - &self, - server_signature: &str, - ) -> std::result::Result<(), ApplicationError> { + async fn approve_server(&self, server_signature: &str) -> Result<(), ServerRouteError> { self.manager .approve_server(server_signature) - .map_err(core_error_to_app)?; + .map_err(core_error_to_server)?; self.reload_from_source().await } - async fn reject_server( - &self, - server_signature: &str, - ) -> std::result::Result<(), ApplicationError> { + async fn reject_server(&self, server_signature: &str) -> Result<(), ServerRouteError> { self.manager .reject_server(server_signature) - .map_err(core_error_to_app)?; + .map_err(core_error_to_server)?; self.reload_from_source().await } - async fn reconnect_server(&self, name: &str) -> std::result::Result<(), ApplicationError> { + async fn reconnect_server(&self, name: &str) -> Result<(), ServerRouteError> { self.manager .reconnect_server(name) .await - .map_err(core_error_to_app)?; + .map_err(core_error_to_server)?; self.sync_capabilities().await } - async fn reset_project_choices(&self) -> std::result::Result<(), ApplicationError> { + async fn reset_project_choices(&self) -> Result<(), ServerRouteError> { self.manager .reset_project_choices() - .map_err(core_error_to_app)?; + .map_err(core_error_to_server)?; self.reload_from_source().await } async fn upsert_server( &self, - input: &RegisterMcpServerInput, - ) -> std::result::Result<(), ApplicationError> { + input: ServerRegisterMcpServerInput, + ) -> Result<(), ServerRouteError> { self.config_service - .upsert_mcp_server(self.working_dir.as_path(), input) + .upsert_mcp_server(self.working_dir.as_path(), &input) .await?; self.reload_from_source().await } async fn remove_server( &self, - scope: astrcode_application::McpConfigScope, + scope: ServerMcpConfigScope, name: &str, - ) -> std::result::Result<(), ApplicationError> { + ) -> Result<(), ServerRouteError> { self.config_service .remove_mcp_server(self.working_dir.as_path(), scope, name) .await?; @@ -172,10 +169,10 @@ impl McpPort for ManagerMcpPort { async fn set_server_enabled( &self, - scope: astrcode_application::McpConfigScope, + scope: ServerMcpConfigScope, name: &str, enabled: bool, - ) -> std::result::Result<(), ApplicationError> { + ) -> Result<(), ServerRouteError> { self.config_service .set_mcp_server_enabled(self.working_dir.as_path(), scope, name, enabled) .await?; @@ -184,32 +181,32 @@ impl McpPort for ManagerMcpPort { } impl ManagerMcpPort { - async fn reload_from_source(&self) -> std::result::Result<(), ApplicationError> { + async fn reload_from_source(&self) -> Result<(), ServerRouteError> { let configs = load_declared_configs(&self.config_service, self.working_dir.as_path()).await?; self.manager .reload_config(configs) .await - .map_err(core_error_to_app)?; + .map_err(core_error_to_server)?; self.sync_capabilities().await } - async fn sync_capabilities(&self) -> std::result::Result<(), ApplicationError> { + async fn sync_capabilities(&self) -> Result<(), ServerRouteError> { let surface = self.manager.current_surface().await; self.capability_sync .apply_external_invokers(surface.capability_invokers) - .map_err(core_error_to_app) + .map_err(core_error_to_server) } } -fn snapshot_to_view( +fn snapshot_to_summary( snapshot: astrcode_adapter_mcp::manager::surface::McpServerStatusSnapshot, -) -> McpServerStatusView { - McpServerStatusView { +) -> ServerMcpServerStatusSummary { + ServerMcpServerStatusSummary { name: snapshot.name, scope: snapshot.scope, enabled: snapshot.enabled, - state: snapshot.state, + status: snapshot.state, error: snapshot.error, tool_count: snapshot.tool_count, prompt_count: snapshot.prompt_count, @@ -219,14 +216,14 @@ fn snapshot_to_view( } } -fn core_error_to_app(error: AstrError) -> ApplicationError { - ApplicationError::Internal(error.to_string()) +fn core_error_to_server(error: AstrError) -> ServerRouteError { + ServerRouteError::internal(error.to_string()) } pub(crate) async fn load_declared_configs( - config_service: &Arc, + config_service: &Arc, working_dir: &Path, -) -> std::result::Result, ApplicationError> { +) -> Result, ServerRouteError> { let mut merged = HashMap::new(); let working_dir_display = working_dir.display().to_string(); @@ -235,7 +232,8 @@ pub(crate) async fn load_declared_configs( merge_configs_or_warn( &mut merged, "user config.json mcp", - McpConfigManager::load_from_value(mcp, McpConfigScope::User).map_err(core_error_to_app), + McpConfigManager::load_from_value(mcp, McpConfigScope::User) + .map_err(core_error_to_server), ); } @@ -244,7 +242,7 @@ pub(crate) async fn load_declared_configs( &mut merged, "user mcp.json", McpConfigManager::load_from_value(&mcp, McpConfigScope::User) - .map_err(core_error_to_app), + .map_err(core_error_to_server), ), Ok(None) => {}, Err(error) => log::warn!("failed to load user mcp.json, skipping source: {error}"), @@ -256,7 +254,7 @@ pub(crate) async fn load_declared_configs( &mut merged, &format!("project MCP file '{}'", project_file.display()), McpConfigManager::load_from_file(&project_file, McpConfigScope::Project) - .map_err(core_error_to_app), + .map_err(core_error_to_server), ); } @@ -267,7 +265,7 @@ pub(crate) async fn load_declared_configs( &mut merged, &format!("local overlay mcp for '{}'", working_dir_display), McpConfigManager::load_from_value(&mcp, McpConfigScope::Local) - .map_err(core_error_to_app), + .map_err(core_error_to_server), ); } }, @@ -283,7 +281,7 @@ pub(crate) async fn load_declared_configs( &mut merged, &format!("local sidecar mcp for '{}'", working_dir_display), McpConfigManager::load_from_value(&mcp, McpConfigScope::Local) - .map_err(core_error_to_app), + .map_err(core_error_to_server), ), Ok(None) => {}, Err(error) => log::warn!( @@ -298,7 +296,7 @@ pub(crate) async fn load_declared_configs( fn merge_configs_or_warn( merged: &mut HashMap, source_label: &str, - configs: std::result::Result, ApplicationError>, + configs: Result, ServerRouteError>, ) { match configs { Ok(configs) => { @@ -399,7 +397,9 @@ mod tests { ) .expect("local sidecar should save"); - let config_service = Arc::new(ConfigService::new(store)); + let config_service = Arc::new(ServerConfigService::new(Arc::new( + crate::ConfigService::new(store), + ))); let configs = load_declared_configs(&config_service, project.path()) .await .expect("configs should load"); @@ -442,7 +442,9 @@ mod tests { fs::write(project.path().join(".mcp.json"), "{ invalid json") .expect("broken project mcp should be written"); - let config_service = Arc::new(ConfigService::new(store)); + let config_service = Arc::new(ServerConfigService::new(Arc::new( + crate::ConfigService::new(store), + ))); let configs = load_declared_configs(&config_service, project.path()) .await .expect("invalid project source should be skipped"); diff --git a/crates/server/src/bootstrap/mod.rs b/crates/server/src/bootstrap/mod.rs index f5fd9098..84da35db 100644 --- a/crates/server/src/bootstrap/mod.rs +++ b/crates/server/src/bootstrap/mod.rs @@ -4,7 +4,7 @@ //! //! ## 职责范围 //! -//! - **运行时组合根**（`runtime`）：组装 `App`、`AppGovernance` 等 +//! - **运行时组合根**（`runtime`）：组装 server owner bridge、治理层与运行时依赖 //! - **前端静态文件服务**：加载 `frontend/dist/` 构建产物并注入 bootstrap token //! - **运行信息管理**：写入/清理 `~/.astrcode/run.json`，供浏览器桥接和诊断读取 //! - **浏览器引导 token 注入**：将 `window.__ASTRCODE_BOOTSTRAP__` 嵌入 HTML @@ -21,12 +21,10 @@ //! 它保留的原因是浏览器开发模式仍需要一个稳定的本地文件来读取 bootstrap token。 mod capabilities; -mod composer_skills; mod deps; mod governance; mod mcp; mod plugins; -mod prompt_facts; mod providers; pub(crate) mod runtime; mod runtime_coordinator; diff --git a/crates/server/src/bootstrap/plugins.rs b/crates/server/src/bootstrap/plugins.rs index 78fc98f9..c60ea2a9 100644 --- a/crates/server/src/bootstrap/plugins.rs +++ b/crates/server/src/bootstrap/plugins.rs @@ -13,17 +13,29 @@ use std::{ fs, path::{Component, Path, PathBuf}, sync::Arc, + time::{Instant, SystemTime, UNIX_EPOCH}, }; use astrcode_adapter_skills::collect_asset_files; -use astrcode_core::{GovernanceModeSpec, SkillSource, SkillSpec, is_valid_skill_name}; -use astrcode_plugin::{PluginLoader, Supervisor, default_initialize_message, default_profiles}; -use astrcode_protocol::plugin::{PeerDescriptor, SkillDescriptor}; +use astrcode_core::{ + AstrError, CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, + GovernanceModeSpec, InvocationMode, ManagedRuntimeComponent, Result, SkillSource, SkillSpec, + is_valid_skill_name, +}; +use astrcode_plugin_host::{ + PluginDescriptor, PluginLoader, PluginManifest, PluginRegistry, PluginSourceKind, PluginType, + ResourceCatalog, + backend::{ExternalPluginRuntimeHandle, PluginBackendPlan}, + default_initialize_message, default_local_peer_descriptor, default_profiles, + resources_discover, +}; +use astrcode_protocol::plugin::{EventPhase, InvocationContext, SkillDescriptor, WorkspaceRef}; #[cfg(test)] use astrcode_support::hostpaths::resolve_home_dir; +use async_trait::async_trait; use log::warn; - -use super::deps::core::{CapabilityInvoker, PluginRegistry}; +use serde_json::{Value, json}; +use tokio::sync::Mutex; /// 插件装配结果。 pub(crate) struct PluginBootstrapResult { @@ -35,10 +47,14 @@ pub(crate) struct PluginBootstrapResult { pub modes: Vec, /// 插件注册表引用（治理视图使用）。 pub registry: Arc, - /// 活跃的插件 supervisor 列表（shutdown 时需要关闭）。 - pub supervisors: Vec>, + /// 活跃的插件宿主组件列表（shutdown/reload 时需要关闭）。 + pub managed_components: Vec>, /// 插件搜索路径。 pub search_paths: Vec, + /// plugin-host 聚合出的统一资源目录。 + pub resource_catalog: ResourceCatalog, + /// plugin-host 发现出的完整 descriptor 贡献面。 + pub descriptors: Vec, } /// 发现、装载并物化所有插件。 @@ -65,8 +81,8 @@ pub(crate) async fn bootstrap_plugins_with_skill_root( search_paths: search_paths.clone(), }; - let manifests = match loader.discover() { - Ok(manifests) => manifests, + let mut descriptors = match loader.discover_descriptors() { + Ok(descriptors) => descriptors, Err(error) => { log::warn!("plugin discovery failed: {error}"); return PluginBootstrapResult { @@ -74,87 +90,470 @@ pub(crate) async fn bootstrap_plugins_with_skill_root( skills: Vec::new(), modes: Vec::new(), registry, - supervisors: Vec::new(), + managed_components: Vec::new(), search_paths, + resource_catalog: ResourceCatalog::default(), + descriptors: Vec::new(), }; }, }; + descriptors.sort_by(|left, right| left.plugin_id.cmp(&right.plugin_id)); + log::info!("discovered {} plugin(s)", descriptors.len()); - log::info!("discovered {} plugin(s)", manifests.len()); - - let local_peer = PeerDescriptor { - id: "astrcode-host".to_string(), - name: "Astrcode Host".to_string(), - role: astrcode_protocol::plugin::PeerRole::Core, - version: env!("CARGO_PKG_VERSION").to_string(), - supported_profiles: vec!["coding".to_string()], - metadata: serde_json::json!({}), - }; + let local_peer = default_local_peer_descriptor(); let init_message = default_initialize_message(local_peer.clone(), Vec::new(), default_profiles()); let mut all_invokers: Vec> = Vec::new(); let mut all_skills = Vec::new(); let mut all_modes = Vec::new(); - let mut supervisors = Vec::new(); + let mut managed_components: Vec> = Vec::new(); - for manifest in manifests { - let name = manifest.name.clone(); + for descriptor in &mut descriptors { + let manifest = plugin_manifest_from_descriptor(descriptor); + let name = descriptor.plugin_id.clone(); log::info!("loading plugin '{name}'..."); - registry.record_discovered(manifest.clone()); - match loader - .start(&manifest, local_peer.clone(), Some(init_message.clone())) - .await - { - Ok(supervisor) => { - let supervisor = Arc::new(supervisor); - // 物化能力 - let invokers = supervisor.capability_invokers(); - let capabilities: Vec<_> = invokers - .iter() - .map(|invoker| invoker.capability_spec()) - .collect(); - let (skills, warnings) = materialize_plugin_skills( + match bootstrap_external_plugin_runtime(descriptor, init_message.clone()).await { + Ok(initialized) => { + let (skills, mut warnings) = materialize_plugin_skills( plugin_skill_root.as_path(), &name, - supervisor.declared_skills(), + initialized.declared_skills.clone(), ); - let modes = supervisor.declared_modes(); - + warnings.extend(initialized.warnings.clone()); log::info!( "plugin '{name}' initialized with {} capabilities, {} skills and {} modes", - capabilities.len(), + initialized.capabilities.len(), skills.len(), - modes.len() + initialized.modes.len() ); - registry.record_initialized(manifest, capabilities, warnings); - all_invokers.extend(invokers); + registry.record_initialized(manifest, initialized.capabilities.clone(), warnings); + apply_remote_descriptor_enrichment(descriptor, &initialized); + all_invokers.extend(initialized.invokers); all_skills.extend(skills); - all_modes.extend(modes); - supervisors.push(supervisor); + all_modes.extend(initialized.modes); + managed_components.push(initialized.runtime); }, Err(error) => { log::error!("plugin '{name}' failed to initialize: {error}"); registry.record_failed( manifest, error.to_string(), - Vec::new(), + descriptor.tools.clone(), vec![format!("initialization failed: {error}")], ); }, } } + let resource_catalog = resource_catalog_from_descriptors(&descriptors); + PluginBootstrapResult { invokers: all_invokers, skills: all_skills, modes: all_modes, registry, - supervisors, + managed_components, search_paths, + resource_catalog, + descriptors, + } +} + +fn resource_catalog_from_descriptors(descriptors: &[PluginDescriptor]) -> ResourceCatalog { + match resources_discover(descriptors).map(|report| report.catalog) { + Ok(catalog) => catalog, + Err(error) => { + warn!("plugin resource discovery failed: {error}"); + ResourceCatalog::default() + }, + } +} + +struct BootstrappedPluginRuntime { + runtime: Arc, + invokers: Vec>, + capabilities: Vec, + declared_skills: Vec, + modes: Vec, + warnings: Vec, +} + +struct HostedExternalPluginRuntime { + plugin_id: String, + display_name: String, + handle: Mutex, +} + +impl HostedExternalPluginRuntime { + fn new(plugin_id: String, display_name: String, handle: ExternalPluginRuntimeHandle) -> Self { + Self { + plugin_id, + display_name, + handle: Mutex::new(handle), + } + } + + async fn invoke( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + invocation_mode: InvocationMode, + ) -> Result { + let started_at = Instant::now(); + let invocation = to_invocation_context(ctx, capability_name); + let mut handle = self.handle.lock().await; + + if matches!(invocation_mode, InvocationMode::Streaming) { + let events = handle + .invoke_stream(&astrcode_protocol::plugin::InvokeMessage { + id: invocation.request_id.clone(), + capability: capability_name.to_string(), + input: payload, + context: invocation, + stream: true, + }) + .await?; + finish_stream_invocation(capability_name.to_string(), events, started_at) + } else { + let result = handle + .invoke_unary(&astrcode_protocol::plugin::InvokeMessage { + id: invocation.request_id.clone(), + capability: capability_name.to_string(), + input: payload, + context: invocation, + stream: false, + }) + .await?; + let (success, error) = if result.success { + (true, None) + } else { + let message = result + .error + .map(|value| value.message) + .unwrap_or_else(|| "plugin invocation failed".to_string()); + (false, Some(message)) + }; + Ok(CapabilityExecutionResult::from_common( + capability_name.to_string(), + success, + result.output, + None, + astrcode_core::ExecutionResultCommon { + error, + metadata: Some(result.metadata), + duration_ms: started_at.elapsed().as_millis() as u64, + truncated: false, + }, + )) + } + } +} + +#[async_trait] +impl ManagedRuntimeComponent for HostedExternalPluginRuntime { + fn component_name(&self) -> String { + format!("plugin-host '{}' ({})", self.plugin_id, self.display_name) + } + + async fn shutdown_component(&self) -> Result<()> { + let mut handle = self.handle.lock().await; + handle.shutdown().await + } +} + +#[derive(Clone)] +struct HostedPluginCapabilityInvoker { + runtime: Arc, + capability_spec: CapabilitySpec, + remote_name: String, +} + +#[async_trait] +impl CapabilityInvoker for HostedPluginCapabilityInvoker { + fn capability_spec(&self) -> CapabilitySpec { + self.capability_spec.clone() + } + + async fn invoke( + &self, + payload: Value, + ctx: &CapabilityContext, + ) -> Result { + self.runtime + .invoke( + self.remote_name.as_str(), + payload, + ctx, + self.capability_spec.invocation_mode, + ) + .await + } +} + +async fn bootstrap_external_plugin_runtime( + descriptor: &PluginDescriptor, + init_message: astrcode_protocol::plugin::InitializeMessage, +) -> Result { + if !matches!( + descriptor.source_kind, + PluginSourceKind::Process | PluginSourceKind::Command + ) { + return Err(AstrError::Validation(format!( + "plugin '{}' 不是 external process backend，无法走 plugin-host 宿主路径", + descriptor.plugin_id + ))); + } + + let plan = PluginBackendPlan::from_descriptor(descriptor)?; + let backend = plan.start_process().await?; + let mut handle = ExternalPluginRuntimeHandle::from_backend(backend).with_initialize_state( + astrcode_plugin_host::PluginInitializeState::new(init_message), + ); + let remote_initialize = handle.initialize_remote().await?.clone(); + let runtime = Arc::new(HostedExternalPluginRuntime::new( + descriptor.plugin_id.clone(), + descriptor.display_name.clone(), + handle, + )); + let capabilities = remote_initialize.capabilities.clone(); + let invokers = capabilities + .iter() + .cloned() + .filter_map(|capability| { + create_plugin_capability_invoker(Arc::clone(&runtime), capability.clone()).map_or_else( + |error| { + log::error!( + "failed to adapt plugin capability '{}' for '{}': {}", + capability.name, + descriptor.plugin_id, + error + ); + None + }, + Some, + ) + }) + .collect(); + + Ok(BootstrappedPluginRuntime { + runtime: runtime as Arc, + invokers, + capabilities, + declared_skills: remote_initialize.skills, + modes: remote_initialize.modes, + warnings: Vec::new(), + }) +} + +fn create_plugin_capability_invoker( + runtime: Arc, + capability: CapabilitySpec, +) -> Result> { + capability.validate().map_err(|error| { + AstrError::Validation(format!( + "invalid protocol capability wire descriptor '{}': {}", + capability.name, error + )) + })?; + Ok(Arc::new(HostedPluginCapabilityInvoker { + runtime, + remote_name: capability.name.to_string(), + capability_spec: capability, + }) as Arc) +} + +fn apply_remote_descriptor_enrichment( + descriptor: &mut PluginDescriptor, + initialized: &BootstrappedPluginRuntime, +) { + descriptor.tools = initialized.capabilities.clone(); + descriptor.modes = initialized.modes.clone(); + + let mut known_skill_ids = descriptor + .skills + .iter() + .map(|skill| skill.skill_id.clone()) + .collect::>(); + for skill in &initialized.declared_skills { + if known_skill_ids.insert(skill.name.clone()) { + descriptor + .skills + .push(astrcode_plugin_host::SkillDescriptor { + skill_id: skill.name.clone(), + entry_ref: format!("plugin://{}/skills/{}", descriptor.plugin_id, skill.name), + }); + } + } +} + +fn plugin_manifest_from_descriptor(descriptor: &PluginDescriptor) -> PluginManifest { + let mut plugin_type = Vec::new(); + if !descriptor.tools.is_empty() { + plugin_type.push(PluginType::Tool); + } + if !descriptor.providers.is_empty() { + plugin_type.push(PluginType::Provider); + } + if !descriptor.hooks.is_empty() { + plugin_type.push(PluginType::Hook); + } + if plugin_type.is_empty() { + plugin_type.push(PluginType::Tool); + } + + PluginManifest { + name: descriptor.plugin_id.clone(), + version: descriptor.version.clone(), + description: descriptor.display_name.clone(), + plugin_type, + capabilities: descriptor.tools.clone(), + executable: descriptor.launch_command.clone(), + args: descriptor.launch_args.clone(), + working_dir: descriptor.working_dir.clone(), + repository: descriptor.repository.clone(), + resources: descriptor + .resources + .iter() + .cloned() + .map(|resource| astrcode_plugin_host::ResourceManifestEntry { + id: resource.resource_id, + kind: resource.kind, + locator: resource.locator, + }) + .collect(), + commands: descriptor + .commands + .iter() + .cloned() + .map(|command| astrcode_plugin_host::CommandManifestEntry { + id: command.command_id, + entry_ref: command.entry_ref, + }) + .collect(), + themes: descriptor + .themes + .iter() + .cloned() + .map(|theme| astrcode_plugin_host::ThemeManifestEntry { id: theme.theme_id }) + .collect(), + providers: descriptor + .providers + .iter() + .cloned() + .map(|provider| astrcode_plugin_host::ProviderManifestEntry { + id: provider.provider_id, + api_kind: provider.api_kind, + }) + .collect(), + prompts: descriptor + .prompts + .iter() + .cloned() + .map(|prompt| astrcode_plugin_host::PromptManifestEntry { + id: prompt.prompt_id, + body: prompt.body, + }) + .collect(), + skills: descriptor + .skills + .iter() + .cloned() + .map(|skill| astrcode_plugin_host::SkillManifestEntry { + id: skill.skill_id, + entry_ref: skill.entry_ref, + }) + .collect(), + } +} + +fn finish_stream_invocation( + capability_name: String, + events: Vec, + started_at: Instant, +) -> Result { + let mut deltas = Vec::new(); + for event in events { + match event.phase { + EventPhase::Started => {}, + EventPhase::Delta => deltas.push(json!({ + "event": event.event, + "payload": event.payload, + "seq": event.seq, + })), + EventPhase::Completed => { + return Ok(CapabilityExecutionResult::from_common( + capability_name, + true, + event.payload, + None, + astrcode_core::ExecutionResultCommon::success( + Some(json!({ "streamEvents": deltas })), + started_at.elapsed().as_millis() as u64, + false, + ), + )); + }, + EventPhase::Failed => { + let error = event + .error + .map(|value| value.message) + .unwrap_or_else(|| "stream invocation failed".to_string()); + return Ok(CapabilityExecutionResult::from_common( + capability_name, + false, + Value::Null, + None, + astrcode_core::ExecutionResultCommon::failure( + error, + Some(json!({ "streamEvents": deltas })), + started_at.elapsed().as_millis() as u64, + false, + ), + )); + }, + } + } + + Err(AstrError::Internal( + "plugin stream ended without terminal event".to_string(), + )) +} + +fn to_invocation_context(ctx: &CapabilityContext, capability_name: &str) -> InvocationContext { + let working_dir = ctx.working_dir.to_string_lossy().into_owned(); + let request_id = ctx.request_id.clone().unwrap_or_else(|| { + format!( + "{}:{}:{}", + ctx.session_id, + capability_name, + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() + ) + }); + + InvocationContext { + request_id, + trace_id: ctx.trace_id.clone(), + session_id: Some(ctx.session_id.to_string()), + caller: None, + workspace: Some(WorkspaceRef { + working_dir: Some(working_dir.clone()), + repo_root: Some(working_dir), + branch: None, + metadata: Value::Null, + }), + deadline_ms: None, + budget: None, + profile: ctx.profile.clone(), + profile_context: ctx.profile_context.clone(), + metadata: ctx.metadata.clone(), } } @@ -355,10 +754,97 @@ fn write_asset_if_changed(path: &Path, content: &str) -> std::io::Result<()> { #[cfg(test)] mod tests { + use astrcode_core::{CapabilitySelector, ModeId, SkillSource}; + use astrcode_plugin_host::{PluginHealth, PluginState}; use astrcode_protocol::plugin::{SkillAssetDescriptor, SkillDescriptor}; use super::*; - use crate::bootstrap::deps::core::plugin::{PluginHealth, PluginState}; + + fn node_protocol_script() -> &'static str { + r#" +const readline = require('node:readline'); +const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity }); +rl.on('line', (line) => { + const msg = JSON.parse(line); + if (msg.type === 'initialize') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'initialize', + success: true, + output: { + protocolVersion: '5', + peer: { + id: 'fixture-worker', + name: 'fixture-worker', + role: 'worker', + version: '0.1.0', + supportedProfiles: ['coding'], + metadata: { fixture: true } + }, + capabilities: [{ + name: 'tool.echo', + kind: 'tool', + description: 'Echo input', + inputSchema: { type: 'object' }, + outputSchema: { type: 'object' }, + invocationMode: 'unary', + concurrencySafe: false, + compactClearable: false, + profiles: ['coding'], + tags: ['source:plugin'], + permissions: [], + sideEffect: 'none', + stability: 'stable', + metadata: null, + maxResultInlineSize: null + }], + handlers: [], + profiles: [{ + name: 'coding', + version: '1', + description: 'coding', + contextSchema: null, + metadata: null + }], + skills: [{ + name: 'repo-search', + description: 'Search repo', + guide: 'Use repo-search skill.', + allowedTools: ['grep'], + assets: [], + metadata: null + }], + modes: [{ + id: 'plugin-review', + name: 'Plugin Review', + description: 'review via plugin', + capabilitySelector: 'allTools', + actionPolicies: {}, + childPolicy: {}, + executionPolicy: {}, + promptProgram: [], + transitionPolicy: { allowedTargets: ['code'] } + }], + metadata: null + }, + metadata: null + })); + return; + } + if (msg.type === 'invoke') { + console.log(JSON.stringify({ + type: 'result', + id: msg.id, + kind: 'tool_result', + success: true, + output: { echoed: msg.input }, + metadata: null + })); + } +}); +"# + } #[tokio::test] async fn bootstrap_with_empty_paths_returns_empty() { @@ -366,7 +852,7 @@ mod tests { assert!(result.invokers.is_empty()); assert!(result.skills.is_empty()); assert!(result.modes.is_empty()); - assert!(result.supervisors.is_empty()); + assert!(result.managed_components.is_empty()); assert!(result.registry.snapshot().is_empty()); } @@ -376,7 +862,7 @@ mod tests { assert!(result.invokers.is_empty()); assert!(result.skills.is_empty()); assert!(result.modes.is_empty()); - assert!(result.supervisors.is_empty()); + assert!(result.managed_components.is_empty()); } #[tokio::test] @@ -400,7 +886,10 @@ executable = "nonexistent-binary" let result = bootstrap_plugins(vec![temp_dir.path().to_path_buf()]).await; // 插件被发现了，但启动失败（进程不存在） - assert!(result.supervisors.is_empty(), "不应有成功的 supervisor"); + assert!( + result.managed_components.is_empty(), + "不应有成功的托管插件组件" + ); let entries = result.registry.snapshot(); assert_eq!(entries.len(), 1, "应有一个 registry 条目"); @@ -469,6 +958,61 @@ executable = "also-missing" } } + #[tokio::test] + async fn external_plugin_bootstrap_materializes_invokers_skills_and_modes() { + let temp_dir = tempfile::tempdir().expect("tempdir should be created"); + let script_path = temp_dir.path().join("protocol-plugin.js"); + std::fs::write(&script_path, node_protocol_script()).expect("script should be written"); + std::fs::write( + temp_dir.path().join("protocol-plugin.toml"), + format!( + r#" +name = "protocol-plugin" +version = "0.1.0" +description = "Protocol plugin" +plugin_type = ["Tool"] +capabilities = [] +executable = "node" +args = ["{script_path}"] +"#, + script_path = script_path.display().to_string().replace('\\', "\\\\") + ), + ) + .expect("toml should be written"); + + let result = bootstrap_plugins(vec![temp_dir.path().to_path_buf()]).await; + + assert_eq!(result.managed_components.len(), 1); + assert_eq!(result.invokers.len(), 1); + assert_eq!( + result.invokers[0].capability_spec().name.as_str(), + "tool.echo" + ); + assert_eq!(result.skills.len(), 1); + assert_eq!(result.skills[0].id, "repo-search"); + assert_eq!(result.skills[0].source, SkillSource::Plugin); + assert_eq!(result.modes.len(), 1); + assert_eq!(result.modes[0].id, ModeId::from("plugin-review")); + assert_eq!( + result.modes[0].capability_selector, + CapabilitySelector::AllTools + ); + assert!(result.descriptors.iter().any(|descriptor| { + descriptor.plugin_id == "protocol-plugin" + && descriptor + .tools + .iter() + .any(|tool| tool.name.as_str() == "tool.echo") + })); + + let entry = result + .registry + .get("protocol-plugin") + .expect("plugin registry entry should exist"); + assert!(matches!(entry.state, PluginState::Initialized)); + assert_eq!(entry.health, PluginHealth::Healthy); + } + #[test] fn plugin_declared_skills_materialize_into_skill_specs() { let temp_home = tempfile::tempdir().expect("temp home should be created"); diff --git a/crates/server/src/bootstrap/prompt_facts.rs b/crates/server/src/bootstrap/prompt_facts.rs deleted file mode 100644 index 1863b748..00000000 --- a/crates/server/src/bootstrap/prompt_facts.rs +++ /dev/null @@ -1,308 +0,0 @@ -//! # Prompt 事实装配 -//! -//! 将 prompt 组装依赖的 profile / skill / agent profile / prompt declaration -//! 收敛为稳定端口，避免 session-runtime 直接触碰 adapter 实现。 - -use std::{ - path::{Path, PathBuf}, - sync::Arc, -}; - -use astrcode_adapter_agents::AgentProfileLoader; -use astrcode_adapter_mcp::manager::McpConnectionManager; -use astrcode_application::config::{ConfigService, resolve_current_model}; -use astrcode_core::SkillCatalog; -use async_trait::async_trait; - -use super::deps::core::{ - AstrError, PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, - PromptDeclarationSource, PromptEntrySummary, PromptFacts, PromptFactsProvider, - PromptFactsRequest, Result, SystemPromptLayer, resolve_runtime_config, -}; - -pub(crate) fn build_prompt_facts_provider( - config_service: Arc, - skill_catalog: Arc, - mcp_manager: Arc, - agent_loader: AgentProfileLoader, -) -> Result> { - Ok(Arc::new(RuntimePromptFactsProvider { - config_service, - skill_catalog, - agent_loader, - mcp_manager, - })) -} - -struct RuntimePromptFactsProvider { - config_service: Arc, - skill_catalog: Arc, - agent_loader: AgentProfileLoader, - mcp_manager: Arc, -} - -impl std::fmt::Debug for RuntimePromptFactsProvider { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("RuntimePromptFactsProvider") - .finish_non_exhaustive() - } -} - -#[async_trait] -impl PromptFactsProvider for RuntimePromptFactsProvider { - async fn resolve_prompt_facts(&self, request: &PromptFactsRequest) -> Result { - let working_dir = request.working_dir.clone(); - let config = self - .config_service - .load_overlayed_config(Some(working_dir.as_path())) - .map_err(|error| AstrError::Internal(error.to_string()))?; - let runtime = resolve_runtime_config(&config.runtime); - let governance = request.governance.clone().unwrap_or_default(); - let selection = resolve_current_model(&config) - .map_err(|error| AstrError::Internal(error.to_string()))?; - let skill_summaries = self - .skill_catalog - .resolve_for_working_dir(&working_dir.to_string_lossy()) - .into_iter() - .map(|skill| PromptEntrySummary::new(skill.id, skill.description)) - .collect(); - let agent_profiles = self - .agent_loader - .load_for_working_dir(Some(working_dir.as_path())) - .map_err(|error| AstrError::Internal(error.to_string()))? - .list_subagent_profiles() - .into_iter() - .map(|profile| PromptEntrySummary::new(profile.id.clone(), profile.description.clone())) - .collect(); - let prompt_declarations = self - .mcp_manager - .current_surface() - .await - .prompt_declarations - .into_iter() - .filter(|declaration| { - prompt_declaration_is_visible( - governance.allowed_capability_names.as_slice(), - declaration, - ) - }) - .map(convert_prompt_declaration) - .collect(); - - Ok(PromptFacts { - profile: selection.profile_name, - profile_context: build_profile_context( - working_dir.as_path(), - request.session_id.as_ref().map(ToString::to_string), - request.turn_id.as_ref().map(ToString::to_string), - governance.approval_mode.as_str(), - ), - metadata: serde_json::json!({ - "configVersion": config.version, - "activeProfile": config.active_profile, - "activeModel": config.active_model, - "modeId": governance.mode_id, - "agentMaxSubrunDepth": governance.max_subrun_depth.unwrap_or(runtime.agent.max_subrun_depth), - "agentMaxSpawnPerTurn": governance.max_spawn_per_turn.unwrap_or(runtime.agent.max_spawn_per_turn), - "governancePolicyRevision": governance.policy_revision, - }), - skills: skill_summaries, - agent_profiles, - prompt_declarations, - }) - } -} - -fn build_profile_context( - working_dir: &Path, - session_id: Option, - turn_id: Option, - approval_mode: &str, -) -> serde_json::Value { - let working_dir = normalize_context_path(working_dir); - let mut context = serde_json::Map::new(); - context.insert( - "workingDir".to_string(), - serde_json::Value::String(working_dir.clone()), - ); - context.insert( - "repoRoot".to_string(), - serde_json::Value::String(working_dir), - ); - context.insert( - "approvalMode".to_string(), - serde_json::Value::String(if approval_mode.trim().is_empty() { - "inherit".to_string() - } else { - approval_mode.to_string() - }), - ); - if let Some(session_id) = session_id { - context.insert( - "sessionId".to_string(), - serde_json::Value::String(session_id), - ); - } - if let Some(turn_id) = turn_id { - context.insert("turnId".to_string(), serde_json::Value::String(turn_id)); - } - serde_json::Value::Object(context) -} - -fn normalize_context_path(path: &Path) -> String { - path.canonicalize() - .unwrap_or_else(|_| PathBuf::from(path)) - .to_string_lossy() - .into_owned() -} - -fn convert_prompt_declaration( - declaration: astrcode_adapter_prompt::PromptDeclaration, -) -> PromptDeclaration { - PromptDeclaration { - block_id: declaration.block_id, - title: declaration.title, - content: declaration.content, - render_target: match declaration.render_target { - astrcode_adapter_prompt::PromptDeclarationRenderTarget::System => { - PromptDeclarationRenderTarget::System - }, - astrcode_adapter_prompt::PromptDeclarationRenderTarget::PrependUser => { - PromptDeclarationRenderTarget::PrependUser - }, - astrcode_adapter_prompt::PromptDeclarationRenderTarget::PrependAssistant => { - PromptDeclarationRenderTarget::PrependAssistant - }, - astrcode_adapter_prompt::PromptDeclarationRenderTarget::AppendUser => { - PromptDeclarationRenderTarget::AppendUser - }, - astrcode_adapter_prompt::PromptDeclarationRenderTarget::AppendAssistant => { - PromptDeclarationRenderTarget::AppendAssistant - }, - }, - layer: match declaration.layer { - astrcode_adapter_prompt::PromptLayer::Stable => SystemPromptLayer::Stable, - astrcode_adapter_prompt::PromptLayer::SemiStable => SystemPromptLayer::SemiStable, - astrcode_adapter_prompt::PromptLayer::Inherited => SystemPromptLayer::Inherited, - astrcode_adapter_prompt::PromptLayer::Dynamic => SystemPromptLayer::Dynamic, - astrcode_adapter_prompt::PromptLayer::Unspecified => SystemPromptLayer::Unspecified, - }, - kind: match declaration.kind { - astrcode_adapter_prompt::PromptDeclarationKind::ToolGuide => { - PromptDeclarationKind::ToolGuide - }, - astrcode_adapter_prompt::PromptDeclarationKind::ExtensionInstruction => { - PromptDeclarationKind::ExtensionInstruction - }, - }, - priority_hint: declaration.priority_hint, - always_include: declaration.always_include, - source: match declaration.source { - astrcode_adapter_prompt::PromptDeclarationSource::Builtin => { - PromptDeclarationSource::Builtin - }, - astrcode_adapter_prompt::PromptDeclarationSource::Plugin => { - PromptDeclarationSource::Plugin - }, - astrcode_adapter_prompt::PromptDeclarationSource::Mcp => PromptDeclarationSource::Mcp, - }, - capability_name: declaration.capability_name, - origin: declaration.origin, - } -} - -fn prompt_declaration_is_visible( - allowed_capability_names: &[String], - declaration: &astrcode_adapter_prompt::PromptDeclaration, -) -> bool { - declaration - .capability_name - .as_ref() - .is_none_or(|capability_name| { - allowed_capability_names - .iter() - .any(|allowed| allowed == capability_name) - }) -} - -#[cfg(test)] -mod tests { - use std::path::PathBuf; - - use astrcode_adapter_prompt::{ - PromptDeclaration as AdapterPromptDeclaration, PromptDeclarationKind, - PromptDeclarationRenderTarget, PromptDeclarationSource, PromptLayer, - }; - - use super::prompt_declaration_is_visible; - use crate::bootstrap::deps::core::PromptFactsRequest; - - fn declaration(capability_name: Option<&str>) -> AdapterPromptDeclaration { - AdapterPromptDeclaration { - block_id: "tool-guide".to_string(), - title: "Tool Guide".to_string(), - content: "only visible for allowed capabilities".to_string(), - render_target: PromptDeclarationRenderTarget::System, - layer: PromptLayer::Dynamic, - kind: PromptDeclarationKind::ToolGuide, - priority_hint: None, - always_include: false, - source: PromptDeclarationSource::Mcp, - capability_name: capability_name.map(ToString::to_string), - origin: Some("test".to_string()), - } - } - - fn request(allowed_capability_names: &[&str]) -> PromptFactsRequest { - PromptFactsRequest { - session_id: None, - turn_id: None, - working_dir: PathBuf::from("."), - allowed_capability_names: allowed_capability_names - .iter() - .map(|name| (*name).to_string()) - .collect(), - governance: Some(astrcode_core::PromptGovernanceContext { - allowed_capability_names: allowed_capability_names - .iter() - .map(|name| (*name).to_string()) - .collect(), - mode_id: Some(astrcode_core::ModeId::code()), - approval_mode: "inherit".to_string(), - policy_revision: "governance-surface-v1".to_string(), - max_subrun_depth: Some(3), - max_spawn_per_turn: Some(2), - }), - } - } - - #[test] - fn prompt_declaration_visibility_keeps_capabilityless_declarations() { - assert!(prompt_declaration_is_visible( - &request(&[]).governance.unwrap().allowed_capability_names, - &declaration(None) - )); - } - - #[test] - fn prompt_declaration_visibility_filters_out_ungranted_capabilities() { - assert!(!prompt_declaration_is_visible( - &request(&["readFile"]) - .governance - .unwrap() - .allowed_capability_names, - &declaration(Some("spawn")) - )); - } - - #[test] - fn prompt_declaration_visibility_keeps_granted_capabilities() { - assert!(prompt_declaration_is_visible( - &request(&["spawn"]) - .governance - .unwrap() - .allowed_capability_names, - &declaration(Some("spawn")) - )); - } -} diff --git a/crates/server/src/bootstrap/providers.rs b/crates/server/src/bootstrap/providers.rs index 4171069a..f64c7e94 100644 --- a/crates/server/src/bootstrap/providers.rs +++ b/crates/server/src/bootstrap/providers.rs @@ -14,58 +14,57 @@ use astrcode_adapter_llm::{ LlmClientConfig, ModelLimits, openai::{OpenAiProvider, OpenAiProviderCapabilities}, }; -use astrcode_adapter_mcp::{core_port::McpResourceProvider, manager::McpConnectionManager}; -use astrcode_adapter_prompt::{ - core_port::ComposerPromptProvider, layered_builder::default_layered_prompt_builder, -}; use astrcode_adapter_storage::config_store::FileConfigStore; -use astrcode_application::{ - ApplicationError, ProfileResolutionService, - config::{ - ConfigService, PROVIDER_KIND_OPENAI, api_key, resolve_current_model, - resolve_openai_chat_completions_api_url, resolve_openai_responses_api_url, - }, - execution::ProfileProvider, -}; +use astrcode_agent_runtime::{LlmEventSink, LlmOutput, LlmProvider, LlmRequest}; use astrcode_core::config::{OpenAiApiMode, OpenAiProfileCapabilities}; +use astrcode_plugin_host::{OPENAI_API_KIND, ProviderContributionCatalog}; use super::deps::core::{ - AgentProfile, AstrError, LlmEventSink, LlmOutput, LlmProvider, LlmRequest, ModelConfig, - PromptProvider, ResolvedRuntimeConfig, ResourceProvider, Result, resolve_runtime_config, + AgentProfile, AstrError, ModelConfig, ResolvedRuntimeConfig, Result, resolve_runtime_config, +}; +use crate::{ + ApplicationError, ConfigService, ProfileProvider, ProfileResolutionService, + application_error_bridge::ServerRouteError, + config_mode_helpers, + config_service_bridge::ServerConfigService, + profile_service::{ServerProfilePort, ServerProfileService}, }; pub(crate) fn build_llm_provider( - config_service: Arc, + config_service: Arc, working_dir: PathBuf, + provider_catalog: Arc>, ) -> Arc { - Arc::new(ConfigBackedLlmProvider::new(config_service, working_dir)) -} - -pub(crate) fn build_prompt_provider() -> Arc { - Arc::new(ComposerPromptProvider::new(default_layered_prompt_builder())) -} - -pub(crate) fn build_resource_provider( - manager: Arc, -) -> Arc { - Arc::new(McpResourceProvider::new(manager)) + Arc::new(ConfigBackedLlmProvider::new( + config_service, + working_dir, + provider_catalog, + )) } -pub(crate) fn build_config_service(config_path: PathBuf) -> Result> { +pub(crate) fn build_config_service(config_path: PathBuf) -> Result> { let config_store = FileConfigStore::new(config_path); - Ok(Arc::new(ConfigService::new(Arc::new(config_store)))) + Ok(Arc::new(ServerConfigService::new(Arc::new( + ConfigService::new(Arc::new(config_store)), + )))) } pub(crate) fn build_profile_resolution_service( loader: AgentProfileLoader, -) -> Result> { +) -> Result> { let provider: Arc = Arc::new(LoaderBackedProfileProvider { loader }); - Ok(Arc::new(ProfileResolutionService::new(provider))) + let profile_resolver = Arc::new(ProfileResolutionService::new(provider)); + Ok(Arc::new(ServerProfileService::new(Arc::new( + ApplicationProfilePort { + inner: Arc::clone(&profile_resolver), + }, + )))) } struct ConfigBackedLlmProvider { - config_service: Arc, + config_service: Arc, working_dir: PathBuf, + provider_catalog: Arc>, providers: RwLock>>, } @@ -73,6 +72,49 @@ struct LoaderBackedProfileProvider { loader: AgentProfileLoader, } +struct ApplicationProfilePort { + inner: Arc, +} + +impl ServerProfilePort for ApplicationProfilePort { + fn resolve( + &self, + working_dir: &Path, + ) -> std::result::Result>, ServerRouteError> { + self.inner + .resolve(working_dir) + .map_err(application_error_to_server) + } + + fn find_profile( + &self, + working_dir: &Path, + profile_id: &str, + ) -> std::result::Result { + self.inner + .find_profile(working_dir, profile_id) + .map_err(application_error_to_server) + } + + fn resolve_global(&self) -> std::result::Result>, ServerRouteError> { + self.inner + .resolve_global() + .map_err(application_error_to_server) + } + + fn invalidate(&self, working_dir: &Path) { + self.inner.invalidate(working_dir); + } + + fn invalidate_global(&self) { + self.inner.invalidate_global(); + } + + fn invalidate_all(&self) { + self.inner.invalidate_all(); + } +} + impl ProfileProvider for LoaderBackedProfileProvider { fn load_for_working_dir( &self, @@ -103,10 +145,15 @@ impl std::fmt::Debug for ConfigBackedLlmProvider { } impl ConfigBackedLlmProvider { - fn new(config_service: Arc, working_dir: PathBuf) -> Self { + fn new( + config_service: Arc, + working_dir: PathBuf, + provider_catalog: Arc>, + ) -> Self { Self { config_service, working_dir, + provider_catalog, providers: RwLock::new(HashMap::new()), } } @@ -114,8 +161,10 @@ impl ConfigBackedLlmProvider { fn resolve_spec(&self) -> std::result::Result { let config = self .config_service - .load_overlayed_config(Some(self.working_dir.as_path()))?; - let selection = resolve_current_model(&config)?; + .load_overlayed_config(Some(self.working_dir.as_path())) + .map_err(server_error_to_application)?; + let selection = config_mode_helpers::resolve_current_model(&config) + .map_err(|error| ApplicationError::InvalidArgument(error.to_string()))?; let profile = config .profiles .iter() @@ -136,23 +185,42 @@ impl ConfigBackedLlmProvider { selection.model, profile.name )) })?; - let api_key = api_key::resolve_api_key(profile) + let api_key = config_mode_helpers::resolve_api_key(profile) .map_err(|error| ApplicationError::Internal(error.to_string()))?; let limits = resolve_model_limits(&profile.provider_kind, model); let runtime = resolve_runtime_config(&config.runtime); let client_config = client_config_from_runtime(&runtime); - if profile.provider_kind != PROVIDER_KIND_OPENAI { + let provider_descriptor = { + let catalog = self + .provider_catalog + .read() + .expect("provider catalog read lock poisoned"); + catalog + .provider(&profile.provider_kind) + .or_else(|| catalog.provider_for_api_kind(&profile.provider_kind)) + .cloned() + .ok_or_else(|| { + ApplicationError::InvalidArgument(format!( + "unsupported provider_kind '{}'：未在 plugin-host ProviderDescriptor \ + catalog 中注册", + profile.provider_kind + )) + })? + }; + if provider_descriptor.api_kind != OPENAI_API_KIND { return Err(ApplicationError::InvalidArgument(format!( - "unsupported provider_kind '{}'", - profile.provider_kind + "registered provider '{}' uses unsupported api_kind '{}'", + provider_descriptor.provider_id, provider_descriptor.api_kind ))); } let api_mode = resolve_openai_api_mode(profile); let endpoint = match api_mode { OpenAiApiMode::ChatCompletions => { - resolve_openai_chat_completions_api_url(&profile.base_url) + config_mode_helpers::resolve_openai_chat_completions_api_url(&profile.base_url) + }, + OpenAiApiMode::Responses => { + config_mode_helpers::resolve_openai_responses_api_url(&profile.base_url) }, - OpenAiApiMode::Responses => resolve_openai_responses_api_url(&profile.base_url), }; let openai_capabilities = Some(resolve_openai_provider_capabilities( endpoint.as_str(), @@ -161,8 +229,9 @@ impl ConfigBackedLlmProvider { Ok(ResolvedLlmProviderSpec { cache_key: format!( - "{}|{}|{}|{}|{}|{}|{}|{}|{}|{}|{}", - profile.provider_kind, + "{}|{}|{}|{}|{}|{}|{}|{}|{}|{}|{}|{}", + provider_descriptor.provider_id, + provider_descriptor.api_kind, match api_mode { OpenAiApiMode::ChatCompletions => "chat_completions", OpenAiApiMode::Responses => "responses", @@ -181,7 +250,8 @@ impl ConfigBackedLlmProvider { .map(|caps| caps.supports_stream_usage) .unwrap_or(false) ), - provider_kind: profile.provider_kind.clone(), + provider_id: provider_descriptor.provider_id, + api_kind: provider_descriptor.api_kind, endpoint, api_key, model: model.id.clone(), @@ -205,10 +275,10 @@ impl ConfigBackedLlmProvider { return Ok(existing); } - if spec.provider_kind != PROVIDER_KIND_OPENAI { + if spec.api_kind != OPENAI_API_KIND { return Err(AstrError::Validation(format!( - "unsupported provider_kind '{}'", - spec.provider_kind + "registered provider '{}' uses unsupported api_kind '{}'", + spec.provider_id, spec.api_kind ))); } let provider: Arc = Arc::new(OpenAiProvider::new_with_capabilities( @@ -230,6 +300,26 @@ impl ConfigBackedLlmProvider { } } +fn server_error_to_application(error: ServerRouteError) -> ApplicationError { + match error { + ServerRouteError::NotFound(message) => ApplicationError::NotFound(message), + ServerRouteError::Conflict(message) => ApplicationError::Conflict(message), + ServerRouteError::InvalidArgument(message) => ApplicationError::InvalidArgument(message), + ServerRouteError::PermissionDenied(message) => ApplicationError::PermissionDenied(message), + ServerRouteError::Internal(message) => ApplicationError::Internal(message), + } +} + +fn application_error_to_server(error: ApplicationError) -> ServerRouteError { + match error { + ApplicationError::NotFound(message) => ServerRouteError::NotFound(message), + ApplicationError::Conflict(message) => ServerRouteError::Conflict(message), + ApplicationError::InvalidArgument(message) => ServerRouteError::InvalidArgument(message), + ApplicationError::PermissionDenied(message) => ServerRouteError::PermissionDenied(message), + ApplicationError::Internal(message) => ServerRouteError::Internal(message), + } +} + fn client_config_from_runtime(runtime: &ResolvedRuntimeConfig) -> LlmClientConfig { LlmClientConfig { connect_timeout: std::time::Duration::from_secs(runtime.llm_connect_timeout_secs), @@ -269,7 +359,8 @@ impl LlmProvider for ConfigBackedLlmProvider { #[derive(Debug, Clone)] struct ResolvedLlmProviderSpec { cache_key: String, - provider_kind: String, + provider_id: String, + api_kind: String, endpoint: String, api_key: String, model: String, @@ -280,7 +371,7 @@ struct ResolvedLlmProviderSpec { fn resolve_model_limits(provider_kind: &str, model: &ModelConfig) -> ModelLimits { let default_context_window = match provider_kind { - PROVIDER_KIND_OPENAI => 128_000, + config_mode_helpers::PROVIDER_KIND_OPENAI => 128_000, _ => 128_000, }; ModelLimits { @@ -321,3 +412,94 @@ fn resolve_openai_provider_capabilities( } resolved } + +#[cfg(test)] +mod tests { + use std::sync::{Arc, RwLock}; + + use astrcode_adapter_storage::config_store::FileConfigStore; + use astrcode_core::{Config, ModelConfig, Profile}; + use astrcode_plugin_host::{ + OPENAI_API_KIND, PluginDescriptor, ProviderContributionCatalog, ProviderDescriptor, + }; + + use super::ConfigBackedLlmProvider; + use crate::{ConfigService, config_service_bridge::ServerConfigService}; + + fn provider_with_config( + config: Config, + catalog: ProviderContributionCatalog, + working_dir: &std::path::Path, + ) -> ConfigBackedLlmProvider { + let config_path = working_dir.join("config.json"); + let store = FileConfigStore::new(config_path); + store.save(&config).expect("config should save"); + ConfigBackedLlmProvider::new( + Arc::new(ServerConfigService::new(Arc::new(ConfigService::new( + Arc::new(store), + )))), + working_dir.to_path_buf(), + Arc::new(RwLock::new(catalog)), + ) + } + + fn config_for_provider_kind(provider_kind: &str) -> Config { + let mut model = ModelConfig::new("corp-model"); + model.max_tokens = Some(4096); + model.context_limit = Some(128_000); + Config { + active_profile: "corp".to_string(), + active_model: "corp-model".to_string(), + profiles: vec![Profile { + name: "corp".to_string(), + provider_kind: provider_kind.to_string(), + base_url: "https://api.example.test".to_string(), + api_key: Some("literal:test-key".to_string()), + models: vec![model], + ..Profile::default() + }], + ..Config::default() + } + } + + #[test] + fn resolve_spec_uses_registered_provider_id_before_api_kind() { + let temp = tempfile::tempdir().expect("tempdir should exist"); + let mut descriptor = PluginDescriptor::builtin("corp-provider", "Corp Provider"); + descriptor.providers.push(ProviderDescriptor { + provider_id: "corp-openai".to_string(), + api_kind: OPENAI_API_KIND.to_string(), + }); + let catalog = ProviderContributionCatalog::from_descriptors(&[descriptor]) + .expect("catalog should build"); + let provider = provider_with_config( + config_for_provider_kind("corp-openai"), + catalog, + temp.path(), + ); + + let spec = provider.resolve_spec().expect("provider should resolve"); + + assert_eq!(spec.provider_id, "corp-openai"); + assert_eq!(spec.api_kind, OPENAI_API_KIND); + } + + #[test] + fn resolve_spec_keeps_api_kind_fallback_for_existing_openai_configs() { + let temp = tempfile::tempdir().expect("tempdir should exist"); + let mut descriptor = PluginDescriptor::builtin("renamed-openai", "Renamed OpenAI"); + descriptor.providers.push(ProviderDescriptor { + provider_id: "renamed-openai".to_string(), + api_kind: OPENAI_API_KIND.to_string(), + }); + let catalog = ProviderContributionCatalog::from_descriptors(&[descriptor]) + .expect("catalog should build"); + let provider = + provider_with_config(config_for_provider_kind("openai"), catalog, temp.path()); + + let spec = provider.resolve_spec().expect("provider should resolve"); + + assert_eq!(spec.provider_id, "renamed-openai"); + assert_eq!(spec.api_kind, OPENAI_API_KIND); + } +} diff --git a/crates/server/src/bootstrap/runtime.rs b/crates/server/src/bootstrap/runtime.rs index fc7d4361..e12582d6 100644 --- a/crates/server/src/bootstrap/runtime.rs +++ b/crates/server/src/bootstrap/runtime.rs @@ -1,7 +1,8 @@ //! # 服务器运行时组合根 //! -//! 由 server 显式组装 adapter、kernel、session-runtime、application。 -//! 所有 provider 和 gateway 在此唯一位置接线，handler 只依赖 `App`。 +//! 由 server 装配 adapter 与运行时 owner。 +//! plugin/provider/resource 生效事实统一来自 plugin-host active snapshot， +//! 组合根只负责把 server-owned bridge、host-session 与 agent-runtime 接起来。 use std::{ path::{Path, PathBuf}, @@ -10,43 +11,70 @@ use std::{ use astrcode_adapter_storage::session::FileSystemSessionRepository; use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; -use astrcode_application::{ - AgentOrchestrationService, App, AppGovernance, GovernanceSurfaceAssembler, - RuntimeObservabilityCollector, WatchService, builtin_mode_catalog, lifecycle::TaskRegistry, +use astrcode_core::SkillCatalog; +use astrcode_host_session::{CollaborationExecutor, EventStore, SessionCatalog, SubAgentExecutor}; +use astrcode_plugin_host::{ + CommandDescriptor, PluginActiveSnapshot, PluginDescriptor, PluginRegistry, + ProviderContributionCatalog, ResourceCatalog, builtin_collaboration_tools_descriptor, + builtin_modes_descriptor, builtin_openai_provider_descriptor, builtin_tools_descriptor, + resources_discover, }; use astrcode_support::hostpaths::resolve_home_dir; use super::{ + super::{ + agent_api::ServerAgentApi, + agent_runtime_bridge::{ServerAgentRuntimeBuildInput, build_server_agent_runtime_bundle}, + }, capabilities::{ CapabilitySurfaceSync, build_agent_tool_invokers, build_core_tool_invokers, - build_server_capability_router, build_skill_catalog, build_stable_local_invokers, - sync_external_tool_search_index, + build_skill_catalog, build_stable_local_invokers, sync_external_tool_search_index, }, - composer_skills::RuntimeComposerSkillPort, - deps::{ - core::{ - self, AstrError, CapabilityInvoker, Config, EventStore, LlmProvider, PromptProvider, - ResolvedRuntimeConfig, ResourceProvider, Result, resolve_runtime_config, - }, - kernel::{AgentControlLimits, CapabilityRouter, Kernel, KernelBuilder}, - session_runtime::SessionRuntime, + deps::core::{ + self, AstrError, CapabilityInvoker, Config, ResolvedRuntimeConfig, Result, + resolve_runtime_config, }, - governance::{GovernanceBuildInput, build_app_governance}, + governance::{GovernanceBuildInput, build_server_governance_service}, mcp::{bootstrap_mcp_manager, build_mcp_service, warmup_mcp_manager}, plugins::{PluginBootstrapResult, bootstrap_plugins_with_skill_root}, - prompt_facts::build_prompt_facts_provider, - providers::{ - build_config_service, build_llm_provider, build_profile_resolution_service, - build_prompt_provider, build_resource_provider, - }, + providers::{build_config_service, build_llm_provider, build_profile_resolution_service}, runtime_coordinator::RuntimeCoordinator, watch::{bootstrap_profile_watch_runtime, build_watch_service}, }; +use crate::{ + agent_control_bridge::ServerAgentControlPort, + config_service_bridge::ServerConfigService, + governance_service::ServerGovernanceService, + mcp_service::ServerMcpService, + mode_catalog_service::ServerModeCatalog, + profile_service::ServerProfileService, + runtime_owner_bridge::{ + ServerRuntimeObservability, ServerTaskRegistry, builtin_server_mode_specs, + }, + session_runtime_owner_bridge::{ + ServerAgentControlLimits, ServerSessionRuntimeBootstrapInput, bootstrap_session_runtime, + }, + watch_service::WatchService, +}; + +const BUILTIN_GOVERNANCE_MODES_PLUGIN_ID: &str = "builtin-governance-modes"; +const EXTERNAL_PLUGIN_MODES_PLUGIN_ID: &str = "external-plugin-modes"; /// 服务器运行时：组合根输出。 pub struct ServerRuntime { - pub app: Arc, - pub governance: Arc, + pub agent_api: Arc, + pub agent_control: Arc, + pub config: Arc, + pub session_catalog: Arc, + pub profiles: Arc, + pub subagent_executor: Arc, + #[allow(dead_code)] + pub collaboration_executor: Arc, + pub mcp_service: Arc, + pub skill_catalog: Arc, + pub resource_catalog: Arc>, + pub mode_catalog: Arc, + pub governance: Arc, pub handles: Arc, } @@ -54,7 +82,10 @@ pub struct ServerRuntimeHandles { // Why: server 集成测试需要直接操纵底层 session-runtime，避免把原始状态访问重新暴露给 // application 端口；生产路径只把它当作资源守卫持有。 #[allow(dead_code)] - pub(crate) session_runtime: Arc, + pub(crate) session_runtime_guard: Arc, + #[cfg(test)] + pub(crate) session_runtime_test_support: + Arc, _profile_watch_runtime: Option, _mcp_warmup_runtime: McpWarmupRuntime, } @@ -160,8 +191,10 @@ pub async fn bootstrap_server_runtime_with_options( skills: plugin_skills, modes: plugin_modes, registry: plugin_registry, - supervisors: plugin_supervisors, + managed_components: managed_plugin_components, search_paths: plugin_search_paths, + resource_catalog: plugin_resource_catalog, + descriptors: plugin_descriptors, } = bootstrap_plugins_with_skill_root( paths.plugin_search_paths.clone(), paths.plugin_skill_root.clone(), @@ -175,70 +208,90 @@ pub async fn bootstrap_server_runtime_with_options( // core builtin tools：工具定义本身是 builtin + stable； // 其中 `Skill` 工具消费的 catalog 可以包含 builtin / mcp / plugin 三类 skill。 - let skill_catalog = build_skill_catalog(paths.home_dir.as_path(), plugin_skills); + let skill_catalog = build_skill_catalog( + paths.home_dir.as_path(), + plugin_skills, + &plugin_resource_catalog, + ); + let skill_catalog_bridge: Arc = skill_catalog.clone(); + let builtin_mode_specs = builtin_server_mode_specs()?; let core_tool_invokers = build_core_tool_invokers(Arc::clone(&tool_search_index), skill_catalog.clone())?; - - // 初始 router 先用“当前可立即装配的能力面”启动： - // core builtin tools + 当前 external 动态能力。 - // agent tools 要等 agent_service 准备好后再并入稳定本地层。 - let mut initial_router_invokers = core_tool_invokers.clone(); - initial_router_invokers.extend(external_dynamic_invokers.clone()); - let capabilities = build_server_capability_router(initial_router_invokers)?; - - let kernel = Arc::new(build_kernel( - capabilities, - build_llm_provider(config_service.clone(), working_dir.clone()), - build_prompt_provider(), - build_resource_provider(mcp_manager.clone()), - resolve_agent_control_limits(&resolved_config), - )?); - let observability = Arc::new(RuntimeObservabilityCollector::new()); - let task_registry = Arc::new(TaskRegistry::new()); - let mode_catalog = Arc::new(builtin_mode_catalog()?); - mode_catalog.replace_plugin_modes(plugin_modes.clone())?; - let governance_surface = Arc::new(GovernanceSurfaceAssembler::new( - mode_catalog.as_ref().clone(), + let active_plugin_descriptors = build_server_plugin_contribution_descriptors( + &core_tool_invokers, + &mcp_invokers, + builtin_mode_specs, + plugin_modes, + plugin_descriptors.clone(), + ); + let plugin_host_reload = + reload_server_plugin_host_snapshot(plugin_registry.as_ref(), active_plugin_descriptors)?; + log::info!( + "plugin-host bridge activated snapshot {} with {} plugins", + plugin_host_reload.snapshot.snapshot_id, + plugin_host_reload.snapshot.plugin_ids.len() + ); + let plugin_resource_catalog_state = + Arc::new(std::sync::RwLock::new(plugin_host_reload.resources.clone())); + let provider_catalog = Arc::new(std::sync::RwLock::new( + plugin_host_reload.provider_catalog.clone(), )); + let observability = ServerRuntimeObservability::new(); + let task_registry = ServerTaskRegistry::new(); + let mode_catalog = ServerModeCatalog::from_mode_specs( + plugin_host_reload.builtin_modes.clone(), + plugin_host_reload.plugin_modes.clone(), + )?; + let event_store: Arc = Arc::new( FileSystemSessionRepository::new_with_projects_root(paths.projects_root.clone()), ); - let prompt_facts_provider = build_prompt_facts_provider( - config_service.clone(), - skill_catalog.clone(), - mcp_manager.clone(), - agent_loader.clone(), - )?; - let session_runtime = Arc::new(SessionRuntime::new( - kernel.clone(), - prompt_facts_provider, - event_store, - observability.clone(), - )); + let session_catalog = Arc::new(SessionCatalog::new(Arc::clone(&event_store))); + // 初始 capability surface 先用“当前可立即装配的能力面”启动： + // core builtin tools + 当前 external 动态能力。 + // agent tools 要等 agent_service 准备好后再并入稳定本地层。 + let mut initial_router_invokers = core_tool_invokers.clone(); + initial_router_invokers.extend(external_dynamic_invokers.clone()); + let session_runtime = bootstrap_session_runtime(ServerSessionRuntimeBootstrapInput { + capability_invokers: initial_router_invokers, + llm_provider: build_llm_provider( + config_service.clone(), + working_dir.clone(), + Arc::clone(&provider_catalog), + ), + session_catalog: Arc::clone(&session_catalog), + mode_catalog: Arc::clone(&mode_catalog), + agent_limits: resolve_agent_control_limits(&resolved_config), + })?; let profiles = build_profile_resolution_service(agent_loader.clone())?; let watch_service = match options.watch_service_override.clone() { Some(service) => service, None => build_watch_service(agent_loader) .map_err(|error| AstrError::Internal(error.to_string()))?, }; - let agent_service = Arc::new(AgentOrchestrationService::new( - kernel.clone(), - session_runtime.clone(), - config_service.clone(), - profiles.clone(), - Arc::clone(&governance_surface), - task_registry.clone(), - observability.clone(), - )); + let agent_runtime = build_server_agent_runtime_bundle(ServerAgentRuntimeBuildInput { + agent_kernel: session_runtime.agent_kernel.clone(), + agent_sessions: session_runtime.agent_sessions.clone(), + app_sessions: session_runtime.app_sessions.clone(), + agent_control: session_runtime.agent_control.clone(), + config_service: config_service.clone(), + profiles: profiles.clone(), + mode_catalog: mode_catalog.clone(), + task_registry: task_registry.clone(), + observability: observability.clone(), + }); // agent 四工具依赖 agent_service，必须在 kernel/session_runtime 之后单独注册。 // 组装完成后，稳定本地层 = core builtin tools + agent tools。 - let agent_tool_invokers = build_agent_tool_invokers(agent_service.clone())?; + let agent_tool_invokers = build_agent_tool_invokers( + Arc::clone(&agent_runtime.subagent_executor), + Arc::clone(&agent_runtime.collaboration_executor), + )?; let stable_local_invokers = build_stable_local_invokers(core_tool_invokers, agent_tool_invokers); let capability_sync = CapabilitySurfaceSync::new( - kernel.clone(), + session_runtime.capability_surface.clone(), stable_local_invokers, Arc::clone(&tool_search_index), ); @@ -254,21 +307,8 @@ pub async fn bootstrap_server_runtime_with_options( mcp_manager.clone(), capability_sync.clone(), ); - - let app = Arc::new(App::new( - kernel.clone(), - session_runtime.clone(), - profiles, - config_service.clone(), - Arc::new(RuntimeComposerSkillPort::new(skill_catalog.clone())), - Arc::clone(&governance_surface), - Arc::clone(&mode_catalog), - mcp_service, - agent_service, - )); - let session_runtime_handle = Arc::clone(&session_runtime); - let governance = build_app_governance(GovernanceBuildInput { - session_runtime, + let governance = build_server_governance_service(GovernanceBuildInput { + sessions: session_runtime.sessions.clone(), config_service: config_service.clone(), coordinator, task_registry, @@ -276,17 +316,23 @@ pub async fn bootstrap_server_runtime_with_options( mcp_manager: Arc::clone(&mcp_manager), capability_sync: capability_sync.clone(), skill_catalog, + resource_catalog: Arc::clone(&plugin_resource_catalog_state), + provider_catalog, plugin_search_paths: plugin_search_paths.clone(), plugin_skill_root: paths.plugin_skill_root.clone(), - plugin_supervisors, + managed_plugin_components, working_dir: working_dir.clone(), - mode_catalog: Some(mode_catalog), + mode_catalog: Some(Arc::clone(&mode_catalog)), }); let profile_watch_runtime = if options.enable_profile_watch { Some( - bootstrap_profile_watch_runtime(Arc::clone(&app), Arc::clone(&watch_service)) - .await - .map_err(|error| AstrError::Internal(error.to_string()))?, + bootstrap_profile_watch_runtime( + Arc::clone(&session_catalog), + Arc::clone(&profiles), + Arc::clone(&watch_service), + ) + .await + .map_err(|error| AstrError::Internal(error.to_string()))?, ) } else { None @@ -302,16 +348,122 @@ pub async fn bootstrap_server_runtime_with_options( }; Ok(ServerRuntime { - app, + agent_api: agent_runtime.agent_api, + agent_control: agent_runtime.agent_control, + config: config_service, + session_catalog, + profiles, + subagent_executor: agent_runtime.subagent_executor, + collaboration_executor: agent_runtime.collaboration_executor, + mcp_service, + skill_catalog: skill_catalog_bridge, + resource_catalog: Arc::clone(&plugin_resource_catalog_state), + mode_catalog, governance, handles: Arc::new(ServerRuntimeHandles { - session_runtime: session_runtime_handle, + session_runtime_guard: session_runtime.keepalive, + #[cfg(test)] + session_runtime_test_support: session_runtime.test_support, _profile_watch_runtime: profile_watch_runtime, _mcp_warmup_runtime: mcp_warmup_runtime, }), }) } +fn build_server_plugin_contribution_descriptors( + core_tool_invokers: &[Arc], + mcp_invokers: &[Arc], + builtin_modes: Vec, + plugin_modes: Vec, + mut external_descriptors: Vec, +) -> Vec { + let mut descriptors = vec![ + builtin_openai_provider_descriptor(), + builtin_modes_descriptor( + BUILTIN_GOVERNANCE_MODES_PLUGIN_ID, + "Builtin Governance Modes", + builtin_modes, + ), + builtin_modes_descriptor( + EXTERNAL_PLUGIN_MODES_PLUGIN_ID, + "External Plugin Modes", + plugin_modes, + ), + builtin_composer_resources_descriptor(), + builtin_tools_descriptor( + "builtin-core-tools", + "Builtin Core Tools", + core_tool_invokers + .iter() + .map(|invoker| invoker.capability_spec()) + .collect(), + ), + builtin_tools_descriptor( + "external-mcp-tools", + "External MCP Tools", + mcp_invokers + .iter() + .map(|invoker| invoker.capability_spec()) + .collect(), + ), + builtin_collaboration_tools_descriptor(), + ]; + descriptors.append(&mut external_descriptors); + descriptors +} + +fn builtin_composer_resources_descriptor() -> PluginDescriptor { + let mut descriptor = + PluginDescriptor::builtin("builtin-composer-resources", "Builtin Composer Resources"); + descriptor.commands.push(CommandDescriptor { + command_id: "compact".to_string(), + entry_ref: "builtin://commands/compact".to_string(), + }); + descriptor +} + +#[derive(Debug, Clone)] +struct ServerPluginHostReload { + snapshot: PluginActiveSnapshot, + resources: ResourceCatalog, + provider_catalog: ProviderContributionCatalog, + builtin_modes: Vec, + plugin_modes: Vec, +} + +fn reload_server_plugin_host_snapshot( + registry: &PluginRegistry, + descriptors: Vec, +) -> Result { + let resources = resources_discover(&descriptors)?.catalog; + let provider_catalog = ProviderContributionCatalog::from_descriptors(&descriptors)?; + let builtin_modes = descriptor_modes(&descriptors, BUILTIN_GOVERNANCE_MODES_PLUGIN_ID); + let plugin_modes = descriptor_modes(&descriptors, EXTERNAL_PLUGIN_MODES_PLUGIN_ID); + registry.stage_candidate(descriptors)?; + let snapshot = registry.commit_candidate().ok_or_else(|| { + AstrError::Internal("plugin-host active snapshot commit unexpectedly failed".to_string()) + })?; + + Ok(ServerPluginHostReload { + snapshot, + resources, + provider_catalog, + builtin_modes, + plugin_modes, + }) +} + +fn descriptor_modes( + descriptors: &[PluginDescriptor], + plugin_id: &str, +) -> Vec { + descriptors + .iter() + .find(|descriptor| descriptor.plugin_id == plugin_id) + .map(|descriptor| descriptor.modes.clone()) + .unwrap_or_default() +} + /// 解析插件搜索路径。 /// /// 从环境变量 `ASTRCODE_PLUGIN_DIRS` 读取，未设置时默认为 @@ -334,32 +486,15 @@ fn resolve_plugin_search_paths( } } -fn build_kernel( - capabilities: CapabilityRouter, - llm_provider: Arc, - prompt_provider: Arc, - resource_provider: Arc, - agent_limits: AgentControlLimits, -) -> Result { - KernelBuilder::default() - .with_capabilities(capabilities) - .with_llm_provider(llm_provider) - .with_prompt_provider(prompt_provider) - .with_resource_provider(resource_provider) - .with_agent_limits(agent_limits) - .build() - .map_err(|error| AstrError::Internal(error.to_string())) -} - -fn resolve_agent_control_limits(config: &Config) -> AgentControlLimits { +fn resolve_agent_control_limits(config: &Config) -> ServerAgentControlLimits { let runtime = resolve_runtime_config(&config.runtime); resolve_agent_control_limits_from_runtime(&runtime) } fn resolve_agent_control_limits_from_runtime( runtime: &ResolvedRuntimeConfig, -) -> AgentControlLimits { - AgentControlLimits { +) -> ServerAgentControlLimits { + ServerAgentControlLimits { max_depth: runtime.agent.max_subrun_depth, max_concurrent: runtime.agent.max_concurrent, finalized_retain_limit: runtime.agent.finalized_retain_limit, @@ -370,7 +505,14 @@ fn resolve_agent_control_limits_from_runtime( #[cfg(test)] mod tests { - use super::resolve_agent_control_limits; + use astrcode_plugin_host::{ + CommandDescriptor, PluginDescriptor, PluginRegistry, ProviderDescriptor, + }; + + use super::{ + build_server_plugin_contribution_descriptors, builtin_server_mode_specs, + reload_server_plugin_host_snapshot, resolve_agent_control_limits, + }; use crate::bootstrap::deps::core::{AgentConfig, Config, RuntimeConfig, config}; #[test] @@ -405,4 +547,94 @@ mod tests { assert_eq!(limits.max_depth, config::DEFAULT_MAX_SUBRUN_DEPTH); } + + #[test] + fn server_plugin_descriptors_collect_builtin_and_external_contributions() { + let external = PluginDescriptor::builtin("external-plugin", "External Plugin"); + let builtin_modes = builtin_server_mode_specs().expect("builtin mode specs should build"); + + let descriptors = build_server_plugin_contribution_descriptors( + &[], + &[], + builtin_modes, + Vec::new(), + vec![external], + ); + let plugin_ids = descriptors + .iter() + .map(|descriptor| descriptor.plugin_id.as_str()) + .collect::>(); + + assert_eq!( + plugin_ids, + vec![ + "builtin-provider-openai", + "builtin-governance-modes", + "external-plugin-modes", + "builtin-composer-resources", + "builtin-core-tools", + "external-mcp-tools", + "builtin-collaboration-tools", + "external-plugin", + ] + ); + assert_eq!(descriptors[1].modes.len(), 3); + } + + #[test] + fn server_plugin_reload_bridge_commits_snapshot_resources_and_providers() { + let registry = PluginRegistry::default(); + let mut descriptor = PluginDescriptor::builtin("project-runtime", "Project Runtime"); + descriptor.commands.push(CommandDescriptor { + command_id: "project.apply".to_string(), + entry_ref: ".codex/commands/apply.md".to_string(), + }); + descriptor.providers.push(ProviderDescriptor { + provider_id: "project-openai".to_string(), + api_kind: "openai".to_string(), + }); + let builtin_modes = builtin_server_mode_specs().expect("builtin mode specs should build"); + let descriptors = build_server_plugin_contribution_descriptors( + &[], + &[], + builtin_modes, + Vec::new(), + vec![descriptor], + ); + + let reload = reload_server_plugin_host_snapshot(®istry, descriptors) + .expect("bridge reload should commit"); + + assert_eq!( + reload.snapshot.plugin_ids, + vec![ + "builtin-provider-openai".to_string(), + "builtin-governance-modes".to_string(), + "external-plugin-modes".to_string(), + "builtin-composer-resources".to_string(), + "builtin-core-tools".to_string(), + "external-mcp-tools".to_string(), + "builtin-collaboration-tools".to_string(), + "project-runtime".to_string(), + ] + ); + assert_eq!(reload.builtin_modes.len(), 3); + assert_eq!(reload.snapshot.modes.len(), 3); + assert_eq!(reload.resources.commands.len(), 2); + assert_eq!( + reload + .provider_catalog + .provider("project-openai") + .expect("provider should be registered") + .api_kind, + "openai" + ); + assert_eq!( + registry + .active_snapshot() + .expect("active snapshot should be committed") + .snapshot_id, + reload.snapshot.snapshot_id + ); + } } diff --git a/crates/server/src/bootstrap/runtime_coordinator.rs b/crates/server/src/bootstrap/runtime_coordinator.rs index 653648b6..64a3ece2 100644 --- a/crates/server/src/bootstrap/runtime_coordinator.rs +++ b/crates/server/src/bootstrap/runtime_coordinator.rs @@ -4,9 +4,10 @@ use std::sync::{Arc, RwLock}; +use astrcode_plugin_host::{PluginEntry, PluginRegistry}; + use super::deps::core::{ - AstrError, CapabilitySpec, ManagedRuntimeComponent, PluginRegistry, Result, RuntimeHandle, - plugin::PluginEntry, support, + AstrError, CapabilitySpec, ManagedRuntimeComponent, Result, RuntimeHandle, support, }; /// 运行时协调器。 @@ -149,14 +150,14 @@ impl RuntimeCoordinator { mod tests { use std::sync::{Arc, Mutex}; + use astrcode_plugin_host::{PluginEntry, PluginHealth, PluginRegistry, PluginState}; use async_trait::async_trait; use serde_json::json; use super::RuntimeCoordinator; use crate::bootstrap::deps::core::{ - AstrError, CapabilityKind, CapabilitySpec, InvocationMode, ManagedRuntimeComponent, - PluginRegistry, Result, RuntimeHandle, SideEffect, Stability, - plugin::{PluginEntry, PluginHealth}, + AstrError, CapabilityKind, CapabilitySpec, InvocationMode, ManagedRuntimeComponent, Result, + RuntimeHandle, SideEffect, Stability, }; struct FakeRuntimeHandle { @@ -306,16 +307,22 @@ mod tests { fn replace_runtime_surface_swaps_registry_capabilities_and_components() { let events = Arc::new(Mutex::new(Vec::new())); let registry = Arc::new(PluginRegistry::default()); - registry.record_discovered(crate::bootstrap::deps::core::PluginManifest { + registry.record_discovered(astrcode_plugin_host::PluginManifest { name: "alpha".to_string(), version: "0.1.0".to_string(), description: "alpha".to_string(), - plugin_type: vec![crate::bootstrap::deps::core::PluginType::Tool], + plugin_type: vec![astrcode_plugin_host::PluginType::Tool], capabilities: Vec::new(), executable: Some("alpha.exe".to_string()), args: Vec::new(), working_dir: None, repository: None, + resources: Vec::new(), + commands: Vec::new(), + themes: Vec::new(), + prompts: Vec::new(), + providers: Vec::new(), + skills: Vec::new(), }); let coordinator = RuntimeCoordinator::new( Arc::new(FakeRuntimeHandle { @@ -333,18 +340,24 @@ mod tests { let old = coordinator.replace_runtime_surface( vec![PluginEntry { - manifest: crate::bootstrap::deps::core::PluginManifest { + manifest: astrcode_plugin_host::PluginManifest { name: "beta".to_string(), version: "0.2.0".to_string(), description: "beta".to_string(), - plugin_type: vec![crate::bootstrap::deps::core::PluginType::Tool], + plugin_type: vec![astrcode_plugin_host::PluginType::Tool], capabilities: Vec::new(), executable: Some("beta.exe".to_string()), args: Vec::new(), working_dir: None, repository: None, + resources: Vec::new(), + commands: Vec::new(), + themes: Vec::new(), + prompts: Vec::new(), + providers: Vec::new(), + skills: Vec::new(), }, - state: crate::bootstrap::deps::core::PluginState::Initialized, + state: PluginState::Initialized, health: PluginHealth::Healthy, failure_count: 0, capabilities: vec![capability("tool.beta")], diff --git a/crates/server/src/bootstrap/watch.rs b/crates/server/src/bootstrap/watch.rs index 4f657d47..cc0a152d 100644 --- a/crates/server/src/bootstrap/watch.rs +++ b/crates/server/src/bootstrap/watch.rs @@ -5,43 +5,51 @@ use std::{ }; use astrcode_adapter_agents::{AgentProfileLoader, AgentWatchPath}; -use astrcode_application::{App, ApplicationError, WatchPort, WatchService, WatchSource}; +use astrcode_host_session::SessionCatalog; use notify::{Config as NotifyConfig, Event, RecommendedWatcher, RecursiveMode, Watcher}; use tokio::sync::broadcast; +use crate::{ + application_error_bridge::ServerRouteError, + profile_service::ServerProfileService, + watch_service::{WatchEvent, WatchPort, WatchService, WatchSource}, +}; + pub(crate) fn build_watch_service( loader: AgentProfileLoader, -) -> Result, ApplicationError> { +) -> Result, ServerRouteError> { Ok(Arc::new(WatchService::new(Arc::new( FileSystemWatchPort::new(loader), )))) } pub(crate) async fn bootstrap_profile_watch_runtime( - app: Arc, + session_catalog: Arc, + profiles: Arc, watch_service: Arc, -) -> Result { - let mut sources = desired_agent_watch_sources(&app).await?; +) -> Result { + let mut sources = desired_agent_watch_sources(session_catalog.as_ref()).await?; watch_service.start_watch(sources.iter().cloned().collect())?; - let mut catalog_rx = app.subscribe_catalog(); - let watch_app = Arc::downgrade(&app); + let mut catalog_rx = session_catalog.subscribe_catalog_events(); + let watch_session_catalog = Arc::downgrade(&session_catalog); let watch_service_for_catalog = Arc::clone(&watch_service); let catalog_task = tokio::spawn(async move { loop { if catalog_rx.recv().await.is_err() { break; } - let Some(watch_app) = watch_app.upgrade() else { + let Some(watch_session_catalog) = watch_session_catalog.upgrade() else { break; }; - let next_sources = match desired_agent_watch_sources(&watch_app).await { - Ok(next) => next, - Err(error) => { - log::warn!("failed to recompute agent watch sources: {error}"); - continue; - }, - }; + let next_sources = + match desired_agent_watch_sources(watch_session_catalog.as_ref()).await { + Ok(next) => next, + Err(error) => { + log::warn!("failed to recompute agent watch sources: {error}"); + continue; + }, + }; for source in next_sources.difference(&sources) { if let Err(error) = watch_service_for_catalog.add_source(source.clone()) { @@ -57,7 +65,6 @@ pub(crate) async fn bootstrap_profile_watch_runtime( } }); - let profiles = Arc::clone(app.profiles()); let mut watch_rx = watch_service.subscribe(); let event_task = tokio::spawn(async move { loop { @@ -78,7 +85,6 @@ pub(crate) async fn bootstrap_profile_watch_runtime( WatchSource::AgentDefinitions { working_dir } => { profiles.invalidate(Path::new(&working_dir)); }, - _ => {}, } } }); @@ -107,9 +113,9 @@ impl Drop for ProfileWatchRuntime { } async fn desired_agent_watch_sources( - app: &Arc, -) -> Result, ApplicationError> { - let sessions = app.list_sessions().await?; + session_catalog: &SessionCatalog, +) -> Result, ServerRouteError> { + let sessions = session_catalog.list_session_metas().await?; let mut sources = HashSet::from([WatchSource::GlobalAgentDefinitions]); for session in sessions { sources.insert(WatchSource::AgentDefinitions { @@ -140,14 +146,11 @@ impl FileSystemWatchPort { } } - fn ensure_watcher( - &self, - tx: broadcast::Sender, - ) -> Result<(), ApplicationError> { + fn ensure_watcher(&self, tx: broadcast::Sender) -> Result<(), ServerRouteError> { let mut watcher_guard = self .watcher .lock() - .map_err(|_| ApplicationError::Internal("watcher lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watcher lock poisoned"))?; if watcher_guard.is_some() { return Ok(()); } @@ -159,7 +162,7 @@ impl FileSystemWatchPort { }, NotifyConfig::default(), ) - .map_err(|error| ApplicationError::Internal(error.to_string()))?; + .map_err(|error| ServerRouteError::internal(error.to_string()))?; *watcher_guard = Some(watcher); Ok(()) } @@ -170,25 +173,24 @@ impl FileSystemWatchPort { WatchSource::AgentDefinitions { working_dir } => { self.loader.watch_paths(Some(Path::new(working_dir))) }, - _ => Vec::new(), } } - fn add_source_inner(&self, source: WatchSource) -> Result<(), ApplicationError> { + fn add_source_inner(&self, source: WatchSource) -> Result<(), ServerRouteError> { let targets = self.resolve_targets(&source); let mut watcher_guard = self .watcher .lock() - .map_err(|_| ApplicationError::Internal("watcher lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watcher lock poisoned"))?; let Some(watcher) = watcher_guard.as_mut() else { - return Err(ApplicationError::Internal( + return Err(ServerRouteError::internal( "watcher must be initialized before adding sources".to_string(), )); }; let mut registry = self .registry .lock() - .map_err(|_| ApplicationError::Internal("watch registry lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watch registry lock poisoned"))?; if registry.source_targets.contains_key(&source) { return Ok(()); } @@ -205,7 +207,7 @@ impl FileSystemWatchPort { RecursiveMode::NonRecursive }, ) - .map_err(|error| ApplicationError::Internal(error.to_string()))?; + .map_err(|error| ServerRouteError::internal(error.to_string()))?; } *entry += 1; } @@ -213,15 +215,15 @@ impl FileSystemWatchPort { Ok(()) } - fn remove_source_inner(&self, source: &WatchSource) -> Result<(), ApplicationError> { + fn remove_source_inner(&self, source: &WatchSource) -> Result<(), ServerRouteError> { let mut watcher_guard = self .watcher .lock() - .map_err(|_| ApplicationError::Internal("watcher lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watcher lock poisoned"))?; let mut registry = self .registry .lock() - .map_err(|_| ApplicationError::Internal("watch registry lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watch registry lock poisoned"))?; let Some(targets) = registry.source_targets.remove(source) else { return Ok(()); }; @@ -240,7 +242,7 @@ impl FileSystemWatchPort { registry.watched_targets.remove(&key); watcher .unwatch(&target.path) - .map_err(|error| ApplicationError::Internal(error.to_string()))?; + .map_err(|error| ServerRouteError::internal(error.to_string()))?; } } Ok(()) @@ -251,8 +253,8 @@ impl WatchPort for FileSystemWatchPort { fn start_watch( &self, sources: Vec, - tx: broadcast::Sender, - ) -> Result<(), ApplicationError> { + tx: broadcast::Sender, + ) -> Result<(), ServerRouteError> { self.ensure_watcher(tx)?; for source in sources { self.add_source_inner(source)?; @@ -260,33 +262,33 @@ impl WatchPort for FileSystemWatchPort { Ok(()) } - fn stop_all(&self) -> Result<(), ApplicationError> { + fn stop_all(&self) -> Result<(), ServerRouteError> { let mut watcher_guard = self .watcher .lock() - .map_err(|_| ApplicationError::Internal("watcher lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watcher lock poisoned"))?; *watcher_guard = None; let mut registry = self .registry .lock() - .map_err(|_| ApplicationError::Internal("watch registry lock poisoned".to_string()))?; + .map_err(|_| ServerRouteError::internal("watch registry lock poisoned"))?; registry.source_targets.clear(); registry.watched_targets.clear(); Ok(()) } - fn add_source(&self, source: WatchSource) -> Result<(), ApplicationError> { + fn add_source(&self, source: WatchSource) -> Result<(), ServerRouteError> { self.add_source_inner(source) } - fn remove_source(&self, source: &WatchSource) -> Result<(), ApplicationError> { + fn remove_source(&self, source: &WatchSource) -> Result<(), ServerRouteError> { self.remove_source_inner(source) } } fn dispatch_watch_event( registry: &Arc>, - tx: &broadcast::Sender, + tx: &broadcast::Sender, event: Event, ) { let registry = match registry.lock() { @@ -310,7 +312,7 @@ fn dispatch_watch_event( if affected_paths.is_empty() { continue; } - let _ = tx.send(astrcode_application::WatchEvent { + let _ = tx.send(WatchEvent { source: source.clone(), affected_paths, }); diff --git a/crates/server/src/capability_router.rs b/crates/server/src/capability_router.rs new file mode 100644 index 00000000..bc621667 --- /dev/null +++ b/crates/server/src/capability_router.rs @@ -0,0 +1,201 @@ +//! server 私有的 capability router。 +//! +//! Why: `6.5.5b` 需要删除 `server -> astrcode-kernel` 的正式依赖， +//! 运行时端口仍需要一份最小的 in-memory router 来承接 turn 执行和测试夹具。 +//! 这里把仍被使用的最小路由逻辑收敛到 server，避免继续把整个 +//! `astrcode-kernel` crate 留在活跃依赖图里。 + +use std::{ + collections::HashMap, + sync::{Arc, RwLock}, +}; + +use astrcode_core::{ + AstrError, CapabilityInvoker, CapabilitySpec, Result, ToolCallRequest, ToolContext, + ToolExecutionResult, support, +}; + +fn validate_capability_spec(capability_spec: &CapabilitySpec) -> Result<()> { + capability_spec.validate().map_err(|error| { + AstrError::Validation(format!( + "invalid capability spec '{}': {}", + capability_spec.name, error + )) + }) +} + +fn build_registry_snapshot( + invokers: impl IntoIterator>, +) -> Result { + let mut invokers_by_name = HashMap::new(); + let mut order = Vec::new(); + + for invoker in invokers { + let capability_spec = invoker.capability_spec(); + validate_capability_spec(&capability_spec)?; + if invokers_by_name + .insert(capability_spec.name.to_string(), Arc::clone(&invoker)) + .is_some() + { + return Err(AstrError::Validation(format!( + "duplicate capability '{}' registered", + capability_spec.name + ))); + } + order.push(capability_spec.name.to_string()); + } + + Ok(CapabilityRouterInner { + invokers_by_name, + order, + }) +} + +pub(crate) struct CapabilityRouterBuilder { + invokers: Vec>, +} + +impl Default for CapabilityRouterBuilder { + fn default() -> Self { + Self::new() + } +} + +impl CapabilityRouterBuilder { + pub(crate) fn new() -> Self { + Self { + invokers: Vec::new(), + } + } + + #[allow(dead_code)] + pub(crate) fn register_invoker(mut self, invoker: Arc) -> Self { + self.invokers.push(invoker); + self + } + + pub(crate) fn build(self) -> Result { + let snapshot = build_registry_snapshot(self.invokers)?; + Ok(CapabilityRouter { + inner: Arc::new(RwLock::new(snapshot)), + }) + } +} + +struct CapabilityRouterInner { + invokers_by_name: HashMap>, + order: Vec, +} + +#[derive(Clone)] +pub(crate) struct CapabilityRouter { + inner: Arc>, +} + +impl Default for CapabilityRouter { + fn default() -> Self { + Self::empty() + } +} + +impl CapabilityRouter { + pub(crate) fn builder() -> CapabilityRouterBuilder { + CapabilityRouterBuilder::new() + } + + pub(crate) fn empty() -> Self { + Self { + inner: Arc::new(RwLock::new(CapabilityRouterInner { + invokers_by_name: HashMap::new(), + order: Vec::new(), + })), + } + } + + pub(crate) fn replace_invokers(&self, invokers: Vec>) -> Result<()> { + let snapshot = build_registry_snapshot(invokers)?; + support::with_write_lock_recovery(&self.inner, "capability_router", |inner| { + *inner = snapshot; + Ok(()) + }) + } + + pub(crate) fn capability_specs(&self) -> Vec { + support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { + inner + .order + .iter() + .filter_map(|name| inner.invokers_by_name.get(name)) + .map(|invoker| invoker.capability_spec()) + .collect() + }) + } + + pub(crate) fn capability_spec(&self, name: &str) -> Option { + support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { + inner + .invokers_by_name + .get(name) + .map(|invoker| invoker.capability_spec()) + }) + } + + pub(crate) async fn execute_tool( + &self, + call: &ToolCallRequest, + ctx: &ToolContext, + ) -> ToolExecutionResult { + let invoker = support::with_read_lock_recovery(&self.inner, "capability_router", |inner| { + inner.invokers_by_name.get(&call.name).cloned() + }); + + let Some(invoker) = invoker else { + return ToolExecutionResult { + tool_call_id: call.id.clone(), + tool_name: call.name.clone(), + ok: false, + output: String::new(), + error: Some(format!("unknown tool '{}'", call.name)), + metadata: None, + continuation: None, + duration_ms: 0, + truncated: false, + }; + }; + + let capability_spec = invoker.capability_spec(); + if !capability_spec.kind.is_tool() { + return ToolExecutionResult { + tool_call_id: call.id.clone(), + tool_name: call.name.clone(), + ok: false, + output: String::new(), + error: Some(format!("capability '{}' is not tool-callable", call.name)), + metadata: None, + continuation: None, + duration_ms: 0, + truncated: false, + }; + } + + let capability_ctx = crate::tool_capability_invoker::capability_context_from_tool_context( + ctx, + Some(call.id.clone()), + ); + + match invoker.invoke(call.args.clone(), &capability_ctx).await { + Ok(result) => result.into_tool_execution_result(call.id.clone()), + Err(error) => ToolExecutionResult { + tool_call_id: call.id.clone(), + tool_name: call.name.clone(), + ok: false, + output: String::new(), + error: Some(error.to_string()), + metadata: None, + continuation: None, + duration_ms: 0, + truncated: false, + }, + } + } +} diff --git a/crates/application/src/config/api_key.rs b/crates/server/src/config/api_key.rs similarity index 100% rename from crates/application/src/config/api_key.rs rename to crates/server/src/config/api_key.rs diff --git a/crates/application/src/config/constants.rs b/crates/server/src/config/constants.rs similarity index 88% rename from crates/application/src/config/constants.rs rename to crates/server/src/config/constants.rs index 042a2f0d..e69489ea 100644 --- a/crates/application/src/config/constants.rs +++ b/crates/server/src/config/constants.rs @@ -12,8 +12,7 @@ //! //! `resolve_*_api_url` 系列函数处理 Provider 地址的多种写法（根地址、版本根、完整集合地址）， //! 确保运行时始终拿到可直接发请求的完整 URL。 - -pub use astrcode_core::config::DEFAULT_MAX_SUBRUN_DEPTH; +#![allow(dead_code)] // ============================================================ // Provider 标识符 @@ -45,9 +44,8 @@ pub const LITERAL_VALUE_PREFIX: &str = "literal:"; pub use astrcode_core::env::{ ASTRCODE_HOME_DIR_ENV, ASTRCODE_MAX_TOOL_CONCURRENCY_ENV, ASTRCODE_PLUGIN_DIRS_ENV, - ASTRCODE_TEST_HOME_ENV, ASTRCODE_TOOL_INLINE_LIMIT_PREFIX, - ASTRCODE_TOOL_RESULT_INLINE_LIMIT_ENV, DEEPSEEK_API_KEY_ENV, OPENAI_API_KEY_ENV, - TAURI_ENV_TARGET_TRIPLE_ENV, + ASTRCODE_TEST_HOME_ENV, ASTRCODE_TOOL_RESULT_INLINE_LIMIT_ENV, DEEPSEEK_API_KEY_ENV, + OPENAI_API_KEY_ENV, TAURI_ENV_TARGET_TRIPLE_ENV, }; /// 影响 Astrcode 本地存储路径的环境变量。 @@ -106,23 +104,6 @@ pub const DEFAULT_OPENAI_CONTEXT_LIMIT: usize = 128_000; /// 加载配置时空白的 version 字段会被迁移到此值，不支持的版本号会导致加载失败。 pub const CURRENT_CONFIG_VERSION: &str = "1"; -pub use astrcode_core::config::{ - DEFAULT_AGGREGATE_RESULT_BYTES_BUDGET, DEFAULT_API_SESSION_TTL_HOURS, - DEFAULT_AUTO_COMPACT_ENABLED, DEFAULT_COMPACT_KEEP_RECENT_TURNS, - DEFAULT_COMPACT_THRESHOLD_PERCENT, DEFAULT_FINALIZED_AGENT_RETAIN_LIMIT, - DEFAULT_INBOX_CAPACITY, DEFAULT_LLM_CONNECT_TIMEOUT_SECS, DEFAULT_LLM_MAX_RETRIES, - DEFAULT_LLM_READ_TIMEOUT_SECS, DEFAULT_LLM_RETRY_BASE_DELAY_MS, DEFAULT_MAX_CONCURRENT_AGENTS, - DEFAULT_MAX_CONCURRENT_BRANCH_DEPTH, DEFAULT_MAX_CONSECUTIVE_FAILURES, DEFAULT_MAX_GREP_LINES, - DEFAULT_MAX_IMAGE_SIZE, DEFAULT_MAX_REACTIVE_COMPACT_ATTEMPTS, DEFAULT_MAX_RECOVERED_FILES, - DEFAULT_MAX_TOOL_CONCURRENCY, DEFAULT_MAX_TRACKED_FILES, - DEFAULT_MICRO_COMPACT_GAP_THRESHOLD_SECS, DEFAULT_MICRO_COMPACT_KEEP_RECENT_RESULTS, - DEFAULT_PARENT_DELIVERY_CAPACITY, DEFAULT_RECOVERY_TOKEN_BUDGET, - DEFAULT_RECOVERY_TRUNCATE_BYTES, DEFAULT_RESERVED_CONTEXT_SIZE, - DEFAULT_SESSION_BROADCAST_CAPACITY, DEFAULT_SESSION_RECENT_RECORD_LIMIT, - DEFAULT_SUMMARY_RESERVE_TOKENS, DEFAULT_TOOL_RESULT_INLINE_LIMIT, - DEFAULT_TOOL_RESULT_MAX_BYTES, DEFAULT_TOOL_RESULT_PREVIEW_LIMIT, -}; - // ============================================================ // URL 标准化辅助函数 // ============================================================ diff --git a/crates/application/src/config/env_resolver.rs b/crates/server/src/config/env_resolver.rs similarity index 99% rename from crates/application/src/config/env_resolver.rs rename to crates/server/src/config/env_resolver.rs index 1ef7999f..84b0b221 100644 --- a/crates/application/src/config/env_resolver.rs +++ b/crates/server/src/config/env_resolver.rs @@ -75,6 +75,7 @@ pub fn resolve_env_value(raw: &str) -> Result { } /// 构建序列化的 `env:` 引用字符串。 +#[allow(dead_code)] pub fn env_reference(env_name: &str) -> String { format!("{ENV_REFERENCE_PREFIX}{env_name}") } diff --git a/crates/application/src/config/mcp.rs b/crates/server/src/config/mcp.rs similarity index 100% rename from crates/application/src/config/mcp.rs rename to crates/server/src/config/mcp.rs diff --git a/crates/application/src/config/mod.rs b/crates/server/src/config/mod.rs similarity index 85% rename from crates/application/src/config/mod.rs rename to crates/server/src/config/mod.rs index eaf8bfb5..97f3b4e5 100644 --- a/crates/application/src/config/mod.rs +++ b/crates/server/src/config/mod.rs @@ -10,8 +10,10 @@ //! - `selection`: Profile/Model 选择与回退逻辑 //! - `validation`: 配置规范化与验证 +#[cfg(test)] pub mod api_key; pub mod constants; +#[cfg(test)] pub mod env_resolver; pub mod mcp; pub mod selection; @@ -24,38 +26,11 @@ use std::{ sync::Arc, }; -use astrcode_core::{Config, ConfigOverlay, TestConnectionResult}; -pub use astrcode_core::{ - config::{ - DEFAULT_API_SESSION_TTL_HOURS, DEFAULT_AUTO_COMPACT_ENABLED, - DEFAULT_COMPACT_KEEP_RECENT_TURNS, DEFAULT_COMPACT_THRESHOLD_PERCENT, - DEFAULT_FINALIZED_AGENT_RETAIN_LIMIT, DEFAULT_INBOX_CAPACITY, - DEFAULT_LLM_CONNECT_TIMEOUT_SECS, DEFAULT_LLM_MAX_RETRIES, DEFAULT_LLM_READ_TIMEOUT_SECS, - DEFAULT_LLM_RETRY_BASE_DELAY_MS, DEFAULT_MAX_CONCURRENT_AGENTS, - DEFAULT_MAX_CONCURRENT_BRANCH_DEPTH, DEFAULT_MAX_CONSECUTIVE_FAILURES, - DEFAULT_MAX_GREP_LINES, DEFAULT_MAX_IMAGE_SIZE, DEFAULT_MAX_REACTIVE_COMPACT_ATTEMPTS, - DEFAULT_MAX_RECOVERED_FILES, DEFAULT_MAX_SPAWN_PER_TURN, DEFAULT_MAX_SUBRUN_DEPTH, - DEFAULT_MAX_TOOL_CONCURRENCY, DEFAULT_MAX_TRACKED_FILES, DEFAULT_PARENT_DELIVERY_CAPACITY, - DEFAULT_RECOVERY_TOKEN_BUDGET, DEFAULT_RECOVERY_TRUNCATE_BYTES, - DEFAULT_RESERVED_CONTEXT_SIZE, DEFAULT_SESSION_BROADCAST_CAPACITY, - DEFAULT_SESSION_RECENT_RECORD_LIMIT, DEFAULT_SUMMARY_RESERVE_TOKENS, - DEFAULT_TOOL_RESULT_INLINE_LIMIT, DEFAULT_TOOL_RESULT_MAX_BYTES, - DEFAULT_TOOL_RESULT_PREVIEW_LIMIT, ResolvedAgentConfig, ResolvedRuntimeConfig, - max_tool_concurrency, resolve_agent_config, resolve_runtime_config, - }, +use astrcode_core::{ + Config, ConfigOverlay, TestConnectionResult, + config::{ResolvedRuntimeConfig, resolve_runtime_config}, ports::{ConfigStore, McpConfigFileScope}, }; -pub use constants::{ - ALL_ASTRCODE_ENV_VARS, ASTRCODE_HOME_DIR_ENV, ASTRCODE_MAX_TOOL_CONCURRENCY_ENV, - ASTRCODE_PLUGIN_DIRS_ENV, ASTRCODE_TEST_HOME_ENV, ASTRCODE_TOOL_INLINE_LIMIT_PREFIX, - ASTRCODE_TOOL_RESULT_INLINE_LIMIT_ENV, BUILD_ENV_VARS, CURRENT_CONFIG_VERSION, - DEEPSEEK_API_KEY_ENV, DEFAULT_OPENAI_CONTEXT_LIMIT, ENV_REFERENCE_PREFIX, HOME_ENV_VARS, - LITERAL_VALUE_PREFIX, OPENAI_API_KEY_ENV, OPENAI_CHAT_COMPLETIONS_API_URL, - OPENAI_RESPONSES_API_URL, PLUGIN_ENV_VARS, PROVIDER_API_KEY_ENV_VARS, PROVIDER_KIND_OPENAI, - RUNTIME_ENV_VARS, TAURI_ENV_TARGET_TRIPLE_ENV, resolve_openai_chat_completions_api_url, - resolve_openai_responses_api_url, -}; -pub use selection::{list_model_options, resolve_active_selection, resolve_current_model}; use tokio::sync::RwLock; use crate::ApplicationError; @@ -67,6 +42,7 @@ pub struct ConfigService { } /// 单个 profile 的摘要输入。 +#[cfg(test)] #[derive(Debug, Clone, PartialEq, Eq)] pub struct ConfigProfileSummary { pub name: String, @@ -79,6 +55,7 @@ pub struct ConfigProfileSummary { /// /// 这是 protocol `ConfigView` 的共享 projection input， /// server 只需要补上 `config_path` 和协议外层壳。 +#[cfg(test)] #[derive(Debug, Clone, PartialEq, Eq)] pub struct ResolvedConfigSummary { pub active_profile: String, @@ -191,6 +168,8 @@ impl ConfigService { } /// 解析指定 profile 的 API key。 + #[cfg(test)] + #[allow(dead_code)] pub fn resolve_api_key_for_profile( &self, profile_name: &str, @@ -208,6 +187,7 @@ impl ConfigService { } /// 生成配置摘要输入，供协议层投影复用。 +#[cfg(test)] pub fn resolve_config_summary(config: &Config) -> Result { if config.profiles.is_empty() { return Ok(ResolvedConfigSummary { @@ -256,6 +236,7 @@ pub fn resolve_config_summary(config: &Config) -> Result 4 → 显示 "****" + 最后 4 个字符 /// - 其他 → "****" +#[cfg(test)] pub fn api_key_preview(api_key: Option<&str>) -> String { match api_key.map(str::trim) { None | Some("") => "未配置".to_string(), @@ -278,6 +259,7 @@ pub fn api_key_preview(api_key: Option<&str>) -> String { } } +#[cfg(test)] fn masked_key_preview(value: &str) -> String { let char_starts: Vec = value.char_indices().map(|(index, _)| index).collect(); @@ -306,13 +288,19 @@ fn apply_overlay(mut base: Config, overlay: ConfigOverlay) -> Config { base } +#[cfg(test)] pub fn is_env_var_name(value: &str) -> bool { env_resolver::is_env_var_name(value) } #[cfg(test)] mod tests { - use astrcode_core::{ModelConfig, Profile}; + use astrcode_core::{ + ModelConfig, Profile, + config::{ + DEFAULT_MAX_SPAWN_PER_TURN, DEFAULT_MAX_SUBRUN_DEPTH, DEFAULT_TOOL_RESULT_INLINE_LIMIT, + }, + }; use super::*; use crate::config::test_support::TestConfigStore; diff --git a/crates/application/src/config/selection.rs b/crates/server/src/config/selection.rs similarity index 97% rename from crates/application/src/config/selection.rs rename to crates/server/src/config/selection.rs index d907a64f..a6219539 100644 --- a/crates/application/src/config/selection.rs +++ b/crates/server/src/config/selection.rs @@ -6,10 +6,9 @@ //! - active_model 不在 profile 中 → 回退到 profile 的第一个 model //! - profile 无 model → 返回错误 -use astrcode_core::{ - ActiveSelection, Config, CurrentModelSelection, ModelConfig, ModelOption, ModelSelection, - Profile, -}; +use astrcode_core::{ActiveSelection, Profile}; +#[cfg(test)] +use astrcode_core::{Config, CurrentModelSelection, ModelConfig, ModelOption, ModelSelection}; use crate::ApplicationError; @@ -62,6 +61,7 @@ pub fn resolve_active_selection( } /// 获取当前生效的模型信息。 +#[cfg(test)] pub fn resolve_current_model(config: &Config) -> Result { let selected = resolve_active_selection( &config.active_profile, @@ -88,6 +88,8 @@ pub fn resolve_current_model(config: &Config) -> Result( profile: &'a Profile, active_model: &str, @@ -143,6 +145,7 @@ fn active_selection( } /// 列出所有可用的模型选项。 +#[cfg(test)] pub fn list_model_options(config: &Config) -> Vec { config .profiles diff --git a/crates/application/src/config/test_support.rs b/crates/server/src/config/test_support.rs similarity index 100% rename from crates/application/src/config/test_support.rs rename to crates/server/src/config/test_support.rs diff --git a/crates/application/src/config/validation.rs b/crates/server/src/config/validation.rs similarity index 86% rename from crates/application/src/config/validation.rs rename to crates/server/src/config/validation.rs index 0faf8614..10e987eb 100644 --- a/crates/application/src/config/validation.rs +++ b/crates/server/src/config/validation.rs @@ -80,6 +80,7 @@ fn validate_runtime_params(runtime: &astrcode_core::RuntimeConfig) -> Result<()> runtime.aggregate_result_bytes_budget => "runtime.aggregateResultBytesBudget", runtime.micro_compact_keep_recent_results => "runtime.microCompactKeepRecentResults", runtime.max_consecutive_failures => "runtime.maxConsecutiveFailures", + runtime.max_output_continuation_attempts => "runtime.maxOutputContinuationAttempts", runtime.recovery_truncate_bytes => "runtime.recoveryTruncateBytes", runtime.reserved_context_size => "runtime.reservedContextSize", )?; @@ -164,38 +165,35 @@ fn validate_profiles(profiles: &[astrcode_core::Profile]) -> Result<()> { validate_model(profile.name.as_str(), model, &mut seen_model_ids)?; } - match profile.provider_kind.as_str() { - PROVIDER_KIND_OPENAI => { - if profile.base_url.trim().is_empty() { - return Err(AstrError::Validation(format!( - "profile '{}' base_url cannot be empty", - profile.name - ))); - } - for model in &profile.models { - if model.max_tokens.is_none() || model.context_limit.is_none() { - return Err(AstrError::Validation(format!( - "openai profile '{}' model '{}' must set both maxTokens and \ - contextLimit", - profile.name, model.id - ))); - } - } - if matches!(profile.api_mode, Some(OpenAiApiMode::Responses)) - && profile.base_url.trim().is_empty() - { + if profile.provider_kind.trim().is_empty() { + return Err(AstrError::Validation(format!( + "profile '{}' provider_kind cannot be empty", + profile.name + ))); + } + if profile.base_url.trim().is_empty() { + return Err(AstrError::Validation(format!( + "profile '{}' base_url cannot be empty", + profile.name + ))); + } + if profile.provider_kind == PROVIDER_KIND_OPENAI { + for model in &profile.models { + if model.max_tokens.is_none() || model.context_limit.is_none() { return Err(AstrError::Validation(format!( - "openai profile '{}' responses mode requires a non-empty baseUrl", - profile.name, + "openai profile '{}' model '{}' must set both maxTokens and contextLimit", + profile.name, model.id ))); } - }, - other => { + } + if matches!(profile.api_mode, Some(OpenAiApiMode::Responses)) + && profile.base_url.trim().is_empty() + { return Err(AstrError::Validation(format!( - "profile '{}' has unsupported provider_kind '{}'", - profile.name, other + "openai profile '{}' responses mode requires a non-empty baseUrl", + profile.name, ))); - }, + } } } Ok(()) @@ -276,6 +274,24 @@ mod tests { assert!(validate_config(&config).is_ok()); } + #[test] + fn custom_provider_kind_passes_schema_validation() { + let config = Config { + active_profile: "corp".to_string(), + active_model: "corp-model".to_string(), + profiles: vec![astrcode_core::Profile { + name: "corp".to_string(), + provider_kind: "corp-openai".to_string(), + base_url: "https://api.example.test".to_string(), + models: vec![ModelConfig::new("corp-model")], + ..astrcode_core::Profile::default() + }], + ..Config::default() + }; + + assert!(validate_config(&config).is_ok()); + } + #[test] fn duplicate_profile_name_fails() { let mut config = Config::default(); diff --git a/crates/server/src/config_mode_helpers.rs b/crates/server/src/config_mode_helpers.rs new file mode 100644 index 00000000..8cdc0c9f --- /dev/null +++ b/crates/server/src/config_mode_helpers.rs @@ -0,0 +1,306 @@ +use astrcode_core::{ + ActiveSelection, AstrError, Config, CurrentModelSelection, ModelOption, ModelSelection, + Profile, Result, +}; + +pub(crate) const PROVIDER_KIND_OPENAI: &str = "openai"; +const OPENAI_CHAT_COMPLETIONS_API_URL: &str = "https://api.openai.com/v1/chat/completions"; +const OPENAI_RESPONSES_API_URL: &str = "https://api.openai.com/v1/responses"; +const LITERAL_VALUE_PREFIX: &str = "literal:"; +const ENV_REFERENCE_PREFIX: &str = "env:"; + +pub(crate) fn resolve_current_model(config: &Config) -> Result { + let selected = resolve_active_selection( + &config.active_profile, + &config.active_model, + &config.profiles, + )?; + + let profile = config + .profiles + .iter() + .find(|profile| profile.name == selected.active_profile) + .ok_or_else(|| { + AstrError::Validation(format!( + "active profile '{}' not found", + selected.active_profile + )) + })?; + + Ok(ModelSelection::new( + selected.active_profile, + selected.active_model, + profile.provider_kind.clone(), + )) +} + +pub(crate) fn list_model_options(config: &Config) -> Vec { + config + .profiles + .iter() + .flat_map(|profile| { + profile.models.iter().map(|model| { + ModelSelection::new( + profile.name.clone(), + model.id.clone(), + profile.provider_kind.clone(), + ) + }) + }) + .collect() +} + +pub(crate) fn is_env_var_name(value: &str) -> bool { + value + .chars() + .all(|ch| ch.is_ascii_uppercase() || ch.is_ascii_digit() || ch == '_') + && value.contains('_') +} + +pub(crate) fn resolve_api_key(profile: &Profile) -> Result { + let value = match &profile.api_key { + None => { + return Err(AstrError::MissingApiKey(format!( + "profile '{}' 未配置 apiKey", + profile.name + ))); + }, + Some(value) => value.trim().to_string(), + }; + + if value.is_empty() { + return Err(AstrError::MissingApiKey(format!( + "profile '{}' 的 apiKey 不能为空", + profile.name + ))); + } + + let resolved = resolve_env_value(&value).map_err(|error| match error { + AstrError::Validation(message) => { + AstrError::Validation(format!("profile '{}' 的 apiKey {}", profile.name, message)) + }, + other => other, + })?; + + if resolved.is_empty() { + return Err(AstrError::MissingApiKey(format!( + "profile '{}' 的 apiKey 解析后为空", + profile.name + ))); + } + + Ok(resolved) +} + +pub(crate) fn resolve_openai_chat_completions_api_url(base_url: &str) -> String { + let (path, query) = split_url_query(base_url.trim()); + let trimmed = path.trim_end_matches('/'); + if trimmed.is_empty() { + return OPENAI_CHAT_COMPLETIONS_API_URL.to_string(); + } + + let normalized = if trimmed.ends_with("/chat/completions") { + trimmed.to_string() + } else if let Some(replaced) = replace_openai_collection_tail(trimmed, "chat/completions") { + replaced + } else if let Some(versioned_url) = + normalize_openai_versioned_base_url(trimmed, "chat/completions") + { + versioned_url + } else { + format!("{trimmed}/v1/chat/completions") + }; + + join_url_query(normalized, query) +} + +pub(crate) fn resolve_openai_responses_api_url(base_url: &str) -> String { + let (path, query) = split_url_query(base_url.trim()); + let trimmed = path.trim_end_matches('/'); + if trimmed.is_empty() { + return OPENAI_RESPONSES_API_URL.to_string(); + } + + let normalized = if trimmed.ends_with("/responses") { + trimmed.to_string() + } else if let Some(replaced) = replace_openai_collection_tail(trimmed, "responses") { + replaced + } else if let Some(versioned_url) = normalize_openai_versioned_base_url(trimmed, "responses") { + versioned_url + } else { + format!("{trimmed}/v1/responses") + }; + + join_url_query(normalized, query) +} + +pub(crate) fn resolve_active_selection( + active_profile: &str, + active_model: &str, + profiles: &[Profile], +) -> Result { + if profiles.is_empty() { + return Err(AstrError::Validation("no profiles configured".to_string())); + } + + let selected_profile = profiles + .iter() + .find(|profile| profile.name == active_profile) + .unwrap_or(&profiles[0]); + + if selected_profile.name != active_profile { + return fallback_selection( + selected_profile, + format!( + "配置中的 Profile 不存在，已自动选择 {}", + selected_profile.name + ), + ); + } + + if let Some(model) = selected_profile + .models + .iter() + .find(|model| model.id == active_model) + { + return Ok(active_selection(selected_profile, model.id.clone(), None)); + } + + let fallback_model = first_model_id(selected_profile)?.to_string(); + Ok(active_selection( + selected_profile, + fallback_model.clone(), + Some(format!( + "配置中的 {} 在当前 Profile 下不存在，已自动选择 {}", + active_model, fallback_model + )), + )) +} + +fn first_model_id(profile: &Profile) -> Result<&str> { + profile + .models + .first() + .map(|model| model.id.as_str()) + .ok_or_else(|| { + AstrError::Validation(format!( + "profile '{}' has no models configured", + profile.name + )) + }) +} + +fn fallback_selection(profile: &Profile, warning: String) -> Result { + Ok(active_selection( + profile, + first_model_id(profile)?.to_string(), + Some(warning), + )) +} + +fn active_selection( + profile: &Profile, + active_model: String, + warning: Option, +) -> ActiveSelection { + ActiveSelection { + active_profile: profile.name.clone(), + active_model, + warning, + } +} + +fn resolve_env_value(raw: &str) -> Result { + match parse_env_value(raw)? { + ParsedEnvValue::Literal(value) => Ok(value.to_string()), + ParsedEnvValue::ExplicitEnv(env_name) => std::env::var(env_name).map_err(|_| { + AstrError::EnvVarNotFound(format!( + "环境变量 {} 未设置。\n解决方案：\n1. \ + 在系统属性中设置用户环境变量（需重启应用）\n2. 或在配置文件中使用 \ + literal:YOUR_API_KEY 直接指定", + env_name + )) + }), + ParsedEnvValue::OptionalEnv(env_name) => { + Ok(std::env::var(env_name).unwrap_or_else(|_| env_name.to_string())) + }, + } +} + +fn parse_env_value(raw: &str) -> Result> { + let trimmed = raw.trim(); + + if let Some(literal) = trimmed.strip_prefix(LITERAL_VALUE_PREFIX) { + return Ok(ParsedEnvValue::Literal(literal.trim())); + } + + if let Some(env_name) = trimmed.strip_prefix(ENV_REFERENCE_PREFIX) { + let env_name = env_name.trim(); + if !is_env_var_name(env_name) { + return Err(AstrError::Validation(format!( + "env 引用 '{}' 非法", + env_name + ))); + } + return Ok(ParsedEnvValue::ExplicitEnv(env_name)); + } + + if is_env_var_name(trimmed) { + return Ok(ParsedEnvValue::OptionalEnv(trimmed)); + } + + Ok(ParsedEnvValue::Literal(trimmed)) +} + +fn looks_like_api_version_segment(segment: &str) -> bool { + let mut chars = segment.chars(); + matches!(chars.next(), Some('v' | 'V')) + && matches!(chars.next(), Some(ch) if ch.is_ascii_digit()) + && chars.all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '_' | '-')) +} + +fn normalize_openai_versioned_base_url(trimmed: &str, collection_suffix: &str) -> Option { + let segments = trimmed.split('/').collect::>(); + let version_index = segments + .iter() + .rposition(|segment| looks_like_api_version_segment(segment))?; + let prefix = segments[..=version_index].join("/"); + Some(format!("{prefix}/{collection_suffix}")) +} + +fn split_url_query(url: &str) -> (&str, Option<&str>) { + match url.split_once('?') { + Some((path, query)) => (path, Some(query)), + None => (url, None), + } +} + +fn join_url_query(path: String, query: Option<&str>) -> String { + match query { + Some(query) if !query.is_empty() => format!("{path}?{query}"), + _ => path, + } +} + +fn replace_openai_collection_tail(trimmed: &str, collection_suffix: &str) -> Option { + const KNOWN_SUFFIXES: &[&str] = &[ + "/chat/completions", + "/chat/completion", + "/chat", + "/responses", + "/response", + ]; + + KNOWN_SUFFIXES.iter().find_map(|suffix| { + trimmed + .strip_suffix(suffix) + .map(|prefix| format!("{prefix}/{collection_suffix}")) + }) +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum ParsedEnvValue<'a> { + Literal(&'a str), + ExplicitEnv(&'a str), + OptionalEnv(&'a str), +} diff --git a/crates/server/src/config_service_bridge.rs b/crates/server/src/config_service_bridge.rs new file mode 100644 index 00000000..85851410 --- /dev/null +++ b/crates/server/src/config_service_bridge.rs @@ -0,0 +1,175 @@ +use std::{ + path::{Path, PathBuf}, + sync::Arc, +}; + +use astrcode_core::{ + Config, ConfigOverlay, ResolvedRuntimeConfig, TestConnectionResult, ports::McpConfigFileScope, +}; +use serde_json::Value; + +use crate::{ + ApplicationError, McpConfigScope, RegisterMcpServerInput, + application_error_bridge::ServerRouteError, + config::ConfigService, + mcp_service::{ServerMcpConfigScope, ServerRegisterMcpServerInput}, +}; + +#[derive(Clone)] +pub(crate) struct ServerConfigService { + inner: Arc, +} + +impl ServerConfigService { + pub(crate) fn new(inner: Arc) -> Self { + Self { inner } + } + + pub(crate) fn inner(&self) -> &Arc { + &self.inner + } + + pub(crate) async fn get_config(&self) -> Config { + self.inner.get_config().await + } + + pub(crate) fn config_path(&self) -> PathBuf { + self.inner.config_path() + } + + pub(crate) fn load_overlay( + &self, + working_dir: &Path, + ) -> Result, ServerRouteError> { + self.inner + .load_overlay(working_dir) + .map_err(application_error_to_server) + } + + pub(crate) fn load_overlayed_config( + &self, + working_dir: Option<&Path>, + ) -> Result { + self.inner + .load_overlayed_config(working_dir) + .map_err(application_error_to_server) + } + + pub(crate) fn load_resolved_runtime_config( + &self, + working_dir: Option<&Path>, + ) -> Result { + self.inner + .load_resolved_runtime_config(working_dir) + .map_err(application_error_to_server) + } + + pub(crate) fn load_mcp( + &self, + scope: McpConfigFileScope, + working_dir: Option<&Path>, + ) -> Result, ServerRouteError> { + self.inner + .load_mcp(scope, working_dir) + .map_err(application_error_to_server) + } + + pub(crate) async fn reload_from_disk(&self) -> Result { + self.inner + .reload_from_disk() + .await + .map_err(application_error_to_server) + } + + pub(crate) async fn save_active_selection( + &self, + active_profile: String, + active_model: String, + ) -> Result<(), ServerRouteError> { + self.inner + .save_active_selection(active_profile, active_model) + .await + .map_err(application_error_to_server) + } + + pub(crate) async fn test_connection( + &self, + profile_name: &str, + model: &str, + ) -> Result { + self.inner + .test_connection(profile_name, model) + .await + .map_err(application_error_to_server) + } + + pub(crate) async fn upsert_mcp_server( + &self, + working_dir: &Path, + input: &ServerRegisterMcpServerInput, + ) -> Result<(), ServerRouteError> { + self.inner + .upsert_mcp_server( + working_dir, + &RegisterMcpServerInput { + name: input.name.clone(), + scope: server_scope_to_application(input.scope), + enabled: input.enabled, + timeout_secs: input.timeout_secs, + init_timeout_secs: input.init_timeout_secs, + max_reconnect_attempts: input.max_reconnect_attempts, + transport_config: input.transport_config.clone(), + }, + ) + .await + .map_err(application_error_to_server) + } + + pub(crate) async fn remove_mcp_server( + &self, + working_dir: &Path, + scope: ServerMcpConfigScope, + name: &str, + ) -> Result<(), ServerRouteError> { + self.inner + .remove_mcp_server(working_dir, server_scope_to_application(scope), name) + .await + .map_err(application_error_to_server) + } + + pub(crate) async fn set_mcp_server_enabled( + &self, + working_dir: &Path, + scope: ServerMcpConfigScope, + name: &str, + enabled: bool, + ) -> Result<(), ServerRouteError> { + self.inner + .set_mcp_server_enabled( + working_dir, + server_scope_to_application(scope), + name, + enabled, + ) + .await + .map_err(application_error_to_server) + } +} + +fn application_error_to_server(error: ApplicationError) -> ServerRouteError { + match error { + ApplicationError::NotFound(message) => ServerRouteError::NotFound(message), + ApplicationError::Conflict(message) => ServerRouteError::Conflict(message), + ApplicationError::InvalidArgument(message) => ServerRouteError::InvalidArgument(message), + ApplicationError::PermissionDenied(message) => ServerRouteError::PermissionDenied(message), + ApplicationError::Internal(message) => ServerRouteError::Internal(message), + } +} + +fn server_scope_to_application(scope: ServerMcpConfigScope) -> McpConfigScope { + match scope { + ServerMcpConfigScope::User => McpConfigScope::User, + ServerMcpConfigScope::Project => McpConfigScope::Project, + ServerMcpConfigScope::Local => McpConfigScope::Local, + } +} diff --git a/crates/session-runtime/src/query/conversation.rs b/crates/server/src/conversation_read_model.rs similarity index 61% rename from crates/session-runtime/src/query/conversation.rs rename to crates/server/src/conversation_read_model.rs index b40825bf..4724c52d 100644 --- a/crates/session-runtime/src/query/conversation.rs +++ b/crates/server/src/conversation_read_model.rs @@ -1,9 +1,10 @@ -//! authoritative conversation / tool display 读模型。 +//! server-owned conversation read-model bridge。 //! -//! Why: 工具展示的聚合语义属于单 session query 真相，不应该继续滞留在 -//! `server` route/projector 或前端 regroup 逻辑里。 +//! Why: route / terminal surface 不应直接暴露底层 conversation query DTO； +//! server 在这里收口正式 read-model surface。 +#![allow(dead_code)] -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use astrcode_core::{ AgentEvent, ChildAgentRef, ChildSessionNotification, ChildSessionNotificationKind, @@ -11,19 +12,48 @@ use astrcode_core::{ ToolExecutionResult, ToolOutputStream, }; use serde_json::Value; +use tokio::sync::broadcast; +#[path = "conversation_read_model/facts.rs"] mod facts; -#[path = "conversation/projection_support.rs"] -mod projection_support; +#[path = "conversation_read_model/plan_projection.rs"] +mod plan_projection; -pub use facts::*; -use projection_support::*; -pub(crate) use projection_support::{ - build_conversation_replay_frames, project_conversation_snapshot, -}; +pub(crate) use facts::*; + +pub(crate) const ROOT_AGENT_ID: &str = "root-agent"; + +#[derive(Debug)] +pub(crate) struct ConversationReplayStream { + pub receiver: broadcast::Receiver, + pub live_receiver: broadcast::Receiver, +} + +#[derive(Debug)] +pub(crate) struct SessionReplay { + pub history: Vec, + pub receiver: broadcast::Receiver, + pub live_receiver: broadcast::Receiver, +} + +#[derive(Debug, Clone)] +pub(crate) struct SessionTranscriptSnapshot { + pub records: Vec, + pub cursor: Option, + pub phase: Phase, +} + +#[derive(Debug)] +pub(crate) struct ConversationStreamReplayFacts { + pub cursor: Option, + pub phase: Phase, + pub seed_records: Vec, + pub replay_frames: Vec, + pub replay_history: Vec, +} #[derive(Default)] -pub struct ConversationDeltaProjector { +pub(crate) struct ConversationDeltaProjector { blocks: Vec, block_index: HashMap, turn_blocks: HashMap, @@ -31,7 +61,7 @@ pub struct ConversationDeltaProjector { } #[derive(Default)] -pub struct ConversationStreamProjector { +pub(crate) struct ConversationStreamProjector { projector: ConversationDeltaProjector, last_sent_cursor: Option, fallback_live_cursor: Option, @@ -192,26 +222,92 @@ fn turn_scoped_block_id(turn_id: &str, role: &str, ordinal: usize) -> String { } } +fn prompt_metrics_block_id(turn_id: Option<&str>, step_index: u32) -> String { + match turn_id { + Some(turn_id) => format!("turn:{turn_id}:prompt_metrics:{}", step_index + 1), + None => format!("session:prompt_metrics:{}", step_index + 1), + } +} + +fn should_suppress_tool_call_block(tool_name: &str, _input: Option<&Value>) -> bool { + matches!(tool_name, "upsertSessionPlan" | "exitPlanMode") +} + +fn summarize_inline_text(text: &str, max_chars: usize) -> Option { + let normalized = text.split_whitespace().collect::>().join(" "); + truncate_text(&normalized, max_chars) +} + +fn truncate_text(text: &str, max_chars: usize) -> Option { + let trimmed = text.trim(); + if trimmed.is_empty() { + return None; + } + + if trimmed.chars().count() <= max_chars { + return Some(trimmed.to_string()); + } + + Some(trimmed.chars().take(max_chars).collect::() + "...") +} + +fn tool_result_summary(result: &ToolExecutionResult) -> String { + const MAX_SUMMARY_CHARS: usize = 120; + + if result.ok { + if !result.output.trim().is_empty() { + summarize_inline_text(&result.output, MAX_SUMMARY_CHARS) + .unwrap_or_else(|| format!("{} completed", result.tool_name)) + } else { + format!("{} completed", result.tool_name) + } + } else if let Some(error) = &result.error { + summarize_inline_text(error, MAX_SUMMARY_CHARS) + .unwrap_or_else(|| format!("{} failed", result.tool_name)) + } else if !result.output.trim().is_empty() { + summarize_inline_text(&result.output, MAX_SUMMARY_CHARS) + .unwrap_or_else(|| format!("{} failed", result.tool_name)) + } else { + format!("{} failed", result.tool_name) + } +} + +fn classify_transcript_error(message: &str) -> ConversationTranscriptErrorKind { + let lower = message.to_lowercase(); + if lower.contains("context window") || lower.contains("token limit") { + ConversationTranscriptErrorKind::ContextWindowExceeded + } else if lower.contains("rate limit") { + ConversationTranscriptErrorKind::RateLimit + } else if lower.contains("tool") { + ConversationTranscriptErrorKind::ToolFatal + } else { + ConversationTranscriptErrorKind::ProviderError + } +} + impl ConversationDeltaProjector { - pub fn new() -> Self { + pub(crate) fn new() -> Self { Self::default() } - pub fn seed(&mut self, history: &[SessionEventRecord]) { + pub(crate) fn seed(&mut self, history: &[SessionEventRecord]) { for record in history { let _ = self.project_record(record); } } - pub fn blocks(&self) -> &[ConversationBlockFacts] { + pub(crate) fn blocks(&self) -> &[ConversationBlockFacts] { &self.blocks } - pub fn into_blocks(self) -> Vec { + pub(crate) fn into_blocks(self) -> Vec { self.blocks } - pub fn project_record(&mut self, record: &SessionEventRecord) -> Vec { + pub(crate) fn project_record( + &mut self, + record: &SessionEventRecord, + ) -> Vec { self.project_event( &record.event, ProjectionSource::Durable, @@ -219,7 +315,7 @@ impl ConversationDeltaProjector { ) } - pub fn project_live_event(&mut self, event: &AgentEvent) -> Vec { + pub(crate) fn project_live_event(&mut self, event: &AgentEvent) -> Vec { self.project_event(event, ProjectionSource::Live, None) } @@ -241,6 +337,9 @@ impl ConversationDeltaProjector { AgentEvent::ModelDelta { turn_id, delta, .. } => { self.append_markdown_streaming_block(turn_id, delta, BlockKind::Assistant) }, + AgentEvent::StreamRetryStarted { turn_id, .. } if source.is_live() => { + self.reset_live_markdown_blocks(turn_id) + }, AgentEvent::AssistantMessage { turn_id, content, @@ -293,12 +392,9 @@ impl ConversationDeltaProjector { AgentEvent::ToolCallResult { turn_id, result, .. } => { - if let Some(block) = plan_block_from_tool_result(turn_id, result) { + if let Some(block) = plan_projection::plan_block_from_tool_result(turn_id, result) { self.push_block(ConversationBlockFacts::Plan(Box::new(block))) } else if should_suppress_tool_call_block(&result.tool_name, None) { - // Why: plan-mode canonical tools own a dedicated plan surface. - // Letting failed retries fall back to generic tool cards leaks - // internal validation churn and produces conflicting UI. Vec::new() } else { self.complete_tool_call(turn_id, result, source) @@ -350,6 +446,7 @@ impl ConversationDeltaProjector { | AgentEvent::AgentInputDiscarded { .. } | AgentEvent::UserMessage { .. } | AgentEvent::AssistantMessage { .. } + | AgentEvent::StreamRetryStarted { .. } | AgentEvent::CompactApplied { .. } | AgentEvent::Error { .. } | AgentEvent::TurnDone { .. } => Vec::new(), @@ -385,7 +482,7 @@ impl ConversationDeltaProjector { .current_or_next_block_id(turn_id, kind); if let Some(index) = self.block_index.get(&block_id).copied() { self.append_markdown(index, delta); - return vec![ConversationDeltaFacts::PatchBlock { + return vec![ConversationDeltaFacts::Patch { block_id, patch: ConversationBlockPatchFacts::AppendMarkdown { markdown: delta.to_string(), @@ -415,6 +512,39 @@ impl ConversationDeltaProjector { self.push_block(block) } + fn reset_live_markdown_blocks(&mut self, turn_id: &str) -> Vec { + let block_ids = self + .turn_blocks + .get(turn_id) + .map(|refs| { + [ + refs.current_thinking.clone(), + refs.current_assistant.clone(), + ] + .into_iter() + .flatten() + .collect::>() + }) + .unwrap_or_default(); + let mut deltas = Vec::new(); + for block_id in block_ids { + let Some(index) = self.block_index.get(&block_id).copied() else { + continue; + }; + if self.block_markdown(index).is_empty() { + continue; + } + self.replace_markdown(index, ""); + deltas.push(ConversationDeltaFacts::Patch { + block_id, + patch: ConversationBlockPatchFacts::ReplaceMarkdown { + markdown: String::new(), + }, + }); + } + deltas + } + fn finalize_assistant_block( &mut self, turn_id: &str, @@ -480,14 +610,14 @@ impl ConversationDeltaProjector { if suffix.is_empty() { return Vec::new(); } - return vec![ConversationDeltaFacts::PatchBlock { + return vec![ConversationDeltaFacts::Patch { block_id: block_id.to_string(), patch: ConversationBlockPatchFacts::AppendMarkdown { markdown: suffix.to_string(), }, }]; } - return vec![ConversationDeltaFacts::PatchBlock { + return vec![ConversationDeltaFacts::Patch { block_id: block_id.to_string(), patch: ConversationBlockPatchFacts::ReplaceMarkdown { markdown: content.to_string(), @@ -530,7 +660,7 @@ impl ConversationDeltaProjector { return None; } block.step_index = step_index; - Some(ConversationDeltaFacts::AppendBlock { + Some(ConversationDeltaFacts::Append { block: Box::new(self.blocks[index].clone()), }) } @@ -634,7 +764,7 @@ impl ConversationDeltaProjector { return deltas; }; self.append_tool_stream_content(index, stream, &chunk); - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id, patch: ConversationBlockPatchFacts::AppendToolStream { stream, chunk }, }); @@ -674,7 +804,7 @@ impl ConversationDeltaProjector { if let Some(index) = self.block_index.get(&call_block_id).copied() { if self.replace_tool_summary(index, &summary) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::ReplaceSummary { summary: summary.clone(), @@ -682,7 +812,7 @@ impl ConversationDeltaProjector { }); } if self.replace_tool_error(index, result.error.as_deref()) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::ReplaceError { error: result.error.clone(), @@ -690,7 +820,7 @@ impl ConversationDeltaProjector { }); } if self.replace_tool_duration(index, result.duration_ms) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::ReplaceDuration { duration_ms: result.duration_ms, @@ -698,7 +828,7 @@ impl ConversationDeltaProjector { }); } if self.replace_tool_truncated(index, result.truncated) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::SetTruncated { truncated: result.truncated, @@ -707,7 +837,7 @@ impl ConversationDeltaProjector { } if let Some(metadata) = &result.metadata { if self.replace_tool_metadata(index, metadata) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::ReplaceMetadata { metadata: metadata.clone(), @@ -720,7 +850,7 @@ impl ConversationDeltaProjector { .and_then(astrcode_core::ExecutionContinuation::child_agent_ref) { if self.replace_tool_child_ref(index, child_ref) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id.clone(), patch: ConversationBlockPatchFacts::ReplaceChildRef { child_ref: child_ref.clone(), @@ -774,7 +904,7 @@ impl ConversationDeltaProjector { { if let Some(index) = self.block_index.get(&call_block_id).copied() { if self.replace_tool_child_ref(index, ¬ification.child_ref) { - deltas.push(ConversationDeltaFacts::PatchBlock { + deltas.push(ConversationDeltaFacts::Patch { block_id: call_block_id, patch: ConversationBlockPatchFacts::ReplaceChildRef { child_ref: notification.child_ref.clone(), @@ -878,7 +1008,7 @@ impl ConversationDeltaProjector { let id = block_id(&block).to_string(); self.block_index.insert(id, self.blocks.len()); self.blocks.push(block.clone()); - vec![ConversationDeltaFacts::AppendBlock { + vec![ConversationDeltaFacts::Append { block: Box::new(block), }] } @@ -890,7 +1020,7 @@ impl ConversationDeltaProjector { return Vec::new(); } self.blocks[index] = block.clone(); - return vec![ConversationDeltaFacts::AppendBlock { + return vec![ConversationDeltaFacts::Append { block: Box::new(block), }]; } @@ -907,7 +1037,7 @@ impl ConversationDeltaProjector { return None; } self.set_status(index, status); - return Some(ConversationDeltaFacts::CompleteBlock { + return Some(ConversationDeltaFacts::Complete { block_id: block_id.to_string(), status, }); @@ -1049,12 +1179,491 @@ impl ConversationDeltaProjector { } } -fn prompt_metrics_block_id(turn_id: Option<&str>, step_index: u32) -> String { - match turn_id { - Some(turn_id) => format!("turn:{turn_id}:prompt_metrics:{}", step_index + 1), - None => format!("session:prompt_metrics:{}", step_index + 1), +impl ConversationStreamProjector { + pub(crate) fn new( + last_sent_cursor: Option, + facts: &ConversationStreamReplayFacts, + ) -> Self { + let mut projector = ConversationDeltaProjector::new(); + projector.seed(&facts.seed_records); + let step_progress = durable_step_progress_from_blocks(projector.blocks()); + Self { + projector, + last_sent_cursor, + fallback_live_cursor: fallback_live_cursor(facts), + step_progress, + } + } + + pub(crate) fn last_sent_cursor(&self) -> Option<&str> { + self.last_sent_cursor.as_deref() + } + + pub(crate) fn step_progress(&self) -> &ConversationStepProgressFacts { + &self.step_progress + } + + pub(crate) fn seed_initial_replay( + &mut self, + facts: &ConversationStreamReplayFacts, + ) -> Vec { + let frames = facts.replay_frames.clone(); + self.observe_durable_frames(&frames); + frames + } + + pub(crate) fn project_durable_record( + &mut self, + record: &SessionEventRecord, + ) -> Vec { + let deltas = self.projector.project_record(record); + self.wrap_durable_deltas(record.event_id.as_str(), deltas) + } + + pub(crate) fn project_live_event( + &mut self, + event: &AgentEvent, + ) -> Vec { + self.observe_live_event_step(event); + let cursor = self.live_cursor(); + self.projector + .project_live_event(event) + .into_iter() + .map(|delta| ConversationDeltaFrameFacts { + cursor: cursor.clone(), + step_progress: self.step_progress.clone(), + delta, + }) + .collect() + } + + pub(crate) fn recover_from( + &mut self, + recovered: &ConversationStreamReplayFacts, + ) -> Vec { + self.fallback_live_cursor = fallback_live_cursor(recovered); + let mut frames = Vec::new(); + for record in &recovered.replay_history { + frames.extend(self.project_durable_record(record)); + } + frames + } + + fn wrap_durable_deltas( + &mut self, + cursor: &str, + deltas: Vec, + ) -> Vec { + if deltas.is_empty() { + return Vec::new(); + } + let cursor_owned = cursor.to_string(); + self.last_sent_cursor = Some(cursor_owned.clone()); + deltas + .into_iter() + .map(|delta| { + self.observe_durable_delta_step(&delta); + ConversationDeltaFrameFacts { + cursor: cursor_owned.clone(), + step_progress: self.step_progress.clone(), + delta, + } + }) + .collect() + } + + fn observe_durable_frames(&mut self, frames: &[ConversationDeltaFrameFacts]) { + if let Some(cursor) = frames.last().map(|frame| frame.cursor.clone()) { + self.last_sent_cursor = Some(cursor); + } + if let Some(step_progress) = frames.last().map(|frame| frame.step_progress.clone()) { + self.step_progress = step_progress; + } + } + + fn live_cursor(&self) -> String { + self.last_sent_cursor + .clone() + .or_else(|| self.fallback_live_cursor.clone()) + .unwrap_or_else(|| "0.0".to_string()) + } + + fn observe_durable_delta_step(&mut self, delta: &ConversationDeltaFacts) { + observe_durable_delta_step(&mut self.step_progress, delta); + } + + fn observe_live_event_step(&mut self, event: &AgentEvent) { + let turn_id = match event { + AgentEvent::ThinkingDelta { turn_id, .. } + | AgentEvent::ModelDelta { turn_id, .. } + | AgentEvent::StreamRetryStarted { turn_id, .. } + | AgentEvent::ToolCallStart { turn_id, .. } + | AgentEvent::ToolCallDelta { turn_id, .. } + | AgentEvent::ToolCallResult { turn_id, .. } => Some(turn_id.as_str()), + AgentEvent::TurnDone { turn_id, .. } => { + if self + .step_progress + .live + .as_ref() + .is_some_and(|cursor| cursor.turn_id == *turn_id) + { + self.step_progress.live = None; + } + None + }, + _ => None, + }; + let Some(turn_id) = turn_id else { + return; + }; + + let step_index = self + .step_progress + .durable + .as_ref() + .filter(|cursor| cursor.turn_id == turn_id) + .map(|cursor| cursor.step_index.saturating_add(1)) + .unwrap_or(0); + let next_live = ConversationStepCursorFacts { + turn_id: turn_id.to_string(), + step_index, + }; + if self.step_progress.durable.as_ref().is_some_and(|cursor| { + cursor.turn_id == next_live.turn_id && cursor.step_index >= next_live.step_index + }) { + return; + } + if self.step_progress.live.as_ref() == Some(&next_live) { + return; + } + self.step_progress.live = Some(next_live); + } +} + +pub(crate) fn project_conversation_snapshot( + records: &[SessionEventRecord], + phase: Phase, +) -> ConversationSnapshotFacts { + let mut projector = ConversationDeltaProjector::new(); + projector.seed(records); + let blocks = suppress_draft_approval_plan_leakage(projector.into_blocks()); + ConversationSnapshotFacts { + cursor: records.last().map(|record| record.event_id.clone()), + phase, + step_progress: durable_step_progress_from_blocks(&blocks), + blocks, + } +} + +pub(crate) fn build_conversation_replay_frames( + seed_records: &[SessionEventRecord], + history: &[SessionEventRecord], +) -> Vec { + let mut projector = ConversationDeltaProjector::new(); + projector.seed(seed_records); + let mut step_progress = durable_step_progress_from_blocks(projector.blocks()); + let mut raw_frames = Vec::new(); + for record in history { + raw_frames.extend( + projector + .project_record(record) + .into_iter() + .map(|delta| (record.event_id.clone(), delta)), + ); + } + let hidden_block_ids = draft_approval_leakage_hidden_block_ids(projector.blocks()); + + let mut frames = Vec::new(); + for (cursor, delta) in raw_frames { + if delta_block_id(&delta).is_some_and(|block_id| hidden_block_ids.contains(block_id)) { + continue; + } + observe_durable_delta_step(&mut step_progress, &delta); + frames.push(ConversationDeltaFrameFacts { + cursor, + step_progress: step_progress.clone(), + delta, + }); + } + frames +} + +fn suppress_draft_approval_plan_leakage( + blocks: Vec, +) -> Vec { + let hidden_block_ids = draft_approval_leakage_hidden_block_ids(&blocks); + blocks + .into_iter() + .filter(|block| !hidden_block_ids.contains(block_id(block))) + .collect() +} + +fn draft_approval_leakage_hidden_block_ids(blocks: &[ConversationBlockFacts]) -> HashSet { + let mut turn_facts = HashMap::::new(); + for block in blocks { + match block { + ConversationBlockFacts::User(block) => { + let Some(turn_id) = block.turn_id.as_deref() else { + continue; + }; + let facts = turn_facts + .entry(turn_id.to_string()) + .or_insert((false, false)); + if is_approval_like_turn_text(&block.markdown) { + facts.0 = true; + } + }, + ConversationBlockFacts::Plan(block) => { + let Some(turn_id) = block.turn_id.as_deref() else { + continue; + }; + let facts = turn_facts + .entry(turn_id.to_string()) + .or_insert((false, false)); + if block.status.as_deref() == Some("awaiting_approval") + || matches!( + block.event_kind, + ConversationPlanEventKind::Presented + | ConversationPlanEventKind::ReviewPending + ) + { + facts.1 = true; + } + }, + _ => {}, + } + } + + blocks + .iter() + .filter_map(|block| { + let turn_id = turn_id(block)?; + let (approval_like_user, has_review_plan) = turn_facts.get(turn_id).copied()?; + if !approval_like_user || !has_review_plan { + return None; + } + matches!( + block, + ConversationBlockFacts::Assistant(_) | ConversationBlockFacts::Thinking(_) + ) + .then(|| block_id(block).to_string()) + }) + .collect() +} + +fn delta_block_id(delta: &ConversationDeltaFacts) -> Option<&str> { + match delta { + ConversationDeltaFacts::Append { block } => Some(block_id(block.as_ref())), + ConversationDeltaFacts::Patch { block_id, .. } + | ConversationDeltaFacts::Complete { block_id, .. } => Some(block_id.as_str()), + } +} + +fn turn_id(block: &ConversationBlockFacts) -> Option<&str> { + match block { + ConversationBlockFacts::User(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Assistant(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Thinking(block) => block.turn_id.as_deref(), + ConversationBlockFacts::PromptMetrics(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Plan(block) => block.turn_id.as_deref(), + ConversationBlockFacts::ToolCall(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Error(block) => block.turn_id.as_deref(), + ConversationBlockFacts::SystemNote(_) | ConversationBlockFacts::ChildHandoff(_) => None, + } +} + +fn is_approval_like_turn_text(text: &str) -> bool { + let normalized_english = text + .split_whitespace() + .collect::>() + .join(" ") + .to_ascii_lowercase(); + for phrase in ["approved", "go ahead", "implement it"] { + if normalized_english == phrase + || (phrase != "implement it" && normalized_english.starts_with(&format!("{phrase} "))) + { + return true; + } + } + + let normalized_chinese = text + .chars() + .filter(|ch| { + !ch.is_whitespace() + && !matches!( + ch, + ',' | '.' + | '!' + | '?' + | ';' + | ':' + | '，' + | '。' + | '！' + | '？' + | '；' + | '：' + | '【' + | '】' + | '、' + ) + }) + .collect::(); + for phrase in ["同意", "可以", "按这个做", "开始实现"] { + let matched = if matches!(phrase, "同意" | "可以") { + normalized_chinese == phrase + } else { + normalized_chinese == phrase || normalized_chinese.starts_with(phrase) + }; + if matched { + return true; + } + } + + false +} + +fn fallback_live_cursor(facts: &ConversationStreamReplayFacts) -> Option { + facts + .seed_records + .last() + .map(|record| record.event_id.clone()) + .or_else(|| { + facts + .replay_history + .last() + .map(|record| record.event_id.clone()) + }) +} + +fn block_id(block: &ConversationBlockFacts) -> &str { + match block { + ConversationBlockFacts::User(block) => &block.id, + ConversationBlockFacts::Assistant(block) => &block.id, + ConversationBlockFacts::Thinking(block) => &block.id, + ConversationBlockFacts::PromptMetrics(block) => &block.id, + ConversationBlockFacts::Plan(block) => &block.id, + ConversationBlockFacts::ToolCall(block) => &block.id, + ConversationBlockFacts::Error(block) => &block.id, + ConversationBlockFacts::SystemNote(block) => &block.id, + ConversationBlockFacts::ChildHandoff(block) => &block.id, + } +} + +fn durable_step_progress_from_blocks( + blocks: &[ConversationBlockFacts], +) -> ConversationStepProgressFacts { + let mut step_progress = ConversationStepProgressFacts::default(); + for block in blocks { + observe_durable_block_step(&mut step_progress, block); + } + step_progress +} + +fn observe_durable_delta_step( + step_progress: &mut ConversationStepProgressFacts, + delta: &ConversationDeltaFacts, +) { + if let ConversationDeltaFacts::Append { block } = delta { + observe_durable_block_step(step_progress, block.as_ref()); + } +} + +fn observe_durable_block_step( + step_progress: &mut ConversationStepProgressFacts, + block: &ConversationBlockFacts, +) { + let step_cursor = match block { + ConversationBlockFacts::PromptMetrics(block) => Some(ConversationStepCursorFacts { + turn_id: block + .turn_id + .clone() + .unwrap_or_else(|| "session".to_string()), + step_index: block.step_index, + }), + ConversationBlockFacts::Assistant(block) => { + block + .step_index + .map(|step_index| ConversationStepCursorFacts { + turn_id: block + .turn_id + .clone() + .unwrap_or_else(|| "session".to_string()), + step_index, + }) + }, + _ => None, + }; + + if let Some(step_cursor) = step_cursor { + step_progress.durable = Some(step_cursor.clone()); + if let Some(live) = step_progress.live.as_ref() { + if live.turn_id != step_cursor.turn_id || live.step_index <= step_cursor.step_index { + step_progress.live = None; + } + } } } #[cfg(test)] -mod tests; +mod tests { + use astrcode_core::AgentEventContext; + + use super::*; + + #[test] + fn stream_retry_reset_clears_live_markdown_blocks_without_duplicates() { + let mut projector = ConversationDeltaProjector::new(); + + projector.project_live_event(&AgentEvent::ThinkingDelta { + turn_id: "turn-1".to_string(), + agent: AgentEventContext::default(), + delta: "old thought".to_string(), + }); + projector.project_live_event(&AgentEvent::ModelDelta { + turn_id: "turn-1".to_string(), + agent: AgentEventContext::default(), + delta: "old answer".to_string(), + }); + + let reset = projector.project_live_event(&AgentEvent::StreamRetryStarted { + turn_id: "turn-1".to_string(), + agent: AgentEventContext::default(), + attempt: 2, + max_attempts: 2, + reason: "bad stream".to_string(), + }); + assert_eq!( + reset, + vec![ + ConversationDeltaFacts::Patch { + block_id: "turn:turn-1:thinking".to_string(), + patch: ConversationBlockPatchFacts::ReplaceMarkdown { + markdown: String::new(), + }, + }, + ConversationDeltaFacts::Patch { + block_id: "turn:turn-1:assistant".to_string(), + patch: ConversationBlockPatchFacts::ReplaceMarkdown { + markdown: String::new(), + }, + }, + ] + ); + + let retry_delta = projector.project_live_event(&AgentEvent::ModelDelta { + turn_id: "turn-1".to_string(), + agent: AgentEventContext::default(), + delta: "new answer".to_string(), + }); + assert_eq!( + retry_delta, + vec![ConversationDeltaFacts::Patch { + block_id: "turn:turn-1:assistant".to_string(), + patch: ConversationBlockPatchFacts::AppendMarkdown { + markdown: "new answer".to_string(), + }, + }] + ); + } +} diff --git a/crates/session-runtime/src/query/conversation/facts.rs b/crates/server/src/conversation_read_model/facts.rs similarity index 80% rename from crates/session-runtime/src/query/conversation/facts.rs rename to crates/server/src/conversation_read_model/facts.rs index f17bd3be..31c3e749 100644 --- a/crates/session-runtime/src/query/conversation/facts.rs +++ b/crates/server/src/conversation_read_model/facts.rs @@ -1,12 +1,13 @@ +#![allow(dead_code)] + use astrcode_core::{ ChildAgentRef, CompactAppliedMeta, CompactTrigger, Phase, PromptCacheDiagnostics, - SessionEventRecord, SystemPromptLayer, ToolOutputStream, + SystemPromptLayer, ToolOutputStream, }; use serde_json::Value; -use crate::SessionReplay; #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationBlockStatus { +pub(crate) enum ConversationBlockStatus { Streaming, Complete, Failed, @@ -14,20 +15,20 @@ pub enum ConversationBlockStatus { } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationSystemNoteKind { +pub(crate) enum ConversationSystemNoteKind { Compact, SystemNote, } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationChildHandoffKind { +pub(crate) enum ConversationChildHandoffKind { Delegated, Progress, Returned, } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationTranscriptErrorKind { +pub(crate) enum ConversationTranscriptErrorKind { ProviderError, ContextWindowExceeded, ToolFatal, @@ -35,33 +36,33 @@ pub enum ConversationTranscriptErrorKind { } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationPlanEventKind { +pub(crate) enum ConversationPlanEventKind { Saved, ReviewPending, Presented, } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum ConversationPlanReviewKind { +pub(crate) enum ConversationPlanReviewKind { RevisePlan, FinalReview, } #[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ToolCallStreamsFacts { +pub(crate) struct ToolCallStreamsFacts { pub stdout: String, pub stderr: String, } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationUserBlockFacts { +pub(crate) struct ConversationUserBlockFacts { pub id: String, pub turn_id: Option, pub markdown: String, } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationAssistantBlockFacts { +pub(crate) struct ConversationAssistantBlockFacts { pub id: String, pub turn_id: Option, pub status: ConversationBlockStatus, @@ -70,7 +71,7 @@ pub struct ConversationAssistantBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationThinkingBlockFacts { +pub(crate) struct ConversationThinkingBlockFacts { pub id: String, pub turn_id: Option, pub status: ConversationBlockStatus, @@ -78,7 +79,7 @@ pub struct ConversationThinkingBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPromptMetricsBlockFacts { +pub(crate) struct ConversationPromptMetricsBlockFacts { pub id: String, pub turn_id: Option, pub step_index: u32, @@ -99,19 +100,19 @@ pub struct ConversationPromptMetricsBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPlanReviewFacts { +pub(crate) struct ConversationPlanReviewFacts { pub kind: ConversationPlanReviewKind, pub checklist: Vec, } #[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ConversationPlanBlockersFacts { +pub(crate) struct ConversationPlanBlockersFacts { pub missing_headings: Vec, pub invalid_sections: Vec, } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationPlanBlockFacts { +pub(crate) struct ConversationPlanBlockFacts { pub id: String, pub turn_id: Option, pub tool_call_id: String, @@ -128,7 +129,7 @@ pub struct ConversationPlanBlockFacts { } #[derive(Debug, Clone, PartialEq)] -pub struct ToolCallBlockFacts { +pub(crate) struct ToolCallBlockFacts { pub id: String, pub turn_id: Option, pub tool_call_id: String, @@ -145,7 +146,7 @@ pub struct ToolCallBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationErrorBlockFacts { +pub(crate) struct ConversationErrorBlockFacts { pub id: String, pub turn_id: Option, pub code: ConversationTranscriptErrorKind, @@ -153,7 +154,7 @@ pub struct ConversationErrorBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationSystemNoteBlockFacts { +pub(crate) struct ConversationSystemNoteBlockFacts { pub id: String, pub note_kind: ConversationSystemNoteKind, pub markdown: String, @@ -163,7 +164,7 @@ pub struct ConversationSystemNoteBlockFacts { } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationChildHandoffBlockFacts { +pub(crate) struct ConversationChildHandoffBlockFacts { pub id: String, pub handoff_kind: ConversationChildHandoffKind, pub child_ref: ChildAgentRef, @@ -171,7 +172,7 @@ pub struct ConversationChildHandoffBlockFacts { } #[derive(Debug, Clone, PartialEq)] -pub enum ConversationBlockFacts { +pub(crate) enum ConversationBlockFacts { User(ConversationUserBlockFacts), Assistant(ConversationAssistantBlockFacts), Thinking(ConversationThinkingBlockFacts), @@ -184,7 +185,7 @@ pub enum ConversationBlockFacts { } #[derive(Debug, Clone, PartialEq)] -pub enum ConversationBlockPatchFacts { +pub(crate) enum ConversationBlockPatchFacts { AppendMarkdown { markdown: String, }, @@ -219,52 +220,43 @@ pub enum ConversationBlockPatchFacts { } #[derive(Debug, Clone, PartialEq)] -pub enum ConversationDeltaFacts { - AppendBlock { +pub(crate) enum ConversationDeltaFacts { + Append { block: Box, }, - PatchBlock { + Patch { block_id: String, patch: ConversationBlockPatchFacts, }, - CompleteBlock { + Complete { block_id: String, status: ConversationBlockStatus, }, } #[derive(Debug, Clone, PartialEq, Eq)] -pub struct ConversationStepCursorFacts { +pub(crate) struct ConversationStepCursorFacts { pub turn_id: String, pub step_index: u32, } #[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct ConversationStepProgressFacts { +pub(crate) struct ConversationStepProgressFacts { pub durable: Option, pub live: Option, } #[derive(Debug, Clone, PartialEq)] -pub struct ConversationDeltaFrameFacts { +pub(crate) struct ConversationDeltaFrameFacts { pub cursor: String, pub step_progress: ConversationStepProgressFacts, pub delta: ConversationDeltaFacts, } #[derive(Debug, Clone, PartialEq)] -pub struct ConversationSnapshotFacts { +pub(crate) struct ConversationSnapshotFacts { pub cursor: Option, pub phase: Phase, pub step_progress: ConversationStepProgressFacts, pub blocks: Vec, } - -#[derive(Debug)] -pub struct ConversationStreamReplayFacts { - pub cursor: Option, - pub phase: Phase, - pub seed_records: Vec, - pub replay_frames: Vec, - pub replay: SessionReplay, -} diff --git a/crates/session-runtime/src/query/conversation/plan_projection.rs b/crates/server/src/conversation_read_model/plan_projection.rs similarity index 99% rename from crates/session-runtime/src/query/conversation/plan_projection.rs rename to crates/server/src/conversation_read_model/plan_projection.rs index acdfe28a..2f961870 100644 --- a/crates/session-runtime/src/query/conversation/plan_projection.rs +++ b/crates/server/src/conversation_read_model/plan_projection.rs @@ -1,3 +1,5 @@ +use serde_json::Value; + use super::*; pub(super) fn plan_block_from_tool_result( diff --git a/crates/application/src/errors.rs b/crates/server/src/errors.rs similarity index 100% rename from crates/application/src/errors.rs rename to crates/server/src/errors.rs diff --git a/crates/application/src/execution/control.rs b/crates/server/src/execution/control.rs similarity index 100% rename from crates/application/src/execution/control.rs rename to crates/server/src/execution/control.rs diff --git a/crates/application/src/execution/mod.rs b/crates/server/src/execution/mod.rs similarity index 95% rename from crates/application/src/execution/mod.rs rename to crates/server/src/execution/mod.rs index bfdfbead..c6735929 100644 --- a/crates/application/src/execution/mod.rs +++ b/crates/server/src/execution/mod.rs @@ -5,13 +5,11 @@ mod control; mod profiles; -mod root; mod subagent; use astrcode_core::{AgentMode, AgentProfile}; pub use control::ExecutionControl; pub use profiles::{ProfileProvider, ProfileResolutionService}; -pub use root::{RootExecutionRequest, execute_root_agent}; pub use subagent::{LaunchedSubagent, SubagentExecutionRequest, launch_subagent}; use crate::ApplicationError; diff --git a/crates/application/src/execution/profiles.rs b/crates/server/src/execution/profiles.rs similarity index 99% rename from crates/application/src/execution/profiles.rs rename to crates/server/src/execution/profiles.rs index d07ca846..3e8593c2 100644 --- a/crates/application/src/execution/profiles.rs +++ b/crates/server/src/execution/profiles.rs @@ -114,6 +114,7 @@ impl ProfileResolutionService { } /// 按 profile ID 查找全局 profile。 + #[allow(dead_code)] pub fn find_global_profile(&self, profile_id: &str) -> Result { let profiles = self.resolve_global()?; profiles diff --git a/crates/application/src/execution/subagent.rs b/crates/server/src/execution/subagent.rs similarity index 94% rename from crates/application/src/execution/subagent.rs rename to crates/server/src/execution/subagent.rs index 3c08040a..425baa3f 100644 --- a/crates/application/src/execution/subagent.rs +++ b/crates/server/src/execution/subagent.rs @@ -9,7 +9,7 @@ use astrcode_core::{ AgentLifecycleStatus, AgentMode, AgentProfile, ExecutionAccepted, ModeId, ResolvedRuntimeConfig, RuntimeMetricsRecorder, }; -use astrcode_kernel::AgentControlError; +use astrcode_host_session::SubRunHandle; use crate::{ AgentKernelPort, AgentSessionPort, @@ -22,6 +22,7 @@ use crate::{ FreshChildGovernanceInput, GovernanceBusyPolicy, GovernanceSurfaceAssembler, build_delegation_metadata, }, + ports::ServerKernelControlError, }; /// 子代理执行请求。 @@ -46,7 +47,7 @@ pub struct SubagentExecutionRequest { /// 不能再回头二次查询 handle 并容忍缺失。 pub struct LaunchedSubagent { pub accepted: ExecutionAccepted, - pub handle: astrcode_core::SubRunHandle, + pub handle: SubRunHandle, } /// 启动子代理执行。 @@ -69,7 +70,6 @@ pub async fn launch_subagent( ensure_subagent_profile_mode(&request.profile)?; let surface = governance .fresh_child_surface( - kernel, session_runtime, FreshChildGovernanceInput { session_id: request.parent_session_id.clone(), @@ -175,22 +175,22 @@ fn ensure_subagent_profile_mode(profile: &AgentProfile) -> Result<(), Applicatio /// - MaxDepthExceeded → InvalidArgument（提示复用已有 child） /// - MaxConcurrentExceeded → Conflict（提示等待或关闭已有 child） /// - ParentAgentNotFound → NotFound -fn map_spawn_error(error: AgentControlError) -> ApplicationError { +fn map_spawn_error(error: ServerKernelControlError) -> ApplicationError { match error { - AgentControlError::MaxDepthExceeded { current, max } => { + ServerKernelControlError::MaxDepthExceeded { current, max } => { ApplicationError::InvalidArgument(format!( "subagent depth limit reached at depth {current} (configured max: {max}); reuse \ an existing child with send/observe/close, or finish the work in the current \ agent" )) }, - AgentControlError::MaxConcurrentExceeded { current, max } => { + ServerKernelControlError::MaxConcurrentExceeded { current, max } => { ApplicationError::Conflict(format!( "too many active agents ({current}/{max}); wait for an existing child to go idle \ or close one before spawning more" )) }, - AgentControlError::ParentAgentNotFound { agent_id } => { + ServerKernelControlError::ParentAgentNotFound { agent_id } => { ApplicationError::NotFound(format!("parent agent '{agent_id}' not found")) }, } @@ -295,7 +295,8 @@ mod tests { #[test] fn map_spawn_error_turns_depth_limit_into_actionable_invalid_argument() { - let err = map_spawn_error(AgentControlError::MaxDepthExceeded { current: 4, max: 3 }); + let err = + map_spawn_error(ServerKernelControlError::MaxDepthExceeded { current: 4, max: 3 }); assert!(matches!(err, ApplicationError::InvalidArgument(_))); assert!(err.to_string().contains("configured max: 3")); @@ -304,7 +305,8 @@ mod tests { #[test] fn map_spawn_error_turns_concurrency_limit_into_conflict() { - let err = map_spawn_error(AgentControlError::MaxConcurrentExceeded { current: 8, max: 4 }); + let err = + map_spawn_error(ServerKernelControlError::MaxConcurrentExceeded { current: 8, max: 4 }); assert!(matches!(err, ApplicationError::Conflict(_))); assert!(err.to_string().contains("too many active agents")); diff --git a/crates/server/src/governance_service.rs b/crates/server/src/governance_service.rs new file mode 100644 index 00000000..0d122e3d --- /dev/null +++ b/crates/server/src/governance_service.rs @@ -0,0 +1,76 @@ +//! server-owned governance bridge。 +//! +//! server 状态面只暴露本地治理 contract。 + +use std::{path::PathBuf, sync::Arc}; + +use astrcode_core::{CapabilitySpec, RuntimeObservabilitySnapshot}; +use astrcode_plugin_host::PluginEntry; +use async_trait::async_trait; + +#[derive(Debug, Clone)] +pub(crate) struct ServerGovernanceSnapshot { + pub runtime_name: String, + pub runtime_kind: String, + pub loaded_session_count: usize, + pub running_session_ids: Vec, + pub plugin_search_paths: Vec, + pub metrics: RuntimeObservabilitySnapshot, + pub capabilities: Vec, + pub plugins: Vec, +} + +#[derive(Debug, Clone)] +pub(crate) struct ServerGovernanceReloadResult { + pub snapshot: ServerGovernanceSnapshot, + pub reloaded_at: chrono::DateTime, +} + +#[async_trait] +pub(crate) trait ServerGovernancePort: Send + Sync { + fn capabilities(&self) -> Vec; + + async fn reload( + &self, + ) -> Result; + + async fn shutdown( + &self, + timeout_secs: u64, + ) -> Result<(), crate::application_error_bridge::ServerRouteError>; +} + +pub(crate) struct ServerGovernanceService { + port: Arc, +} + +impl ServerGovernanceService { + pub(crate) fn new(port: Arc) -> Self { + Self { port } + } + + pub(crate) fn capabilities(&self) -> Vec { + self.port.capabilities() + } + + pub(crate) async fn reload( + &self, + ) -> Result + { + self.port.reload().await + } + + pub(crate) async fn shutdown( + &self, + timeout_secs: u64, + ) -> Result<(), crate::application_error_bridge::ServerRouteError> { + self.port.shutdown(timeout_secs).await + } +} + +impl std::fmt::Debug for ServerGovernanceService { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("ServerGovernanceService") + .finish_non_exhaustive() + } +} diff --git a/crates/application/src/governance_surface/assembler.rs b/crates/server/src/governance_surface/assembler.rs similarity index 73% rename from crates/application/src/governance_surface/assembler.rs rename to crates/server/src/governance_surface/assembler.rs index 488f8151..11e0a06d 100644 --- a/crates/application/src/governance_surface/assembler.rs +++ b/crates/server/src/governance_surface/assembler.rs @@ -19,8 +19,8 @@ use super::{ ResumedChildGovernanceInput, RootGovernanceInput, SessionGovernanceInput, }; use crate::{ - AgentSessionPort, AppKernelPort, ApplicationError, CompiledModeEnvelope, ComposerResolvedSkill, - ExecutionControl, ModeCatalog, compile_mode_envelope, compile_mode_envelope_for_child, + AgentSessionPort, ApplicationError, CompiledModeEnvelope, ExecutionControl, ModeCatalog, + compile_mode_envelope, compile_mode_envelope_for_child, }; #[derive(Debug, Clone)] @@ -50,69 +50,25 @@ impl GovernanceSurfaceAssembler { Ok(runtime) } - pub fn build_submission_skill_declaration( - &self, - skill: &ComposerResolvedSkill, - user_prompt: Option<&str>, - ) -> astrcode_core::PromptDeclaration { - let mut content = format!( - "The user explicitly selected the `{}` skill for this turn.\n\nSelected skill:\n- id: \ - {}\n- description: {}\n\nTurn contract:\n- Call the `Skill` tool for `{}` before \ - continuing.\n- Treat the user's message as the task-specific instruction for this \ - skill.\n- If the user message is empty, follow the skill's default workflow and ask \ - only if blocked.\n- Do not silently substitute a different skill unless `{}` is \ - unavailable.", - skill.id, - skill.id, - skill.description.trim(), - skill.id, - skill.id - ); - if let Some(user_prompt) = user_prompt.map(str::trim).filter(|value| !value.is_empty()) { - content.push_str(&format!("\n- User prompt focus: {user_prompt}")); - } - astrcode_core::PromptDeclaration { - block_id: format!("submission.skill.{}", skill.id), - title: format!("Selected Skill: {}", skill.id), - content, - render_target: astrcode_core::PromptDeclarationRenderTarget::System, - layer: astrcode_core::SystemPromptLayer::Dynamic, - kind: astrcode_core::PromptDeclarationKind::ExtensionInstruction, - priority_hint: Some(590), - always_include: true, - source: astrcode_core::PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some(format!("skill-slash:{}", skill.id)), - } - } - fn compile_mode_surface( &self, - kernel: &dyn AppKernelPort, mode_id: &astrcode_core::ModeId, extra_prompt_declarations: Vec, ) -> Result { let spec = self.mode_catalog.get(mode_id).ok_or_else(|| { ApplicationError::InvalidArgument(format!("unknown mode '{}'", mode_id)) })?; - compile_mode_envelope( - kernel.gateway().capabilities(), - &spec, - extra_prompt_declarations, - ) - .map_err(ApplicationError::from) + compile_mode_envelope(&spec, extra_prompt_declarations).map_err(ApplicationError::from) } fn compile_child_mode_surface( &self, - kernel: &dyn AppKernelPort, mode_id: &astrcode_core::ModeId, ) -> Result { let spec = self.mode_catalog.get(mode_id).ok_or_else(|| { ApplicationError::InvalidArgument(format!("unknown mode '{}'", mode_id)) })?; - compile_mode_envelope_for_child(kernel.gateway().capabilities(), &spec) - .map_err(ApplicationError::from) + compile_mode_envelope_for_child(&spec).map_err(ApplicationError::from) } fn build_surface( @@ -146,7 +102,6 @@ impl GovernanceSurfaceAssembler { let surface = ResolvedGovernanceSurface { mode_id: compiled.envelope.mode_id.clone(), runtime: runtime.clone(), - capability_router: compiled.capability_router, prompt_declarations, bound_mode_tool_contract: compiled.envelope.bound_tool_contract_snapshot(), resolved_limits: ResolvedExecutionLimitsSnapshot, @@ -175,12 +130,11 @@ impl GovernanceSurfaceAssembler { pub fn session_surface( &self, - kernel: &dyn AppKernelPort, input: SessionGovernanceInput, ) -> Result { let runtime = self.runtime_with_control(input.runtime, input.control.as_ref(), false)?; let compiled = - self.compile_mode_surface(kernel, &input.mode_id, input.extra_prompt_declarations)?; + self.compile_mode_surface(&input.mode_id, input.extra_prompt_declarations)?; self.build_surface(BuildSurfaceInput { session_id: input.session_id, turn_id: input.turn_id, @@ -197,32 +151,27 @@ impl GovernanceSurfaceAssembler { pub fn root_surface( &self, - kernel: &dyn AppKernelPort, input: RootGovernanceInput, ) -> Result { - self.session_surface( - kernel, - SessionGovernanceInput { - session_id: input.session_id, - turn_id: input.turn_id, - working_dir: input.working_dir, - profile: input.profile, - mode_id: input.mode_id, - runtime: input.runtime, - control: input.control, - extra_prompt_declarations: Vec::new(), - busy_policy: GovernanceBusyPolicy::BranchOnBusy, - }, - ) + self.session_surface(SessionGovernanceInput { + session_id: input.session_id, + turn_id: input.turn_id, + working_dir: input.working_dir, + profile: input.profile, + mode_id: input.mode_id, + runtime: input.runtime, + control: input.control, + extra_prompt_declarations: Vec::new(), + busy_policy: GovernanceBusyPolicy::BranchOnBusy, + }) } pub async fn fresh_child_surface( &self, - kernel: &dyn AppKernelPort, session_runtime: &dyn AgentSessionPort, input: FreshChildGovernanceInput, ) -> Result { - let compiled = self.compile_child_mode_surface(kernel, &input.mode_id)?; + let compiled = self.compile_child_mode_surface(&input.mode_id)?; let resolved_overrides = ResolvedSubagentContextOverrides { fork_mode: compiled.envelope.fork_mode.clone(), ..ResolvedSubagentContextOverrides::default() @@ -255,11 +204,10 @@ impl GovernanceSurfaceAssembler { pub fn resumed_child_surface( &self, - kernel: &dyn AppKernelPort, input: ResumedChildGovernanceInput, ) -> Result { let runtime = input.runtime; - let compiled = self.compile_mode_surface(kernel, &input.mode_id, Vec::new())?; + let compiled = self.compile_mode_surface(&input.mode_id, Vec::new())?; let delegation = input.delegation.unwrap_or_else(|| { super::build_delegation_metadata( "", @@ -286,6 +234,7 @@ impl GovernanceSurfaceAssembler { }) } + #[allow(dead_code)] pub fn tool_collaboration_context( &self, runtime: ResolvedRuntimeConfig, @@ -309,6 +258,7 @@ impl GovernanceSurfaceAssembler { ) } + #[allow(dead_code)] pub fn mode_catalog(&self) -> &ModeCatalog { &self.mode_catalog } diff --git a/crates/application/src/governance_surface/inherited.rs b/crates/server/src/governance_surface/inherited.rs similarity index 96% rename from crates/application/src/governance_surface/inherited.rs rename to crates/server/src/governance_surface/inherited.rs index f3701769..622bea82 100644 --- a/crates/application/src/governance_surface/inherited.rs +++ b/crates/server/src/governance_surface/inherited.rs @@ -4,9 +4,8 @@ //! - **Compact summary**：从父消息中提取压缩摘要，给子代理一个精简的上下文概览 //! - **Recent tail**：按 fork mode 截取父消息尾部（LastNTurns 或 FullHistory） -use astrcode_core::{ - ForkMode, LlmMessage, ResolvedSubagentContextOverrides, UserMessageOrigin, project, -}; +use astrcode_core::{ForkMode, LlmMessage, ResolvedSubagentContextOverrides, UserMessageOrigin}; +use astrcode_host_session::project; use crate::{AgentSessionPort, ApplicationError}; diff --git a/crates/application/src/governance_surface/mod.rs b/crates/server/src/governance_surface/mod.rs similarity index 96% rename from crates/application/src/governance_surface/mod.rs rename to crates/server/src/governance_surface/mod.rs index 556b4bc8..642b9770 100644 --- a/crates/application/src/governance_surface/mod.rs +++ b/crates/server/src/governance_surface/mod.rs @@ -24,7 +24,7 @@ use astrcode_core::{ ModeId, PolicyContext, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, ResolvedSubagentContextOverrides, }; -use astrcode_kernel::CapabilityRouter; +use astrcode_host_session::PromptGovernanceContext; pub(crate) use inherited::resolve_inherited_parent_messages; #[cfg(test)] pub(crate) use inherited::{build_inherited_messages, select_inherited_recent_tail}; @@ -68,7 +68,6 @@ pub struct GovernanceApprovalPipeline { pub struct ResolvedGovernanceSurface { pub mode_id: ModeId, pub runtime: ResolvedRuntimeConfig, - pub capability_router: Option, pub prompt_declarations: Vec, pub bound_mode_tool_contract: BoundModeToolContractSnapshot, pub resolved_limits: ResolvedExecutionLimitsSnapshot, @@ -78,7 +77,9 @@ pub struct ResolvedGovernanceSurface { pub collaboration_policy: AgentCollaborationPolicyContext, pub approval: GovernanceApprovalPipeline, pub governance_revision: String, + #[allow(dead_code)] pub busy_policy: GovernanceBusyPolicy, + #[allow(dead_code)] pub diagnostics: Vec, } @@ -97,8 +98,8 @@ impl ResolvedGovernanceSurface { Ok(()) } - pub fn prompt_facts_context(&self) -> astrcode_core::PromptGovernanceContext { - astrcode_core::PromptGovernanceContext { + pub fn prompt_facts_context(&self) -> PromptGovernanceContext { + PromptGovernanceContext { allowed_capability_names: Vec::new(), mode_id: Some(self.mode_id.clone()), approval_mode: if self.approval.pending.is_some() { @@ -120,7 +121,6 @@ impl ResolvedGovernanceSurface { let prompt_governance = self.prompt_facts_context(); AppAgentPromptSubmission { agent, - capability_router: self.capability_router, current_mode_id: self.mode_id, prompt_declarations: self.prompt_declarations, bound_mode_tool_contract: Some(self.bound_mode_tool_contract), @@ -135,6 +135,7 @@ impl ResolvedGovernanceSurface { } } + #[allow(dead_code)] pub async fn check_model_request( &self, engine: &dyn astrcode_core::PolicyEngine, @@ -145,6 +146,7 @@ impl ResolvedGovernanceSurface { .await } + #[allow(dead_code)] pub async fn check_capability_call( &self, engine: &dyn astrcode_core::PolicyEngine, diff --git a/crates/application/src/governance_surface/policy.rs b/crates/server/src/governance_surface/policy.rs similarity index 99% rename from crates/application/src/governance_surface/policy.rs rename to crates/server/src/governance_surface/policy.rs index db42fb35..689648e8 100644 --- a/crates/application/src/governance_surface/policy.rs +++ b/crates/server/src/governance_surface/policy.rs @@ -3,6 +3,7 @@ //! 提供两个核心功能： //! - 构建协作策略上下文（`collaboration_policy_context`），包含 depth/spawn 限制 //! - 构建审批管线（`default_approval_pipeline`），当 mode 要求审批时安装占位骨架 +#![allow(dead_code)] use astrcode_core::{ AgentCollaborationPolicyContext, ApprovalPending, ApprovalRequest, CapabilityCall, ModeId, diff --git a/crates/application/src/governance_surface/prompt.rs b/crates/server/src/governance_surface/prompt.rs similarity index 100% rename from crates/application/src/governance_surface/prompt.rs rename to crates/server/src/governance_surface/prompt.rs diff --git a/crates/application/src/governance_surface/tests.rs b/crates/server/src/governance_surface/tests.rs similarity index 54% rename from crates/application/src/governance_surface/tests.rs rename to crates/server/src/governance_surface/tests.rs index 74a6fda0..a6a9244a 100644 --- a/crates/application/src/governance_surface/tests.rs +++ b/crates/server/src/governance_surface/tests.rs @@ -6,16 +6,11 @@ //! - 工具白名单、审批管线、协作策略上下文的正确性 //! - 各种 capability selector（all / subset / none / union / difference）的编译结果 -use std::sync::Arc; - use astrcode_core::{ - AllowAllPolicyEngine, ApprovalDefault, AstrError, BoundModeToolContractSnapshot, - CapabilityKind, CapabilitySpec, LlmMessage, LlmOutput, LlmProvider, LlmRequest, ModeId, - ModelLimits, ModelRequest, PromptBuildOutput, PromptBuildRequest, PromptProvider, - ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, ResourceProvider, ResourceReadResult, - ResourceRequestContext, SideEffect, Stability, UserMessageOrigin, + AllowAllPolicyEngine, ApprovalDefault, BoundModeToolContractSnapshot, CapabilityKind, + CapabilitySpec, LlmMessage, ModeId, ModelRequest, ResolvedExecutionLimitsSnapshot, + ResolvedRuntimeConfig, UserMessageOrigin, }; -use async_trait::async_trait; use serde_json::{Value, json}; use super::{ @@ -26,149 +21,21 @@ use super::{ }; use crate::{ExecutionControl, test_support::StubSessionPort}; -#[derive(Debug)] -struct TestTool { - name: &'static str, -} - -#[async_trait] -impl astrcode_core::Tool for TestTool { - fn definition(&self) -> astrcode_core::ToolDefinition { - astrcode_core::ToolDefinition { - name: self.name.to_string(), - description: self.name.to_string(), - parameters: json!({"type":"object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result { - CapabilitySpec::builder(self.name, CapabilityKind::Tool) - .description(self.name) - .schema(json!({"type":"object"}), json!({"type":"object"})) - .side_effect(SideEffect::Workspace) - .stability(Stability::Stable) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - _ctx: &astrcode_core::ToolContext, - ) -> astrcode_core::Result { - Ok(astrcode_core::ToolExecutionResult { - tool_call_id, - tool_name: self.name.to_string(), - ok: true, - output: String::new(), - continuation: None, - error: None, - metadata: None, - duration_ms: 0, - truncated: false, - }) - } -} - -fn router() -> astrcode_kernel::CapabilityRouter { - astrcode_kernel::CapabilityRouter::builder() - .register_invoker(Arc::new( - astrcode_kernel::ToolCapabilityInvoker::new(Arc::new(TestTool { name: "spawn" })) - .expect("tool should build"), - )) - .register_invoker(Arc::new( - astrcode_kernel::ToolCapabilityInvoker::new(Arc::new(TestTool { name: "readFile" })) - .expect("tool should build"), - )) - .build() - .expect("router should build") -} - -#[derive(Debug)] -struct NoopLlmProvider; - -#[async_trait] -impl LlmProvider for NoopLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> astrcode_core::Result { - Err(AstrError::Validation("noop".to_string())) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 32_000, - max_output_tokens: 4_096, - } - } -} - -#[derive(Debug)] -struct NoopPromptProvider; - -#[async_trait] -impl PromptProvider for NoopPromptProvider { - async fn build_prompt( - &self, - _request: PromptBuildRequest, - ) -> astrcode_core::Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: json!({}), - }) - } -} - -#[derive(Debug)] -struct NoopResourceProvider; - -#[async_trait] -impl ResourceProvider for NoopResourceProvider { - async fn read_resource( - &self, - uri: &str, - _context: &ResourceRequestContext, - ) -> astrcode_core::Result { - Ok(ResourceReadResult { - uri: uri.to_string(), - content: json!({}), - metadata: json!({}), - }) - } -} - #[test] fn session_surface_builds_collaboration_prompt_and_policy_context() { - let kernel = astrcode_kernel::Kernel::builder() - .with_capabilities(router()) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"); let assembler = GovernanceSurfaceAssembler::default(); let surface = assembler - .session_surface( - &kernel, - SessionGovernanceInput { - session_id: "session-1".to_string(), - turn_id: "turn-1".to_string(), - working_dir: ".".to_string(), - profile: "coding".to_string(), - mode_id: ModeId::code(), - runtime: ResolvedRuntimeConfig::default(), - control: None, - extra_prompt_declarations: Vec::new(), - busy_policy: GovernanceBusyPolicy::BranchOnBusy, - }, - ) + .session_surface(SessionGovernanceInput { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + working_dir: ".".to_string(), + profile: "coding".to_string(), + mode_id: ModeId::code(), + runtime: ResolvedRuntimeConfig::default(), + control: None, + extra_prompt_declarations: Vec::new(), + busy_policy: GovernanceBusyPolicy::BranchOnBusy, + }) .expect("surface should build"); assert_eq!(surface.governance_revision, GOVERNANCE_POLICY_REVISION); @@ -188,7 +55,6 @@ async fn surface_policy_pipeline_defaults_to_allow_all() { let surface = ResolvedGovernanceSurface { mode_id: ModeId::code(), runtime: ResolvedRuntimeConfig::default(), - capability_router: None, prompt_declarations: Vec::new(), bound_mode_tool_contract: BoundModeToolContractSnapshot { mode_id: ModeId::code(), @@ -290,49 +156,30 @@ fn inherited_messages_follow_compact_and_tail_policy() { #[test] fn root_surface_applies_execution_control_without_special_case_logic() { - let kernel = astrcode_kernel::Kernel::builder() - .with_capabilities(router()) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"); let assembler = GovernanceSurfaceAssembler::default(); let surface = assembler - .root_surface( - &kernel, - RootGovernanceInput { - session_id: "session-1".to_string(), - turn_id: "turn-1".to_string(), - working_dir: ".".to_string(), - profile: "coding".to_string(), - mode_id: ModeId::code(), - runtime: ResolvedRuntimeConfig::default(), - control: Some(ExecutionControl { - manual_compact: None, - }), - }, - ) + .root_surface(RootGovernanceInput { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + working_dir: ".".to_string(), + profile: "coding".to_string(), + mode_id: ModeId::code(), + runtime: ResolvedRuntimeConfig::default(), + control: Some(ExecutionControl { + manual_compact: None, + }), + }) .expect("surface should build"); - assert!(surface.capability_router.is_none()); assert_eq!(surface.busy_policy, GovernanceBusyPolicy::BranchOnBusy); } #[tokio::test] async fn fresh_child_surface_restricts_tools_and_inherits_governance_defaults() { - let kernel = astrcode_kernel::Kernel::builder() - .with_capabilities(router()) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"); let assembler = GovernanceSurfaceAssembler::default(); let session_runtime = StubSessionPort::default(); let surface = assembler .fresh_child_surface( - &kernel, &session_runtime, FreshChildGovernanceInput { session_id: "session-1".to_string(), @@ -349,7 +196,6 @@ async fn fresh_child_surface_restricts_tools_and_inherits_governance_defaults() .expect("surface should build"); assert_eq!(surface.resolved_limits, ResolvedExecutionLimitsSnapshot); - assert!(surface.capability_router.is_none()); assert!( surface .prompt_declarations @@ -360,31 +206,21 @@ async fn fresh_child_surface_restricts_tools_and_inherits_governance_defaults() #[test] fn resumed_child_surface_reuses_existing_limits_and_contract_source() { - let kernel = astrcode_kernel::Kernel::builder() - .with_capabilities(router()) - .with_llm_provider(Arc::new(NoopLlmProvider)) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build"); let assembler = GovernanceSurfaceAssembler::default(); let limits = ResolvedExecutionLimitsSnapshot; let surface = assembler - .resumed_child_surface( - &kernel, - ResumedChildGovernanceInput { - session_id: "session-1".to_string(), - turn_id: "turn-1".to_string(), - working_dir: ".".to_string(), - mode_id: ModeId::code(), - runtime: ResolvedRuntimeConfig::default(), - resolved_limits: limits.clone(), - delegation: None, - message: "continue with the same branch".to_string(), - context: Some("keep scope tight".to_string()), - busy_policy: GovernanceBusyPolicy::RejectOnBusy, - }, - ) + .resumed_child_surface(ResumedChildGovernanceInput { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + working_dir: ".".to_string(), + mode_id: ModeId::code(), + runtime: ResolvedRuntimeConfig::default(), + resolved_limits: limits.clone(), + delegation: None, + message: "continue with the same branch".to_string(), + context: Some("keep scope tight".to_string()), + busy_policy: GovernanceBusyPolicy::RejectOnBusy, + }) .expect("surface should build"); assert_eq!(surface.resolved_limits, limits); assert_eq!(surface.busy_policy, GovernanceBusyPolicy::RejectOnBusy); diff --git a/crates/server/src/http/agent_api.rs b/crates/server/src/http/agent_api.rs new file mode 100644 index 00000000..4e8cebed --- /dev/null +++ b/crates/server/src/http/agent_api.rs @@ -0,0 +1,308 @@ +//! server-owned agent route bridge。 +//! +//! 负责把 agent 路由需要的 root execute / status / close 能力， +//! 直接接到 kernel + session-runtime + profile/governance 装配面， +//! 避免继续经由旧的应用层协作入口。 + +use std::sync::Arc; + +use astrcode_core::{ + AgentLifecycleStatus, AgentProfile, ResolvedExecutionLimitsSnapshot, + ResolvedSubagentContextOverrides, SubRunResult, SubRunStorageMode, +}; + +use crate::{ + agent_control_bridge::{ + ServerAgentControlPort, ServerCloseAgentSummary, ServerLiveSubRunStatus, + }, + application_error_bridge::ServerRouteError, + ports::{AppSessionPort, DurableSubRunStatusSummary}, + profile_service::ServerProfileService, + root_execute_service::{ + ServerAgentExecuteSummary, ServerRootExecuteService, ServerRootExecutionRequest, + ServerSessionPromptRequest, + }, +}; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum ServerSubRunStatusSource { + Live, + Durable, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerSubRunStatusSummary { + pub sub_run_id: String, + pub tool_call_id: Option, + pub source: ServerSubRunStatusSource, + pub agent_id: String, + pub agent_profile: String, + pub session_id: String, + pub child_session_id: Option, + pub depth: usize, + pub parent_agent_id: Option, + pub parent_sub_run_id: Option, + pub storage_mode: SubRunStorageMode, + pub lifecycle: AgentLifecycleStatus, + pub last_turn_outcome: Option, + pub result: Option, + pub step_count: Option, + pub estimated_tokens: Option, + pub resolved_overrides: Option, + pub resolved_limits: Option, +} + +#[derive(Clone)] +pub(crate) struct ServerAgentApi { + agent_control: Arc, + sessions: Arc, + profiles: Arc, + root_executor: Arc, +} + +impl ServerAgentApi { + pub(crate) fn new( + agent_control: Arc, + sessions: Arc, + profiles: Arc, + root_executor: Arc, + ) -> Self { + Self { + agent_control, + sessions, + profiles, + root_executor, + } + } + + pub(crate) fn list_global_agent_profiles(&self) -> Result, ServerRouteError> { + Ok(self.profiles.resolve_global()?.as_ref().clone()) + } + + pub(crate) async fn execute_root_agent_summary( + &self, + request: ServerRootExecutionRequest, + ) -> Result { + self.root_executor.execute_summary(request).await + } + + pub(crate) async fn submit_existing_session_prompt( + &self, + request: ServerSessionPromptRequest, + ) -> Result { + self.root_executor + .submit_existing_session_prompt(request) + .await + } + + pub(crate) async fn get_subrun_status_summary( + &self, + session_id: &str, + requested_subrun_id: &str, + ) -> Result { + validate_non_empty("sessionId", session_id)?; + validate_non_empty("subRunId", requested_subrun_id)?; + + if let Some(view) = self.get_subrun_status(requested_subrun_id).await? { + if view.session_id == session_id { + return Ok(summarize_live_subrun_status(view)); + } + } + + if let Some(view) = self.get_root_agent_status(session_id).await? { + if view.sub_run_id == requested_subrun_id { + return Ok(summarize_live_subrun_status(view)); + } + return Err(ServerRouteError::not_found(format!( + "subrun '{}' not found in session '{}'", + requested_subrun_id, session_id + ))); + } + + if let Some(summary) = self + .durable_subrun_status_summary(session_id, requested_subrun_id) + .await? + { + return Ok(summary); + } + + Ok(default_subrun_status_summary( + session_id.to_string(), + requested_subrun_id.to_string(), + )) + } + + pub(crate) async fn close_agent( + &self, + session_id: &str, + agent_id: &str, + ) -> Result { + validate_non_empty("sessionId", session_id)?; + validate_non_empty("agentId", agent_id)?; + let Some(handle) = self.agent_control.get_handle(agent_id).await else { + return Err(ServerRouteError::not_found(format!( + "agent '{}' not found", + agent_id + ))); + }; + if handle.session_id.as_str() != session_id { + return Err(ServerRouteError::not_found(format!( + "agent '{}' not found in session '{}'", + agent_id, session_id + ))); + } + self.agent_control.close_subtree(agent_id).await + } + + pub(crate) async fn get_subrun_status( + &self, + agent_id: &str, + ) -> Result, ServerRouteError> { + validate_non_empty("agentId", agent_id)?; + Ok(self.agent_control.query_subrun_status(agent_id).await) + } + + async fn get_root_agent_status( + &self, + session_id: &str, + ) -> Result, ServerRouteError> { + validate_non_empty("sessionId", session_id)?; + Ok(self.agent_control.query_root_status(session_id).await) + } + + async fn durable_subrun_status_summary( + &self, + parent_session_id: &str, + requested_subrun_id: &str, + ) -> Result, ServerRouteError> { + Ok(self + .sessions + .durable_subrun_status_snapshot(parent_session_id, requested_subrun_id) + .await + .map_err(|error| ServerRouteError::internal(error.to_string()))? + .map(summarize_durable_subrun_status)) + } +} + +fn validate_non_empty(field: &str, value: &str) -> Result<(), ServerRouteError> { + if value.trim().is_empty() { + return Err(ServerRouteError::invalid_argument(format!( + "field '{field}' must not be empty" + ))); + } + Ok(()) +} + +fn summarize_live_subrun_status(view: ServerLiveSubRunStatus) -> ServerSubRunStatusSummary { + ServerSubRunStatusSummary { + sub_run_id: view.sub_run_id, + tool_call_id: None, + source: ServerSubRunStatusSource::Live, + agent_id: view.agent_id, + agent_profile: view.agent_profile, + session_id: view.session_id, + child_session_id: view.child_session_id, + depth: view.depth, + parent_agent_id: view.parent_agent_id, + parent_sub_run_id: None, + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: view.lifecycle, + last_turn_outcome: view.last_turn_outcome, + result: None, + step_count: None, + estimated_tokens: None, + resolved_overrides: None, + resolved_limits: Some(view.resolved_limits), + } +} + +fn default_subrun_status_summary( + session_id: String, + sub_run_id: String, +) -> ServerSubRunStatusSummary { + ServerSubRunStatusSummary { + sub_run_id, + tool_call_id: None, + source: ServerSubRunStatusSource::Live, + agent_id: "root-agent".to_string(), + agent_profile: "default".to_string(), + session_id, + child_session_id: None, + depth: 0, + parent_agent_id: None, + parent_sub_run_id: None, + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: AgentLifecycleStatus::Idle, + last_turn_outcome: None, + result: None, + step_count: None, + estimated_tokens: None, + resolved_overrides: None, + resolved_limits: Some(ResolvedExecutionLimitsSnapshot), + } +} + +fn summarize_durable_subrun_status( + snapshot: DurableSubRunStatusSummary, +) -> ServerSubRunStatusSummary { + ServerSubRunStatusSummary { + sub_run_id: snapshot.sub_run_id, + tool_call_id: snapshot.tool_call_id, + source: ServerSubRunStatusSource::Durable, + agent_id: snapshot.agent_id, + agent_profile: snapshot.agent_profile, + session_id: snapshot.session_id, + child_session_id: snapshot.child_session_id, + depth: snapshot.depth, + parent_agent_id: snapshot.parent_agent_id, + parent_sub_run_id: snapshot.parent_sub_run_id, + storage_mode: snapshot.storage_mode, + lifecycle: snapshot.lifecycle, + last_turn_outcome: snapshot.last_turn_outcome, + result: snapshot.result, + step_count: snapshot.step_count, + estimated_tokens: snapshot.estimated_tokens, + resolved_overrides: snapshot.resolved_overrides, + resolved_limits: Some(snapshot.resolved_limits), + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{ + AgentLifecycleStatus, AgentTurnOutcome, ResolvedExecutionLimitsSnapshot, + ResolvedSubagentContextOverrides, SubRunStorageMode, + }; + + use super::{ServerSubRunStatusSource, summarize_durable_subrun_status}; + use crate::ports::DurableSubRunStatusSummary; + + #[test] + fn summarize_durable_subrun_status_reuses_runtime_projection() { + let summary = summarize_durable_subrun_status(DurableSubRunStatusSummary { + sub_run_id: "subrun-child".to_string(), + tool_call_id: Some("tool-1".to_string()), + agent_id: "agent-child".to_string(), + agent_profile: "reviewer".to_string(), + session_id: "session-parent".to_string(), + child_session_id: Some("session-child".to_string()), + depth: 1, + parent_agent_id: None, + parent_sub_run_id: Some("subrun-parent".to_string()), + storage_mode: SubRunStorageMode::IndependentSession, + lifecycle: AgentLifecycleStatus::Idle, + last_turn_outcome: Some(AgentTurnOutcome::Completed), + result: None, + step_count: Some(3), + estimated_tokens: Some(120), + resolved_overrides: Some(ResolvedSubagentContextOverrides::default()), + resolved_limits: ResolvedExecutionLimitsSnapshot, + }); + + assert_eq!(summary.source, ServerSubRunStatusSource::Durable); + assert_eq!(summary.sub_run_id, "subrun-child"); + assert_eq!(summary.child_session_id.as_deref(), Some("session-child")); + assert_eq!(summary.step_count, Some(3)); + assert!(summary.resolved_limits.is_some()); + } +} diff --git a/crates/server/src/http/composer_catalog.rs b/crates/server/src/http/composer_catalog.rs new file mode 100644 index 00000000..1157735e --- /dev/null +++ b/crates/server/src/http/composer_catalog.rs @@ -0,0 +1,181 @@ +//! server-owned composer catalog adapter。 +//! +//! 负责把 `plugin-host::ResourceCatalog`、分层 `SkillCatalog` 与当前 runtime capability +//! 快照统一投影成 `host-session::ComposerOption`，从而让 HTTP 路由不再依赖 +//! `application::composer` 过渡面。 + +use astrcode_core::{SessionId, SkillSpec}; +use astrcode_host_session::{ComposerOption, ComposerOptionActionKind, ComposerOptionKind}; + +use crate::{AppState, application_error_bridge::ServerRouteError}; + +pub(crate) async fn list_session_composer_options( + state: &AppState, + session_id: &str, + query: Option<&str>, + kinds: &[ComposerOptionKind], + limit: usize, +) -> Result, ServerRouteError> { + let working_dir = state + .session_catalog + .ensure_loaded_session(&SessionId::from(session_id.to_string())) + .await + .map_err(|error| ServerRouteError::internal(error.to_string()))? + .working_dir + .display() + .to_string(); + let mut items = command_options(state); + items.extend(skill_options( + state.skill_catalog.resolve_for_working_dir(&working_dir), + )); + items.extend(capability_options(state)); + + if !kinds.is_empty() { + items.retain(|item| kinds.contains(&item.kind)); + } + + if let Some(query) = normalize_query(query) { + items.retain(|item| option_matches_query(item, &query)); + } + + items.truncate(limit); + Ok(items) +} + +fn command_options(state: &AppState) -> Vec { + state + .resource_catalog + .read() + .expect("plugin resource catalog lock poisoned") + .commands + .iter() + .map(|command| ComposerOption { + kind: ComposerOptionKind::Command, + id: command.command_id.clone(), + title: humanize_token_path(&command.command_id), + description: describe_command(&command.command_id), + insert_text: format!("/{}", command.command_id), + action_kind: ComposerOptionActionKind::ExecuteCommand, + action_value: format!("/{}", command.command_id), + badges: vec!["command".to_string()], + keywords: command_keywords(&command.command_id), + }) + .collect() +} + +fn skill_options(skills: Vec) -> Vec { + skills + .into_iter() + .map(|skill| ComposerOption { + kind: ComposerOptionKind::Skill, + id: skill.id.clone(), + title: humanize_token_path(&skill.id), + description: skill.description, + insert_text: format!("/{}", skill.id), + action_kind: ComposerOptionActionKind::InsertText, + action_value: format!("/{}", skill.id), + badges: vec!["skill".to_string(), skill.source.as_tag().to_string()], + keywords: skill_keywords(&skill.id), + }) + .collect() +} + +fn capability_options(state: &AppState) -> Vec { + state + .governance + .capabilities() + .into_iter() + .map(|spec| { + let name = spec.name.to_string(); + ComposerOption { + kind: ComposerOptionKind::Capability, + id: name.clone(), + title: name.clone(), + description: spec.description, + insert_text: name.clone(), + action_kind: ComposerOptionActionKind::InsertText, + action_value: name.clone(), + badges: vec!["capability".to_string()], + keywords: capability_keywords(&name), + } + }) + .collect() +} + +fn describe_command(command_id: &str) -> String { + match command_id { + "compact" => "压缩当前会话上下文".to_string(), + _ => format!("执行 /{command_id} 命令"), + } +} + +fn command_keywords(command_id: &str) -> Vec { + let mut keywords = split_keywords(command_id); + if command_id == "compact" { + keywords.push("compress".to_string()); + } + keywords +} + +fn skill_keywords(skill_id: &str) -> Vec { + split_keywords(skill_id) +} + +fn capability_keywords(capability_name: &str) -> Vec { + let mut keywords = split_keywords(capability_name); + let lowered = capability_name.to_lowercase(); + if !keywords.contains(&lowered) { + keywords.push(lowered); + } + keywords +} + +fn split_keywords(value: &str) -> Vec { + value + .split(['-', '.', '_', '/', ' ']) + .filter(|segment| !segment.is_empty()) + .map(|segment| segment.to_lowercase()) + .collect() +} + +fn humanize_token_path(value: &str) -> String { + let words = value + .split(['-', '.', '_', '/']) + .filter(|segment| !segment.is_empty()) + .map(title_case_token) + .collect::>(); + if words.is_empty() { + value.to_string() + } else { + words.join(" ") + } +} + +fn title_case_token(token: &str) -> String { + let mut chars = token.chars(); + let Some(first) = chars.next() else { + return String::new(); + }; + let rest = chars.as_str(); + if first.is_alphabetic() { + format!("{}{}", first.to_uppercase(), rest) + } else { + format!("{first}{rest}") + } +} + +fn normalize_query(raw: Option<&str>) -> Option { + raw.map(str::trim) + .filter(|value| !value.is_empty()) + .map(|value| value.to_lowercase()) +} + +fn option_matches_query(option: &ComposerOption, query: &str) -> bool { + option.id.to_lowercase().contains(query) + || option.title.to_lowercase().contains(query) + || option.description.to_lowercase().contains(query) + || option + .keywords + .iter() + .any(|keyword| keyword.to_lowercase().contains(query)) +} diff --git a/crates/server/src/http/mapper.rs b/crates/server/src/http/mapper.rs index c0f9d504..04b146af 100644 --- a/crates/server/src/http/mapper.rs +++ b/crates/server/src/http/mapper.rs @@ -19,29 +19,32 @@ //! - **配置相关**：`Config` → `ConfigView`、模型选项解析 //! - **SSE 工具**：事件 ID 解析/格式化（`{storage_seq}.{subindex}` 格式） -use astrcode_application::{ - AgentExecuteSummary, ApplicationError, ComposerOption, Config, ResolvedRuntimeStatusSummary, - SessionCatalogEvent, SessionListSummary, SubRunStatusSourceSummary, SubRunStatusSummary, - SubagentContextOverrides, - config::{ - ResolvedConfigSummary, list_model_options as resolve_model_options, - resolve_current_model as resolve_runtime_current_model, - }, +use astrcode_core::{SessionMeta, format_local_rfc3339}; +use astrcode_host_session::{ + ComposerOption, ComposerOptionActionKind, ComposerOptionKind, SessionCatalogEvent, }; use astrcode_protocol::http::{ - AgentExecuteResponseDto, ComposerOptionsResponseDto, ConfigView, CurrentModelInfoDto, - ModelOptionDto, PROTOCOL_VERSION, ProfileView, ResolvedExecutionLimitsDto, + AgentExecuteResponseDto, ComposerOptionActionKindDto, ComposerOptionDto, ComposerOptionKindDto, + ComposerOptionsResponseDto, ConfigView, CurrentModelInfoDto, ModelOptionDto, PROTOCOL_VERSION, + PluginHealthDto, PluginRuntimeStateDto, ProfileView, ResolvedExecutionLimitsDto, RuntimeCapabilityDto, RuntimePluginDto, RuntimeStatusDto, SessionCatalogEventEnvelope, - SessionListItem, SubRunResultDto, SubRunStatusDto, SubRunStatusSourceDto, - SubagentContextOverridesDto, + SessionCatalogEventPayload, SessionListItem, SubRunResultDto, SubRunStatusDto, + SubRunStatusSourceDto, }; -use axum::{http::StatusCode, response::sse::Event}; +use axum::response::sse::Event; -use crate::ApiError; +use crate::{ + ApiError, + agent_api::{ServerSubRunStatusSource, ServerSubRunStatusSummary}, + config_mode_helpers, + root_execute_service::ServerAgentExecuteSummary, + view_projection::{ + ServerResolvedConfigSummary, ServerResolvedRuntimeStatusSummary, + ServerRuntimeCapabilitySummary, + }, +}; -fn to_runtime_capability_dto( - capability: astrcode_application::RuntimeCapabilitySummary, -) -> RuntimeCapabilityDto { +fn to_runtime_capability_dto(capability: ServerRuntimeCapabilitySummary) -> RuntimeCapabilityDto { RuntimeCapabilityDto { name: capability.name, kind: capability.kind, @@ -51,26 +54,26 @@ fn to_runtime_capability_dto( } } -/// 将会话摘要输入映射为列表项 DTO。 +/// 将会话元数据映射为列表项 DTO。 /// /// 用于 `GET /api/sessions` 和 `POST /api/sessions` 的响应， -/// server 只负责协议包装，不再自行格式化时间字段。 -pub(crate) fn to_session_list_item(summary: SessionListSummary) -> SessionListItem { +/// server 只负责协议包装，catalog 真相来自 `host-session`。 +pub(crate) fn to_session_list_item(meta: SessionMeta) -> SessionListItem { SessionListItem { - session_id: summary.session_id, - working_dir: summary.working_dir, - display_name: summary.display_name, - title: summary.title, - created_at: summary.created_at, - updated_at: summary.updated_at, - parent_session_id: summary.parent_session_id, - parent_storage_seq: summary.parent_storage_seq, - phase: summary.phase, + session_id: meta.session_id, + working_dir: meta.working_dir, + display_name: meta.display_name, + title: meta.title, + created_at: format_local_rfc3339(meta.created_at), + updated_at: format_local_rfc3339(meta.updated_at), + parent_session_id: meta.parent_session_id, + parent_storage_seq: meta.parent_storage_seq, + phase: meta.phase, } } pub(crate) fn to_agent_execute_response_dto( - summary: AgentExecuteSummary, + summary: ServerAgentExecuteSummary, ) -> AgentExecuteResponseDto { AgentExecuteResponseDto { accepted: summary.accepted, @@ -81,13 +84,13 @@ pub(crate) fn to_agent_execute_response_dto( } } -pub(crate) fn to_subrun_status_dto(summary: SubRunStatusSummary) -> SubRunStatusDto { +pub(crate) fn to_subrun_status_dto(summary: ServerSubRunStatusSummary) -> SubRunStatusDto { SubRunStatusDto { sub_run_id: summary.sub_run_id, tool_call_id: summary.tool_call_id, source: match summary.source { - SubRunStatusSourceSummary::Live => SubRunStatusSourceDto::Live, - SubRunStatusSourceSummary::Durable => SubRunStatusSourceDto::Durable, + ServerSubRunStatusSource::Live => SubRunStatusSourceDto::Live, + ServerSubRunStatusSource::Durable => SubRunStatusSourceDto::Durable, }, agent_id: summary.agent_id, agent_profile: summary.agent_profile, @@ -103,7 +106,9 @@ pub(crate) fn to_subrun_status_dto(summary: SubRunStatusSummary) -> SubRunStatus step_count: summary.step_count, estimated_tokens: summary.estimated_tokens, resolved_overrides: summary.resolved_overrides, - resolved_limits: summary.resolved_limits.map(|_| ResolvedExecutionLimitsDto), + resolved_limits: summary + .resolved_limits + .map(|_| ResolvedExecutionLimitsDto {}), } } @@ -111,7 +116,9 @@ pub(crate) fn to_subrun_status_dto(summary: SubRunStatusSummary) -> SubRunStatus /// /// 包含运行时名称、类型、已加载会话数、运行中的会话 ID、 /// 插件搜索路径、运行时指标、能力描述和插件状态。 -pub(crate) fn to_runtime_status_dto(summary: ResolvedRuntimeStatusSummary) -> RuntimeStatusDto { +pub(crate) fn to_runtime_status_dto( + summary: ServerResolvedRuntimeStatusSummary, +) -> RuntimeStatusDto { RuntimeStatusDto { runtime_name: summary.runtime_name, runtime_kind: summary.runtime_kind, @@ -131,8 +138,8 @@ pub(crate) fn to_runtime_status_dto(summary: ResolvedRuntimeStatusSummary) -> Ru name: plugin.name, version: plugin.version, description: plugin.description, - state: plugin.state, - health: plugin.health, + state: to_plugin_runtime_state_dto(plugin.state), + health: to_plugin_health_dto(plugin.health), failure_count: plugin.failure_count, failure: plugin.failure, warnings: plugin.warnings, @@ -147,10 +154,21 @@ pub(crate) fn to_runtime_status_dto(summary: ResolvedRuntimeStatusSummary) -> Ru } } -pub(crate) fn from_subagent_context_overrides_dto( - dto: Option, -) -> Option { - dto +fn to_plugin_runtime_state_dto(state: astrcode_plugin_host::PluginState) -> PluginRuntimeStateDto { + match state { + astrcode_plugin_host::PluginState::Discovered => PluginRuntimeStateDto::Discovered, + astrcode_plugin_host::PluginState::Initialized => PluginRuntimeStateDto::Initialized, + astrcode_plugin_host::PluginState::Failed => PluginRuntimeStateDto::Failed, + } +} + +fn to_plugin_health_dto(health: astrcode_plugin_host::PluginHealth) -> PluginHealthDto { + match health { + astrcode_plugin_host::PluginHealth::Unknown => PluginHealthDto::Unknown, + astrcode_plugin_host::PluginHealth::Healthy => PluginHealthDto::Healthy, + astrcode_plugin_host::PluginHealth::Degraded => PluginHealthDto::Degraded, + astrcode_plugin_host::PluginHealth::Unavailable => PluginHealthDto::Unavailable, + } } /// 将会话目录事件转换为 SSE 事件。 @@ -159,17 +177,19 @@ pub(crate) fn from_subagent_context_overrides_dto( /// 序列化失败时返回 `projectDeleted` 事件并携带错误信息， /// 保证 SSE 流不会中断。 pub(crate) fn to_session_catalog_sse_event(event: SessionCatalogEvent) -> Event { - let payload = - serde_json::to_string(&SessionCatalogEventEnvelope::new(event)).unwrap_or_else(|error| { - serde_json::json!({ - "protocolVersion": PROTOCOL_VERSION, - "event": "projectDeleted", - "data": { - "workingDir": format!("serialization-error: {error}") - } - }) - .to_string() - }); + let payload = serde_json::to_string(&SessionCatalogEventEnvelope::new( + to_session_catalog_event_payload(event), + )) + .unwrap_or_else(|error| { + serde_json::json!({ + "protocolVersion": PROTOCOL_VERSION, + "event": "projectDeleted", + "data": { + "workingDir": format!("serialization-error: {error}") + } + }) + .to_string() + }); Event::default().data(payload) } @@ -177,7 +197,10 @@ pub(crate) fn to_session_catalog_sse_event(event: SessionCatalogEvent) -> Event /// /// server 只负责补充 `config_path` 和协议外层壳， /// 已解析选择、profile 摘要与 API key 预览均由 application 统一提供。 -pub(crate) fn build_config_view(summary: ResolvedConfigSummary, config_path: String) -> ConfigView { +pub(crate) fn build_config_view( + summary: ServerResolvedConfigSummary, + config_path: String, +) -> ConfigView { ConfigView { config_path, active_profile: summary.active_profile, @@ -200,16 +223,19 @@ pub(crate) fn build_config_view(summary: ResolvedConfigSummary, config_path: Str /// /// 从配置中提取当前使用的 profile 名称、模型名称和提供者类型， /// 用于 `GET /api/models/current` 响应。 -pub(crate) fn resolve_current_model(config: &Config) -> Result { - resolve_runtime_current_model(config).map_err(config_selection_error) +pub(crate) fn resolve_current_model( + config: &astrcode_core::Config, +) -> Result { + config_mode_helpers::resolve_current_model(config) + .map_err(|error| ApiError::bad_request(error.to_string())) } /// 列出所有可用的模型选项。 /// /// 遍历配置中所有 profile 的模型，扁平化为列表， /// 用于 `GET /api/models` 响应，前端据此渲染模型选择器。 -pub(crate) fn list_model_options(config: &Config) -> Vec { - resolve_model_options(config) +pub(crate) fn list_model_options(config: &astrcode_core::Config) -> Vec { + config_mode_helpers::list_model_options(config) } /// 将 runtime 输入候选项映射为协议 DTO。 @@ -218,27 +244,62 @@ pub(crate) fn list_model_options(config: &Config) -> Vec { pub(crate) fn to_composer_options_response( items: Vec, ) -> ComposerOptionsResponseDto { - ComposerOptionsResponseDto { items } + ComposerOptionsResponseDto { + items: items.into_iter().map(to_composer_option_dto).collect(), + } } -fn config_selection_error(error: ApplicationError) -> ApiError { - ApiError { - status: StatusCode::BAD_REQUEST, - message: error.to_string(), +fn to_session_catalog_event_payload(event: SessionCatalogEvent) -> SessionCatalogEventPayload { + match event { + SessionCatalogEvent::SessionCreated { session_id } => { + SessionCatalogEventPayload::SessionCreated { session_id } + }, + SessionCatalogEvent::SessionDeleted { session_id } => { + SessionCatalogEventPayload::SessionDeleted { session_id } + }, + SessionCatalogEvent::ProjectDeleted { working_dir } => { + SessionCatalogEventPayload::ProjectDeleted { working_dir } + }, + SessionCatalogEvent::SessionBranched { + session_id, + source_session_id, + } => SessionCatalogEventPayload::SessionBranched { + session_id, + source_session_id, + }, } } -fn to_subrun_result_dto(result: astrcode_application::SubRunResult) -> SubRunResultDto { - match result { - astrcode_application::SubRunResult::Running { handoff } => { - SubRunResultDto::Running { handoff } +fn to_composer_option_dto(option: ComposerOption) -> ComposerOptionDto { + ComposerOptionDto { + kind: match option.kind { + ComposerOptionKind::Command => ComposerOptionKindDto::Command, + ComposerOptionKind::Skill => ComposerOptionKindDto::Skill, + ComposerOptionKind::Capability => ComposerOptionKindDto::Capability, }, - astrcode_application::SubRunResult::Completed { outcome, handoff } => match outcome { + id: option.id, + title: option.title, + description: option.description, + insert_text: option.insert_text, + action_kind: match option.action_kind { + ComposerOptionActionKind::InsertText => ComposerOptionActionKindDto::InsertText, + ComposerOptionActionKind::ExecuteCommand => ComposerOptionActionKindDto::ExecuteCommand, + }, + action_value: option.action_value, + badges: option.badges, + keywords: option.keywords, + } +} + +fn to_subrun_result_dto(result: astrcode_core::SubRunResult) -> SubRunResultDto { + match result { + astrcode_core::SubRunResult::Running { handoff } => SubRunResultDto::Running { handoff }, + astrcode_core::SubRunResult::Completed { outcome, handoff } => match outcome { astrcode_core::CompletedSubRunOutcome::Completed => { SubRunResultDto::Completed { handoff } }, }, - astrcode_application::SubRunResult::Failed { outcome, failure } => match outcome { + astrcode_core::SubRunResult::Failed { outcome, failure } => match outcome { astrcode_core::FailedSubRunOutcome::Failed => SubRunResultDto::Failed { failure }, astrcode_core::FailedSubRunOutcome::Cancelled => SubRunResultDto::Cancelled { failure }, }, diff --git a/crates/server/src/http/routes/agents.rs b/crates/server/src/http/routes/agents.rs index 66370d45..2495630d 100644 --- a/crates/server/src/http/routes/agents.rs +++ b/crates/server/src/http/routes/agents.rs @@ -1,14 +1,12 @@ //! # Agent 路由 //! //! 提供 Agent Profile 查询、根执行入口和子会话状态查询。 -//! 所有路由通过 `App` 的稳定用例接口访问，不直接依赖 kernel 内部结构。 +//! 所有路由通过 server-owned bridge 访问，不直接依赖 kernel 内部结构。 use std::path::PathBuf; -use astrcode_application::{AgentExecuteSummary, RootExecutionRequest}; use astrcode_protocol::http::{ - AgentExecuteRequestDto, AgentExecuteResponseDto, AgentProfileDto, ExecutionControlDto, - SubRunStatusDto, + AgentExecuteRequestDto, AgentExecuteResponseDto, AgentProfileDto, SubRunStatusDto, }; use axum::{ Json, @@ -20,25 +18,18 @@ use serde::Serialize; use crate::{ ApiError, AppState, auth::require_auth, - mapper::{ - from_subagent_context_overrides_dto, to_agent_execute_response_dto, to_subrun_status_dto, - }, + mapper::{to_agent_execute_response_dto, to_subrun_status_dto}, + root_execute_service::{ServerAgentExecuteSummary, ServerRootExecutionRequest}, routes::sessions, }; -fn to_execution_control( - control: Option, -) -> Option { - control -} - pub(crate) async fn list_agents( State(state): State, headers: HeaderMap, ) -> Result>, ApiError> { require_auth(&state, &headers, None)?; let profiles = state - .app + .agent_api .list_global_agent_profiles() .map_err(ApiError::from)? .into_iter() @@ -57,15 +48,15 @@ pub(crate) async fn execute_agent( .working_dir .map(PathBuf::from) .ok_or_else(|| ApiError::bad_request("workingDir is required".to_string()))?; - let summary: AgentExecuteSummary = state - .app - .execute_root_agent_summary(RootExecutionRequest { + let summary: ServerAgentExecuteSummary = state + .agent_api + .execute_root_agent_summary(ServerRootExecutionRequest { agent_id: agent_id.clone(), working_dir: working_dir.to_string_lossy().to_string(), task: request.task, context: request.context, - control: to_execution_control(request.control), - context_overrides: from_subagent_context_overrides_dto(request.context_overrides), + control: request.control, + context_overrides: request.context_overrides, }) .await .map_err(ApiError::from)?; @@ -83,7 +74,7 @@ pub(crate) async fn get_subrun_status( require_auth(&state, &headers, None)?; let session_id = sessions::validate_session_path_id(&session_id)?; let summary = state - .app + .agent_api .get_subrun_status_summary(&session_id, &sub_run_id) .await .map_err(ApiError::from)?; @@ -101,7 +92,7 @@ pub(crate) async fn close_agent( require_auth(&state, &headers, None)?; let session_id = sessions::validate_session_path_id(&session_id)?; let result = state - .app + .agent_api .close_agent(&session_id, &agent_id) .await .map_err(ApiError::from)?; diff --git a/crates/server/src/http/routes/composer.rs b/crates/server/src/http/routes/composer.rs index ed95ce2b..19852e8a 100644 --- a/crates/server/src/http/routes/composer.rs +++ b/crates/server/src/http/routes/composer.rs @@ -3,7 +3,7 @@ //! 该接口服务于前端输入框的自动展开面板，返回已经过 runtime 统一投影的候选项。 //! 它故意不直接暴露 `SkillSpec` / `CapabilityWireDescriptor`，避免 UI 反向理解内部装配细节。 -use astrcode_application::{ComposerOptionKind, ComposerOptionsRequest}; +use astrcode_host_session::ComposerOptionKind; use astrcode_protocol::http::ComposerOptionsResponseDto; use axum::{ Json, @@ -13,8 +13,8 @@ use axum::{ use serde::Deserialize; use crate::{ - ApiError, AppState, auth::require_auth, mapper::to_composer_options_response, - routes::sessions::validate_session_path_id, + ApiError, AppState, auth::require_auth, composer_catalog::list_session_composer_options, + mapper::to_composer_options_response, routes::sessions::validate_session_path_id, }; /// 输入候选查询参数。 @@ -38,20 +38,15 @@ pub(crate) async fn session_composer_options( require_auth(&state, &headers, None)?; let _session_id = validate_session_path_id(&session_id)?; let requested_kinds = parse_composer_option_kinds(query.kinds.as_deref())?; - let items = state - .app - .list_composer_options( - &session_id, - ComposerOptionsRequest { - query: query.q, - kinds: requested_kinds, - // 候选面板是交互式 UI，单次响应保持上限可以避免把全部 surface - // 一股脑推给前端造成首屏抖动。 - limit: 50, - }, - ) - .await - .map_err(ApiError::from)?; + let items = list_session_composer_options( + &state, + &session_id, + query.q.as_deref(), + &requested_kinds, + 50, + ) + .await + .map_err(ApiError::from)?; Ok(Json(to_composer_options_response(items))) } diff --git a/crates/server/src/http/routes/config.rs b/crates/server/src/http/routes/config.rs index b289611d..1db20dc5 100644 --- a/crates/server/src/http/routes/config.rs +++ b/crates/server/src/http/routes/config.rs @@ -4,9 +4,6 @@ //! - `GET /api/config` — 获取配置视图（含 profile 列表和当前选择） //! - `POST /api/config/active-selection` — 保存活跃的 profile/model 选择 -use astrcode_application::{ - config::resolve_config_summary, format_local_rfc3339, resolve_runtime_status_summary, -}; use astrcode_protocol::http::{ConfigReloadResponse, ConfigView, SaveActiveSelectionRequest}; use axum::{ Json, @@ -18,6 +15,7 @@ use crate::{ ApiError, AppState, auth::require_auth, mapper::{build_config_view, to_runtime_status_dto}, + view_projection::{resolve_server_config_summary, resolve_server_runtime_status_summary}, }; /// 获取当前配置视图。 @@ -29,14 +27,9 @@ pub(crate) async fn get_config( headers: HeaderMap, ) -> Result, ApiError> { require_auth(&state, &headers, None)?; - let config = state.app.config().get_config().await; - let config_path = state - .app - .config() - .config_path() - .to_string_lossy() - .to_string(); - let summary = resolve_config_summary(&config).map_err(ApiError::from)?; + let config = state.config.get_config().await; + let config_path = state.config.config_path().to_string_lossy().to_string(); + let summary = resolve_server_config_summary(&config).map_err(ApiError::bad_request)?; Ok(Json(build_config_view(summary, config_path))) } @@ -52,8 +45,7 @@ pub(crate) async fn save_active_selection( ) -> Result { require_auth(&state, &headers, None)?; state - .app - .config() + .config .save_active_selection(request.active_profile, request.active_model) .await .map_err(ApiError::from)?; @@ -70,22 +62,17 @@ pub(crate) async fn reload_config( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; let reloaded = state.governance.reload().await.map_err(ApiError::from)?; - let config = state.app.config().get_config().await; - let summary = resolve_config_summary(&config).map_err(ApiError::from)?; - let config_path = state - .app - .config() - .config_path() - .to_string_lossy() - .to_string(); + let config = state.config.get_config().await; + let summary = resolve_server_config_summary(&config).map_err(ApiError::bad_request)?; + let config_path = state.config.config_path().to_string_lossy().to_string(); let config_view = build_config_view(summary, config_path); Ok(( StatusCode::ACCEPTED, Json(ConfigReloadResponse { - reloaded_at: format_local_rfc3339(reloaded.reloaded_at), + reloaded_at: astrcode_core::format_local_rfc3339(reloaded.reloaded_at), config: config_view, - status: to_runtime_status_dto(resolve_runtime_status_summary(reloaded.snapshot)), + status: to_runtime_status_dto(resolve_server_runtime_status_summary(reloaded.snapshot)), }), )) } diff --git a/crates/server/src/http/routes/conversation.rs b/crates/server/src/http/routes/conversation.rs index 4dbe1a2f..205695b1 100644 --- a/crates/server/src/http/routes/conversation.rs +++ b/crates/server/src/http/routes/conversation.rs @@ -1,15 +1,12 @@ -use std::{convert::Infallible, pin::Pin, time::Duration}; - -use astrcode_application::{ - ApplicationError, - terminal::{ - ConversationAuthoritativeSummary, ConversationChildSummarySummary, - ConversationControlSummary, ConversationFocus, ConversationSlashCandidateSummary, - ConversationStreamProjector, TerminalStreamFacts, TerminalStreamReplayFacts, - summarize_conversation_authoritative, - }, +use std::{ + convert::Infallible, + path::{Path as FsPath, PathBuf}, + pin::Pin, + time::Duration, }; -use astrcode_core::AgentEvent; + +use astrcode_core::{AgentEvent, Phase, SessionId}; +use astrcode_host_session::ComposerOptionKind; use astrcode_protocol::http::conversation::v1::{ ConversationDeltaDto, ConversationSlashCandidatesResponseDto, ConversationSnapshotResponseDto, ConversationStreamEnvelopeDto, @@ -29,14 +26,27 @@ use serde_json::Value; use crate::{ AppState, + application_error_bridge::ServerRouteError, auth::is_authorized, + composer_catalog::list_session_composer_options, + conversation_read_model::{ + ConversationReplayStream, ConversationStreamProjector, ConversationStreamReplayFacts, + ROOT_AGENT_ID, + }, routes::sessions::validate_session_path_id, terminal_projection::{ - child_summary_summary_lookup, project_conversation_child_summary_summary_deltas, + ConversationAuthoritativeSummary, ConversationChildSummarySummary, + ConversationControlSummary, ConversationFocus, ConversationSlashCandidateSummary, + TaskItemFacts, TerminalChildSummaryFacts, TerminalControlFacts, TerminalFacts, + TerminalRehydrateFacts, TerminalRehydrateReason, TerminalSlashAction, + TerminalSlashCandidateFacts, TerminalStreamFacts, TerminalStreamReplayFacts, + build_conversation_replay_frames, build_conversation_snapshot, + child_summary_summary_lookup, latest_terminal_summary, map_control_facts, + project_conversation_child_summary_summary_deltas, project_conversation_control_summary_delta, project_conversation_frame, project_conversation_rehydrate_envelope, project_conversation_slash_candidate_summaries, project_conversation_slash_candidates, project_conversation_snapshot, - project_conversation_step_progress, + project_conversation_step_progress, summarize_conversation_authoritative, }, }; @@ -97,43 +107,29 @@ impl ConversationRouteError { } } -impl IntoResponse for ConversationRouteError { - fn into_response(self) -> Response { - ( - self.status, - Json(ConversationRouteErrorPayload { - code: self.code, - message: self.message, - details: self.details, - }), - ) - .into_response() - } -} - -impl From for ConversationRouteError { - fn from(value: ApplicationError) -> Self { +impl From for ConversationRouteError { + fn from(value: ServerRouteError) -> Self { match value { - ApplicationError::NotFound(message) => Self { + ServerRouteError::NotFound(message) => Self { status: StatusCode::NOT_FOUND, code: "not_found", message, details: None, }, - ApplicationError::Conflict(message) => Self { + ServerRouteError::Conflict(message) => Self { status: StatusCode::CONFLICT, code: "conflict", message, details: None, }, - ApplicationError::InvalidArgument(message) => Self::invalid_request(message, None), - ApplicationError::PermissionDenied(message) => Self { + ServerRouteError::InvalidArgument(message) => Self::invalid_request(message, None), + ServerRouteError::PermissionDenied(message) => Self { status: StatusCode::FORBIDDEN, code: "forbidden", message, details: None, }, - ApplicationError::Internal(message) => Self { + ServerRouteError::Internal(message) => Self { status: StatusCode::INTERNAL_SERVER_ERROR, code: "internal_error", message, @@ -143,6 +139,20 @@ impl From for ConversationRouteError { } } +impl IntoResponse for ConversationRouteError { + fn into_response(self) -> Response { + ( + self.status, + Json(ConversationRouteErrorPayload { + code: self.code, + message: self.message, + details: self.details, + }), + ) + .into_response() + } +} + pub(crate) async fn conversation_snapshot( State(state): State, headers: HeaderMap, @@ -153,11 +163,7 @@ pub(crate) async fn conversation_snapshot( let session_id = validate_session_path_id(&session_id) .map_err(|error| ConversationRouteError::invalid_request(error.message, None))?; let focus = parse_focus_query(query.focus.as_deref())?; - let facts = state - .app - .conversation_snapshot_facts(&session_id, focus) - .await - .map_err(ConversationRouteError::from)?; + let facts = build_terminal_snapshot_facts(&state, &session_id, &focus).await?; Ok(Json(project_conversation_snapshot(&facts))) } @@ -178,11 +184,8 @@ pub(crate) async fn conversation_stream( .map(|value| value.to_string()) .or(query.cursor); - let stream_facts = state - .app - .conversation_stream_facts(&session_id, cursor.as_deref(), focus.clone()) - .await - .map_err(ConversationRouteError::from)?; + let stream_facts = + build_terminal_stream_facts(&state, &session_id, cursor.as_deref(), &focus).await?; match stream_facts { TerminalStreamFacts::Replay(facts) => Ok(build_conversation_stream( @@ -203,11 +206,7 @@ pub(crate) async fn conversation_slash_candidates( require_conversation_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id) .map_err(|error| ConversationRouteError::invalid_request(error.message, None))?; - let candidates = state - .app - .terminal_slash_candidates(&session_id, query.q.as_deref()) - .await - .map_err(ConversationRouteError::from)?; + let candidates = terminal_slash_candidates(&state, &session_id, query.q.as_deref()).await?; Ok(Json(project_conversation_slash_candidates(&candidates))) } @@ -236,7 +235,6 @@ fn build_conversation_stream( let initial_envelopes = stream_state.seed_initial_replay(&facts); let mut durable_receiver = facts.stream.receiver; let mut live_receiver = facts.stream.live_receiver; - let app = state.app.clone(); let session_id_for_stream = session_id.clone(); let mut live_receiver_open = true; @@ -256,7 +254,7 @@ fn build_conversation_stream( } let Ok(refreshed_facts) = refresh_conversation_authoritative_facts( - &app, + &state, &session_id_for_stream, &focus, ).await else { @@ -279,14 +277,12 @@ fn build_conversation_stream( skipped, session_id_for_stream ); - match app - .conversation_stream_facts( - &session_id_for_stream, - stream_state.last_sent_cursor(), - focus.clone(), - ) - .await - { + match build_terminal_stream_facts( + &state, + &session_id_for_stream, + stream_state.last_sent_cursor(), + &focus, + ).await { Ok(TerminalStreamFacts::Replay(recovered)) => { for envelope in stream_state.recover_from(&recovered) { yield Ok::(to_conversation_sse_event(envelope)); @@ -303,7 +299,7 @@ fn build_conversation_stream( } Err(error) => { log::warn!( - "conversation stream recovery failed for session '{}': {}", + "conversation stream recovery failed for session '{}': {:?}", session_id_for_stream, error ); @@ -419,7 +415,8 @@ impl ConversationStreamProjectorState { } fn project_live_event(&mut self, event: &AgentEvent) -> Vec { - self.projector + let mut envelopes = self + .projector .project_live_event(event) .into_iter() .map(|frame| { @@ -429,7 +426,42 @@ impl ConversationStreamProjectorState { &child_summary_summary_lookup(&self.authoritative.child_summaries), ) }) - .collect() + .collect::>(); + if let Some(control) = self.live_control_overlay(event) { + let cursor = self + .projector + .last_sent_cursor() + .unwrap_or("0.0") + .to_string(); + envelopes.extend(self.wrap_durable_deltas( + cursor.as_str(), + vec![project_conversation_control_summary_delta(&control)], + )); + } + envelopes + } + + fn live_control_overlay(&self, event: &AgentEvent) -> Option { + let (phase, active_turn_id) = match event { + AgentEvent::ThinkingDelta { turn_id, .. } + | AgentEvent::ModelDelta { turn_id, .. } + | AgentEvent::StreamRetryStarted { turn_id, .. } => { + (Phase::Streaming, Some(turn_id.clone())) + }, + AgentEvent::ToolCallStart { turn_id, .. } + | AgentEvent::ToolCallDelta { turn_id, .. } + | AgentEvent::ToolCallResult { turn_id, .. } => { + (Phase::CallingTool, Some(turn_id.clone())) + }, + AgentEvent::TurnDone { .. } | AgentEvent::Error { .. } => (Phase::Idle, None), + _ => return None, + }; + let mut control = self.authoritative.control.clone(); + control.phase = phase; + control.active_turn_id = active_turn_id; + control.can_submit_prompt = control.active_turn_id.is_none() + && matches!(phase, Phase::Idle | Phase::Done | Phase::Interrupted); + Some(control) } fn apply_authoritative_refresh( @@ -492,7 +524,8 @@ impl ConversationStreamProjectorState { return Vec::new(); } let cursor_owned = cursor.to_string(); - let step_progress = project_conversation_step_progress(self.projector.step_progress()); + let step_progress = + project_conversation_step_progress(self.projector.step_progress().clone()); deltas .into_iter() .map(|delta| { @@ -508,16 +541,509 @@ impl ConversationStreamProjectorState { } async fn refresh_conversation_authoritative_facts( - app: &astrcode_application::App, + state: &AppState, session_id: &str, focus: &ConversationFocus, -) -> Result { +) -> Result { + let control = terminal_control_facts(state, session_id).await?; + let child_summaries = conversation_child_summaries(state, session_id, focus).await?; + let slash_candidates = terminal_slash_candidates(state, session_id, None).await?; Ok(ConversationAuthoritativeFacts::from_summary( - app.conversation_authoritative_summary(session_id, focus) - .await?, + summarize_conversation_authoritative(&control, &child_summaries, &slash_candidates), )) } +async fn build_terminal_snapshot_facts( + state: &AppState, + session_id: &str, + focus: &ConversationFocus, +) -> Result { + let focus_session_id = resolve_conversation_focus_session_id(state, session_id, focus).await?; + let focus_session = state + .session_catalog + .ensure_loaded_session(&SessionId::from(focus_session_id.clone())) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let transcript = build_conversation_snapshot( + &state + .session_catalog + .conversation_stream_replay(&SessionId::from(focus_session_id.clone()), None) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + .history, + focus_session.state.current_phase().map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?, + ); + let session_title = session_title(state, session_id).await?; + let control = terminal_control_facts(state, session_id).await?; + let child_summaries = conversation_child_summaries(state, session_id, focus).await?; + let slash_candidates = terminal_slash_candidates(state, session_id, None).await?; + + Ok(TerminalFacts { + active_session_id: session_id.to_string(), + session_title, + transcript, + control, + child_summaries, + slash_candidates, + }) +} + +async fn build_terminal_stream_facts( + state: &AppState, + session_id: &str, + last_event_id: Option<&str>, + focus: &ConversationFocus, +) -> Result { + let focus_session_id = resolve_conversation_focus_session_id(state, session_id, focus).await?; + if let Some(requested_cursor) = last_event_id { + validate_cursor_format(requested_cursor)?; + let records = state + .session_catalog + .conversation_stream_replay(&SessionId::from(focus_session_id.clone()), None) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + .history; + let latest_cursor = records.last().map(|record| record.event_id.clone()); + let cursor_missing_from_transcript = !records + .iter() + .any(|record| record.event_id == requested_cursor); + if cursor_is_after_head(requested_cursor, latest_cursor.as_deref())? + || cursor_missing_from_transcript + { + return Ok(TerminalStreamFacts::RehydrateRequired( + TerminalRehydrateFacts { + session_id: session_id.to_string(), + requested_cursor: requested_cursor.to_string(), + latest_cursor, + reason: TerminalRehydrateReason::CursorExpired, + }, + )); + } + } + + let replay = state + .session_catalog + .conversation_stream_replay(&SessionId::from(focus_session_id.clone()), last_event_id) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let loaded = state + .session_catalog + .ensure_loaded_session(&SessionId::from(focus_session_id)) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let phase = loaded.state.current_phase().map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let replay_history = replay.history.clone(); + let seed_records = replay.seed_records.clone(); + let replay_facts = ConversationStreamReplayFacts { + cursor: replay.cursor.clone(), + phase, + seed_records: seed_records.clone(), + replay_frames: build_conversation_replay_frames(&seed_records, &replay_history), + replay_history: replay_history.clone(), + }; + let control = terminal_control_facts(state, session_id).await?; + let child_summaries = conversation_child_summaries(state, session_id, focus).await?; + let slash_candidates = terminal_slash_candidates(state, session_id, None).await?; + + Ok(TerminalStreamFacts::Replay(Box::new( + TerminalStreamReplayFacts { + replay: replay_facts, + stream: ConversationReplayStream { + receiver: loaded.state.broadcaster.subscribe(), + live_receiver: loaded.state.subscribe_live(), + }, + control, + child_summaries, + slash_candidates, + }, + ))) +} + +async fn session_title( + state: &AppState, + session_id: &str, +) -> Result { + state + .session_catalog + .list_session_metas() + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + .into_iter() + .find(|meta| meta.session_id == session_id) + .map(|meta| meta.title) + .ok_or_else(|| { + ConversationRouteError::from(ServerRouteError::not_found(format!( + "session '{}' not found", + session_id + ))) + }) +} + +async fn terminal_control_facts( + state: &AppState, + session_id: &str, +) -> Result { + let session_id = SessionId::from(session_id.to_string()); + let mut facts = map_control_facts( + state + .session_catalog + .session_control_state(&session_id) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?, + ); + let loaded = state + .session_catalog + .ensure_loaded_session(&session_id) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + facts.active_tasks = state + .session_catalog + .active_task_snapshot(&session_id, ROOT_AGENT_ID) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + .map(|snapshot| { + snapshot + .items + .into_iter() + .map(|item| TaskItemFacts { + content: item.content, + status: item.status, + active_form: item.active_form, + }) + .collect() + }); + facts.active_plan = active_plan_reference(session_id.as_str(), &loaded.working_dir) + .map_err(ConversationRouteError::from)?; + Ok(facts) +} + +async fn conversation_child_summaries( + state: &AppState, + root_session_id: &str, + focus: &ConversationFocus, +) -> Result, ConversationRouteError> { + let focus_session_id = + resolve_conversation_focus_session_id(state, root_session_id, focus).await?; + let children = state + .session_catalog + .session_child_nodes(&SessionId::from(focus_session_id.clone())) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let session_metas = state + .session_catalog + .list_session_metas() + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + + let mut resolved = Vec::new(); + for node in children + .into_iter() + .filter(|node| node.parent_sub_run_id().is_none()) + { + if node.parent_session_id.as_str() != focus_session_id { + return Err(ConversationRouteError::from( + ServerRouteError::permission_denied(format!( + "child '{}' is not visible from session '{}'", + node.sub_run_id(), + focus_session_id + )), + )); + } + let child_meta = session_metas + .iter() + .find(|meta| meta.session_id == node.child_session_id.as_str()); + let child_session_id = SessionId::from(node.child_session_id.to_string()); + let child_loaded = state + .session_catalog + .ensure_loaded_session(&child_session_id) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?; + let child_transcript = build_conversation_snapshot( + &state + .session_catalog + .conversation_stream_replay(&child_session_id, None) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + .history, + child_loaded.state.current_phase().map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })?, + ); + resolved.push(TerminalChildSummaryFacts { + node, + phase: child_transcript.phase, + title: child_meta.map(|meta| meta.title.clone()), + display_name: child_meta.map(|meta| meta.display_name.clone()), + recent_output: latest_terminal_summary(&child_transcript), + }); + } + resolved.sort_by(|left, right| left.node.sub_run_id().cmp(right.node.sub_run_id())); + Ok(resolved) +} + +async fn terminal_slash_candidates( + state: &AppState, + session_id: &str, + query: Option<&str>, +) -> Result, ConversationRouteError> { + let query = normalize_query(query); + let control = terminal_control_facts(state, session_id).await?; + let mut candidates = terminal_builtin_candidates(&control); + candidates.extend( + list_session_composer_options( + state, + session_id, + query.as_deref(), + &[ComposerOptionKind::Skill], + 50, + ) + .await + .map_err(ConversationRouteError::from)? + .into_iter() + .map(|option| TerminalSlashCandidateFacts { + id: option.id.clone(), + title: option.title, + description: option.description, + keywords: option.keywords, + badges: option.badges, + action: TerminalSlashAction::InsertText { + text: format!("/{}", option.id), + }, + }), + ); + + if let Some(query) = query.as_deref() { + candidates.retain(|candidate| slash_candidate_matches(candidate, query)); + } + + Ok(candidates) +} + +async fn resolve_conversation_focus_session_id( + state: &AppState, + root_session_id: &str, + focus: &ConversationFocus, +) -> Result { + match focus { + ConversationFocus::Root => Ok(root_session_id.to_string()), + ConversationFocus::SubRun { sub_run_id } => { + let mut pending = vec![root_session_id.to_string()]; + let mut visited = std::collections::HashSet::new(); + + while let Some(session_id) = pending.pop() { + if !visited.insert(session_id.clone()) { + continue; + } + for node in state + .session_catalog + .session_child_nodes(&SessionId::from(session_id.clone())) + .await + .map_err(|error| { + ConversationRouteError::from(ServerRouteError::internal(error.to_string())) + })? + { + if node.sub_run_id().as_str() == sub_run_id { + return Ok(node.child_session_id.to_string()); + } + pending.push(node.child_session_id.to_string()); + } + } + + Err(ConversationRouteError::from(ServerRouteError::not_found( + format!( + "sub-run '{}' not found under session '{}'", + sub_run_id, root_session_id + ), + ))) + }, + } +} + +fn normalize_query(query: Option<&str>) -> Option { + query + .map(str::trim) + .filter(|query| !query.is_empty()) + .map(|query| query.to_lowercase()) +} + +fn terminal_builtin_candidates(control: &TerminalControlFacts) -> Vec { + let mut candidates = vec![ + TerminalSlashCandidateFacts { + id: "new".to_string(), + title: "新建会话".to_string(), + description: "创建新 session 并切换焦点".to_string(), + keywords: vec!["new".to_string(), "session".to_string()], + badges: vec!["built-in".to_string()], + action: TerminalSlashAction::CreateSession, + }, + TerminalSlashCandidateFacts { + id: "resume".to_string(), + title: "恢复会话".to_string(), + description: "搜索并切换到已有 session".to_string(), + keywords: vec!["resume".to_string(), "switch".to_string()], + badges: vec!["built-in".to_string()], + action: TerminalSlashAction::OpenResume, + }, + ]; + + if !control.manual_compact_pending && !control.compacting { + candidates.push(TerminalSlashCandidateFacts { + id: "compact".to_string(), + title: "压缩上下文".to_string(), + description: "向服务端提交显式 compact 控制请求".to_string(), + keywords: vec!["compact".to_string(), "compress".to_string()], + badges: vec!["built-in".to_string()], + action: TerminalSlashAction::RequestCompact, + }); + } + candidates +} + +fn slash_candidate_matches(candidate: &TerminalSlashCandidateFacts, query: &str) -> bool { + candidate.id.to_lowercase().contains(query) + || candidate.title.to_lowercase().contains(query) + || candidate.description.to_lowercase().contains(query) + || candidate + .keywords + .iter() + .any(|keyword| keyword.to_lowercase().contains(query)) +} + +fn validate_cursor_format(cursor: &str) -> Result<(), ConversationRouteError> { + let Some((storage_seq, subindex)) = cursor.split_once('.') else { + return Err(ConversationRouteError::invalid_request( + format!("invalid cursor '{cursor}'"), + None, + )); + }; + if storage_seq.parse::().is_err() || subindex.parse::().is_err() { + return Err(ConversationRouteError::invalid_request( + format!("invalid cursor '{cursor}'"), + None, + )); + } + Ok(()) +} + +fn cursor_is_after_head( + requested_cursor: &str, + latest_cursor: Option<&str>, +) -> Result { + let Some(latest_cursor) = latest_cursor else { + return Ok(false); + }; + Ok(parse_cursor(requested_cursor)? > parse_cursor(latest_cursor)?) +} + +fn parse_cursor(cursor: &str) -> Result<(u64, u32), ConversationRouteError> { + let (storage_seq, subindex) = cursor.split_once('.').ok_or_else(|| { + ConversationRouteError::invalid_request(format!("invalid cursor '{cursor}'"), None) + })?; + let storage_seq = storage_seq.parse::().map_err(|_| { + ConversationRouteError::invalid_request(format!("invalid cursor '{cursor}'"), None) + })?; + let subindex = subindex.parse::().map_err(|_| { + ConversationRouteError::invalid_request(format!("invalid cursor '{cursor}'"), None) + })?; + Ok((storage_seq, subindex)) +} + +fn active_plan_reference( + session_id: &str, + working_dir: &FsPath, +) -> Result, ServerRouteError> { + let Some(state) = load_session_plan_state(session_id, working_dir)? else { + return Ok(None); + }; + Ok(Some(crate::terminal_projection::PlanReferenceFacts { + slug: state.active_plan_slug.clone(), + path: session_plan_markdown_path(session_id, working_dir, &state.active_plan_slug)? + .display() + .to_string(), + status: state.status.to_string(), + title: state.title, + })) +} + +fn load_session_plan_state( + session_id: &str, + working_dir: &FsPath, +) -> Result, ServerRouteError> { + let path = session_plan_state_path(session_id, working_dir)?; + if !path.exists() { + return Ok(None); + } + let content = std::fs::read_to_string(&path).map_err(|error| { + ServerRouteError::internal(format!("reading '{}' failed: {error}", path.display())) + })?; + serde_json::from_str::(&content) + .map(Some) + .map_err(|error| { + ServerRouteError::internal(format!( + "failed to parse session plan state '{}': {error}", + path.display() + )) + }) +} + +fn session_plan_state_path( + session_id: &str, + working_dir: &FsPath, +) -> Result { + Ok(session_plan_dir(session_id, working_dir)?.join("state.json")) +} + +fn session_plan_markdown_path( + session_id: &str, + working_dir: &FsPath, + slug: &str, +) -> Result { + Ok(session_plan_dir(session_id, working_dir)?.join(format!("{slug}.md"))) +} + +fn session_plan_dir(session_id: &str, working_dir: &FsPath) -> Result { + Ok(astrcode_support::hostpaths::project_dir(working_dir) + .map_err(|error| { + ServerRouteError::internal(format!( + "failed to resolve project directory for '{}': {error}", + working_dir.display() + )) + })? + .join("sessions") + .join(session_id) + .join("plan")) +} + fn single_envelope_stream(envelope: ConversationStreamEnvelopeDto) -> ConversationSse { let event_stream = stream! { yield Ok::(to_conversation_sse_event(envelope)); @@ -593,24 +1119,27 @@ type ConversationSse = Sse, history: Vec, @@ -838,7 +1404,6 @@ mod tests { let (_, live_receiver) = broadcast::channel(8); TerminalStreamReplayFacts { - active_session_id: "session-root".to_string(), replay: ConversationStreamReplayFacts { cursor: history.last().map(|record| record.event_id.clone()), phase: Phase::CallingTool, @@ -854,16 +1419,16 @@ mod tests { stream, delta, .. - } => ConversationDeltaFacts::PatchBlock { + } => ConversationDeltaFacts::Patch { block_id: format!("tool:{tool_call_id}:call"), patch: ConversationBlockPatchFacts::AppendToolStream { stream: *stream, chunk: delta.clone(), }, }, - _ => ConversationDeltaFacts::AppendBlock { + _ => ConversationDeltaFacts::Append { block: Box::new(ConversationBlockFacts::User( - astrcode_application::terminal::ConversationUserBlockFacts { + ConversationUserBlockFacts { id: "noop".to_string(), turn_id: None, markdown: String::new(), @@ -873,10 +1438,9 @@ mod tests { }, }) .collect(), - history: history.clone(), + replay_history: history.clone(), }, - stream: SessionReplay { - history, + stream: ConversationReplayStream { receiver, live_receiver, }, @@ -933,4 +1497,22 @@ mod tests { event, } } + + fn live_control_json( + envelopes: &[ConversationStreamEnvelopeDto], + ) -> serde_json::Map { + envelopes + .iter() + .map(|envelope| { + serde_json::to_value(envelope).expect("conversation envelope should encode") + }) + .find_map(|value| { + if value["kind"] == json!("update_control_state") { + value.as_object().cloned() + } else { + None + } + }) + .expect("live event should include control overlay") + } } diff --git a/crates/server/src/http/routes/mcp.rs b/crates/server/src/http/routes/mcp.rs index f415795c..7a872856 100644 --- a/crates/server/src/http/routes/mcp.rs +++ b/crates/server/src/http/routes/mcp.rs @@ -2,9 +2,6 @@ //! //! 提供 MCP 状态查询、审批，以及服务端配置管理入口。 -use astrcode_application::{ - McpActionSummary, McpConfigScope, McpServerStatusSummary, RegisterMcpServerInput, -}; use axum::{ Json, extract::State, @@ -12,7 +9,14 @@ use axum::{ }; use serde::{Deserialize, Serialize}; -use crate::{ApiError, AppState, auth::require_auth}; +use crate::{ + ApiError, AppState, + auth::require_auth, + mcp_service::{ + ServerMcpActionSummary, ServerMcpConfigScope, ServerMcpServerStatusSummary, + ServerRegisterMcpServerInput, + }, +}; #[derive(Debug, Serialize)] #[serde(rename_all = "camelCase")] @@ -92,8 +96,7 @@ pub(crate) async fn get_mcp_status( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; let servers = state - .app - .mcp() + .mcp_service .list_status_summary() .await .into_iter() @@ -109,8 +112,7 @@ pub(crate) async fn approve_mcp_server( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .approve_server(&request.server_signature) .await .map_err(ApiError::from)?; @@ -124,8 +126,7 @@ pub(crate) async fn reject_mcp_server( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .reject_server(&request.server_signature) .await .map_err(ApiError::from)?; @@ -139,8 +140,7 @@ pub(crate) async fn reconnect_mcp_server( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .reconnect_server(&request.name) .await .map_err(ApiError::from)?; @@ -153,8 +153,7 @@ pub(crate) async fn reset_project_mcp_choices( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .reset_project_choices() .await .map_err(ApiError::from)?; @@ -167,7 +166,7 @@ pub(crate) async fn upsert_mcp_server( Json(request): Json, ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; - let input = RegisterMcpServerInput { + let input = ServerRegisterMcpServerInput { name: request.name, scope: parse_scope(&request.scope)?, enabled: request.enabled.unwrap_or(true), @@ -177,8 +176,7 @@ pub(crate) async fn upsert_mcp_server( transport_config: request.transport, }; state - .app - .mcp() + .mcp_service .upsert_config(input) .await .map_err(ApiError::from)?; @@ -192,8 +190,7 @@ pub(crate) async fn remove_mcp_server( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .remove_config(parse_scope(&request.scope)?, &request.name) .await .map_err(ApiError::from)?; @@ -207,8 +204,7 @@ pub(crate) async fn set_mcp_server_enabled( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; state - .app - .mcp() + .mcp_service .set_enabled(parse_scope(&request.scope)?, &request.name, request.enabled) .await .map_err(ApiError::from)?; @@ -216,7 +212,7 @@ pub(crate) async fn set_mcp_server_enabled( } fn ok_response(status: StatusCode) -> (StatusCode, Json) { - let summary = McpActionSummary::ok(); + let summary = ServerMcpActionSummary::ok(); ( status, Json(McpActionResponse { @@ -226,11 +222,11 @@ fn ok_response(status: StatusCode) -> (StatusCode, Json) { ) } -fn parse_scope(scope: &str) -> Result { +fn parse_scope(scope: &str) -> Result { match scope { - "user" => Ok(McpConfigScope::User), - "project" => Ok(McpConfigScope::Project), - "local" => Ok(McpConfigScope::Local), + "user" => Ok(ServerMcpConfigScope::User), + "project" => Ok(ServerMcpConfigScope::Project), + "local" => Ok(ServerMcpConfigScope::Local), other => Err(ApiError::bad_request(format!( "unsupported MCP scope '{}'", other @@ -238,8 +234,8 @@ fn parse_scope(scope: &str) -> Result { } } -impl From for McpServerStatus { - fn from(value: McpServerStatusSummary) -> Self { +impl From for McpServerStatus { + fn from(value: ServerMcpServerStatusSummary) -> Self { Self { name: value.name, scope: value.scope, diff --git a/crates/server/src/http/routes/model.rs b/crates/server/src/http/routes/model.rs index 969da3fa..747b3174 100644 --- a/crates/server/src/http/routes/model.rs +++ b/crates/server/src/http/routes/model.rs @@ -24,7 +24,7 @@ pub(crate) async fn get_current_model( headers: HeaderMap, ) -> Result, ApiError> { require_auth(&state, &headers, None)?; - let config = state.app.config().get_config().await; + let config = state.config.get_config().await; Ok(Json(resolve_current_model(&config)?)) } @@ -37,7 +37,7 @@ pub(crate) async fn list_models( headers: HeaderMap, ) -> Result>, ApiError> { require_auth(&state, &headers, None)?; - let config = state.app.config().get_config().await; + let config = state.config.get_config().await; Ok(Json(list_model_options(&config))) } @@ -52,8 +52,7 @@ pub(crate) async fn test_model_connection( ) -> Result, ApiError> { require_auth(&state, &headers, None)?; let result = state - .app - .config() + .config .test_connection(&request.profile_name, &request.model) .await .map_err(ApiError::from)?; diff --git a/crates/server/src/http/routes/sessions/mutation.rs b/crates/server/src/http/routes/sessions/mutation.rs index 2b984d26..a036e130 100644 --- a/crates/server/src/http/routes/sessions/mutation.rs +++ b/crates/server/src/http/routes/sessions/mutation.rs @@ -1,8 +1,15 @@ +use std::{fs, path::Path as FsPath}; + +use astrcode_core::{ExecutionControl, SessionId}; +use astrcode_host_session::{ + CompactSessionMutationInput, ForkPoint, InterruptSessionMutationInput, TurnMutationPreparation, +}; use astrcode_protocol::http::{ CompactSessionRequest, CompactSessionResponse, CreateSessionRequest, DeleteProjectResultDto, ForkSessionRequest, PromptAcceptedResponse, PromptRequest, SessionListItem, SessionModeStateDto, SwitchModeRequest, }; +use astrcode_support::hostpaths::project_dir; use axum::{ Json, extract::{Path, Query, State}, @@ -12,7 +19,7 @@ use serde::Deserialize; use crate::{ ApiError, AppState, auth::require_auth, mapper::to_session_list_item, - routes::sessions::validate_session_path_id, + root_execute_service::ServerSessionPromptRequest, routes::sessions::validate_session_path_id, }; #[derive(Debug, Deserialize)] @@ -28,13 +35,11 @@ pub(crate) async fn create_session( ) -> Result, ApiError> { require_auth(&state, &headers, None)?; let meta = state - .app + .session_catalog .create_session(request.working_dir) .await .map_err(ApiError::from)?; - Ok(Json(to_session_list_item( - astrcode_application::summarize_session_meta(meta), - ))) + Ok(Json(to_session_list_item(meta))) } pub(crate) async fn submit_prompt( @@ -45,28 +50,39 @@ pub(crate) async fn submit_prompt( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id)?; - let summary = state - .app - .submit_prompt_summary( - &session_id, - request.text, - request.control, - request.skill_invocation.map(|invocation| { - astrcode_application::PromptSkillInvocation { - skill_id: invocation.skill_id, - user_prompt: invocation.user_prompt, - } - }), - ) + let loaded = state + .session_catalog + .ensure_loaded_session(&SessionId::from(session_id.clone())) + .await + .map_err(ApiError::from)?; + let text = normalize_prompt_request_text(request.text, request.skill_invocation)?; + if let Some(control) = &request.control { + control.validate().map_err(ApiError::from)?; + } + let accepted_control = request.control.clone(); + let accepted = state + .agent_api + .submit_existing_session_prompt(ServerSessionPromptRequest { + session_id, + working_dir: loaded.working_dir.display().to_string(), + text, + control: request.control, + }) .await .map_err(ApiError::from)?; + let turn_id = accepted.turn_id.ok_or_else(|| { + ApiError::internal_server_error("accepted prompt response omitted turn id".into()) + })?; + let session_id = accepted.session_id.ok_or_else(|| { + ApiError::internal_server_error("accepted prompt response omitted session id".into()) + })?; Ok(( StatusCode::ACCEPTED, Json(PromptAcceptedResponse { - turn_id: summary.turn_id, - session_id: summary.session_id, - branched_from_session_id: summary.branched_from_session_id, - accepted_control: summary.accepted_control, + turn_id, + session_id, + branched_from_session_id: accepted.branched_from_session_id, + accepted_control, }), )) } @@ -79,8 +95,10 @@ pub(crate) async fn interrupt_session( require_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id)?; state - .app - .interrupt_session(&session_id) + .session_catalog + .interrupt_running_turn(InterruptSessionMutationInput { + session_id: SessionId::from(session_id), + }) .await .map_err(ApiError::from)?; Ok(StatusCode::NO_CONTENT) @@ -96,12 +114,17 @@ pub(crate) async fn compact_session( let session_id = validate_session_path_id(&session_id)?; let request = request.map(|request| request.0); let summary = state - .app - .compact_session_summary( - &session_id, - request.as_ref().and_then(|request| request.control.clone()), - request.and_then(|request| request.instructions), - ) + .session_catalog + .request_manual_compact(CompactSessionMutationInput { + session_id: SessionId::from(session_id), + control: normalize_compact_control( + request.as_ref().and_then(|request| request.control.clone()), + ), + instructions: normalize_compact_instructions( + request.and_then(|request| request.instructions), + ), + preparation: TurnMutationPreparation::external_preparation("server/application"), + }) .await .map_err(ApiError::from)?; Ok(( @@ -114,6 +137,54 @@ pub(crate) async fn compact_session( )) } +fn normalize_prompt_request_text( + text: String, + skill_invocation: Option, +) -> Result { + let text = text.trim().to_string(); + let Some(skill_invocation) = skill_invocation else { + if text.is_empty() { + return Err(ApiError::bad_request( + "prompt must not be empty".to_string(), + )); + } + return Ok(text); + }; + + let skill_prompt = skill_invocation + .user_prompt + .as_deref() + .map(str::trim) + .unwrap_or_default() + .to_string(); + if !text.is_empty() && !skill_prompt.is_empty() && text != skill_prompt { + return Err(ApiError::bad_request( + "skillInvocation.userPrompt must match prompt text".to_string(), + )); + } + if !text.is_empty() { + Ok(text) + } else { + Ok(skill_prompt) + } +} + +fn normalize_compact_control(control: Option) -> Option { + let mut control = control.unwrap_or(ExecutionControl { + manual_compact: None, + }); + if control.manual_compact.is_none() { + control.manual_compact = Some(true); + } + Some(control) +} + +fn normalize_compact_instructions(instructions: Option) -> Option { + instructions + .map(|value| value.trim().to_string()) + .filter(|value| !value.is_empty()) +} + pub(crate) async fn fork_session( State(state): State, headers: HeaderMap, @@ -133,22 +204,42 @@ pub(crate) async fn fork_session( "turnId and storageSeq are mutually exclusive".to_string(), )); } - let selector = match (request.turn_id, request.storage_seq) { - (Some(turn_id), None) => astrcode_application::SessionForkSelector::TurnEnd { turn_id }, - (None, Some(storage_seq)) => { - astrcode_application::SessionForkSelector::StorageSeq { storage_seq } - }, - (None, None) => astrcode_application::SessionForkSelector::Latest, + let fork_point = match (request.turn_id, request.storage_seq) { + (Some(turn_id), None) => ForkPoint::TurnEnd(turn_id), + (None, Some(storage_seq)) => ForkPoint::StorageSeq(storage_seq), + (None, None) => ForkPoint::Latest, (Some(_), Some(_)) => unreachable!("validated above"), }; - let meta = state - .app - .fork_session(&session_id, selector) + let source_session_id = SessionId::from(session_id.clone()); + let source = state + .session_catalog + .ensure_loaded_session(&source_session_id) + .await + .map_err(ApiError::from)?; + let result = state + .session_catalog + .fork_session(&source_session_id, fork_point) .await .map_err(ApiError::from)?; - Ok(Json(to_session_list_item( - astrcode_application::summarize_session_meta(meta), - ))) + copy_fork_plan_artifacts( + &session_id, + result.new_session_id.as_str(), + source.working_dir.as_path(), + )?; + let meta = state + .session_catalog + .list_session_metas() + .await + .map_err(ApiError::from)? + .into_iter() + .find(|meta| meta.session_id == result.new_session_id.as_str()) + .ok_or_else(|| { + ApiError::internal_server_error(format!( + "forked session '{}' was not found in catalog", + result.new_session_id + )) + })?; + Ok(Json(to_session_list_item(meta))) } pub(crate) async fn switch_mode( @@ -159,8 +250,21 @@ pub(crate) async fn switch_mode( ) -> Result<(StatusCode, Json), ApiError> { require_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id)?; + let session_id = SessionId::from(session_id); + let current_mode = state + .session_catalog + .session_mode_state(&session_id) + .await + .map_err(ApiError::from)?; + state + .mode_catalog + .validate_transition( + ¤t_mode.current_mode_id, + &request.mode_id.clone().into(), + ) + .map_err(ApiError::from)?; let mode = state - .app + .session_catalog .switch_mode(&session_id, request.mode_id.into()) .await .map_err(ApiError::from)?; @@ -170,7 +274,7 @@ pub(crate) async fn switch_mode( current_mode_id: mode.current_mode_id.to_string(), last_mode_changed_at: mode .last_mode_changed_at - .map(astrcode_application::format_local_rfc3339), + .map(astrcode_core::format_local_rfc3339), }), )) } @@ -183,8 +287,8 @@ pub(crate) async fn delete_session( require_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id)?; state - .app - .delete_session(&session_id) + .session_catalog + .delete_session(&SessionId::from(session_id)) .await .map_err(ApiError::from)?; Ok(StatusCode::NO_CONTENT) @@ -196,10 +300,85 @@ pub(crate) async fn delete_project( Query(query): Query, ) -> Result, ApiError> { require_auth(&state, &headers, None)?; + let working_dir = fs::canonicalize(&query.working_dir).map_err(|error| { + ApiError::bad_request(format!( + "invalid workingDir '{}': {error}", + query.working_dir + )) + })?; let result = state - .app - .delete_project(&query.working_dir) + .session_catalog + .delete_project(&working_dir.display().to_string()) .await .map_err(ApiError::from)?; Ok(Json(result)) } + +fn copy_fork_plan_artifacts( + source_session_id: &str, + target_session_id: &str, + working_dir: &FsPath, +) -> Result<(), ApiError> { + let project_dir = project_dir(working_dir).map_err(|error| { + ApiError::internal_server_error(format!( + "failed to resolve project directory for '{}': {error}", + working_dir.display() + )) + })?; + let source_dir = project_dir + .join("sessions") + .join(source_session_id) + .join("plan"); + if !source_dir.exists() { + return Ok(()); + } + let target_dir = project_dir + .join("sessions") + .join(target_session_id) + .join("plan"); + copy_dir_recursive(&source_dir, &target_dir) +} + +fn copy_dir_recursive(source: &FsPath, target: &FsPath) -> Result<(), ApiError> { + fs::create_dir_all(target).map_err(|error| { + ApiError::internal_server_error(format!( + "creating directory '{}' failed: {error}", + target.display() + )) + })?; + for entry in fs::read_dir(source).map_err(|error| { + ApiError::internal_server_error(format!( + "reading directory '{}' failed: {error}", + source.display() + )) + })? { + let entry = entry.map_err(|error| { + ApiError::internal_server_error(format!( + "reading directory entry '{}' failed: {error}", + source.display() + )) + })?; + let source_path = entry.path(); + let target_path = target.join(entry.file_name()); + let file_type = entry.file_type().map_err(|error| { + ApiError::internal_server_error(format!( + "reading file type '{}' failed: {error}", + source_path.display() + )) + })?; + if file_type.is_symlink() { + continue; + } + if file_type.is_dir() { + copy_dir_recursive(&source_path, &target_path)?; + } else { + fs::copy(&source_path, &target_path).map_err(|error| { + ApiError::internal_server_error(format!( + "copying file '{}' failed: {error}", + source_path.display() + )) + })?; + } + } + Ok(()) +} diff --git a/crates/server/src/http/routes/sessions/query.rs b/crates/server/src/http/routes/sessions/query.rs index bbc3b1eb..91cf30e9 100644 --- a/crates/server/src/http/routes/sessions/query.rs +++ b/crates/server/src/http/routes/sessions/query.rs @@ -16,12 +16,11 @@ pub(crate) async fn list_sessions( ) -> Result>, ApiError> { require_auth(&state, &headers, None)?; let sessions = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .map_err(ApiError::from)? .into_iter() - .map(astrcode_application::summarize_session_meta) .map(to_session_list_item) .collect(); Ok(Json(sessions)) @@ -33,10 +32,8 @@ pub(crate) async fn list_modes( ) -> Result>, ApiError> { require_auth(&state, &headers, None)?; let modes = state - .app - .list_modes() - .await - .map_err(ApiError::from)? + .mode_catalog + .list() .into_iter() .map(|summary| ModeSummaryDto { id: summary.id.to_string(), @@ -55,14 +52,14 @@ pub(crate) async fn get_session_mode( require_auth(&state, &headers, None)?; let session_id = validate_session_path_id(&session_id)?; let mode = state - .app - .session_mode_state(&session_id) + .session_catalog + .session_mode_state(&session_id.into()) .await .map_err(ApiError::from)?; Ok(Json(SessionModeStateDto { current_mode_id: mode.current_mode_id.to_string(), last_mode_changed_at: mode .last_mode_changed_at - .map(astrcode_application::format_local_rfc3339), + .map(astrcode_core::format_local_rfc3339), })) } diff --git a/crates/server/src/http/routes/sessions/stream.rs b/crates/server/src/http/routes/sessions/stream.rs index 4f0d15c8..4bab0ba1 100644 --- a/crates/server/src/http/routes/sessions/stream.rs +++ b/crates/server/src/http/routes/sessions/stream.rs @@ -15,7 +15,7 @@ pub(crate) async fn session_catalog_events( headers: HeaderMap, ) -> Result>>, ApiError> { require_auth(&state, &headers, None)?; - let mut receiver = state.app.subscribe_catalog(); + let mut receiver = state.session_catalog.subscribe_catalog_events(); let event_stream = stream! { loop { diff --git a/crates/server/src/http/terminal_projection.rs b/crates/server/src/http/terminal_projection.rs index f37a73e2..9a7f6887 100644 --- a/crates/server/src/http/terminal_projection.rs +++ b/crates/server/src/http/terminal_projection.rs @@ -1,18 +1,9 @@ -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; -use astrcode_application::terminal::{ - ConversationBlockFacts, ConversationBlockPatchFacts, ConversationBlockStatus, - ConversationChildHandoffBlockFacts, ConversationChildHandoffKind, - ConversationChildSummarySummary, ConversationControlSummary, ConversationDeltaFacts, - ConversationDeltaFrameFacts, ConversationPlanBlockFacts, ConversationPlanEventKind, - ConversationPlanReviewKind, ConversationSlashActionSummary, ConversationSlashCandidateSummary, - ConversationStepCursorFacts, ConversationStepProgressFacts, ConversationSystemNoteKind, - ConversationTranscriptErrorKind, TerminalChildSummaryFacts, TerminalFacts, - TerminalRehydrateFacts, TerminalSlashCandidateFacts, ToolCallBlockFacts, - summarize_conversation_child_ref, summarize_conversation_child_summary, - summarize_conversation_control, summarize_conversation_slash_candidate, +use astrcode_core::{ + ChildAgentRef, CompactAppliedMeta, CompactTrigger, ExecutionTaskStatus, Phase, }; -use astrcode_core::ChildAgentRef; +use astrcode_host_session::SessionControlStateSnapshot; use astrcode_protocol::http::{ ChildAgentRefDto, ConversationAssistantBlockDto, ConversationBannerDto, ConversationBannerErrorCodeDto, ConversationBlockDto, ConversationBlockPatchDto, @@ -29,6 +20,421 @@ use astrcode_protocol::http::{ ConversationToolStreamsDto, ConversationTranscriptErrorCodeDto, ConversationUserBlockDto, conversation::v1::ConversationPromptMetricsBlockDto, }; + +use crate::conversation_read_model::{ + ConversationBlockFacts, ConversationBlockPatchFacts, ConversationBlockStatus, + ConversationChildHandoffBlockFacts, ConversationChildHandoffKind, ConversationDeltaFacts, + ConversationDeltaFrameFacts, ConversationDeltaProjector, ConversationPlanBlockFacts, + ConversationPlanEventKind, ConversationPlanReviewKind, ConversationReplayStream, + ConversationSnapshotFacts, ConversationStepCursorFacts, ConversationStepProgressFacts, + ConversationStreamReplayFacts, ConversationSystemNoteKind, ConversationTranscriptErrorKind, + ToolCallBlockFacts, +}; + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub(crate) enum ConversationFocus { + #[default] + Root, + SubRun { + sub_run_id: String, + }, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TerminalLastCompactMetaFacts { + pub trigger: CompactTrigger, + pub meta: CompactAppliedMeta, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct PlanReferenceFacts { + pub slug: String, + pub path: String, + pub status: String, + pub title: String, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TaskItemFacts { + pub content: String, + pub status: ExecutionTaskStatus, + pub active_form: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ConversationControlSummary { + pub phase: Phase, + pub can_submit_prompt: bool, + pub can_request_compact: bool, + pub compact_pending: bool, + pub compacting: bool, + pub active_turn_id: Option, + pub last_compact_meta: Option, + pub current_mode_id: String, + pub active_plan: Option, + pub active_tasks: Option>, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TerminalControlFacts { + pub phase: Phase, + pub active_turn_id: Option, + pub manual_compact_pending: bool, + pub compacting: bool, + pub last_compact_meta: Option, + pub current_mode_id: String, + pub active_plan: Option, + pub active_tasks: Option>, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TerminalChildSummaryFacts { + pub node: astrcode_core::ChildSessionNode, + pub phase: Phase, + pub title: Option, + pub display_name: Option, + pub recent_output: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ConversationChildSummarySummary { + pub child_session_id: String, + pub child_agent_id: String, + pub title: String, + pub lifecycle: astrcode_core::AgentLifecycleStatus, + pub latest_output_summary: Option, + pub child_ref: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) enum TerminalSlashAction { + CreateSession, + OpenResume, + RequestCompact, + InsertText { text: String }, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum ConversationSlashActionSummary { + InsertText, + ExecuteCommand, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TerminalSlashCandidateFacts { + pub id: String, + pub title: String, + pub description: String, + pub keywords: Vec, + pub badges: Vec, + pub action: TerminalSlashAction, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ConversationSlashCandidateSummary { + pub id: String, + pub title: String, + pub description: String, + pub keywords: Vec, + pub action_kind: ConversationSlashActionSummary, + pub action_value: String, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ConversationAuthoritativeSummary { + pub control: ConversationControlSummary, + pub child_summaries: Vec, + pub slash_candidates: Vec, +} + +#[derive(Debug, Clone, PartialEq)] +pub(crate) struct TerminalFacts { + pub active_session_id: String, + pub session_title: String, + pub transcript: ConversationSnapshotFacts, + pub control: TerminalControlFacts, + pub child_summaries: Vec, + pub slash_candidates: Vec, +} + +#[derive(Debug)] +pub(crate) struct TerminalStreamReplayFacts { + pub replay: ConversationStreamReplayFacts, + pub stream: ConversationReplayStream, + pub control: TerminalControlFacts, + pub child_summaries: Vec, + pub slash_candidates: Vec, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum TerminalRehydrateReason { + CursorExpired, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct TerminalRehydrateFacts { + pub session_id: String, + pub requested_cursor: String, + pub latest_cursor: Option, + pub reason: TerminalRehydrateReason, +} + +#[derive(Debug)] +pub(crate) enum TerminalStreamFacts { + Replay(Box), + RehydrateRequired(TerminalRehydrateFacts), +} + +pub(crate) fn map_control_facts(control: SessionControlStateSnapshot) -> TerminalControlFacts { + TerminalControlFacts { + phase: control.phase, + active_turn_id: control.active_turn_id, + manual_compact_pending: control.manual_compact_pending, + compacting: control.compacting, + last_compact_meta: control + .last_compact_meta + .map(|meta| TerminalLastCompactMetaFacts { + trigger: meta.trigger, + meta: meta.meta, + }), + current_mode_id: control.current_mode_id.to_string(), + active_plan: None, + active_tasks: None, + } +} + +pub(crate) fn summarize_conversation_control( + control: &TerminalControlFacts, +) -> ConversationControlSummary { + ConversationControlSummary { + phase: control.phase, + can_submit_prompt: control.active_turn_id.is_none() + && matches!( + control.phase, + Phase::Idle | Phase::Done | Phase::Interrupted + ), + can_request_compact: !control.manual_compact_pending && !control.compacting, + compact_pending: control.manual_compact_pending, + compacting: control.compacting, + active_turn_id: control.active_turn_id.clone(), + last_compact_meta: control.last_compact_meta.clone(), + current_mode_id: control.current_mode_id.clone(), + active_plan: control.active_plan.clone(), + active_tasks: control.active_tasks.clone(), + } +} + +pub(crate) fn summarize_conversation_child_summary( + summary: &TerminalChildSummaryFacts, +) -> ConversationChildSummarySummary { + ConversationChildSummarySummary { + child_session_id: summary.node.child_session_id.to_string(), + child_agent_id: summary.node.agent_id().to_string(), + title: summary + .title + .clone() + .or_else(|| summary.display_name.clone()) + .unwrap_or_else(|| summary.node.child_session_id.to_string()), + lifecycle: summary.node.status, + latest_output_summary: summary.recent_output.clone(), + child_ref: Some(summary.node.child_ref()), + } +} + +pub(crate) fn summarize_conversation_child_ref( + child_ref: &ChildAgentRef, +) -> ConversationChildSummarySummary { + ConversationChildSummarySummary { + child_session_id: child_ref.open_session_id.to_string(), + child_agent_id: child_ref.agent_id().to_string(), + title: child_ref.agent_id().to_string(), + lifecycle: child_ref.status, + latest_output_summary: None, + child_ref: Some(child_ref.clone()), + } +} + +pub(crate) fn summarize_conversation_slash_candidate( + candidate: &TerminalSlashCandidateFacts, +) -> ConversationSlashCandidateSummary { + let (action_kind, action_value) = match &candidate.action { + TerminalSlashAction::CreateSession => ( + ConversationSlashActionSummary::ExecuteCommand, + "/new".to_string(), + ), + TerminalSlashAction::OpenResume => ( + ConversationSlashActionSummary::ExecuteCommand, + "/resume".to_string(), + ), + TerminalSlashAction::RequestCompact => ( + ConversationSlashActionSummary::ExecuteCommand, + "/compact".to_string(), + ), + TerminalSlashAction::InsertText { text } => { + (ConversationSlashActionSummary::InsertText, text.clone()) + }, + }; + + ConversationSlashCandidateSummary { + id: candidate.id.clone(), + title: candidate.title.clone(), + description: candidate.description.clone(), + keywords: candidate.keywords.clone(), + action_kind, + action_value, + } +} + +pub(crate) fn summarize_conversation_authoritative( + control: &TerminalControlFacts, + child_summaries: &[TerminalChildSummaryFacts], + slash_candidates: &[TerminalSlashCandidateFacts], +) -> ConversationAuthoritativeSummary { + ConversationAuthoritativeSummary { + control: summarize_conversation_control(control), + child_summaries: child_summaries + .iter() + .map(summarize_conversation_child_summary) + .collect(), + slash_candidates: slash_candidates + .iter() + .map(summarize_conversation_slash_candidate) + .collect(), + } +} + +pub(crate) fn truncate_terminal_summary(content: &str) -> String { + const MAX_SUMMARY_CHARS: usize = 120; + let normalized = content.split_whitespace().collect::>().join(" "); + let mut chars = normalized.chars(); + let truncated = chars.by_ref().take(MAX_SUMMARY_CHARS).collect::(); + if chars.next().is_some() { + format!("{truncated}...") + } else { + truncated + } +} + +pub(crate) fn latest_terminal_summary(snapshot: &ConversationSnapshotFacts) -> Option { + snapshot + .blocks + .iter() + .rev() + .find_map(summary_from_block) + .or_else(|| latest_transcript_cursor(snapshot).map(|cursor| format!("cursor:{cursor}"))) +} + +pub(crate) fn build_conversation_snapshot( + records: &[astrcode_core::SessionEventRecord], + phase: Phase, +) -> ConversationSnapshotFacts { + let mut projector = ConversationDeltaProjector::new(); + projector.seed(records); + let blocks = suppress_draft_approval_plan_leakage(projector.into_blocks()); + ConversationSnapshotFacts { + cursor: records.last().map(|record| record.event_id.clone()), + phase, + step_progress: durable_step_progress_from_blocks(&blocks), + blocks, + } +} + +pub(crate) fn build_conversation_replay_frames( + seed_records: &[astrcode_core::SessionEventRecord], + history: &[astrcode_core::SessionEventRecord], +) -> Vec { + let mut projector = ConversationDeltaProjector::new(); + projector.seed(seed_records); + let mut step_progress = durable_step_progress_from_blocks(projector.blocks()); + let mut raw_frames = Vec::new(); + for record in history { + raw_frames.extend( + projector + .project_record(record) + .into_iter() + .map(|delta| (record.event_id.clone(), delta)), + ); + } + let hidden_block_ids = draft_approval_leakage_hidden_block_ids(projector.blocks()); + + let mut frames = Vec::new(); + for (cursor, delta) in raw_frames { + if delta_block_id(&delta).is_some_and(|block_id| hidden_block_ids.contains(block_id)) { + continue; + } + observe_durable_delta_step(&mut step_progress, &delta); + frames.push(ConversationDeltaFrameFacts { + cursor, + step_progress: step_progress.clone(), + delta, + }); + } + frames +} + +fn latest_transcript_cursor(snapshot: &ConversationSnapshotFacts) -> Option { + snapshot.cursor.clone() +} + +fn summary_from_block(block: &ConversationBlockFacts) -> Option { + match block { + ConversationBlockFacts::Assistant(block) => summary_from_markdown(&block.markdown), + ConversationBlockFacts::Plan(block) => summary_from_plan_block(block), + ConversationBlockFacts::ToolCall(block) => summary_from_tool_call(block), + ConversationBlockFacts::ChildHandoff(block) => summary_from_child_handoff(block), + ConversationBlockFacts::Error(block) => summary_from_markdown(&block.message), + ConversationBlockFacts::SystemNote(block) => summary_from_markdown(&block.markdown), + ConversationBlockFacts::User(_) + | ConversationBlockFacts::Thinking(_) + | ConversationBlockFacts::PromptMetrics(_) => None, + } +} + +fn summary_from_markdown(markdown: &str) -> Option { + (!markdown.trim().is_empty()).then(|| truncate_terminal_summary(markdown)) +} + +fn summary_from_tool_call(block: &ToolCallBlockFacts) -> Option { + block + .summary + .as_deref() + .filter(|summary| !summary.trim().is_empty()) + .map(truncate_terminal_summary) + .or_else(|| { + block + .error + .as_deref() + .filter(|error| !error.trim().is_empty()) + .map(truncate_terminal_summary) + }) + .or_else(|| summary_from_markdown(&block.streams.stderr)) + .or_else(|| summary_from_markdown(&block.streams.stdout)) +} + +fn summary_from_plan_block(block: &ConversationPlanBlockFacts) -> Option { + block + .summary + .as_deref() + .filter(|summary| !summary.trim().is_empty()) + .map(truncate_terminal_summary) + .or_else(|| { + block + .content + .as_deref() + .filter(|content| !content.trim().is_empty()) + .map(truncate_terminal_summary) + }) + .or_else(|| summary_from_markdown(&block.title)) +} + +fn summary_from_child_handoff(block: &ConversationChildHandoffBlockFacts) -> Option { + block + .message + .as_deref() + .filter(|message| !message.trim().is_empty()) + .map(truncate_terminal_summary) +} + pub(crate) fn project_conversation_snapshot( facts: &TerminalFacts, ) -> ConversationSnapshotResponseDto { @@ -163,9 +569,7 @@ pub(crate) fn project_conversation_child_summary_summary_deltas( .collect::>(); removed_ids.sort(); for child_session_id in removed_ids { - deltas.push(ConversationDeltaDto::RemoveChildSummary { - child_session_id: child_session_id.to_string(), - }); + deltas.push(ConversationDeltaDto::RemoveChildSummary { child_session_id }); } let mut current_ids = current_by_id.keys().cloned().collect::>(); @@ -204,21 +608,233 @@ pub(crate) fn project_conversation_slash_candidate_summaries( } } +pub(crate) fn child_summary_summary_lookup( + summaries: &[ConversationChildSummarySummary], +) -> HashMap { + let mut lookup = HashMap::new(); + for summary in summaries { + let dto = to_conversation_child_summary_dto(summary.clone()); + lookup.insert(summary.child_session_id.clone(), dto.clone()); + if let Some(child_ref) = &dto.child_ref { + lookup.insert(child_ref.open_session_id.clone(), dto.clone()); + lookup.insert(child_ref.session_id.clone(), dto.clone()); + } + } + lookup +} + +pub(crate) fn project_conversation_step_progress( + facts: ConversationStepProgressFacts, +) -> ConversationStepProgressDto { + ConversationStepProgressDto { + durable: facts.durable.map(to_step_cursor_dto), + live: facts.live.map(to_step_cursor_dto), + } +} + +fn suppress_draft_approval_plan_leakage( + blocks: Vec, +) -> Vec { + let hidden_block_ids = draft_approval_leakage_hidden_block_ids(&blocks); + blocks + .into_iter() + .filter(|block| !hidden_block_ids.contains(block_id(block))) + .collect() +} + +fn draft_approval_leakage_hidden_block_ids(blocks: &[ConversationBlockFacts]) -> HashSet { + let mut turn_facts = HashMap::::new(); + for block in blocks { + match block { + ConversationBlockFacts::User(block) => { + let Some(turn_id) = block.turn_id.as_deref() else { + continue; + }; + let facts = turn_facts + .entry(turn_id.to_string()) + .or_insert((false, false)); + if is_approval_like_turn_text(&block.markdown) { + facts.0 = true; + } + }, + ConversationBlockFacts::Plan(block) => { + let Some(turn_id) = block.turn_id.as_deref() else { + continue; + }; + let facts = turn_facts + .entry(turn_id.to_string()) + .or_insert((false, false)); + if block.status.as_deref() == Some("awaiting_approval") + || matches!( + block.event_kind, + ConversationPlanEventKind::Presented + | ConversationPlanEventKind::ReviewPending + ) + { + facts.1 = true; + } + }, + _ => {}, + } + } + + blocks + .iter() + .filter_map(|block| { + let turn_id = turn_id(block)?; + let (approval_like_user, has_review_plan) = turn_facts.get(turn_id).copied()?; + if !approval_like_user || !has_review_plan { + return None; + } + matches!( + block, + ConversationBlockFacts::Assistant(_) | ConversationBlockFacts::Thinking(_) + ) + .then(|| block_id(block).to_string()) + }) + .collect() +} + +fn delta_block_id(delta: &ConversationDeltaFacts) -> Option<&str> { + match delta { + ConversationDeltaFacts::Append { block } => Some(block_id(block.as_ref())), + ConversationDeltaFacts::Patch { block_id, .. } + | ConversationDeltaFacts::Complete { block_id, .. } => Some(block_id.as_str()), + } +} + +fn turn_id(block: &ConversationBlockFacts) -> Option<&str> { + match block { + ConversationBlockFacts::User(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Assistant(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Thinking(block) => block.turn_id.as_deref(), + ConversationBlockFacts::PromptMetrics(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Plan(block) => block.turn_id.as_deref(), + ConversationBlockFacts::ToolCall(block) => block.turn_id.as_deref(), + ConversationBlockFacts::Error(block) => block.turn_id.as_deref(), + ConversationBlockFacts::SystemNote(_) | ConversationBlockFacts::ChildHandoff(_) => None, + } +} + +fn is_approval_like_turn_text(text: &str) -> bool { + let normalized_english = text + .split_whitespace() + .collect::>() + .join(" ") + .to_ascii_lowercase(); + for phrase in ["approved", "go ahead", "implement it"] { + if normalized_english == phrase + || (phrase != "implement it" && normalized_english.starts_with(&format!("{phrase} "))) + { + return true; + } + } + + let normalized_chinese = text + .chars() + .filter(|ch| { + !ch.is_whitespace() + && !matches!( + ch, + ',' | '.' + | '!' + | '?' + | ';' + | ':' + | '，' + | '。' + | '！' + | '？' + | '；' + | '：' + | '【' + | '】' + | '、' + ) + }) + .collect::(); + for phrase in ["同意", "可以", "按这个做", "开始实现"] { + let matched = if matches!(phrase, "同意" | "可以") { + normalized_chinese == phrase + } else { + normalized_chinese == phrase || normalized_chinese.starts_with(phrase) + }; + if matched { + return true; + } + } + + false +} + +fn durable_step_progress_from_blocks( + blocks: &[ConversationBlockFacts], +) -> ConversationStepProgressFacts { + let mut step_progress = ConversationStepProgressFacts::default(); + for block in blocks { + observe_durable_block_step(&mut step_progress, block); + } + step_progress +} + +fn observe_durable_delta_step( + step_progress: &mut ConversationStepProgressFacts, + delta: &ConversationDeltaFacts, +) { + if let ConversationDeltaFacts::Append { block } = delta { + observe_durable_block_step(step_progress, block.as_ref()); + } +} + +fn observe_durable_block_step( + step_progress: &mut ConversationStepProgressFacts, + block: &ConversationBlockFacts, +) { + let step_cursor = match block { + ConversationBlockFacts::PromptMetrics(block) => Some(ConversationStepCursorFacts { + turn_id: block + .turn_id + .clone() + .unwrap_or_else(|| "session".to_string()), + step_index: block.step_index, + }), + ConversationBlockFacts::Assistant(block) => { + block + .step_index + .map(|step_index| ConversationStepCursorFacts { + turn_id: block + .turn_id + .clone() + .unwrap_or_else(|| "session".to_string()), + step_index, + }) + }, + _ => None, + }; + + if let Some(step_cursor) = step_cursor { + step_progress.durable = Some(step_cursor.clone()); + if let Some(live) = step_progress.live.as_ref() { + if live.turn_id != step_cursor.turn_id || live.step_index <= step_cursor.step_index { + step_progress.live = None; + } + } + } +} + fn project_delta( delta: ConversationDeltaFacts, child_lookup: &HashMap, ) -> ConversationDeltaDto { match delta { - ConversationDeltaFacts::AppendBlock { block } => ConversationDeltaDto::AppendBlock { + ConversationDeltaFacts::Append { block } => ConversationDeltaDto::AppendBlock { block: project_block(block.as_ref(), child_lookup), }, - ConversationDeltaFacts::PatchBlock { block_id, patch } => { - ConversationDeltaDto::PatchBlock { - block_id, - patch: project_patch(patch), - } + ConversationDeltaFacts::Patch { block_id, patch } => ConversationDeltaDto::PatchBlock { + block_id, + patch: project_patch(patch), }, - ConversationDeltaFacts::CompleteBlock { block_id, status } => { + ConversationDeltaFacts::Complete { block_id, status } => { ConversationDeltaDto::CompleteBlock { block_id, status: to_block_status_dto(status), @@ -461,21 +1077,6 @@ fn child_summary_lookup( ) } -pub(crate) fn child_summary_summary_lookup( - summaries: &[ConversationChildSummarySummary], -) -> HashMap { - let mut lookup = HashMap::new(); - for summary in summaries { - let dto = to_conversation_child_summary_dto(summary.clone()); - lookup.insert(summary.child_session_id.clone(), dto.clone()); - if let Some(child_ref) = &dto.child_ref { - lookup.insert(child_ref.open_session_id.clone(), dto.clone()); - lookup.insert(child_ref.session_id.clone(), dto.clone()); - } - } - lookup -} - fn to_conversation_child_summary_dto( summary: ConversationChildSummarySummary, ) -> ConversationChildSummaryDto { @@ -489,15 +1090,6 @@ fn to_conversation_child_summary_dto( } } -pub(crate) fn project_conversation_step_progress( - facts: ConversationStepProgressFacts, -) -> ConversationStepProgressDto { - ConversationStepProgressDto { - durable: facts.durable.map(to_step_cursor_dto), - live: facts.live.map(to_step_cursor_dto), - } -} - fn to_step_cursor_dto(facts: ConversationStepCursorFacts) -> ConversationStepCursorDto { ConversationStepCursorDto { turn_id: facts.turn_id, @@ -529,15 +1121,9 @@ fn to_conversation_control_state_dto( .map(|task| ConversationTaskItemDto { content: task.content, status: match task.status { - astrcode_core::ExecutionTaskStatus::Pending => { - ConversationTaskStatusDto::Pending - }, - astrcode_core::ExecutionTaskStatus::InProgress => { - ConversationTaskStatusDto::InProgress - }, - astrcode_core::ExecutionTaskStatus::Completed => { - ConversationTaskStatusDto::Completed - }, + ExecutionTaskStatus::Pending => ConversationTaskStatusDto::Pending, + ExecutionTaskStatus::InProgress => ConversationTaskStatusDto::InProgress, + ExecutionTaskStatus::Completed => ConversationTaskStatusDto::Completed, }, active_form: task.active_form, }) @@ -546,9 +1132,7 @@ fn to_conversation_control_state_dto( } } -fn to_plan_reference_dto( - plan: astrcode_application::terminal::PlanReferenceFacts, -) -> ConversationPlanReferenceDto { +fn to_plan_reference_dto(plan: PlanReferenceFacts) -> ConversationPlanReferenceDto { ConversationPlanReferenceDto { slug: plan.slug, path: plan.path, @@ -611,3 +1195,17 @@ fn to_error_code_dto(code: ConversationTranscriptErrorKind) -> ConversationTrans ConversationTranscriptErrorKind::RateLimit => ConversationTranscriptErrorCodeDto::RateLimit, } } + +fn block_id(block: &ConversationBlockFacts) -> &str { + match block { + ConversationBlockFacts::User(block) => &block.id, + ConversationBlockFacts::Assistant(block) => &block.id, + ConversationBlockFacts::Thinking(block) => &block.id, + ConversationBlockFacts::PromptMetrics(block) => &block.id, + ConversationBlockFacts::Plan(block) => &block.id, + ConversationBlockFacts::ToolCall(block) => &block.id, + ConversationBlockFacts::Error(block) => &block.id, + ConversationBlockFacts::SystemNote(block) => &block.id, + ConversationBlockFacts::ChildHandoff(block) => &block.id, + } +} diff --git a/crates/application/src/lifecycle/governance.rs b/crates/server/src/lifecycle/governance.rs similarity index 87% rename from crates/application/src/lifecycle/governance.rs rename to crates/server/src/lifecycle/governance.rs index 31d4dba4..16a965a3 100644 --- a/crates/application/src/lifecycle/governance.rs +++ b/crates/server/src/lifecycle/governance.rs @@ -1,19 +1,19 @@ //! # 应用层治理模型 //! -//! 替代旧 `RuntimeGovernance`，不依赖 `RuntimeService`。 +//! 不依赖具体 runtime service。 //! //! ## 设计要点 //! -//! - 依赖运行时治理端口和会话信息提供者，而非旧 `RuntimeService` +//! - 依赖运行时治理端口和会话信息提供者 //! - 通过运行时治理端口获取运行时标识、插件快照、能力列表和关闭能力 //! - 通过 `SessionInfoProvider` 获取会话计数和活跃会话列表 -//! - 可观测性指标通过 `ObservabilitySnapshotProvider` trait 获取， Phase 10 组合根接线时桥接旧 -//! runtime 的实际收集器 -//! - 重载逻辑通过 `RuntimeReloader` trait 委托，Phase 10 实现具体组装 +//! - 可观测性指标通过 `ObservabilitySnapshotProvider` trait 获取 +//! - 重载逻辑通过 `RuntimeReloader` trait 委托 use std::{future::Future, path::PathBuf, pin::Pin, sync::Arc}; -use astrcode_core::{CapabilitySpec, plugin::PluginEntry}; +use astrcode_core::CapabilitySpec; +use astrcode_plugin_host::PluginEntry; use super::TaskRegistry; use crate::{ @@ -23,16 +23,14 @@ use crate::{ /// 可观测性指标快照提供者。 /// -/// 将指标收集与治理模型解耦。实际实现在 Phase 10 组合根中桥接旧 runtime 的 -/// `RuntimeObservability` 收集器。 +/// 将指标收集与治理模型解耦。 pub trait ObservabilitySnapshotProvider: Send + Sync { fn snapshot(&self) -> RuntimeObservabilitySnapshot; } /// 会话信息提供者。 /// -/// 抽象会话计数和列表查询，过渡期由旧 runtime 实现， -/// 后续由 `SessionRuntime` 直接实现。 +/// 抽象会话计数和列表查询。 pub trait SessionInfoProvider: Send + Sync { /// 已加载的会话数量。 fn loaded_session_count(&self) -> usize; @@ -44,7 +42,7 @@ pub trait SessionInfoProvider: Send + Sync { /// 运行时重载策略。 /// /// 封装插件发现、能力面组装和原子替换的完整重载流程。 -/// 实际实现在 Phase 10 组合根中桥接旧 runtime 的 `assemble_runtime_surface`。 +/// 实际实现由组合根提供。 pub trait RuntimeReloader: Send + Sync { /// 执行重载，返回搜索路径列表。 fn reload( @@ -79,8 +77,7 @@ pub trait RuntimeGovernancePort: Send + Sync { /// 应用层治理。 /// /// 管理运行时的生命周期、可观测性和重载能力。 -/// 不持有旧 `RuntimeService` 引用，通过组合运行时治理端口 -/// 和 trait 提供者实现所有治理功能。 +/// 通过组合运行时治理端口和 trait 提供者实现所有治理功能。 pub struct AppGovernance { runtime: Arc, task_registry: Arc, @@ -131,6 +128,7 @@ impl AppGovernance { /// /// 为什么单独暴露：debug-only 治理读取面只关心指标本身， /// 不需要重新拼完整 runtime status，也不应强依赖 plugin search path 等外围信息。 + #[allow(dead_code)] pub fn observability_snapshot(&self) -> RuntimeObservabilitySnapshot { self.observability.snapshot() } @@ -177,6 +175,7 @@ impl AppGovernance { &self.runtime } + #[allow(dead_code)] pub fn task_registry(&self) -> &Arc { &self.task_registry } diff --git a/crates/application/src/lifecycle/mod.rs b/crates/server/src/lifecycle/mod.rs similarity index 86% rename from crates/application/src/lifecycle/mod.rs rename to crates/server/src/lifecycle/mod.rs index fd05c0c5..a98ddd0e 100644 --- a/crates/application/src/lifecycle/mod.rs +++ b/crates/server/src/lifecycle/mod.rs @@ -1,8 +1,7 @@ //! 生命周期管理：任务注册表、治理模型与 shutdown 协调。 //! -//! 从 `runtime/service/lifecycle/` 迁入核心任务管理逻辑。 //! `TaskRegistry` 是自包含的，不依赖 `RuntimeService`。 -//! `AppGovernance` 替代旧 `RuntimeGovernance`，依赖 `App` 而非 `RuntimeService`。 +//! `AppGovernance` 依赖最小治理端口，而非具体 runtime service。 pub mod governance; @@ -10,7 +9,7 @@ use astrcode_core::support::with_lock_recovery; /// 活跃任务注册表，跟踪 turn 和 subagent 的 JoinHandle。 /// -/// 每次注册新任务时会清理已完成的旧 handle，防止内存无限增长。 +/// 每次注册新任务时会清理已完成的 handle，防止内存无限增长。 /// shutdown 时 `take_all_*` 批量 abort 所有剩余任务。 pub struct TaskRegistry { /// 活跃的子 Agent 后台执行任务的 JoinHandle。 @@ -48,7 +47,7 @@ impl TaskRegistry { } } - /// 注册 turn 任务句柄，同时清理已完成的旧 handle。 + /// 注册 turn 任务句柄，同时清理已完成的 handle。 pub fn register_turn_task(&self, handle: tokio::task::JoinHandle<()>) { with_lock_recovery(&self.turn_handles, "TaskRegistry.turn_handles", |guard| { prune_completed_handles(guard); @@ -56,7 +55,7 @@ impl TaskRegistry { }); } - /// 注册子 Agent 任务句柄，同时清理已完成的旧 handle。 + /// 注册子 Agent 任务句柄，同时清理已完成的 handle。 pub fn register_subagent_task(&self, handle: tokio::task::JoinHandle<()>) { with_lock_recovery( &self.subagent_handles, diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index 1f531343..948292be 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -18,9 +18,21 @@ windows_subsystem = "windows" )] +#[path = "agent/mod.rs"] +mod agent; +#[path = "http/agent_api.rs"] +mod agent_api; +#[path = "agent_control_bridge.rs"] +mod agent_control_bridge; +#[path = "agent_control_registry/mod.rs"] +mod agent_control_registry; #[cfg(test)] #[path = "tests/agent_routes_tests.rs"] mod agent_routes_tests; +#[path = "agent_runtime_bridge.rs"] +mod agent_runtime_bridge; +#[path = "application_error_bridge.rs"] +mod application_error_bridge; #[path = "http/auth.rs"] mod auth; #[cfg(test)] @@ -28,45 +40,132 @@ mod auth; mod auth_routes_tests; #[path = "bootstrap/mod.rs"] mod bootstrap; +#[path = "capability_router.rs"] +mod capability_router; +#[path = "http/composer_catalog.rs"] +mod composer_catalog; #[cfg(test)] #[path = "tests/composer_routes_tests.rs"] mod composer_routes_tests; +#[path = "config/mod.rs"] +mod config; +#[path = "config_mode_helpers.rs"] +mod config_mode_helpers; #[cfg(test)] #[path = "tests/config_routes_tests.rs"] mod config_routes_tests; +#[path = "config_service_bridge.rs"] +mod config_service_bridge; +#[path = "conversation_read_model.rs"] +mod conversation_read_model; +#[path = "errors.rs"] +mod errors; +#[path = "execution/mod.rs"] +mod execution; +#[path = "governance_service.rs"] +mod governance_service; +#[path = "governance_surface/mod.rs"] +mod governance_surface; +#[path = "lifecycle/mod.rs"] +mod lifecycle; #[path = "logging.rs"] mod logging; #[path = "http/mapper.rs"] mod mapper; +#[path = "mcp/mod.rs"] +mod mcp; +#[path = "mcp_service.rs"] +mod mcp_service; +#[path = "mode/mod.rs"] +mod mode; +#[path = "mode_catalog_service.rs"] +mod mode_catalog_service; +#[path = "observability/mod.rs"] +mod observability; +#[path = "ports/mod.rs"] +mod ports; +#[path = "profile_service.rs"] +mod profile_service; +#[path = "root_execute_service.rs"] +mod root_execute_service; #[path = "http/routes/mod.rs"] mod routes; +#[path = "runtime_owner_bridge.rs"] +mod runtime_owner_bridge; #[cfg(test)] #[path = "tests/session_contract_tests.rs"] mod session_contract_tests; +#[path = "session_identity.rs"] +mod session_identity; +#[path = "session_runtime_owner_bridge.rs"] +mod session_runtime_owner_bridge; +#[path = "session_runtime_port.rs"] +mod session_runtime_port; +#[path = "session_use_cases.rs"] +mod session_use_cases; #[path = "http/terminal_projection.rs"] mod terminal_projection; #[cfg(test)] #[path = "tests/test_support.rs"] mod test_support; +#[path = "tool_capability_invoker.rs"] +mod tool_capability_invoker; +#[path = "view_projection.rs"] +mod view_projection; +#[path = "watch_service.rs"] +mod watch_service; use std::{net::SocketAddr, path::PathBuf, sync::Arc}; +pub(crate) use agent::AgentOrchestrationService; use anyhow::{Result as AnyhowResult, anyhow}; -use astrcode_application::{App, AppGovernance, ApplicationError, AstrError}; +use astrcode_core::{AstrError, SkillCatalog}; +use astrcode_host_session::{SessionCatalog, SubAgentExecutor}; +use astrcode_plugin_host::ResourceCatalog; use axum::{ Json, Router, http::StatusCode, response::{IntoResponse, Response}, }; +pub(crate) use config::ConfigService; +pub(crate) use errors::ApplicationError; +pub(crate) use execution::{ExecutionControl, ProfileProvider, ProfileResolutionService}; +pub(crate) use governance_surface::{ + GovernanceSurfaceAssembler, ResolvedGovernanceSurface, RootGovernanceInput, +}; +pub(crate) use lifecycle::{ + TaskRegistry, + governance::{ + AppGovernance, ObservabilitySnapshotProvider, RuntimeGovernancePort, + RuntimeGovernanceSnapshot, RuntimeReloader, SessionInfoProvider, + }, +}; +pub(crate) use mcp::{McpConfigScope, RegisterMcpServerInput}; +pub(crate) use mode::{ + CompiledModeEnvelope, ModeCatalog, builtin_mode_catalog, compile_mode_envelope, + compile_mode_envelope_for_child, +}; +pub(crate) use observability::{GovernanceSnapshot, RuntimeObservabilityCollector}; +pub(crate) use ports::{ + AgentKernelPort, AgentSessionPort, AppAgentPromptSubmission, RecoverableParentDelivery, + SessionTurnOutcomeSummary, +}; use serde::Serialize; use tokio::io::{AsyncRead, AsyncReadExt}; use crate::{ + agent_api::ServerAgentApi, + application_error_bridge::ServerRouteError, auth::{AuthSessionManager, BootstrapAuth}, bootstrap::{ ServerRuntimeHandles, attach_frontend_build, build_cors_layer, clear_run_info, prepare_server_launch, }, + config_service_bridge::ServerConfigService, + governance_service::ServerGovernanceService, + mcp_service::ServerMcpService, + mode_catalog_service::ServerModeCatalog, + profile_service::ServerProfileService, routes::build_api_router, }; @@ -79,14 +178,36 @@ pub(crate) const AUTH_HEADER_NAME: &str = "x-astrcode-token"; /// 应用状态（共享给所有路由处理器）。 /// /// 通过 Axum 的 `State` 提取器注入到每个路由处理器中， -/// 包含应用层入口、治理模型、认证管理器和前端构建产物。 +/// 包含运行时入口、server 侧 owner bridge、治理模型、认证管理器和前端构建产物。 /// 所有字段均为 `Arc` 或可 `Clone` 类型，支持多线程共享。 #[derive(Clone)] pub(crate) struct AppState { - /// 应用层唯一业务入口 - app: Arc, - /// 新治理层（快照/shutdown/reload，替代旧 RuntimeGovernance） - governance: Arc, + /// server-owned agent route bridge；agent routes 不再经由 `application::agent` 用例入口。 + agent_api: Arc, + /// server-owned agent control bridge；测试和路由不直接暴露底层 kernel。 + #[allow(dead_code)] + agent_control: Arc, + /// server-owned 配置服务桥接；配置/模型 API 不再经由 App 访问配置。 + config: Arc, + /// server-owned 会话目录桥接；catalog API 不再经由 App 访问 session catalog。 + session_catalog: Arc, + /// server-owned profile resolver；watch/profile 测试不再经由 `App::profiles()`. + #[allow(dead_code)] + profiles: Arc, + /// subagent 启动桥接；测试直接消费 host-session 合同。 + #[allow(dead_code)] + subagent_executor: Arc, + /// server-owned MCP service；MCP API 不再经由 App facade。 + mcp_service: Arc, + /// server-owned skill catalog bridge；composer/skill discovery 不再经由 App facade。 + skill_catalog: Arc, + /// server-owned plugin resource catalog；commands/prompts/themes/resources discovery 统一走 + /// plugin-host。 + resource_catalog: Arc>, + /// server-owned mode catalog bridge；mode API 不再经由 App 访问 mode catalog。 + mode_catalog: Arc, + /// server-owned 治理层（快照/shutdown/reload）。 + governance: Arc, /// 认证会话管理器 auth_sessions: Arc, /// Bootstrap 阶段的认证（短期 token） @@ -142,6 +263,13 @@ impl ApiError { message, } } + + pub(crate) fn internal_server_error(message: String) -> Self { + Self { + status: StatusCode::INTERNAL_SERVER_ERROR, + message, + } + } } impl IntoResponse for ApiError { @@ -156,28 +284,63 @@ impl IntoResponse for ApiError { } } -impl From for ApiError { - fn from(value: ApplicationError) -> Self { +impl From for ApiError { + fn from(value: AstrError) -> Self { + let message = value.to_string(); + match value { + AstrError::SessionNotFound(_) | AstrError::ProjectNotFound(_) => Self { + status: StatusCode::NOT_FOUND, + message, + }, + AstrError::TurnInProgress(_) => Self { + status: StatusCode::CONFLICT, + message, + }, + AstrError::InvalidSessionId(_) + | AstrError::ConfigError { .. } + | AstrError::MissingApiKey(_) + | AstrError::MissingBaseUrl(_) + | AstrError::NoProfilesConfigured + | AstrError::ModelNotFound { .. } + | AstrError::UnsupportedProvider(_) + | AstrError::Validation(_) => Self { + status: StatusCode::BAD_REQUEST, + message, + }, + AstrError::Cancelled => Self { + status: StatusCode::CONFLICT, + message, + }, + _ => Self { + status: StatusCode::INTERNAL_SERVER_ERROR, + message, + }, + } + } +} + +impl From for ApiError { + fn from(value: ServerRouteError) -> Self { match value { - ApplicationError::NotFound(message) => Self { + ServerRouteError::NotFound(message) => Self { status: StatusCode::NOT_FOUND, message, }, - ApplicationError::Conflict(message) => Self { + ServerRouteError::Conflict(message) => Self { status: StatusCode::CONFLICT, message, }, - ApplicationError::InvalidArgument(message) => Self { + ServerRouteError::InvalidArgument(message) => Self { status: StatusCode::BAD_REQUEST, message, }, - ApplicationError::PermissionDenied(message) => Self { + ServerRouteError::PermissionDenied(message) => Self { status: StatusCode::FORBIDDEN, message, }, - ApplicationError::Internal(error) => Self { + ServerRouteError::Internal(message) => Self { status: StatusCode::INTERNAL_SERVER_ERROR, - message: error, + message, }, } } @@ -201,8 +364,6 @@ async fn main() -> AnyhowResult<()> { let runtime = crate::bootstrap::bootstrap_server_runtime() .await .map_err(|error| anyhow!(error.to_string()))?; - let app_service = runtime.app; - let listener = tokio::net::TcpListener::bind("127.0.0.1:0") .await .map_err(|e| AstrError::io("failed to bind server listener", e))?; @@ -217,7 +378,16 @@ async fn main() -> AnyhowResult<()> { ); let state = AppState { - app: Arc::clone(&app_service), + agent_api: Arc::clone(&runtime.agent_api), + agent_control: Arc::clone(&runtime.agent_control), + config: Arc::clone(&runtime.config), + session_catalog: Arc::clone(&runtime.session_catalog), + profiles: Arc::clone(&runtime.profiles), + subagent_executor: Arc::clone(&runtime.subagent_executor), + mcp_service: Arc::clone(&runtime.mcp_service), + skill_catalog: Arc::clone(&runtime.skill_catalog), + resource_catalog: Arc::clone(&runtime.resource_catalog), + mode_catalog: Arc::clone(&runtime.mode_catalog), governance: Arc::clone(&runtime.governance), auth_sessions: Arc::new(AuthSessionManager::default()), bootstrap_auth: prepared_launch.bootstrap_auth, diff --git a/crates/application/src/mcp/mod.rs b/crates/server/src/mcp/mod.rs similarity index 100% rename from crates/application/src/mcp/mod.rs rename to crates/server/src/mcp/mod.rs diff --git a/crates/server/src/mcp_service.rs b/crates/server/src/mcp_service.rs new file mode 100644 index 00000000..23e53697 --- /dev/null +++ b/crates/server/src/mcp_service.rs @@ -0,0 +1,148 @@ +//! server-owned MCP bridge。 +//! +//! server runtime / state / routes 通过这里的 contract 访问 MCP 用例。 + +use std::sync::Arc; + +use async_trait::async_trait; + +use crate::application_error_bridge::ServerRouteError; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum ServerMcpConfigScope { + User, + Project, + Local, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerMcpServerStatusSummary { + pub name: String, + pub scope: String, + pub enabled: bool, + pub status: String, + pub error: Option, + pub tool_count: usize, + pub prompt_count: usize, + pub resource_count: usize, + pub pending_approval: bool, + pub server_signature: String, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerMcpActionSummary { + pub ok: bool, + pub message: Option, +} + +#[derive(Debug, Clone)] +pub(crate) struct ServerRegisterMcpServerInput { + pub name: String, + pub scope: ServerMcpConfigScope, + pub enabled: bool, + pub timeout_secs: u64, + pub init_timeout_secs: u64, + pub max_reconnect_attempts: u32, + pub transport_config: serde_json::Value, +} + +#[async_trait] +pub(crate) trait ServerMcpPort: Send + Sync { + async fn list_server_status_summary(&self) -> Vec; + + async fn approve_server(&self, server_signature: &str) -> Result<(), ServerRouteError>; + + async fn reject_server(&self, server_signature: &str) -> Result<(), ServerRouteError>; + + async fn reconnect_server(&self, name: &str) -> Result<(), ServerRouteError>; + + async fn reset_project_choices(&self) -> Result<(), ServerRouteError>; + + async fn upsert_server( + &self, + input: ServerRegisterMcpServerInput, + ) -> Result<(), ServerRouteError>; + + async fn remove_server( + &self, + scope: ServerMcpConfigScope, + name: &str, + ) -> Result<(), ServerRouteError>; + + async fn set_server_enabled( + &self, + scope: ServerMcpConfigScope, + name: &str, + enabled: bool, + ) -> Result<(), ServerRouteError>; +} + +#[derive(Clone)] +pub(crate) struct ServerMcpService { + port: Arc, +} + +impl ServerMcpService { + pub(crate) fn new(port: Arc) -> Self { + Self { port } + } + + pub(crate) async fn list_status_summary(&self) -> Vec { + self.port.list_server_status_summary().await + } + + pub(crate) async fn approve_server( + &self, + server_signature: &str, + ) -> Result<(), ServerRouteError> { + self.port.approve_server(server_signature).await + } + + pub(crate) async fn reject_server( + &self, + server_signature: &str, + ) -> Result<(), ServerRouteError> { + self.port.reject_server(server_signature).await + } + + pub(crate) async fn reconnect_server(&self, name: &str) -> Result<(), ServerRouteError> { + self.port.reconnect_server(name).await + } + + pub(crate) async fn reset_project_choices(&self) -> Result<(), ServerRouteError> { + self.port.reset_project_choices().await + } + + pub(crate) async fn upsert_config( + &self, + input: ServerRegisterMcpServerInput, + ) -> Result<(), ServerRouteError> { + self.port.upsert_server(input).await + } + + pub(crate) async fn remove_config( + &self, + scope: ServerMcpConfigScope, + name: &str, + ) -> Result<(), ServerRouteError> { + self.port.remove_server(scope, name).await + } + + pub(crate) async fn set_enabled( + &self, + scope: ServerMcpConfigScope, + name: &str, + enabled: bool, + ) -> Result<(), ServerRouteError> { + self.port.set_server_enabled(scope, name, enabled).await + } +} + +impl ServerMcpActionSummary { + pub(crate) fn ok() -> Self { + Self { + ok: true, + message: None, + } + } +} diff --git a/crates/application/src/mode/builtin_prompts.rs b/crates/server/src/mode/builtin_prompts.rs similarity index 100% rename from crates/application/src/mode/builtin_prompts.rs rename to crates/server/src/mode/builtin_prompts.rs diff --git a/crates/application/src/mode/builtin_prompts/plan_mode.md b/crates/server/src/mode/builtin_prompts/plan_mode.md similarity index 100% rename from crates/application/src/mode/builtin_prompts/plan_mode.md rename to crates/server/src/mode/builtin_prompts/plan_mode.md diff --git a/crates/application/src/mode/builtin_prompts/plan_mode_exit.md b/crates/server/src/mode/builtin_prompts/plan_mode_exit.md similarity index 100% rename from crates/application/src/mode/builtin_prompts/plan_mode_exit.md rename to crates/server/src/mode/builtin_prompts/plan_mode_exit.md diff --git a/crates/application/src/mode/builtin_prompts/plan_mode_reentry.md b/crates/server/src/mode/builtin_prompts/plan_mode_reentry.md similarity index 100% rename from crates/application/src/mode/builtin_prompts/plan_mode_reentry.md rename to crates/server/src/mode/builtin_prompts/plan_mode_reentry.md diff --git a/crates/application/src/mode/builtin_prompts/plan_template.md b/crates/server/src/mode/builtin_prompts/plan_template.md similarity index 100% rename from crates/application/src/mode/builtin_prompts/plan_template.md rename to crates/server/src/mode/builtin_prompts/plan_template.md diff --git a/crates/application/src/mode/catalog.rs b/crates/server/src/mode/catalog.rs similarity index 99% rename from crates/application/src/mode/catalog.rs rename to crates/server/src/mode/catalog.rs index 59c836aa..dbf6345c 100644 --- a/crates/application/src/mode/catalog.rs +++ b/crates/server/src/mode/catalog.rs @@ -1,3 +1,5 @@ +#![allow(dead_code)] + //! 治理模式注册目录。 //! //! `ModeCatalog` 管理所有可用的治理模式（内置 + 插件扩展），提供： diff --git a/crates/application/src/mode/compiler.rs b/crates/server/src/mode/compiler.rs similarity index 69% rename from crates/application/src/mode/compiler.rs rename to crates/server/src/mode/compiler.rs index 426d43dc..434567a7 100644 --- a/crates/application/src/mode/compiler.rs +++ b/crates/server/src/mode/compiler.rs @@ -4,6 +4,7 @@ //! - 保留 mode prompt / contracts / child policy 等稳定语义 //! - 不再根据 capability selector 收缩工具 surface //! - 生成 mode prompt declarations 和子代理策略 +#![allow(dead_code)] use std::collections::BTreeSet; @@ -12,13 +13,11 @@ use astrcode_core::{ PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, PromptDeclarationSource, ResolvedTurnEnvelope, Result, SystemPromptLayer, }; -use astrcode_kernel::CapabilityRouter; #[derive(Clone)] pub struct CompiledModeEnvelope { pub spec: GovernanceModeSpec, pub envelope: ResolvedTurnEnvelope, - pub capability_router: Option, } pub fn compile_capability_selector( @@ -30,7 +29,6 @@ pub fn compile_capability_selector( } pub fn compile_mode_envelope( - _base_router: &CapabilityRouter, spec: &GovernanceModeSpec, extra_prompt_declarations: Vec, ) -> Result { @@ -67,14 +65,10 @@ pub fn compile_mode_envelope( Ok(CompiledModeEnvelope { spec: spec.clone(), envelope, - capability_router: None, }) } -pub fn compile_mode_envelope_for_child( - _base_router: &CapabilityRouter, - spec: &GovernanceModeSpec, -) -> Result { +pub fn compile_mode_envelope_for_child(spec: &GovernanceModeSpec) -> Result { let prompt_declarations = mode_prompt_declarations(spec, Vec::new()); let envelope = ResolvedTurnEnvelope { mode_id: spec.id.clone(), @@ -112,7 +106,6 @@ pub fn compile_mode_envelope_for_child( Ok(CompiledModeEnvelope { spec: spec.clone(), envelope, - capability_router: None, }) } @@ -211,105 +204,59 @@ fn mode_prompt_declarations( #[cfg(test)] mod tests { - use std::sync::Arc; - - use astrcode_core::{ - CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, CapabilityKind, - CapabilitySpec, SideEffect, - }; - use astrcode_kernel::CapabilityRouter; - use async_trait::async_trait; - use serde_json::Value; + use astrcode_core::{CapabilityKind, CapabilitySpec, ForkMode, SideEffect}; - use super::compile_capability_selector; + use super::{compile_capability_selector, compile_mode_envelope_for_child}; use crate::mode::builtin_mode_catalog; - #[derive(Debug)] - struct FakeCapabilityInvoker { - spec: CapabilitySpec, - } - - impl FakeCapabilityInvoker { - fn new(spec: CapabilitySpec) -> Self { - Self { spec } - } - } - - #[async_trait] - impl CapabilityInvoker for FakeCapabilityInvoker { - fn capability_spec(&self) -> CapabilitySpec { - self.spec.clone() - } - - async fn invoke( - &self, - _payload: Value, - _ctx: &CapabilityContext, - ) -> astrcode_core::Result { - Ok(CapabilityExecutionResult::ok( - self.spec.name.to_string(), - Value::Null, - )) - } - } - - fn router() -> CapabilityRouter { - CapabilityRouter::builder() - .register_invoker(Arc::new(FakeCapabilityInvoker::new( - CapabilitySpec::builder("readFile", CapabilityKind::Tool) - .description("read") - .schema( - serde_json::json!({"type":"object"}), - serde_json::json!({"type":"object"}), - ) - .tags(["filesystem", "read"]) - .side_effect(SideEffect::None) - .build() - .expect("readFile should build"), - ))) - .register_invoker(Arc::new(FakeCapabilityInvoker::new( - CapabilitySpec::builder("writeFile", CapabilityKind::Tool) - .description("write") - .schema( - serde_json::json!({"type":"object"}), - serde_json::json!({"type":"object"}), - ) - .tags(["filesystem", "write"]) - .side_effect(SideEffect::Workspace) - .build() - .expect("writeFile should build"), - ))) - .register_invoker(Arc::new(FakeCapabilityInvoker::new( - CapabilitySpec::builder("taskWrite", CapabilityKind::Tool) - .description("task") - .schema( - serde_json::json!({"type":"object"}), - serde_json::json!({"type":"object"}), - ) - .tags(["task", "execution"]) - .side_effect(SideEffect::Local) - .build() - .expect("taskWrite should build"), - ))) - .register_invoker(Arc::new(FakeCapabilityInvoker::new( - CapabilitySpec::builder("spawn", CapabilityKind::Tool) - .description("spawn") - .schema( - serde_json::json!({"type":"object"}), - serde_json::json!({"type":"object"}), - ) - .tags(["agent"]) - .side_effect(SideEffect::None) - .build() - .expect("spawn should build"), - ))) - .build() - .expect("router should build") + fn capability_specs() -> Vec { + vec![ + CapabilitySpec::builder("readFile", CapabilityKind::Tool) + .description("read") + .schema( + serde_json::json!({"type":"object"}), + serde_json::json!({"type":"object"}), + ) + .tags(["filesystem", "read"]) + .side_effect(SideEffect::None) + .build() + .expect("readFile should build"), + CapabilitySpec::builder("writeFile", CapabilityKind::Tool) + .description("write") + .schema( + serde_json::json!({"type":"object"}), + serde_json::json!({"type":"object"}), + ) + .tags(["filesystem", "write"]) + .side_effect(SideEffect::Workspace) + .build() + .expect("writeFile should build"), + CapabilitySpec::builder("taskWrite", CapabilityKind::Tool) + .description("task") + .schema( + serde_json::json!({"type":"object"}), + serde_json::json!({"type":"object"}), + ) + .tags(["task", "execution"]) + .side_effect(SideEffect::Local) + .build() + .expect("taskWrite should build"), + CapabilitySpec::builder("spawn", CapabilityKind::Tool) + .description("spawn") + .schema( + serde_json::json!({"type":"object"}), + serde_json::json!({"type":"object"}), + ) + .tags(["agent"]) + .side_effect(SideEffect::None) + .build() + .expect("spawn should build"), + ] } #[test] fn builtin_modes_compile_expected_tool_equivalence() { - let router = router(); + let capability_specs = capability_specs(); let catalog = builtin_mode_catalog().expect("builtin catalog should build"); let code = catalog.get(&astrcode_core::ModeId::code()).unwrap(); @@ -317,7 +264,7 @@ mod tests { let review = catalog.get(&astrcode_core::ModeId::review()).unwrap(); assert_eq!( - compile_capability_selector(&router.capability_specs(), &code.capability_selector) + compile_capability_selector(&capability_specs, &code.capability_selector) .expect("code selector should compile"), vec![ "readFile".to_string(), @@ -327,12 +274,12 @@ mod tests { ] ); assert_eq!( - compile_capability_selector(&router.capability_specs(), &plan.capability_selector) + compile_capability_selector(&capability_specs, &plan.capability_selector) .expect("plan selector should compile"), vec!["readFile".to_string()] ); assert_eq!( - compile_capability_selector(&router.capability_specs(), &review.capability_selector) + compile_capability_selector(&capability_specs, &review.capability_selector) .expect("review selector should compile"), vec!["readFile".to_string()] ); @@ -340,12 +287,11 @@ mod tests { #[test] fn compile_mode_envelope_projects_mode_contracts_into_compile_artifact() { - let router = router(); let catalog = builtin_mode_catalog().expect("builtin catalog should build"); let plan = catalog.get(&astrcode_core::ModeId::plan()).unwrap(); let compiled = - super::compile_mode_envelope(&router, &plan, Vec::new()).expect("plan should compile"); + super::compile_mode_envelope(&plan, Vec::new()).expect("plan should compile"); assert_eq!( compiled @@ -370,4 +316,26 @@ mod tests { "plan compile artifact should carry prompt hooks" ); } + + #[test] + fn child_mode_compile_uses_child_fork_mode_for_child_execution_fallback() { + let catalog = builtin_mode_catalog().expect("builtin catalog should build"); + let mut mode = catalog.get(&astrcode_core::ModeId::code()).unwrap(); + mode.execution_policy.fork_mode = None; + mode.child_policy.fork_mode = Some(ForkMode::LastNTurns(4)); + + let compiled = + compile_mode_envelope_for_child(&mode).expect("child envelope should compile"); + + assert_eq!( + compiled.envelope.fork_mode, + Some(ForkMode::LastNTurns(4)), + "child execution should inherit childPolicy.forkMode when executionPolicy has no \ + forkMode" + ); + assert_eq!( + compiled.envelope.child_policy.fork_mode, + Some(ForkMode::LastNTurns(4)) + ); + } } diff --git a/crates/application/src/mode/mod.rs b/crates/server/src/mode/mod.rs similarity index 66% rename from crates/application/src/mode/mod.rs rename to crates/server/src/mode/mod.rs index cde93052..c3950da7 100644 --- a/crates/application/src/mode/mod.rs +++ b/crates/server/src/mode/mod.rs @@ -15,12 +15,6 @@ mod catalog; mod compiler; mod validator; -pub use catalog::{ - BuiltinModeCatalog, ModeCatalog, ModeCatalogEntry, ModeCatalogSnapshot, ModeSummary, - builtin_mode_catalog, -}; -pub use compiler::{ - CompiledModeEnvelope, compile_capability_selector, compile_mode_envelope, - compile_mode_envelope_for_child, -}; -pub use validator::{ModeTransitionDecision, validate_mode_transition}; +pub use catalog::{ModeCatalog, builtin_mode_catalog}; +pub use compiler::{CompiledModeEnvelope, compile_mode_envelope, compile_mode_envelope_for_child}; +pub use validator::validate_mode_transition; diff --git a/crates/application/src/mode/validator.rs b/crates/server/src/mode/validator.rs similarity index 100% rename from crates/application/src/mode/validator.rs rename to crates/server/src/mode/validator.rs diff --git a/crates/server/src/mode_catalog_service.rs b/crates/server/src/mode_catalog_service.rs new file mode 100644 index 00000000..5c868a6c --- /dev/null +++ b/crates/server/src/mode_catalog_service.rs @@ -0,0 +1,140 @@ +use std::{ + collections::BTreeMap, + sync::{Arc, RwLock}, +}; + +use astrcode_core::{AstrError, GovernanceModeSpec, ModeId, Result}; + +use crate::mode::{ModeCatalog, validate_mode_transition}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerModeSummary { + pub id: ModeId, + pub name: String, + pub description: String, +} + +#[derive(Debug, Clone)] +pub(crate) struct ServerModeCatalogEntry { + pub spec: GovernanceModeSpec, + pub builtin: bool, +} + +#[derive(Debug, Clone, Default)] +pub(crate) struct ServerModeCatalogSnapshot { + pub entries: BTreeMap, +} + +impl ServerModeCatalogSnapshot { + pub(crate) fn list(&self) -> Vec { + self.entries + .values() + .map(|entry| ServerModeSummary { + id: entry.spec.id.clone(), + name: entry.spec.name.clone(), + description: entry.spec.description.clone(), + }) + .collect() + } +} + +#[derive(Debug, Clone)] +pub(crate) struct ServerModeCatalog { + snapshot: Arc>, +} + +impl ServerModeCatalog { + pub(crate) fn from_mode_specs( + builtin_modes: Vec, + plugin_modes: Vec, + ) -> Result> { + Ok(Arc::new(Self::new(build_snapshot( + builtin_modes, + plugin_modes, + )?))) + } + + pub(crate) fn new(snapshot: ServerModeCatalogSnapshot) -> Self { + Self { + snapshot: Arc::new(RwLock::new(snapshot)), + } + } + + pub(crate) fn snapshot(&self) -> ServerModeCatalogSnapshot { + self.snapshot + .read() + .expect("server mode catalog lock poisoned") + .clone() + } + + pub(crate) fn list(&self) -> Vec { + self.snapshot().list() + } + + pub(crate) fn preview_plugin_modes( + &self, + plugin_modes: Vec, + ) -> Result { + let current = self.snapshot(); + let builtin_modes = current + .entries + .values() + .filter(|entry| entry.builtin) + .map(|entry| entry.spec.clone()) + .collect::>(); + build_snapshot(builtin_modes, plugin_modes) + } + + pub(crate) fn replace_snapshot(&self, snapshot: ServerModeCatalogSnapshot) { + *self + .snapshot + .write() + .expect("server mode catalog lock poisoned") = snapshot; + } + + pub(crate) fn validate_transition( + &self, + from_mode_id: &ModeId, + to_mode_id: &ModeId, + ) -> Result<()> { + let snapshot = self.snapshot(); + let builtin_modes = snapshot + .entries + .values() + .filter(|entry| entry.builtin) + .map(|entry| entry.spec.clone()) + .collect::>(); + let plugin_modes = snapshot + .entries + .values() + .filter(|entry| !entry.builtin) + .map(|entry| entry.spec.clone()) + .collect::>(); + let catalog = ModeCatalog::new(builtin_modes, plugin_modes)?; + validate_mode_transition(&catalog, from_mode_id, to_mode_id)?; + Ok(()) + } +} + +fn build_snapshot( + builtin_modes: impl IntoIterator, + plugin_modes: impl IntoIterator, +) -> Result { + let mut entries = BTreeMap::new(); + for (builtin, spec) in builtin_modes + .into_iter() + .map(|spec| (true, spec)) + .chain(plugin_modes.into_iter().map(|spec| (false, spec))) + { + spec.validate()?; + let mode_id = spec.id.as_str().to_string(); + if entries.contains_key(&mode_id) { + return Err(AstrError::Validation(format!( + "duplicate mode id '{}'", + mode_id + ))); + } + entries.insert(mode_id, ServerModeCatalogEntry { spec, builtin }); + } + Ok(ServerModeCatalogSnapshot { entries }) +} diff --git a/crates/application/src/observability/collector.rs b/crates/server/src/observability/collector.rs similarity index 100% rename from crates/application/src/observability/collector.rs rename to crates/server/src/observability/collector.rs diff --git a/crates/application/src/observability/metrics_snapshot.rs b/crates/server/src/observability/metrics_snapshot.rs similarity index 75% rename from crates/application/src/observability/metrics_snapshot.rs rename to crates/server/src/observability/metrics_snapshot.rs index 0c3be3ee..568f9ddc 100644 --- a/crates/application/src/observability/metrics_snapshot.rs +++ b/crates/server/src/observability/metrics_snapshot.rs @@ -5,6 +5,5 @@ pub use astrcode_core::{ AgentCollaborationScorecardSnapshot, ExecutionDiagnosticsSnapshot, OperationMetricsSnapshot, - ReplayMetricsSnapshot, ReplayPath, RuntimeObservabilitySnapshot, - SubRunExecutionMetricsSnapshot, + ReplayMetricsSnapshot, RuntimeObservabilitySnapshot, SubRunExecutionMetricsSnapshot, }; diff --git a/crates/application/src/observability/mod.rs b/crates/server/src/observability/mod.rs similarity index 66% rename from crates/application/src/observability/mod.rs rename to crates/server/src/observability/mod.rs index 1b08ba33..ad01d065 100644 --- a/crates/application/src/observability/mod.rs +++ b/crates/server/src/observability/mod.rs @@ -1,19 +1,19 @@ //! # 可观测性 //! //! 提供运行时指标快照类型和治理快照能力。 -//! 实际的指标收集逻辑留在旧 runtime，组合根接线时桥接。 +//! 实际的指标收集逻辑由组合根接线。 mod collector; mod metrics_snapshot; use std::path::PathBuf; -use astrcode_core::{CapabilitySpec, plugin::PluginEntry}; +use astrcode_core::CapabilitySpec; +use astrcode_plugin_host::PluginEntry; pub use collector::RuntimeObservabilityCollector; pub use metrics_snapshot::{ AgentCollaborationScorecardSnapshot, ExecutionDiagnosticsSnapshot, OperationMetricsSnapshot, - ReplayMetricsSnapshot, ReplayPath, RuntimeObservabilitySnapshot, - SubRunExecutionMetricsSnapshot, + ReplayMetricsSnapshot, RuntimeObservabilitySnapshot, SubRunExecutionMetricsSnapshot, }; /// 运行时治理快照 @@ -32,104 +32,6 @@ pub struct GovernanceSnapshot { pub plugins: Vec, } -/// runtime capability 的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct RuntimeCapabilitySummary { - pub name: String, - pub kind: String, - pub description: String, - pub profiles: Vec, - pub streaming: bool, -} - -/// runtime plugin 的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct RuntimePluginSummary { - pub name: String, - pub version: String, - pub description: String, - pub state: astrcode_core::PluginState, - pub health: astrcode_core::PluginHealth, - pub failure_count: u32, - pub failure: Option, - pub warnings: Vec, - pub last_checked_at: Option, - pub capabilities: Vec, -} - -/// 已解析的 runtime 状态摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ResolvedRuntimeStatusSummary { - pub runtime_name: String, - pub runtime_kind: String, - pub loaded_session_count: usize, - pub running_session_ids: Vec, - pub plugin_search_paths: Vec, - pub metrics: RuntimeObservabilitySnapshot, - pub capabilities: Vec, - pub plugins: Vec, -} - -/// 将治理快照解析为协议层可复用的摘要输入。 -pub fn resolve_runtime_status_summary( - snapshot: GovernanceSnapshot, -) -> ResolvedRuntimeStatusSummary { - ResolvedRuntimeStatusSummary { - runtime_name: snapshot.runtime_name, - runtime_kind: snapshot.runtime_kind, - loaded_session_count: snapshot.loaded_session_count, - running_session_ids: snapshot.running_session_ids, - plugin_search_paths: snapshot - .plugin_search_paths - .into_iter() - .map(|path| path.display().to_string()) - .collect(), - metrics: snapshot.metrics, - capabilities: snapshot - .capabilities - .into_iter() - .map(resolve_runtime_capability_summary) - .collect(), - plugins: snapshot - .plugins - .into_iter() - .map(resolve_runtime_plugin_summary) - .collect(), - } -} - -fn resolve_runtime_capability_summary(spec: CapabilitySpec) -> RuntimeCapabilitySummary { - RuntimeCapabilitySummary { - name: spec.name.to_string(), - kind: spec.kind.as_str().to_string(), - description: spec.description, - profiles: spec.profiles, - streaming: matches!( - spec.invocation_mode, - astrcode_core::InvocationMode::Streaming - ), - } -} - -fn resolve_runtime_plugin_summary(entry: PluginEntry) -> RuntimePluginSummary { - RuntimePluginSummary { - name: entry.manifest.name, - version: entry.manifest.version, - description: entry.manifest.description, - state: entry.state, - health: entry.health, - failure_count: entry.failure_count, - failure: entry.failure, - warnings: entry.warnings, - last_checked_at: entry.last_checked_at, - capabilities: entry - .capabilities - .into_iter() - .map(resolve_runtime_capability_summary) - .collect(), - } -} - /// 运行时重载操作的结果。 #[derive(Debug, Clone)] pub struct ReloadResult { @@ -143,13 +45,109 @@ pub struct ReloadResult { mod tests { use astrcode_core::{ AgentCollaborationScorecardSnapshot, CapabilitySpec, ExecutionDiagnosticsSnapshot, - OperationMetricsSnapshot, PluginHealth, PluginManifest, PluginState, PluginType, - ReplayMetricsSnapshot, SideEffect, Stability, SubRunExecutionMetricsSnapshot, - plugin::PluginEntry, + OperationMetricsSnapshot, ReplayMetricsSnapshot, SideEffect, Stability, + SubRunExecutionMetricsSnapshot, + }; + use astrcode_plugin_host::{ + PluginEntry, PluginHealth, PluginManifest, PluginState, PluginType, }; use serde_json::json; - use super::{GovernanceSnapshot, RuntimeObservabilitySnapshot, resolve_runtime_status_summary}; + use super::{GovernanceSnapshot, RuntimeObservabilitySnapshot}; + + #[derive(Debug, Clone, PartialEq, Eq)] + struct RuntimeCapabilitySummary { + name: String, + kind: String, + description: String, + profiles: Vec, + streaming: bool, + } + + #[derive(Debug, Clone, PartialEq, Eq)] + struct RuntimePluginSummary { + name: String, + version: String, + description: String, + state: PluginState, + health: PluginHealth, + failure_count: u32, + failure: Option, + warnings: Vec, + last_checked_at: Option, + capabilities: Vec, + } + + #[derive(Debug, Clone, PartialEq, Eq)] + struct ResolvedRuntimeStatusSummary { + runtime_name: String, + runtime_kind: String, + loaded_session_count: usize, + running_session_ids: Vec, + plugin_search_paths: Vec, + metrics: RuntimeObservabilitySnapshot, + capabilities: Vec, + plugins: Vec, + } + + fn resolve_runtime_status_summary( + snapshot: GovernanceSnapshot, + ) -> ResolvedRuntimeStatusSummary { + ResolvedRuntimeStatusSummary { + runtime_name: snapshot.runtime_name, + runtime_kind: snapshot.runtime_kind, + loaded_session_count: snapshot.loaded_session_count, + running_session_ids: snapshot.running_session_ids, + plugin_search_paths: snapshot + .plugin_search_paths + .into_iter() + .map(|path| path.display().to_string()) + .collect(), + metrics: snapshot.metrics, + capabilities: snapshot + .capabilities + .into_iter() + .map(resolve_runtime_capability_summary) + .collect(), + plugins: snapshot + .plugins + .into_iter() + .map(resolve_runtime_plugin_summary) + .collect(), + } + } + + fn resolve_runtime_capability_summary(spec: CapabilitySpec) -> RuntimeCapabilitySummary { + RuntimeCapabilitySummary { + name: spec.name.to_string(), + kind: spec.kind.as_str().to_string(), + description: spec.description, + profiles: spec.profiles, + streaming: matches!( + spec.invocation_mode, + astrcode_core::InvocationMode::Streaming + ), + } + } + + fn resolve_runtime_plugin_summary(entry: PluginEntry) -> RuntimePluginSummary { + RuntimePluginSummary { + name: entry.manifest.name, + version: entry.manifest.version, + description: entry.manifest.description, + state: entry.state, + health: entry.health, + failure_count: entry.failure_count, + failure: entry.failure, + warnings: entry.warnings, + last_checked_at: entry.last_checked_at, + capabilities: entry + .capabilities + .into_iter() + .map(resolve_runtime_capability_summary) + .collect(), + } + } fn capability(name: &str, streaming: bool) -> CapabilitySpec { let mut builder = CapabilitySpec::builder(name, "tool") @@ -177,6 +175,12 @@ mod tests { args: Vec::new(), working_dir: None, repository: None, + resources: Vec::new(), + commands: Vec::new(), + themes: Vec::new(), + prompts: Vec::new(), + providers: Vec::new(), + skills: Vec::new(), } } diff --git a/crates/server/src/ports/agent_kernel.rs b/crates/server/src/ports/agent_kernel.rs new file mode 100644 index 00000000..82ba8f5f --- /dev/null +++ b/crates/server/src/ports/agent_kernel.rs @@ -0,0 +1,79 @@ +//! Agent 编排子域依赖的 kernel 稳定端口。 +//! +//! `AgentKernelPort` 继承 `AppKernelPort`，扩展了 agent 编排所需的全部 kernel 操作： +//! lifecycle 管理、子 agent spawn/resume/terminate、inbox 投递、parent delivery 队列。 +//! +//! 为什么单独抽 trait：`AgentOrchestrationService` 需要的控制面明显大于 `App`， +//! 避免 `AppKernelPort` 被动膨胀成新的大而全 façade。 +//! +//! server-owned bridge 是正式实现入口，不把底层 session runtime 暴露成 kernel owner。 + +use astrcode_core::{ + AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, + DelegationMetadata, +}; +use astrcode_host_session::SubRunHandle; +use async_trait::async_trait; + +use super::{AppKernelPort, RecoverableParentDelivery, ServerKernelControlError}; + +/// Agent 编排子域依赖的 kernel 稳定端口。 +/// +/// Why: `AgentOrchestrationService` 需要的控制面明显大于 `App`， +/// 单独抽 trait 能避免 `AppKernelPort` 被动膨胀成新的大而全 façade。 +#[async_trait] +pub trait AgentKernelPort: AppKernelPort { + async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option; + async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option; + async fn resume(&self, sub_run_or_agent_id: &str, parent_turn_id: &str) + -> Option; + async fn spawn_independent_child( + &self, + profile: &astrcode_core::AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> Result; + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()>; + async fn complete_turn( + &self, + sub_run_or_agent_id: &str, + outcome: AgentTurnOutcome, + ) -> Option; + async fn set_delegation( + &self, + sub_run_or_agent_id: &str, + delegation: Option, + ) -> Option<()>; + async fn count_children_spawned_for_turn( + &self, + parent_agent_id: &str, + parent_turn_id: &str, + ) -> usize; + async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec; + async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option; + async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()>; + async fn drain_inbox(&self, agent_id: &str) -> Option>; + async fn enqueue_child_delivery( + &self, + parent_session_id: String, + parent_turn_id: String, + notification: ChildSessionNotification, + ) -> bool; + async fn checkout_parent_delivery_batch( + &self, + parent_session_id: &str, + ) -> Option>; + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize; + async fn requeue_parent_delivery_batch(&self, parent_session_id: &str, delivery_ids: &[String]); + async fn consume_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) -> bool; +} diff --git a/crates/server/src/ports/agent_session.rs b/crates/server/src/ports/agent_session.rs new file mode 100644 index 00000000..051ba3cf --- /dev/null +++ b/crates/server/src/ports/agent_session.rs @@ -0,0 +1,131 @@ +//! Agent 编排子域依赖的 session 稳定端口。 +//! +//! `AgentSessionPort` 继承 `AppSessionPort`，扩展了 agent 协作编排所需的全部 session 操作： +//! child session 建立、prompt 提交（带 turn id）、durable input queue 管理、 +//! collaboration fact 追加、observe 快照、turn 终态等待。 +//! +//! 先按职责分组在一个端口中表达完整协作流程，未来根据演化决定是否继续瘦身。 +//! +//! 生产路径通过 server-owned bridge 实现该端口，避免把底层 runtime 直接暴露成 session owner。 + +use astrcode_core::{ + AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, ExecutionAccepted, + InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, + ResolvedRuntimeConfig, SessionMeta, StoredEvent, TurnId, +}; +use async_trait::async_trait; + +use super::{ + AppAgentPromptSubmission, AppSessionPort, RecoverableParentDelivery, SessionObserveSnapshot, + SessionTurnOutcomeSummary, SessionTurnTerminalState, +}; + +/// Agent 编排子域依赖的 session 稳定端口。 +/// +/// Why: 这里的方法虽然不少，但调用者仍是同一批 agent collaboration use case。 +/// 先按职责分组，保持一个端口表达完整协作流程，再根据未来演化决定是否继续瘦身。 +#[async_trait] +pub trait AgentSessionPort: AppSessionPort { + // 子 agent session 建立与 prompt 提交。 + async fn create_child_session( + &self, + working_dir: &str, + parent_session_id: &str, + ) -> astrcode_core::Result; + async fn submit_prompt_for_agent_with_submission( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result; + async fn try_submit_prompt_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result>; + async fn submit_queued_inputs_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + queued_inputs: Vec, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result>; + + // Durable input queue / collaboration 事件追加。 + async fn append_agent_input_queued( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputQueuedPayload, + ) -> astrcode_core::Result; + async fn append_agent_input_discarded( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputDiscardedPayload, + ) -> astrcode_core::Result; + async fn append_agent_input_batch_started( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchStartedPayload, + ) -> astrcode_core::Result; + async fn append_agent_input_batch_acked( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchAckedPayload, + ) -> astrcode_core::Result; + async fn append_child_session_notification( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + notification: astrcode_core::ChildSessionNotification, + ) -> astrcode_core::Result; + async fn append_agent_collaboration_fact( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + fact: AgentCollaborationFact, + ) -> astrcode_core::Result; + async fn pending_delivery_ids_for_agent( + &self, + session_id: &str, + agent_id: &str, + ) -> astrcode_core::Result>; + async fn recoverable_parent_deliveries( + &self, + parent_session_id: &str, + ) -> astrcode_core::Result>; + + // 观察与投影读取。 + async fn observe_agent_session( + &self, + open_session_id: &str, + target_agent_id: &str, + lifecycle_status: AgentLifecycleStatus, + ) -> astrcode_core::Result; + async fn project_turn_outcome( + &self, + session_id: &str, + turn_id: &str, + ) -> astrcode_core::Result; + + // Turn 终态等待。 + async fn wait_for_turn_terminal_snapshot( + &self, + session_id: &str, + turn_id: &str, + ) -> astrcode_core::Result; +} diff --git a/crates/server/src/ports/app_kernel.rs b/crates/server/src/ports/app_kernel.rs new file mode 100644 index 00000000..24deb964 --- /dev/null +++ b/crates/server/src/ports/app_kernel.rs @@ -0,0 +1,58 @@ +//! `App` 依赖的 kernel 稳定端口。 +//! +//! 定义 `AppKernelPort` trait，将应用层与 kernel 具体实现解耦。 +//! `App` 只需要一组稳定的 agent 控制与 capability 查询契约。 +//! +//! server-owned bridge 是正式实现入口，避免把底层 session runtime 当成 owner surface 暴露。 + +use std::fmt; + +use astrcode_host_session::SubRunHandle; +use async_trait::async_trait; + +/// server-owned 的最小 agent control 错误模型。 +/// +/// Why: owner bridge 只向执行面暴露 server 真正需要解释的约束语义。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ServerKernelControlError { + MaxDepthExceeded { current: usize, max: usize }, + MaxConcurrentExceeded { current: usize, max: usize }, + ParentAgentNotFound { agent_id: String }, +} + +impl fmt::Display for ServerKernelControlError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::MaxDepthExceeded { current, max } => { + write!(f, "max depth exceeded ({current}/{max})") + }, + Self::MaxConcurrentExceeded { current, max } => { + write!(f, "max concurrent agents exceeded ({current}/{max})") + }, + Self::ParentAgentNotFound { agent_id } => { + write!(f, "parent agent '{agent_id}' not found") + }, + } + } +} + +/// `App` 依赖的 kernel 稳定端口。 +/// +/// Why: `App` 是应用层用例入口，不应直接绑定 `Kernel` 具体实现； +/// 它只需要一组稳定的 agent 控制与 capability 查询契约。 +#[async_trait] +pub trait AppKernelPort: Send + Sync { + async fn get_handle(&self, agent_id: &str) -> Option; + async fn find_root_handle_for_session(&self, session_id: &str) -> Option; + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result; + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: astrcode_core::ResolvedExecutionLimitsSnapshot, + ) -> Option<()>; +} diff --git a/crates/server/src/ports/app_session.rs b/crates/server/src/ports/app_session.rs new file mode 100644 index 00000000..d1e154cf --- /dev/null +++ b/crates/server/src/ports/app_session.rs @@ -0,0 +1,105 @@ +//! `App` 依赖的 session 稳定端口。 +//! +//! 定义 `AppSessionPort` trait，将应用层与底层 session owner 具体实现解耦。 +//! `App` 只编排 session 用例（创建、提交、快照、compact 等）， +//! 不直接耦合具体 owner 的 catalog/fork/query helper。 + +use astrcode_core::{ + ChildSessionNode, DeleteProjectResult, ExecutionAccepted, ResolvedRuntimeConfig, SessionMeta, + StoredEvent, TaskSnapshot, +}; +use astrcode_host_session::{SessionCatalogEvent, SessionControlStateSnapshot, SessionModeState}; +use async_trait::async_trait; +use tokio::sync::broadcast; + +use super::{AppAgentPromptSubmission, DurableSubRunStatusSummary}; +use crate::{ + conversation_read_model::{ + ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionReplay, + SessionTranscriptSnapshot, + }, + session_use_cases::SessionForkSelector, +}; + +/// `App` 依赖的 session 稳定端口。 +/// +/// Why: `App` 只编排 session 用例，不应直接耦合具体 session owner 的 helper 类型。 +#[allow(dead_code)] +#[async_trait] +pub trait AppSessionPort: Send + Sync { + fn subscribe_catalog_events(&self) -> broadcast::Receiver; + + async fn list_session_metas(&self) -> astrcode_core::Result>; + async fn create_session(&self, working_dir: String) -> astrcode_core::Result; + async fn fork_session( + &self, + session_id: &str, + selector: SessionForkSelector, + ) -> astrcode_core::Result; + async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()>; + async fn delete_project(&self, working_dir: &str) + -> astrcode_core::Result; + async fn get_session_working_dir(&self, session_id: &str) -> astrcode_core::Result; + async fn submit_prompt_for_agent( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result; + async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()>; + async fn compact_session( + &self, + session_id: &str, + runtime: ResolvedRuntimeConfig, + instructions: Option, + ) -> astrcode_core::Result; + async fn session_transcript_snapshot( + &self, + session_id: &str, + ) -> astrcode_core::Result; + async fn conversation_snapshot( + &self, + session_id: &str, + ) -> astrcode_core::Result; + async fn session_control_state( + &self, + session_id: &str, + ) -> astrcode_core::Result; + async fn active_task_snapshot( + &self, + session_id: &str, + owner: &str, + ) -> astrcode_core::Result>; + async fn session_mode_state(&self, session_id: &str) + -> astrcode_core::Result; + async fn switch_mode( + &self, + session_id: &str, + from: astrcode_core::ModeId, + to: astrcode_core::ModeId, + ) -> astrcode_core::Result; + async fn session_child_nodes( + &self, + session_id: &str, + ) -> astrcode_core::Result>; + async fn session_stored_events( + &self, + session_id: &str, + ) -> astrcode_core::Result>; + async fn durable_subrun_status_snapshot( + &self, + parent_session_id: &str, + requested_subrun_id: &str, + ) -> astrcode_core::Result>; + async fn session_replay( + &self, + session_id: &str, + last_event_id: Option<&str>, + ) -> astrcode_core::Result; + async fn conversation_stream_replay( + &self, + session_id: &str, + last_event_id: Option<&str>, + ) -> astrcode_core::Result; +} diff --git a/crates/application/src/ports/composer_skill.rs b/crates/server/src/ports/composer_skill.rs similarity index 100% rename from crates/application/src/ports/composer_skill.rs rename to crates/server/src/ports/composer_skill.rs diff --git a/crates/server/src/ports/kernel_bridge.rs b/crates/server/src/ports/kernel_bridge.rs new file mode 100644 index 00000000..97caefc9 --- /dev/null +++ b/crates/server/src/ports/kernel_bridge.rs @@ -0,0 +1,287 @@ +use std::sync::Arc; + +use astrcode_core::{ + AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, + DelegationMetadata, ResolvedExecutionLimitsSnapshot, +}; +use astrcode_host_session::SubRunHandle; +use async_trait::async_trait; + +use super::{AgentKernelPort, AppKernelPort, RecoverableParentDelivery, ServerKernelControlError}; +use crate::{ + agent_control_bridge::{ + ServerAgentControlPort, ServerAgentHandleSummary, ServerCloseAgentSummary, + ServerLiveSubRunStatus, + }, + application_error_bridge::ServerRouteError, + session_runtime_port::SessionRuntimePort, +}; + +pub(crate) fn build_server_kernel_bridge( + session_runtime: Arc, +) -> Arc { + Arc::new(ServerKernelBridge { session_runtime }) +} + +pub(crate) struct ServerKernelBridge { + session_runtime: Arc, +} + +#[async_trait] +impl AppKernelPort for ServerKernelBridge { + async fn get_handle(&self, agent_id: &str) -> Option { + self.session_runtime.get_handle(agent_id).await + } + + async fn find_root_handle_for_session(&self, session_id: &str) -> Option { + self.session_runtime + .find_root_handle_for_session(session_id) + .await + } + + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result { + self.session_runtime + .register_root_agent(agent_id, session_id, profile_id) + .await + } + + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> Option<()> { + self.session_runtime + .set_resolved_limits(sub_run_or_agent_id, resolved_limits) + .await + } +} + +#[async_trait] +impl AgentKernelPort for ServerKernelBridge { + async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option { + self.session_runtime + .get_lifecycle(sub_run_or_agent_id) + .await + } + + async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option { + self.session_runtime + .get_turn_outcome(sub_run_or_agent_id) + .await + } + + async fn resume( + &self, + sub_run_or_agent_id: &str, + parent_turn_id: &str, + ) -> Option { + self.session_runtime + .resume(sub_run_or_agent_id, parent_turn_id) + .await + } + + async fn spawn_independent_child( + &self, + profile: &astrcode_core::AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> Result { + self.session_runtime + .spawn_independent_child( + profile, + session_id, + child_session_id, + parent_turn_id, + parent_agent_id, + ) + .await + } + + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()> { + self.session_runtime + .set_lifecycle(sub_run_or_agent_id, new_status) + .await + } + + async fn complete_turn( + &self, + sub_run_or_agent_id: &str, + outcome: AgentTurnOutcome, + ) -> Option { + self.session_runtime + .complete_turn(sub_run_or_agent_id, outcome) + .await + } + + async fn set_delegation( + &self, + sub_run_or_agent_id: &str, + delegation: Option, + ) -> Option<()> { + self.session_runtime + .set_delegation(sub_run_or_agent_id, delegation) + .await + } + + async fn count_children_spawned_for_turn( + &self, + parent_agent_id: &str, + parent_turn_id: &str, + ) -> usize { + self.session_runtime + .count_children_spawned_for_turn(parent_agent_id, parent_turn_id) + .await + } + + async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec { + self.session_runtime + .collect_subtree_handles(sub_run_or_agent_id) + .await + } + + async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option { + self.session_runtime + .terminate_subtree(sub_run_or_agent_id) + .await + } + + async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()> { + self.session_runtime.deliver(agent_id, envelope).await + } + + async fn drain_inbox(&self, agent_id: &str) -> Option> { + self.session_runtime.drain_inbox(agent_id).await + } + + async fn enqueue_child_delivery( + &self, + parent_session_id: String, + parent_turn_id: String, + notification: ChildSessionNotification, + ) -> bool { + self.session_runtime + .enqueue_child_delivery(parent_session_id, parent_turn_id, notification) + .await + } + + async fn checkout_parent_delivery_batch( + &self, + parent_session_id: &str, + ) -> Option> { + self.session_runtime + .checkout_parent_delivery_batch(parent_session_id) + .await + .map(|deliveries| { + deliveries + .into_iter() + .map(|value| RecoverableParentDelivery { + delivery_id: value.delivery_id, + parent_session_id: value.parent_session_id, + parent_turn_id: value.parent_turn_id, + queued_at_ms: value.queued_at_ms, + notification: value.notification, + }) + .collect() + }) + } + + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { + self.session_runtime + .pending_parent_delivery_count(parent_session_id) + .await + } + + async fn requeue_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) { + self.session_runtime + .requeue_parent_delivery_batch(parent_session_id, delivery_ids) + .await + } + + async fn consume_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) -> bool { + self.session_runtime + .consume_parent_delivery_batch(parent_session_id, delivery_ids) + .await + } +} + +#[async_trait] +impl ServerAgentControlPort for ServerKernelBridge { + async fn query_subrun_status(&self, agent_id: &str) -> Option { + self.session_runtime.query_subrun_status(agent_id).await + } + + async fn query_root_status(&self, session_id: &str) -> Option { + self.session_runtime.query_root_status(session_id).await + } + + async fn get_handle(&self, agent_id: &str) -> Option { + self.session_runtime + .get_handle(agent_id) + .await + .map(|handle| ServerAgentHandleSummary { + agent_id: handle.agent_id.to_string(), + session_id: handle.session_id.to_string(), + }) + } + + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result { + self.session_runtime + .register_root_agent(agent_id, session_id, profile_id) + .await + .map(|handle| ServerAgentHandleSummary { + agent_id: handle.agent_id.to_string(), + session_id: handle.session_id.to_string(), + }) + .map_err(|error| { + ServerRouteError::internal(format!("failed to register root agent: {error}")) + }) + } + + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> bool { + self.session_runtime + .set_resolved_limits(sub_run_or_agent_id, resolved_limits) + .await + .is_some() + } + + async fn close_subtree( + &self, + agent_id: &str, + ) -> Result { + self.session_runtime + .close_subtree(agent_id) + .await + .map(|result| ServerCloseAgentSummary { + closed_agent_ids: result.closed_agent_ids, + }) + .map_err(|error| ServerRouteError::internal(error.to_string())) + } +} diff --git a/crates/application/src/ports/mod.rs b/crates/server/src/ports/mod.rs similarity index 67% rename from crates/application/src/ports/mod.rs rename to crates/server/src/ports/mod.rs index 99173e77..a31dda46 100644 --- a/crates/application/src/ports/mod.rs +++ b/crates/server/src/ports/mod.rs @@ -5,23 +5,24 @@ //! - `AgentKernelPort`：Agent 编排子域扩展的 kernel 端口 //! - `AppSessionPort`：`App` 依赖的 session-runtime 稳定端口 //! - `AgentSessionPort`：Agent 编排子域扩展的 session 端口 -//! - `ComposerSkillPort`：composer 输入补全的 skill 查询端口 mod agent_kernel; mod agent_session; mod app_kernel; mod app_session; -mod composer_skill; +pub(crate) mod kernel_bridge; +pub(crate) mod session_bridge; mod session_contracts; mod session_submission; pub use agent_kernel::AgentKernelPort; pub use agent_session::AgentSessionPort; -pub use app_kernel::AppKernelPort; +pub use app_kernel::{AppKernelPort, ServerKernelControlError}; pub use app_session::AppSessionPort; -pub use composer_skill::{ComposerResolvedSkill, ComposerSkillPort}; +#[cfg(test)] +pub(crate) use session_bridge::recoverable_parent_deliveries; pub use session_contracts::{ - RecoverableParentDelivery, SessionObserveSnapshot, SessionTurnOutcomeSummary, - SessionTurnTerminalState, + DurableSubRunStatusSummary, RecoverableParentDelivery, SessionObserveSnapshot, + SessionTurnOutcomeSummary, SessionTurnTerminalState, }; pub use session_submission::AppAgentPromptSubmission; diff --git a/crates/server/src/ports/session_bridge.rs b/crates/server/src/ports/session_bridge.rs new file mode 100644 index 00000000..5a242e3a --- /dev/null +++ b/crates/server/src/ports/session_bridge.rs @@ -0,0 +1,874 @@ +use std::{ + collections::{HashMap, HashSet}, + sync::Arc, +}; + +use astrcode_core::{ + AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, ExecutionAccepted, + InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, + InvocationKind, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, + ResolvedSubagentContextOverrides, SessionEventRecord, SessionId, SessionMeta, + StorageEventPayload, StoredEvent, SubRunResult, SubRunStorageMode, TurnId, replay_records, +}; +use astrcode_host_session::{ + ForkPoint, InputQueueProjection, ProjectedTurnOutcome, SessionCatalog, SubRunHandle, +}; +use async_trait::async_trait; +use tokio::sync::broadcast; + +use super::{ + AgentSessionPort, AppAgentPromptSubmission, AppSessionPort, DurableSubRunStatusSummary, + RecoverableParentDelivery, SessionObserveSnapshot, SessionTurnOutcomeSummary, + SessionTurnTerminalState, +}; +use crate::{ + conversation_read_model::{ + ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionReplay, + SessionTranscriptSnapshot, build_conversation_replay_frames, project_conversation_snapshot, + }, + session_identity::normalize_external_session_id, + session_runtime_port::SessionRuntimePort, + session_use_cases::SessionForkSelector, +}; + +pub(crate) fn build_server_session_bridge( + session_catalog: Arc, + session_runtime: Arc, +) -> Arc { + Arc::new(ServerSessionBridge { + session_catalog, + session_runtime, + }) +} + +pub(crate) struct ServerSessionBridge { + session_catalog: Arc, + session_runtime: Arc, +} + +impl ServerSessionBridge { + fn session_id(session_id: &str) -> SessionId { + SessionId::from(normalize_external_session_id(session_id)) + } + + async fn replay_history( + &self, + session_id: &SessionId, + last_event_id: Option<&str>, + ) -> astrcode_core::Result> { + let state = self.session_catalog.session_state(session_id).await?; + if let Some(history) = state.recent_records_after(last_event_id)? { + return Ok(history); + } + + let stored = self.session_catalog.stored_events(session_id).await?; + Ok(replay_records(&stored, last_event_id)) + } + + async fn session_phase( + &self, + session_id: &SessionId, + ) -> astrcode_core::Result { + self.session_catalog + .session_state(session_id) + .await? + .current_phase() + } + + async fn session_meta(&self, session_id: &str) -> astrcode_core::Result { + let requested = normalize_external_session_id(session_id); + self.session_catalog + .list_session_metas() + .await? + .into_iter() + .find(|meta| normalize_external_session_id(&meta.session_id) == requested) + .ok_or_else(|| AstrError::SessionNotFound(session_id.to_string())) + } + + async fn durable_subrun_status_summary( + &self, + parent_session_id: &str, + requested_subrun_id: &str, + ) -> astrcode_core::Result> { + let requested_parent_id = normalize_external_session_id(parent_session_id); + for meta in self.session_catalog.list_session_metas().await? { + if meta + .parent_session_id + .as_deref() + .map(normalize_external_session_id) + .as_deref() + != Some(requested_parent_id.as_str()) + { + continue; + } + + let child_session_id = Self::session_id(&meta.session_id); + let stored_events = self + .session_catalog + .stored_events(&child_session_id) + .await?; + if let Some(snapshot) = project_durable_subrun_status_summary( + parent_session_id, + meta.session_id.as_str(), + requested_subrun_id, + &stored_events, + ) { + return Ok(Some(snapshot)); + } + } + + Ok(None) + } +} + +#[async_trait] +impl AppSessionPort for ServerSessionBridge { + fn subscribe_catalog_events( + &self, + ) -> broadcast::Receiver { + self.session_catalog.subscribe_catalog_events() + } + + async fn list_session_metas(&self) -> astrcode_core::Result> { + self.session_catalog.list_session_metas().await + } + + async fn create_session(&self, working_dir: String) -> astrcode_core::Result { + self.session_catalog.create_session(working_dir).await + } + + async fn fork_session( + &self, + session_id: &str, + selector: SessionForkSelector, + ) -> astrcode_core::Result { + let fork_point = match selector { + SessionForkSelector::Latest => ForkPoint::Latest, + SessionForkSelector::TurnEnd { turn_id } => ForkPoint::TurnEnd(turn_id), + SessionForkSelector::StorageSeq { storage_seq } => ForkPoint::StorageSeq(storage_seq), + }; + let result = self + .session_catalog + .fork_session(&Self::session_id(session_id), fork_point) + .await?; + self.session_meta(result.new_session_id.as_str()).await + } + + async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()> { + self.session_catalog + .delete_session(&Self::session_id(session_id)) + .await + } + + async fn delete_project( + &self, + working_dir: &str, + ) -> astrcode_core::Result { + self.session_catalog.delete_project(working_dir).await + } + + async fn get_session_working_dir(&self, session_id: &str) -> astrcode_core::Result { + Ok(self.session_meta(session_id).await?.working_dir) + } + + async fn submit_prompt_for_agent( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + self.session_runtime + .submit_prompt_for_agent(session_id, text, runtime, submission) + .await + } + + async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()> { + self.session_runtime.interrupt_session(session_id).await + } + + async fn compact_session( + &self, + session_id: &str, + runtime: ResolvedRuntimeConfig, + instructions: Option, + ) -> astrcode_core::Result { + self.session_runtime + .compact_session(session_id, runtime, instructions) + .await + } + + async fn session_transcript_snapshot( + &self, + session_id: &str, + ) -> astrcode_core::Result { + let session_id = Self::session_id(session_id); + let records = self.replay_history(&session_id, None).await?; + Ok(SessionTranscriptSnapshot { + cursor: records.last().map(|record| record.event_id.clone()), + phase: self.session_phase(&session_id).await?, + records, + }) + } + + async fn conversation_snapshot( + &self, + session_id: &str, + ) -> astrcode_core::Result { + let transcript = self.session_transcript_snapshot(session_id).await?; + Ok(project_conversation_snapshot( + &transcript.records, + transcript.phase, + )) + } + + async fn session_control_state( + &self, + session_id: &str, + ) -> astrcode_core::Result { + self.session_catalog + .session_control_state(&Self::session_id(session_id)) + .await + } + + async fn active_task_snapshot( + &self, + session_id: &str, + owner: &str, + ) -> astrcode_core::Result> { + self.session_catalog + .active_task_snapshot(&Self::session_id(session_id), owner) + .await + } + + async fn session_mode_state( + &self, + session_id: &str, + ) -> astrcode_core::Result { + self.session_catalog + .session_mode_state(&Self::session_id(session_id)) + .await + } + + async fn switch_mode( + &self, + session_id: &str, + from: astrcode_core::ModeId, + to: astrcode_core::ModeId, + ) -> astrcode_core::Result { + self.session_runtime.switch_mode(session_id, from, to).await + } + + async fn session_child_nodes( + &self, + session_id: &str, + ) -> astrcode_core::Result> { + self.session_catalog + .session_child_nodes(&Self::session_id(session_id)) + .await + } + + async fn session_stored_events( + &self, + session_id: &str, + ) -> astrcode_core::Result> { + self.session_catalog + .stored_events(&Self::session_id(session_id)) + .await + } + + async fn durable_subrun_status_snapshot( + &self, + parent_session_id: &str, + requested_subrun_id: &str, + ) -> astrcode_core::Result> { + self.durable_subrun_status_summary(parent_session_id, requested_subrun_id) + .await + } + + async fn session_replay( + &self, + session_id: &str, + last_event_id: Option<&str>, + ) -> astrcode_core::Result { + let session_id = Self::session_id(session_id); + let state = self.session_catalog.session_state(&session_id).await?; + Ok(SessionReplay { + history: self.replay_history(&session_id, last_event_id).await?, + receiver: state.broadcaster.subscribe(), + live_receiver: state.subscribe_live(), + }) + } + + async fn conversation_stream_replay( + &self, + session_id: &str, + last_event_id: Option<&str>, + ) -> astrcode_core::Result { + let session_id = Self::session_id(session_id); + let replay = self + .session_catalog + .conversation_stream_replay(&session_id, last_event_id) + .await?; + Ok(ConversationStreamReplayFacts { + cursor: replay.cursor, + phase: self.session_phase(&session_id).await?, + replay_frames: build_conversation_replay_frames(&replay.seed_records, &replay.history), + replay_history: replay.history, + seed_records: replay.seed_records, + }) + } +} + +#[async_trait] +impl AgentSessionPort for ServerSessionBridge { + async fn create_child_session( + &self, + working_dir: &str, + parent_session_id: &str, + ) -> astrcode_core::Result { + self.session_catalog + .create_child_session( + working_dir, + normalize_external_session_id(parent_session_id), + None, + ) + .await + } + + async fn submit_prompt_for_agent_with_submission( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + self.session_runtime + .submit_prompt_for_agent_with_submission(session_id, text, runtime, submission) + .await + } + + async fn try_submit_prompt_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + self.session_runtime + .try_submit_prompt_for_agent_with_turn_id( + session_id, turn_id, text, runtime, submission, + ) + .await + } + + async fn submit_queued_inputs_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + queued_inputs: Vec, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + self.session_runtime + .submit_queued_inputs_for_agent_with_turn_id( + session_id, + turn_id, + queued_inputs, + runtime, + submission, + ) + .await + } + + async fn append_agent_input_queued( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputQueuedPayload, + ) -> astrcode_core::Result { + self.session_catalog + .append_agent_input_queued(&Self::session_id(session_id), turn_id, agent, payload) + .await + } + + async fn append_agent_input_discarded( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputDiscardedPayload, + ) -> astrcode_core::Result { + self.session_catalog + .append_agent_input_discarded(&Self::session_id(session_id), turn_id, agent, payload) + .await + } + + async fn append_agent_input_batch_started( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchStartedPayload, + ) -> astrcode_core::Result { + self.session_catalog + .append_agent_input_batch_started( + &Self::session_id(session_id), + turn_id, + agent, + payload, + ) + .await + } + + async fn append_agent_input_batch_acked( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + payload: InputBatchAckedPayload, + ) -> astrcode_core::Result { + self.session_catalog + .append_agent_input_batch_acked(&Self::session_id(session_id), turn_id, agent, payload) + .await + } + + async fn append_child_session_notification( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + notification: astrcode_core::ChildSessionNotification, + ) -> astrcode_core::Result { + self.session_catalog + .append_child_session_notification( + &Self::session_id(session_id), + turn_id, + agent, + notification, + ) + .await + } + + async fn append_agent_collaboration_fact( + &self, + session_id: &str, + turn_id: &str, + agent: AgentEventContext, + fact: AgentCollaborationFact, + ) -> astrcode_core::Result { + self.session_catalog + .append_agent_collaboration_fact(&Self::session_id(session_id), turn_id, agent, fact) + .await + } + + async fn pending_delivery_ids_for_agent( + &self, + session_id: &str, + agent_id: &str, + ) -> astrcode_core::Result> { + self.session_catalog + .pending_delivery_ids_for_agent(&Self::session_id(session_id), agent_id) + .await + } + + async fn recoverable_parent_deliveries( + &self, + parent_session_id: &str, + ) -> astrcode_core::Result> { + let stored_events = self + .session_catalog + .stored_events(&Self::session_id(parent_session_id)) + .await?; + Ok(recoverable_parent_deliveries(&stored_events)) + } + + async fn observe_agent_session( + &self, + open_session_id: &str, + target_agent_id: &str, + lifecycle_status: AgentLifecycleStatus, + ) -> astrcode_core::Result { + self.session_runtime + .observe_agent_session(open_session_id, target_agent_id, lifecycle_status) + .await + } + + async fn project_turn_outcome( + &self, + session_id: &str, + turn_id: &str, + ) -> astrcode_core::Result { + let outcome = self + .session_catalog + .project_turn_outcome(&Self::session_id(session_id), turn_id) + .await?; + Ok(projected_turn_outcome_summary(outcome)) + } + + async fn wait_for_turn_terminal_snapshot( + &self, + session_id: &str, + turn_id: &str, + ) -> astrcode_core::Result { + let snapshot = self + .session_catalog + .wait_for_turn_terminal_snapshot(&Self::session_id(session_id), turn_id) + .await?; + Ok(SessionTurnTerminalState { + phase: snapshot.phase, + projection: snapshot.projection, + events: snapshot.events, + }) + } +} + +fn projected_turn_outcome_summary(value: ProjectedTurnOutcome) -> SessionTurnOutcomeSummary { + match value { + ProjectedTurnOutcome::Completed { summary } => SessionTurnOutcomeSummary { + outcome: astrcode_core::AgentTurnOutcome::Completed, + summary, + technical_message: String::new(), + }, + ProjectedTurnOutcome::Cancelled { summary } => SessionTurnOutcomeSummary { + outcome: astrcode_core::AgentTurnOutcome::Cancelled, + summary, + technical_message: String::new(), + }, + ProjectedTurnOutcome::Failed { + summary, + technical_message, + } => SessionTurnOutcomeSummary { + outcome: astrcode_core::AgentTurnOutcome::Failed, + summary, + technical_message, + }, + } +} + +#[derive(Debug, Clone)] +struct DurableSubRunProjection { + handle: SubRunHandle, + tool_call_id: Option, + result: Option, + step_count: Option, + estimated_tokens: Option, + resolved_overrides: Option, +} + +fn project_durable_subrun_status_summary( + parent_session_id: &str, + child_session_id: &str, + requested_subrun_id: &str, + stored_events: &[StoredEvent], +) -> Option { + let mut projection: Option = None; + + for stored in stored_events { + let agent = &stored.event.agent; + if !matches_requested_subrun(agent, requested_subrun_id) { + continue; + } + + match &stored.event.payload { + StorageEventPayload::SubRunStarted { + tool_call_id, + resolved_overrides, + resolved_limits, + .. + } => { + projection = Some(DurableSubRunProjection { + handle: build_subrun_handle( + parent_session_id, + child_session_id, + requested_subrun_id, + agent, + AgentLifecycleStatus::Running, + None, + resolved_limits.clone(), + ), + tool_call_id: tool_call_id.clone(), + result: None, + step_count: None, + estimated_tokens: None, + resolved_overrides: Some(resolved_overrides.clone()), + }); + }, + StorageEventPayload::SubRunFinished { + tool_call_id, + result, + step_count, + estimated_tokens, + .. + } => { + let entry = projection.get_or_insert_with(|| DurableSubRunProjection { + handle: build_subrun_handle( + parent_session_id, + child_session_id, + requested_subrun_id, + agent, + result.status().lifecycle(), + result.status().last_turn_outcome(), + ResolvedExecutionLimitsSnapshot, + ), + tool_call_id: None, + result: None, + step_count: None, + estimated_tokens: None, + resolved_overrides: None, + }); + entry.tool_call_id = tool_call_id.clone().or_else(|| entry.tool_call_id.clone()); + entry.handle.lifecycle = result.status().lifecycle(); + entry.handle.last_turn_outcome = result.status().last_turn_outcome(); + entry.result = Some(result.clone()); + entry.step_count = Some(*step_count); + entry.estimated_tokens = Some(*estimated_tokens); + }, + _ => {}, + } + } + + projection.map(|projection| DurableSubRunStatusSummary { + sub_run_id: projection.handle.sub_run_id.to_string(), + tool_call_id: projection.tool_call_id, + agent_id: projection.handle.agent_id.to_string(), + agent_profile: projection.handle.agent_profile, + session_id: projection.handle.session_id.to_string(), + child_session_id: projection.handle.child_session_id.map(|id| id.to_string()), + depth: projection.handle.depth, + parent_agent_id: projection.handle.parent_agent_id.map(|id| id.to_string()), + parent_sub_run_id: projection.handle.parent_sub_run_id.map(|id| id.to_string()), + storage_mode: projection.handle.storage_mode, + lifecycle: projection.handle.lifecycle, + last_turn_outcome: projection.handle.last_turn_outcome, + result: projection.result, + step_count: projection.step_count, + estimated_tokens: projection.estimated_tokens, + resolved_overrides: projection.resolved_overrides, + resolved_limits: projection.handle.resolved_limits, + }) +} + +fn build_subrun_handle( + parent_session_id: &str, + child_session_id: &str, + requested_subrun_id: &str, + agent: &AgentEventContext, + lifecycle: AgentLifecycleStatus, + last_turn_outcome: Option, + resolved_limits: ResolvedExecutionLimitsSnapshot, +) -> SubRunHandle { + SubRunHandle { + sub_run_id: agent + .sub_run_id + .clone() + .unwrap_or_else(|| requested_subrun_id.to_string().into()), + agent_id: agent + .agent_id + .clone() + .unwrap_or_else(|| requested_subrun_id.to_string().into()), + session_id: parent_session_id.to_string().into(), + child_session_id: Some( + agent + .child_session_id + .clone() + .unwrap_or_else(|| child_session_id.to_string().into()), + ), + depth: 1, + parent_turn_id: agent.parent_turn_id.clone().unwrap_or_default(), + parent_agent_id: None, + parent_sub_run_id: agent.parent_sub_run_id.clone(), + lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, + agent_profile: agent + .agent_profile + .clone() + .unwrap_or_else(|| "unknown".to_string()), + storage_mode: agent + .storage_mode + .unwrap_or(SubRunStorageMode::IndependentSession), + lifecycle, + last_turn_outcome, + resolved_limits, + delegation: None, + } +} + +fn matches_requested_subrun(agent: &AgentEventContext, requested_subrun_id: &str) -> bool { + if agent.invocation_kind != Some(InvocationKind::SubRun) { + return false; + } + + agent.sub_run_id.as_deref() == Some(requested_subrun_id) + || agent.agent_id.as_deref() == Some(requested_subrun_id) +} + +pub(crate) fn recoverable_parent_deliveries( + events: &[StoredEvent], +) -> Vec { + let projection_index = replay_input_queue_projection_index(events); + let mut recoverable_by_agent = HashMap::>::new(); + for (agent_id, projection) in projection_index { + let active_ids = projection + .active_delivery_ids + .into_iter() + .collect::>(); + let recoverable = projection + .pending_delivery_ids + .into_iter() + .filter(|delivery_id| !active_ids.contains(delivery_id)) + .map(|delivery_id| delivery_id.to_string()) + .collect::>(); + if !recoverable.is_empty() { + recoverable_by_agent.insert(agent_id, recoverable); + } + } + + let queued_at_by_delivery = events + .iter() + .filter_map(|stored| match &stored.event.payload { + StorageEventPayload::AgentInputQueued { payload } => Some(( + payload.envelope.delivery_id.clone(), + payload.envelope.queued_at, + )), + _ => None, + }) + .collect::>(); + + let mut recovered = Vec::new(); + let mut seen = HashSet::new(); + for stored in events { + let StorageEventPayload::ChildSessionNotification { notification, .. } = + &stored.event.payload + else { + continue; + }; + let Some(parent_agent_id) = notification.child_ref.parent_agent_id() else { + continue; + }; + let Some(recoverable_ids) = recoverable_by_agent.get(parent_agent_id.as_str()) else { + continue; + }; + if !recoverable_ids.contains(notification.notification_id.as_str()) { + continue; + } + if !seen.insert(notification.notification_id.clone()) { + continue; + } + let Some(parent_turn_id) = stored.event.turn_id().map(ToString::to_string) else { + continue; + }; + recovered.push(RecoverableParentDelivery { + delivery_id: notification.notification_id.to_string(), + parent_session_id: notification.child_ref.session_id().to_string(), + parent_turn_id, + queued_at_ms: queued_at_by_delivery + .get(¬ification.notification_id) + .map(|queued_at| queued_at.timestamp_millis()) + .unwrap_or_default(), + notification: notification.clone(), + }); + } + + recovered +} + +fn replay_input_queue_projection_index( + events: &[StoredEvent], +) -> HashMap { + let mut index = HashMap::new(); + for stored in events { + apply_input_queue_event_to_index(&mut index, stored); + } + index +} + +fn apply_input_queue_event_to_index( + index: &mut HashMap, + stored: &StoredEvent, +) { + let Some(target_agent_id) = input_queue_projection_target_agent_id(&stored.event.payload) + else { + return; + }; + let projection = index.entry(target_agent_id.to_string()).or_default(); + apply_input_queue_event_for_agent(projection, stored, target_agent_id); +} + +fn input_queue_projection_target_agent_id(payload: &StorageEventPayload) -> Option<&str> { + match payload { + StorageEventPayload::AgentInputQueued { payload } => Some(&payload.envelope.to_agent_id), + StorageEventPayload::AgentInputBatchStarted { payload } => Some(&payload.target_agent_id), + StorageEventPayload::AgentInputBatchAcked { payload } => Some(&payload.target_agent_id), + StorageEventPayload::AgentInputDiscarded { payload } => Some(&payload.target_agent_id), + _ => None, + } +} + +fn apply_input_queue_event_for_agent( + projection: &mut InputQueueProjection, + stored: &StoredEvent, + target_agent_id: &str, +) { + match &stored.event.payload { + StorageEventPayload::AgentInputQueued { payload } => { + if payload.envelope.to_agent_id != target_agent_id { + return; + } + let delivery_id = &payload.envelope.delivery_id; + if !projection.discarded_delivery_ids.contains(delivery_id) + && !projection.pending_delivery_ids.contains(delivery_id) + { + projection.pending_delivery_ids.push(delivery_id.clone()); + } + }, + StorageEventPayload::AgentInputBatchStarted { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + projection.active_batch_id = Some(payload.batch_id.clone()); + projection.active_delivery_ids = payload.delivery_ids.clone(); + }, + StorageEventPayload::AgentInputBatchAcked { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + let acked_set = payload.delivery_ids.iter().collect::>(); + projection.pending_delivery_ids.retain(|delivery_id| { + !acked_set.contains(delivery_id) + && !projection.discarded_delivery_ids.contains(delivery_id) + }); + if projection.active_batch_id.as_deref() == Some(payload.batch_id.as_str()) { + projection.active_batch_id = None; + projection.active_delivery_ids.clear(); + } + }, + StorageEventPayload::AgentInputDiscarded { payload } => { + if payload.target_agent_id != target_agent_id { + return; + } + for delivery_id in &payload.delivery_ids { + if !projection.discarded_delivery_ids.contains(delivery_id) { + projection.discarded_delivery_ids.push(delivery_id.clone()); + } + } + projection + .pending_delivery_ids + .retain(|delivery_id| !projection.discarded_delivery_ids.contains(delivery_id)); + let discarded_set = projection + .discarded_delivery_ids + .iter() + .collect::>(); + if projection + .active_delivery_ids + .iter() + .any(|delivery_id| discarded_set.contains(delivery_id)) + { + projection.active_batch_id = None; + projection.active_delivery_ids.clear(); + } + }, + _ => {}, + } +} diff --git a/crates/server/src/ports/session_contracts.rs b/crates/server/src/ports/session_contracts.rs new file mode 100644 index 00000000..7f187de8 --- /dev/null +++ b/crates/server/src/ports/session_contracts.rs @@ -0,0 +1,89 @@ +//! server 自有的 session 编排合同。 +//! +//! Why: server/application 只应该消费纯数据的编排摘要， +//! 不应继续把 `session-runtime` / `kernel` 的内部快照类型透传给上层。 + +use astrcode_core::{ + AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, Phase, + ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, StoredEvent, SubRunResult, + SubRunStorageMode, +}; +use astrcode_host_session::TurnProjectionSnapshot; +use serde::{Deserialize, Serialize}; + +/// 应用层使用的 turn outcome 摘要。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SessionTurnOutcomeSummary { + pub outcome: AgentTurnOutcome, + pub summary: String, + pub technical_message: String, +} + +/// 应用层使用的 turn 终态快照。 +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SessionTurnTerminalState { + pub phase: Phase, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub projection: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub events: Vec, +} + +/// 应用层使用的 observe 快照。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SessionObserveSnapshot { + pub phase: Phase, + pub turn_count: u32, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub active_task: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub last_output_tail: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub last_turn_tail: Vec, +} + +/// 应用层使用的可恢复父级投递摘要。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct RecoverableParentDelivery { + pub delivery_id: String, + pub parent_session_id: String, + pub parent_turn_id: String, + pub queued_at_ms: i64, + pub notification: ChildSessionNotification, +} + +/// server/application 使用的 durable sub-run 状态摘要。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct DurableSubRunStatusSummary { + pub sub_run_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub tool_call_id: Option, + pub agent_id: String, + pub agent_profile: String, + pub session_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub child_session_id: Option, + pub depth: usize, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub parent_agent_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub parent_sub_run_id: Option, + pub storage_mode: SubRunStorageMode, + pub lifecycle: AgentLifecycleStatus, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub last_turn_outcome: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub result: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub step_count: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub estimated_tokens: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub resolved_overrides: Option, + pub resolved_limits: ResolvedExecutionLimitsSnapshot, +} diff --git a/crates/application/src/ports/session_submission.rs b/crates/server/src/ports/session_submission.rs similarity index 50% rename from crates/application/src/ports/session_submission.rs rename to crates/server/src/ports/session_submission.rs index 3cc727f3..135e9153 100644 --- a/crates/application/src/ports/session_submission.rs +++ b/crates/server/src/ports/session_submission.rs @@ -5,16 +5,16 @@ use astrcode_core::{ AgentEventContext, BoundModeToolContractSnapshot, CapabilityCall, LlmMessage, ModeId, - PolicyContext, PromptDeclaration, PromptGovernanceContext, ResolvedExecutionLimitsSnapshot, + PolicyContext, PromptDeclaration, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, }; -use astrcode_kernel::CapabilityRouter; +use astrcode_host_session::PromptGovernanceContext; /// 应用层提交给 session 端口的稳定载荷。 +#[allow(dead_code)] #[derive(Clone, Default)] pub struct AppAgentPromptSubmission { pub agent: AgentEventContext, - pub capability_router: Option, pub current_mode_id: ModeId, pub prompt_declarations: Vec, pub bound_mode_tool_contract: Option, @@ -27,23 +27,3 @@ pub struct AppAgentPromptSubmission { pub approval: Option>, pub prompt_governance: Option, } - -impl From for astrcode_session_runtime::AgentPromptSubmission { - fn from(value: AppAgentPromptSubmission) -> Self { - Self { - agent: value.agent, - capability_router: value.capability_router, - current_mode_id: value.current_mode_id, - prompt_declarations: value.prompt_declarations, - bound_mode_tool_contract: value.bound_mode_tool_contract, - resolved_limits: value.resolved_limits, - resolved_overrides: value.resolved_overrides, - injected_messages: value.injected_messages, - source_tool_call_id: value.source_tool_call_id, - policy_context: value.policy_context, - governance_revision: value.governance_revision, - approval: value.approval.map(Box::new), - prompt_governance: value.prompt_governance, - } - } -} diff --git a/crates/server/src/profile_service.rs b/crates/server/src/profile_service.rs new file mode 100644 index 00000000..bdf99367 --- /dev/null +++ b/crates/server/src/profile_service.rs @@ -0,0 +1,64 @@ +//! server-owned profile resolver bridge。 +//! +//! server runtime / state / tests 只依赖这里定义的 resolver contract。 + +use std::{path::Path, sync::Arc}; + +use astrcode_core::AgentProfile; + +use crate::application_error_bridge::ServerRouteError; + +pub(crate) trait ServerProfilePort: Send + Sync { + fn resolve(&self, working_dir: &Path) -> Result>, ServerRouteError>; + fn find_profile( + &self, + working_dir: &Path, + profile_id: &str, + ) -> Result; + fn resolve_global(&self) -> Result>, ServerRouteError>; + fn invalidate(&self, working_dir: &Path); + fn invalidate_global(&self); + fn invalidate_all(&self); +} + +#[derive(Clone)] +pub(crate) struct ServerProfileService { + port: Arc, +} + +impl ServerProfileService { + pub(crate) fn new(port: Arc) -> Self { + Self { port } + } + + pub(crate) fn resolve( + &self, + working_dir: &Path, + ) -> Result>, ServerRouteError> { + self.port.resolve(working_dir) + } + + pub(crate) fn find_profile( + &self, + working_dir: &Path, + profile_id: &str, + ) -> Result { + self.port.find_profile(working_dir, profile_id) + } + + pub(crate) fn resolve_global(&self) -> Result>, ServerRouteError> { + self.port.resolve_global() + } + + pub(crate) fn invalidate(&self, working_dir: &Path) { + self.port.invalidate(working_dir); + } + + pub(crate) fn invalidate_global(&self) { + self.port.invalidate_global(); + } + + pub(crate) fn invalidate_all(&self) { + self.port.invalidate_all(); + } +} diff --git a/crates/server/src/root_execute_service.rs b/crates/server/src/root_execute_service.rs new file mode 100644 index 00000000..20994a1a --- /dev/null +++ b/crates/server/src/root_execute_service.rs @@ -0,0 +1,407 @@ +//! server-owned root execute bridge。 +//! +//! agent route / runtime state 只暴露 server-owned 根执行入口和治理装配类型。 + +use std::{path::Path, sync::Arc}; + +use astrcode_core::{ + AgentMode, AgentProfile, ExecutionControl, ResolvedExecutionLimitsSnapshot, + ResolvedRuntimeConfig, SubagentContextOverrides, generate_turn_id, +}; + +use crate::{ + agent::implicit_session_root_agent_id, + agent_control_bridge::ServerAgentControlPort, + application_error_bridge::ServerRouteError, + config_service_bridge::ServerConfigService, + ports::{AppAgentPromptSubmission, AppSessionPort}, + profile_service::ServerProfileService, +}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerRootExecutionRequest { + pub agent_id: String, + pub working_dir: String, + pub task: String, + pub context: Option, + pub control: Option, + pub context_overrides: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerSessionPromptRequest { + pub session_id: String, + pub working_dir: String, + pub text: String, + pub control: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerAgentExecuteSummary { + pub accepted: bool, + pub message: String, + pub session_id: Option, + pub turn_id: Option, + pub agent_id: Option, + pub branched_from_session_id: Option, +} + +#[derive(Debug, Clone)] +pub(crate) struct ServerRootGovernanceInput { + pub agent_id: String, + pub session_id: String, + pub turn_id: String, + pub working_dir: String, + pub profile_id: String, + pub runtime: ResolvedRuntimeConfig, + pub control: Option, +} + +#[derive(Clone)] +pub(crate) struct ServerPreparedRootExecution { + pub runtime: ResolvedRuntimeConfig, + pub resolved_limits: ResolvedExecutionLimitsSnapshot, + pub submission: AppAgentPromptSubmission, +} + +pub(crate) trait ServerRootGovernancePort: Send + Sync { + fn prepare_root_submission( + &self, + input: ServerRootGovernanceInput, + ) -> Result; +} + +#[derive(Clone)] +pub(crate) struct ServerRootExecuteService { + agent_control: Arc, + sessions: Arc, + profiles: Arc, + config_service: Arc, + governance: Arc, +} + +impl ServerRootExecuteService { + pub(crate) fn new( + agent_control: Arc, + sessions: Arc, + profiles: Arc, + config_service: Arc, + governance: Arc, + ) -> Self { + Self { + agent_control, + sessions, + profiles, + config_service, + governance, + } + } + + pub(crate) async fn execute_summary( + &self, + request: ServerRootExecutionRequest, + ) -> Result { + validate_root_request(&request)?; + validate_root_context_overrides_supported(request.context_overrides.as_ref())?; + + let runtime = self + .config_service + .load_resolved_runtime_config(Some(Path::new(&request.working_dir)))?; + let profile = self + .profiles + .find_profile(Path::new(&request.working_dir), &request.agent_id)?; + ensure_root_profile_mode(&profile)?; + let profile_id = profile.id.clone(); + + let session = self + .sessions + .create_session(request.working_dir.clone()) + .await + .map_err(ServerRouteError::from)?; + let turn_id = generate_turn_id(); + let handle = self + .agent_control + .register_root_agent( + request.agent_id.clone(), + session.session_id.clone(), + profile_id.clone(), + ) + .await?; + let prepared = self + .governance + .prepare_root_submission(ServerRootGovernanceInput { + agent_id: request.agent_id.clone(), + session_id: session.session_id.clone(), + turn_id: turn_id.clone(), + working_dir: request.working_dir.clone(), + profile_id: profile_id.clone(), + runtime, + control: request.control.clone(), + })?; + let resolved_limits = prepared.resolved_limits.clone(); + if !self + .agent_control + .set_resolved_limits(&handle.agent_id, resolved_limits) + .await + { + return Err(ServerRouteError::internal(format!( + "failed to persist resolved limits for root agent '{}' because the control handle \ + disappeared before the limits snapshot was recorded", + handle.agent_id + ))); + } + + let accepted = self + .sessions + .submit_prompt_for_agent( + &session.session_id, + merge_task_with_context(&request.task, request.context.as_deref()), + prepared.runtime, + prepared.submission, + ) + .await + .map_err(ServerRouteError::from)?; + let session_id = accepted.session_id.to_string(); + let agent_id = request.agent_id.clone(); + + Ok(ServerAgentExecuteSummary { + accepted: true, + message: format!( + "agent '{}' execution accepted; subscribe to \ + /api/v1/conversation/sessions/{}/stream for progress", + agent_id, session_id + ), + session_id: Some(session_id), + turn_id: Some(accepted.turn_id.to_string()), + agent_id: Some(agent_id), + branched_from_session_id: accepted.branched_from_session_id, + }) + } + + pub(crate) async fn submit_existing_session_prompt( + &self, + request: ServerSessionPromptRequest, + ) -> Result { + validate_session_prompt_request(&request)?; + + let runtime = self + .config_service + .load_resolved_runtime_config(Some(Path::new(&request.working_dir)))?; + let root_status = self + .agent_control + .query_root_status(&request.session_id) + .await; + let (agent_id, profile_id) = root_status + .as_ref() + .map(|status| (status.agent_id.clone(), status.agent_profile.clone())) + .unwrap_or_else(|| { + ( + implicit_session_root_agent_id(&request.session_id), + crate::agent::IMPLICIT_ROOT_PROFILE_ID.to_string(), + ) + }); + let prepared = self + .governance + .prepare_root_submission(ServerRootGovernanceInput { + agent_id: agent_id.clone(), + session_id: request.session_id.clone(), + turn_id: generate_turn_id(), + working_dir: request.working_dir.clone(), + profile_id: profile_id.clone(), + runtime, + control: request.control.clone(), + })?; + let resolved_limits = prepared.resolved_limits.clone(); + if root_status.is_none() { + self.agent_control + .register_root_agent( + agent_id.clone(), + request.session_id.clone(), + profile_id.clone(), + ) + .await?; + } + if !self + .agent_control + .set_resolved_limits(&agent_id, resolved_limits) + .await + { + return Err(ServerRouteError::internal(format!( + "failed to persist resolved limits for root agent '{}' because the control handle \ + disappeared before the limits snapshot was recorded", + agent_id + ))); + } + + let accepted = self + .sessions + .submit_prompt_for_agent( + &request.session_id, + request.text, + prepared.runtime, + prepared.submission, + ) + .await + .map_err(ServerRouteError::from)?; + + Ok(ServerAgentExecuteSummary { + accepted: true, + message: format!( + "session '{}' prompt accepted; subscribe to \ + /api/v1/conversation/sessions/{}/stream for progress", + request.session_id, accepted.session_id + ), + session_id: Some(accepted.session_id.to_string()), + turn_id: Some(accepted.turn_id.to_string()), + agent_id: Some(agent_id), + branched_from_session_id: accepted.branched_from_session_id, + }) + } +} + +fn validate_root_request(request: &ServerRootExecutionRequest) -> Result<(), ServerRouteError> { + if request.agent_id.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'agentId' must not be empty", + )); + } + if request.working_dir.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'workingDir' must not be empty", + )); + } + if request.task.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'task' must not be empty", + )); + } + if let Some(control) = &request.control { + control.validate().map_err(ServerRouteError::from)?; + if control.manual_compact.is_some() { + return Err(ServerRouteError::invalid_argument( + "manualCompact is not valid for root execution", + )); + } + } + Ok(()) +} + +fn validate_session_prompt_request( + request: &ServerSessionPromptRequest, +) -> Result<(), ServerRouteError> { + if request.session_id.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'sessionId' must not be empty", + )); + } + if request.working_dir.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'workingDir' must not be empty", + )); + } + if request.text.trim().is_empty() { + return Err(ServerRouteError::invalid_argument( + "field 'text' must not be empty", + )); + } + if let Some(control) = &request.control { + control.validate().map_err(ServerRouteError::from)?; + if control.manual_compact.is_some() { + return Err(ServerRouteError::invalid_argument( + "manualCompact is not valid for prompt submission", + )); + } + } + Ok(()) +} + +fn validate_root_context_overrides_supported( + overrides: Option<&SubagentContextOverrides>, +) -> Result<(), ServerRouteError> { + let Some(overrides) = overrides else { + return Ok(()); + }; + if overrides != &SubagentContextOverrides::default() { + return Err(ServerRouteError::invalid_argument( + "contextOverrides is not supported yet for root execution", + )); + } + Ok(()) +} + +fn ensure_root_profile_mode(profile: &AgentProfile) -> Result<(), ServerRouteError> { + if matches!(profile.mode, AgentMode::Primary | AgentMode::All) { + return Ok(()); + } + + Err(ServerRouteError::invalid_argument(format!( + "agent profile '{}' cannot be used for root execution", + profile.id + ))) +} + +fn merge_task_with_context(task: &str, context: Option<&str>) -> String { + match context { + Some(context) if !context.trim().is_empty() => { + format!("{}\n\n{}", context.trim(), task) + }, + _ => task.to_string(), + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::SubagentContextOverrides; + + use super::{ + ServerRootExecutionRequest, merge_task_with_context, + validate_root_context_overrides_supported, validate_root_request, + }; + + fn valid_request() -> ServerRootExecutionRequest { + ServerRootExecutionRequest { + agent_id: "root-agent".to_string(), + working_dir: "/tmp/project".to_string(), + task: "do something".to_string(), + context: None, + control: None, + context_overrides: None, + } + } + + #[test] + fn validate_accepts_valid_request() { + assert!(validate_root_request(&valid_request()).is_ok()); + } + + #[test] + fn validate_rejects_manual_compact_control() { + let mut request = valid_request(); + request.control = Some(astrcode_core::ExecutionControl { + manual_compact: Some(true), + }); + + let error = validate_root_request(&request).expect_err("manual compact should fail"); + + assert!(error.to_string().contains("manualCompact")); + } + + #[test] + fn validate_root_context_overrides_rejects_non_empty_override() { + let error = validate_root_context_overrides_supported(Some(&SubagentContextOverrides { + include_compact_summary: Some(true), + ..SubagentContextOverrides::default() + })) + .expect_err("non-empty overrides should fail"); + + assert!(error.to_string().contains("contextOverrides")); + } + + #[test] + fn merge_context_and_task() { + assert_eq!( + merge_task_with_context("main task", Some("background info")), + "background info\n\nmain task" + ); + } +} diff --git a/crates/server/src/runtime_owner_bridge.rs b/crates/server/src/runtime_owner_bridge.rs new file mode 100644 index 00000000..ab94d5c5 --- /dev/null +++ b/crates/server/src/runtime_owner_bridge.rs @@ -0,0 +1,158 @@ +//! server-owned runtime bootstrap bridge。 +//! +//! 把 builtin mode seed、任务注册表、可观测性采集器收敛到 server 本地模块， +//! 避免组合根直接依赖 application runtime 类型。 + +use std::sync::Arc; + +use astrcode_core::{ + AgentCollaborationFact, AgentTurnOutcome, GovernanceModeSpec, Result, RuntimeMetricsRecorder, + RuntimeObservabilitySnapshot, SubRunStorageMode, +}; + +use crate::{ + ObservabilitySnapshotProvider, RuntimeObservabilityCollector, TaskRegistry, + builtin_mode_catalog, +}; + +#[derive(Debug, Clone)] +pub(crate) struct ServerTaskRegistry { + inner: Arc, +} + +impl ServerTaskRegistry { + pub(crate) fn new() -> Arc { + Arc::new(Self { + inner: Arc::new(TaskRegistry::new()), + }) + } + + pub(crate) fn inner(&self) -> Arc { + Arc::clone(&self.inner) + } +} + +#[derive(Clone, Default)] +pub(crate) struct ServerRuntimeObservability { + inner: Arc, +} + +impl ServerRuntimeObservability { + pub(crate) fn new() -> Arc { + Arc::new(Self { + inner: Arc::new(RuntimeObservabilityCollector::new()), + }) + } + + pub(crate) fn snapshot(&self) -> RuntimeObservabilitySnapshot { + self.inner.snapshot() + } +} + +impl RuntimeMetricsRecorder for ServerRuntimeObservability { + fn record_session_rehydrate(&self, duration_ms: u64, success: bool) { + self.inner.record_session_rehydrate(duration_ms, success); + } + + fn record_sse_catch_up( + &self, + duration_ms: u64, + success: bool, + used_disk_fallback: bool, + recovered_events: u64, + ) { + self.inner + .record_sse_catch_up(duration_ms, success, used_disk_fallback, recovered_events); + } + + fn record_turn_execution(&self, duration_ms: u64, success: bool) { + self.inner.record_turn_execution(duration_ms, success); + } + + fn record_subrun_execution( + &self, + duration_ms: u64, + outcome: AgentTurnOutcome, + step_count: Option, + estimated_tokens: Option, + storage_mode: Option, + ) { + self.inner.record_subrun_execution( + duration_ms, + outcome, + step_count, + estimated_tokens, + storage_mode, + ); + } + + fn record_child_spawned(&self) { + self.inner.record_child_spawned(); + } + + fn record_parent_reactivation_requested(&self) { + self.inner.record_parent_reactivation_requested(); + } + + fn record_parent_reactivation_succeeded(&self) { + self.inner.record_parent_reactivation_succeeded(); + } + + fn record_parent_reactivation_failed(&self) { + self.inner.record_parent_reactivation_failed(); + } + + fn record_delivery_buffer_queued(&self) { + self.inner.record_delivery_buffer_queued(); + } + + fn record_delivery_buffer_dequeued(&self) { + self.inner.record_delivery_buffer_dequeued(); + } + + fn record_delivery_buffer_wake_requested(&self) { + self.inner.record_delivery_buffer_wake_requested(); + } + + fn record_delivery_buffer_wake_succeeded(&self) { + self.inner.record_delivery_buffer_wake_succeeded(); + } + + fn record_delivery_buffer_wake_failed(&self) { + self.inner.record_delivery_buffer_wake_failed(); + } + + fn record_cache_reuse_hit(&self) { + self.inner.record_cache_reuse_hit(); + } + + fn record_cache_reuse_miss(&self) { + self.inner.record_cache_reuse_miss(); + } + + fn record_agent_collaboration_fact(&self, fact: &AgentCollaborationFact) { + self.inner.record_agent_collaboration_fact(fact); + } +} + +impl ObservabilitySnapshotProvider for ServerRuntimeObservability { + fn snapshot(&self) -> RuntimeObservabilitySnapshot { + self.snapshot() + } +} + +impl std::fmt::Debug for ServerRuntimeObservability { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("ServerRuntimeObservability") + .finish_non_exhaustive() + } +} + +pub(crate) fn builtin_server_mode_specs() -> Result> { + Ok(builtin_mode_catalog()? + .snapshot() + .entries + .values() + .map(|entry| entry.spec.clone()) + .collect()) +} diff --git a/crates/server/src/session_identity.rs b/crates/server/src/session_identity.rs new file mode 100644 index 00000000..a2ec3b86 --- /dev/null +++ b/crates/server/src/session_identity.rs @@ -0,0 +1,13 @@ +//! server-owned session 输入整形辅助。 +//! +//! Why: `session-runtime` 的 session key 规范化规则非常窄，继续为了这一个 +//! helper 保留正式依赖只会放大迁移尾巴；这里直接下沉同等规则，避免业务代码各自复制。 + +/// 规范化外部传入的 session 标识。 +pub(crate) fn normalize_external_session_id(session_id: &str) -> String { + let trimmed = session_id.trim(); + trimmed + .strip_prefix("session-") + .unwrap_or(trimmed) + .to_string() +} diff --git a/crates/server/src/session_runtime_owner_bridge.rs b/crates/server/src/session_runtime_owner_bridge.rs new file mode 100644 index 00000000..19b75460 --- /dev/null +++ b/crates/server/src/session_runtime_owner_bridge.rs @@ -0,0 +1,154 @@ +use std::{ + any::Any, + collections::HashMap, + sync::{Arc, Mutex}, +}; + +use astrcode_agent_runtime::LlmProvider; +#[cfg(test)] +use astrcode_core::{AgentLifecycleStatus, AgentProfile}; +use astrcode_core::{CapabilityInvoker, Result}; +use astrcode_host_session::SessionCatalog; +#[cfg(test)] +use astrcode_host_session::SubRunHandle; + +#[cfg(test)] +use crate::agent_control_bridge::ServerLiveSubRunStatus; +#[cfg(test)] +use crate::ports::ServerKernelControlError; +use crate::{ + SessionInfoProvider, + agent_control_bridge::ServerAgentControlPort, + ports::{AgentKernelPort, AgentSessionPort, AppSessionPort}, +}; + +#[path = "session_runtime_owner_bridge_impl.rs"] +mod implementation; + +pub(crate) use implementation::bootstrap_session_runtime; + +#[derive(Default)] +pub(crate) struct ActiveSessionRegistry { + counts: Mutex>, +} + +impl ActiveSessionRegistry { + pub(crate) fn new() -> Self { + Self::default() + } + + pub(crate) fn mark_running(&self, session_id: &str) { + let mut counts = self + .counts + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()); + *counts.entry(session_id.to_string()).or_default() += 1; + } + + pub(crate) fn mark_idle(&self, session_id: &str) { + let mut counts = self + .counts + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()); + let Some(count) = counts.get_mut(session_id) else { + return; + }; + if *count <= 1 { + counts.remove(session_id); + } else { + *count -= 1; + } + } + + pub(crate) fn running_session_ids(&self) -> Vec { + let mut session_ids = self + .counts + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .keys() + .cloned() + .collect::>(); + session_ids.sort(); + session_ids + } +} + +pub(crate) trait ServerCapabilitySurfacePort: Send + Sync { + fn replace_capability_invokers(&self, invokers: Vec>) -> Result<()>; +} + +#[cfg(test)] +#[async_trait::async_trait] +pub(crate) trait ServerRuntimeTestSupport: Send + Sync { + fn list_running_session_ids(&self) -> Vec; + + async fn append_event( + &self, + session_id: &str, + event: astrcode_core::StorageEvent, + ) -> Result<()>; + + async fn prepare_test_turn_runtime(&self, session_id: &str, turn_id: &str) -> Result; + + async fn complete_test_turn_runtime(&self, session_id: &str, generation: u64) -> Result<()>; + + async fn replay_stored_events( + &self, + session_id: &str, + ) -> Result>; + + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> std::result::Result; + + async fn spawn_independent_child( + &self, + profile: &AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> std::result::Result; + + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()>; + + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize; + + async fn query_root_status(&self, session_id: &str) -> Option; +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerAgentControlLimits { + pub max_depth: usize, + pub max_concurrent: usize, + pub finalized_retain_limit: usize, + pub inbox_capacity: usize, + pub parent_delivery_capacity: usize, +} + +pub(crate) struct ServerSessionRuntimeBootstrapInput { + pub capability_invokers: Vec>, + pub llm_provider: Arc, + pub session_catalog: Arc, + pub mode_catalog: Arc, + pub agent_limits: ServerAgentControlLimits, +} + +pub(crate) struct ServerBootstrappedSessionRuntime { + pub app_sessions: Arc, + pub agent_sessions: Arc, + pub agent_kernel: Arc, + pub agent_control: Arc, + pub capability_surface: Arc, + pub sessions: Arc, + pub keepalive: Arc, + #[cfg(test)] + pub test_support: Arc, +} diff --git a/crates/server/src/session_runtime_owner_bridge_impl.rs b/crates/server/src/session_runtime_owner_bridge_impl.rs new file mode 100644 index 00000000..70b43d57 --- /dev/null +++ b/crates/server/src/session_runtime_owner_bridge_impl.rs @@ -0,0 +1,254 @@ +use std::sync::Arc; +#[cfg(test)] +use std::sync::atomic::{AtomicU64, Ordering}; + +#[cfg(test)] +use astrcode_core::{ + AgentLifecycleStatus, AgentProfile, EventTranslator, SessionId, SessionTurnAcquireResult, + SessionTurnLease, StorageEvent, StoredEvent, +}; +use astrcode_core::{CapabilityInvoker, Result}; +use astrcode_host_session::SessionCatalog; + +#[cfg(test)] +use crate::session_runtime_owner_bridge::ServerRuntimeTestSupport; +use crate::{ + SessionInfoProvider, + agent_control_bridge::ServerAgentControlPort, + agent_control_registry::{AgentControlLimits, AgentControlRegistry}, + capability_router::CapabilityRouter, + ports::{ + AgentKernelPort, AgentSessionPort, AppSessionPort, + kernel_bridge::build_server_kernel_bridge, session_bridge::build_server_session_bridge, + }, + session_runtime_owner_bridge::{ + ActiveSessionRegistry, ServerBootstrappedSessionRuntime, ServerCapabilitySurfacePort, + ServerSessionRuntimeBootstrapInput, + }, + session_runtime_port::adapter::build_session_runtime_port, +}; +#[cfg(test)] +use crate::{ + agent_control_bridge::ServerLiveSubRunStatus, ports::ServerKernelControlError, + session_runtime_port::SessionRuntimePort, +}; + +pub(crate) fn bootstrap_session_runtime( + input: ServerSessionRuntimeBootstrapInput, +) -> Result { + let capability_router = CapabilityRouter::builder() + .build() + .expect("empty capability router should build"); + capability_router.replace_invokers(input.capability_invokers)?; + let agent_control_registry = Arc::new(AgentControlRegistry::from_limits(AgentControlLimits { + max_depth: input.agent_limits.max_depth, + max_concurrent: input.agent_limits.max_concurrent, + finalized_retain_limit: input.agent_limits.finalized_retain_limit, + inbox_capacity: input.agent_limits.inbox_capacity, + parent_delivery_capacity: input.agent_limits.parent_delivery_capacity, + })); + let active_sessions = Arc::new(ActiveSessionRegistry::new()); + let session_runtime = build_session_runtime_port( + Arc::clone(&input.session_catalog), + Arc::clone(&input.mode_catalog), + Arc::clone(&agent_control_registry), + capability_router.clone(), + Arc::clone(&input.llm_provider), + Arc::clone(&active_sessions), + ); + let session_bridge = + build_server_session_bridge(Arc::clone(&input.session_catalog), session_runtime.clone()); + let kernel_bridge = build_server_kernel_bridge(session_runtime.clone()); + let app_sessions: Arc = session_bridge.clone(); + let agent_sessions: Arc = session_bridge; + let agent_kernel: Arc = kernel_bridge.clone(); + let agent_control: Arc = kernel_bridge; + let capability_surface: Arc = + Arc::new(CapabilitySurfaceBridge { + capability_router: capability_router.clone(), + }); + + Ok(ServerBootstrappedSessionRuntime { + app_sessions, + agent_sessions, + agent_kernel, + agent_control, + capability_surface, + sessions: Arc::new(SessionRuntimeInfoBridge { + session_catalog: Arc::clone(&input.session_catalog), + active_sessions: Arc::clone(&active_sessions), + }), + keepalive: Arc::new(SessionRuntimeCompatKeepalive { + _agent_control: agent_control_registry, + }), + #[cfg(test)] + test_support: Arc::new(SessionRuntimeTestSupportBridge { + session_catalog: input.session_catalog, + active_sessions, + session_runtime: session_runtime.clone(), + next_generation: AtomicU64::new(1), + prepared_turns: std::sync::Mutex::new(std::collections::HashMap::new()), + }), + }) +} + +struct CapabilitySurfaceBridge { + capability_router: CapabilityRouter, +} + +impl ServerCapabilitySurfacePort for CapabilitySurfaceBridge { + fn replace_capability_invokers(&self, invokers: Vec>) -> Result<()> { + self.capability_router.replace_invokers(invokers) + } +} + +struct SessionRuntimeCompatKeepalive { + _agent_control: Arc, +} + +struct SessionRuntimeInfoBridge { + session_catalog: Arc, + active_sessions: Arc, +} + +impl SessionInfoProvider for SessionRuntimeInfoBridge { + fn loaded_session_count(&self) -> usize { + self.session_catalog.list_loaded_sessions().len() + } + + fn running_session_ids(&self) -> Vec { + self.active_sessions.running_session_ids() + } +} + +#[cfg(test)] +struct PreparedTestTurn { + session_id: String, + _lease: Box, +} + +#[cfg(test)] +struct SessionRuntimeTestSupportBridge { + session_catalog: Arc, + active_sessions: Arc, + session_runtime: Arc, + next_generation: AtomicU64, + prepared_turns: std::sync::Mutex>, +} + +#[cfg(test)] +#[async_trait::async_trait] +impl ServerRuntimeTestSupport for SessionRuntimeTestSupportBridge { + fn list_running_session_ids(&self) -> Vec { + self.active_sessions.running_session_ids() + } + + async fn append_event(&self, session_id: &str, event: StorageEvent) -> Result<()> { + let state = self + .session_catalog + .session_state(&SessionId::from(session_id.to_string())) + .await?; + let mut translator = EventTranslator::new(state.current_phase()?); + let stored = state.writer.clone().append(event).await?; + let records = state.translate_store_and_cache(&stored, &mut translator)?; + for record in records { + let _ = state.broadcaster.send(record); + } + Ok(()) + } + + async fn prepare_test_turn_runtime(&self, session_id: &str, turn_id: &str) -> Result { + let session_id_value = SessionId::from(session_id.to_string()); + let acquire = self + .session_catalog + .try_acquire_turn(&session_id_value, turn_id) + .await?; + let SessionTurnAcquireResult::Acquired(lease) = acquire else { + return Err(astrcode_core::AstrError::Validation(format!( + "session '{}' already has an active turn lease", + session_id + ))); + }; + let generation = self.next_generation.fetch_add(1, Ordering::Relaxed); + self.prepared_turns + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .insert( + generation, + PreparedTestTurn { + session_id: session_id.to_string(), + _lease: lease, + }, + ); + self.active_sessions.mark_running(session_id); + Ok(generation) + } + + async fn complete_test_turn_runtime(&self, _session_id: &str, generation: u64) -> Result<()> { + let prepared = self + .prepared_turns + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()) + .remove(&generation); + if let Some(prepared) = prepared { + self.active_sessions.mark_idle(&prepared.session_id); + } + Ok(()) + } + + async fn replay_stored_events(&self, session_id: &str) -> Result> { + self.session_catalog + .replay_stored_events(&SessionId::from(session_id.to_string())) + .await + } + + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> std::result::Result { + self.session_runtime + .register_root_agent(agent_id, session_id, profile_id) + .await + } + + async fn spawn_independent_child( + &self, + profile: &AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> std::result::Result { + self.session_runtime + .spawn_independent_child( + profile, + session_id, + child_session_id, + parent_turn_id, + parent_agent_id, + ) + .await + } + + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()> { + self.session_runtime + .set_lifecycle(sub_run_or_agent_id, new_status) + .await + } + + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { + self.session_runtime + .pending_parent_delivery_count(parent_session_id) + .await + } + + async fn query_root_status(&self, session_id: &str) -> Option { + self.session_runtime.query_root_status(session_id).await + } +} diff --git a/crates/server/src/session_runtime_port.rs b/crates/server/src/session_runtime_port.rs new file mode 100644 index 00000000..14a55c68 --- /dev/null +++ b/crates/server/src/session_runtime_port.rs @@ -0,0 +1,145 @@ +use astrcode_core::{ + AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, + DelegationMetadata, ExecutionAccepted, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, + StoredEvent, TurnId, +}; +use astrcode_host_session::SubRunHandle; +use async_trait::async_trait; + +use crate::{ + agent_control_bridge::{ServerCloseAgentSummary, ServerLiveSubRunStatus}, + application_error_bridge::ServerRouteError, + ports::{ + AppAgentPromptSubmission, RecoverableParentDelivery, ServerKernelControlError, + SessionObserveSnapshot, + }, +}; + +#[path = "session_runtime_port_adapter.rs"] +pub(crate) mod adapter; + +#[allow(dead_code)] +#[async_trait] +pub(crate) trait SessionRuntimePort: Send + Sync { + async fn submit_prompt_for_agent( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result; + async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()>; + async fn compact_session( + &self, + session_id: &str, + runtime: ResolvedRuntimeConfig, + instructions: Option, + ) -> astrcode_core::Result; + async fn switch_mode( + &self, + session_id: &str, + from: astrcode_core::ModeId, + to: astrcode_core::ModeId, + ) -> astrcode_core::Result; + async fn submit_prompt_for_agent_with_submission( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result; + async fn try_submit_prompt_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result>; + async fn submit_queued_inputs_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + queued_inputs: Vec, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result>; + async fn observe_agent_session( + &self, + open_session_id: &str, + target_agent_id: &str, + lifecycle_status: AgentLifecycleStatus, + ) -> astrcode_core::Result; + async fn get_handle(&self, agent_id: &str) -> Option; + async fn find_root_handle_for_session(&self, session_id: &str) -> Option; + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result; + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> Option<()>; + async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option; + async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option; + async fn resume(&self, sub_run_or_agent_id: &str, parent_turn_id: &str) + -> Option; + async fn spawn_independent_child( + &self, + profile: &astrcode_core::AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> Result; + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()>; + async fn complete_turn( + &self, + sub_run_or_agent_id: &str, + outcome: AgentTurnOutcome, + ) -> Option; + async fn set_delegation( + &self, + sub_run_or_agent_id: &str, + delegation: Option, + ) -> Option<()>; + async fn count_children_spawned_for_turn( + &self, + parent_agent_id: &str, + parent_turn_id: &str, + ) -> usize; + async fn collect_subtree_handles(&self, sub_run_or_agent_id: &str) -> Vec; + async fn terminate_subtree(&self, sub_run_or_agent_id: &str) -> Option; + async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()>; + async fn drain_inbox(&self, agent_id: &str) -> Option>; + async fn enqueue_child_delivery( + &self, + parent_session_id: String, + parent_turn_id: String, + notification: ChildSessionNotification, + ) -> bool; + async fn checkout_parent_delivery_batch( + &self, + parent_session_id: &str, + ) -> Option>; + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize; + async fn requeue_parent_delivery_batch(&self, parent_session_id: &str, delivery_ids: &[String]); + async fn consume_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) -> bool; + async fn query_subrun_status(&self, agent_id: &str) -> Option; + async fn query_root_status(&self, session_id: &str) -> Option; + async fn close_subtree( + &self, + agent_id: &str, + ) -> Result; +} diff --git a/crates/server/src/session_runtime_port_adapter.rs b/crates/server/src/session_runtime_port_adapter.rs new file mode 100644 index 00000000..b99d7a64 --- /dev/null +++ b/crates/server/src/session_runtime_port_adapter.rs @@ -0,0 +1,1343 @@ +use std::{path::PathBuf, sync::Arc}; + +use astrcode_agent_runtime::{ + AgentRuntime, AgentRuntimeExecutionSurface, LlmEvent, LlmProvider, RuntimeEventSink, + RuntimeTurnEvent, ToolDispatchRequest, ToolDispatcher, ToolResultReplacementRecord, TurnInput, + TurnOutput, TurnStopCause, +}; +use astrcode_core::{ + AgentEvent, AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, AstrError, + BoundModeToolContractSnapshot, CancelToken, ChildSessionNotification, CompletedSubRunOutcome, + DelegationMetadata, EventTranslator, ExecutionAccepted, ExecutionControl, FailedSubRunOutcome, + LlmMessage, ModeId, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, SessionId, + StorageEvent, StorageEventPayload, StoredEvent, SubRunFailure, SubRunFailureCode, + SubRunHandoff, SubRunResult, ToolEventSink, ToolExecutionResult, TurnId, UserMessageOrigin, +}; +use astrcode_host_session::{ + CompactSessionMutationInput, InputQueueProjection, InterruptSessionMutationInput, + SessionCatalog, SubRunFinishStats, SubmitPromptMutationInput, SubmitTurnBusyPolicy, + TurnMutationPreparation, +}; +use async_trait::async_trait; +use chrono::Utc; + +use crate::{ + agent_control_bridge::{ServerCloseAgentSummary, ServerLiveSubRunStatus}, + agent_control_registry::{AgentControlError, AgentControlRegistry, PendingParentDelivery}, + application_error_bridge::ServerRouteError, + capability_router::CapabilityRouter, + mode_catalog_service::ServerModeCatalog, + ports::{ + AppAgentPromptSubmission, RecoverableParentDelivery, ServerKernelControlError, + SessionObserveSnapshot, + }, + session_runtime_owner_bridge::ActiveSessionRegistry, + session_runtime_port::SessionRuntimePort, +}; + +pub(crate) fn build_session_runtime_port( + session_catalog: Arc, + mode_catalog: Arc, + agent_control: Arc, + capability_router: CapabilityRouter, + llm_provider: Arc, + active_sessions: Arc, +) -> Arc { + Arc::new(SessionRuntimeCompatPort { + session_catalog, + mode_catalog, + agent_control, + capability_router, + llm_provider, + active_sessions, + }) +} + +struct SessionRuntimeCompatPort { + session_catalog: Arc, + mode_catalog: Arc, + agent_control: Arc, + capability_router: CapabilityRouter, + llm_provider: Arc, + active_sessions: Arc, +} + +struct RouterToolDispatcher { + capability_router: CapabilityRouter, + working_dir: PathBuf, + cancel: CancelToken, + agent: astrcode_core::AgentEventContext, + current_mode_id: ModeId, + bound_mode_tool_contract: Option, + event_sink: Arc, +} + +struct SpawnTurnExecutionInput { + begun: astrcode_host_session::BegunAcceptedTurn, + working_dir: PathBuf, + runtime: ResolvedRuntimeConfig, + messages: Vec, + last_assistant_at: Option>, + tool_result_replacements: Vec, + submission: AppAgentPromptSubmission, +} + +impl From for ServerKernelControlError { + fn from(value: AgentControlError) -> Self { + match value { + AgentControlError::MaxDepthExceeded { current, max } => { + Self::MaxDepthExceeded { current, max } + }, + AgentControlError::MaxConcurrentExceeded { current, max } => { + Self::MaxConcurrentExceeded { current, max } + }, + AgentControlError::ParentAgentNotFound { agent_id } => { + Self::ParentAgentNotFound { agent_id } + }, + } + } +} + +#[async_trait] +impl ToolDispatcher for RouterToolDispatcher { + async fn dispatch_tool( + &self, + request: ToolDispatchRequest, + ) -> astrcode_core::Result { + let mut tool_ctx = astrcode_core::ToolContext::new( + request.session_id.clone().into(), + self.working_dir.clone(), + self.cancel.clone(), + ) + .with_turn_id(request.turn_id) + .with_tool_call_id(request.tool_call.id.clone()) + .with_agent_context(self.agent.clone()) + .with_current_mode_id(self.current_mode_id.clone()); + if let Some(snapshot) = &self.bound_mode_tool_contract { + tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot.clone()); + } + if let Some(sender) = request.tool_output_sender { + tool_ctx = tool_ctx.with_tool_output_sender(sender); + } + tool_ctx = tool_ctx.with_event_sink(Arc::clone(&self.event_sink)); + if let Some(max_inline) = self + .capability_router + .capability_spec(&request.tool_call.name) + .and_then(|spec| spec.max_result_inline_size) + { + tool_ctx = tool_ctx.with_resolved_inline_limit(max_inline); + } + Ok(self + .capability_router + .execute_tool(&request.tool_call, &tool_ctx) + .await) + } +} + +impl SessionRuntimeCompatPort { + fn submit_preparation() -> TurnMutationPreparation { + TurnMutationPreparation::external_preparation("server") + } + + async fn begin_turn( + &self, + accepted: astrcode_host_session::AcceptedSubmitPrompt, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result<( + ExecutionAccepted, + astrcode_host_session::BegunAcceptedTurn, + Vec, + PathBuf, + Option>, + Vec, + )> { + let session_id = accepted.summary.session_id.clone(); + let turn_id = accepted.summary.turn_id.clone(); + let loaded = self + .session_catalog + .ensure_loaded_session(&session_id) + .await?; + let working_dir = loaded.working_dir.clone(); + let projected_state = loaded.state.snapshot_projected_state()?; + let last_assistant_at = projected_state.last_assistant_at; + let replacements = + tool_result_replacements_from_events(loaded.state.snapshot_recent_stored_events()?); + let messages = build_turn_messages( + loaded.state.current_turn_messages()?, + accepted.live_user_input.clone(), + accepted.queued_inputs.clone(), + submission.injected_messages.clone(), + ); + let cancel = CancelToken::new(); + let begun = self.session_catalog.begin_accepted_turn( + accepted, + submission.agent.clone(), + cancel.clone(), + )?; + if let Err(error) = self + .session_catalog + .persist_begun_turn_inputs(&begun, submission.agent.clone()) + .await + { + let _ = self + .session_catalog + .complete_running_turn(&session_id, &turn_id); + return Err(error); + } + let accepted = ExecutionAccepted { + session_id: session_id.clone(), + turn_id: turn_id.clone(), + agent_id: None, + branched_from_session_id: begun.summary.branched_from_session_id.clone(), + }; + self.active_sessions.mark_running(session_id.as_str()); + Ok(( + accepted, + begun, + messages, + working_dir, + last_assistant_at, + replacements, + )) + } + + fn spawn_turn_execution(&self, input: SpawnTurnExecutionInput) { + let SpawnTurnExecutionInput { + begun, + working_dir, + runtime, + messages, + last_assistant_at, + tool_result_replacements, + submission, + } = input; + let session_catalog = Arc::clone(&self.session_catalog); + let capability_router = self.capability_router.clone(); + let llm_provider = Arc::clone(&self.llm_provider); + let active_sessions = Arc::clone(&self.active_sessions); + let mode_catalog = Arc::clone(&self.mode_catalog); + let runtime_loop = AgentRuntime::new(); + tokio::spawn(async move { + let session_id = begun.summary.session_id.clone(); + let turn_id = begun.summary.turn_id.clone(); + let agent = submission.agent.clone(); + let source_tool_call_id = submission.source_tool_call_id.clone(); + let resolved_limits = submission.resolved_limits.clone(); + let resolved_overrides = submission.resolved_overrides.clone(); + let current_mode_id = submission.current_mode_id.clone(); + let bound_mode_tool_contract = submission.bound_mode_tool_contract.clone(); + let (runtime_event_sink, runtime_event_bridge) = spawn_runtime_event_bridge( + Arc::clone(&session_catalog), + session_id.clone(), + turn_id.clone(), + agent.clone(), + ); + let tool_event_sink = Arc::new(RuntimeToolEventSink { + runtime_event_sink: Arc::clone(&runtime_event_sink), + mode_catalog: Arc::clone(&mode_catalog), + }); + + let _ = session_catalog + .append_subrun_started( + &session_id, + turn_id.as_str(), + agent.clone(), + resolved_limits.clone(), + resolved_overrides, + source_tool_call_id.clone(), + ) + .await; + + let events_history_path = astrcode_support::hostpaths::project_dir(&working_dir) + .ok() + .map(|project_dir| { + project_dir + .join("sessions") + .join(session_id.as_str()) + .join("events.jsonl") + .to_string_lossy() + .to_string() + }); + + let turn_input = TurnInput::new(AgentRuntimeExecutionSurface { + session_id: session_id.to_string(), + turn_id: turn_id.to_string(), + agent_id: agent_id_for_surface(&agent), + model_ref: "server-owned-runtime".to_string(), + provider_ref: "server-owned-provider".to_string(), + tool_specs: capability_router.capability_specs(), + hook_snapshot_id: "server-owned".to_string(), + }) + .with_agent(agent.clone()) + .with_messages(messages) + .with_provider(llm_provider) + .with_tool_dispatcher(Arc::new(RouterToolDispatcher { + capability_router, + working_dir: working_dir.clone(), + cancel: CancelToken::new(), + agent: agent.clone(), + current_mode_id, + bound_mode_tool_contract, + event_sink: tool_event_sink, + })) + .with_working_dir(working_dir) + .with_runtime_config(runtime.clone()) + .with_last_assistant_at(last_assistant_at) + .with_previous_tool_result_replacements(tool_result_replacements) + .with_max_output_continuations(runtime.max_output_continuation_attempts) + .with_events_history_path(events_history_path) + .with_event_sink(runtime_event_sink); + + let output = runtime_loop.execute_turn(turn_input).await; + if let Err(error) = runtime_event_bridge.await { + log::warn!( + "runtime event bridge join failed for session '{}': {}", + session_id, + error + ); + } + finalize_turn_execution( + session_catalog, + active_sessions, + begun, + output, + agent, + source_tool_call_id, + ) + .await; + }); + } + + #[allow(clippy::too_many_arguments)] + async fn submit_prompt_inner( + &self, + session_id: &str, + requested_turn_id: Option, + prompt_text: Option, + queued_inputs: Vec, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + busy_policy: SubmitTurnBusyPolicy, + ) -> astrcode_core::Result> { + let accepted = self + .session_catalog + .accept_submit_prompt( + SubmitPromptMutationInput { + requested_session_id: SessionId::from(session_id.to_string()), + requested_turn_id, + prompt_text: prompt_text.unwrap_or_default(), + queued_inputs, + control: None, + preparation: Self::submit_preparation(), + }, + busy_policy, + ) + .await?; + let Some(accepted_prompt) = accepted else { + return Ok(None); + }; + let (accepted, begun, messages, working_dir, last_assistant_at, replacements) = + self.begin_turn(accepted_prompt, submission.clone()).await?; + self.spawn_turn_execution(SpawnTurnExecutionInput { + begun, + working_dir, + runtime, + messages, + last_assistant_at, + tool_result_replacements: replacements, + submission, + }); + Ok(Some(accepted)) + } +} + +#[async_trait] +impl SessionRuntimePort for SessionRuntimeCompatPort { + async fn submit_prompt_for_agent( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + let max_branch_depth = runtime.max_concurrent_branch_depth; + self.submit_prompt_inner( + session_id, + None, + Some(text), + Vec::new(), + runtime, + submission, + SubmitTurnBusyPolicy::BranchOnBusy { max_branch_depth }, + ) + .await? + .ok_or_else(|| { + AstrError::Validation( + "submit prompt unexpectedly rejected while branch-on-busy is enabled".to_string(), + ) + }) + } + + async fn interrupt_session(&self, session_id: &str) -> astrcode_core::Result<()> { + let _ = self + .session_catalog + .interrupt_running_turn(InterruptSessionMutationInput { + session_id: SessionId::from(session_id.to_string()), + }) + .await?; + Ok(()) + } + + async fn compact_session( + &self, + session_id: &str, + _runtime: ResolvedRuntimeConfig, + instructions: Option, + ) -> astrcode_core::Result { + Ok(self + .session_catalog + .request_manual_compact(CompactSessionMutationInput { + session_id: SessionId::from(session_id.to_string()), + control: Some(ExecutionControl { + manual_compact: Some(true), + }), + instructions, + preparation: Self::submit_preparation(), + }) + .await? + .deferred) + } + + async fn switch_mode( + &self, + session_id: &str, + from: ModeId, + to: ModeId, + ) -> astrcode_core::Result { + self.mode_catalog.validate_transition(&from, &to)?; + let session_state = self + .session_catalog + .session_state(&SessionId::from(session_id.to_string())) + .await?; + let mut translator = EventTranslator::new(session_state.current_phase()?); + session_state + .append_and_broadcast( + &astrcode_core::StorageEvent { + turn_id: None, + agent: astrcode_core::AgentEventContext::default(), + payload: astrcode_core::StorageEventPayload::ModeChanged { + from, + to, + timestamp: Utc::now(), + }, + }, + &mut translator, + ) + .await + } + + async fn submit_prompt_for_agent_with_submission( + &self, + session_id: &str, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + self.submit_prompt_for_agent(session_id, text, runtime, submission) + .await + } + + async fn try_submit_prompt_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + text: String, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + self.submit_prompt_inner( + session_id, + Some(turn_id), + Some(text), + Vec::new(), + runtime, + submission, + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await + } + + async fn submit_queued_inputs_for_agent_with_turn_id( + &self, + session_id: &str, + turn_id: TurnId, + queued_inputs: Vec, + runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + self.submit_prompt_inner( + session_id, + Some(turn_id), + None, + queued_inputs, + runtime, + submission, + SubmitTurnBusyPolicy::RejectOnBusy, + ) + .await + } + + async fn observe_agent_session( + &self, + open_session_id: &str, + target_agent_id: &str, + lifecycle_status: AgentLifecycleStatus, + ) -> astrcode_core::Result { + let session_state = self + .session_catalog + .session_state(&SessionId::from(open_session_id.to_string())) + .await?; + let projected = session_state.snapshot_projected_state()?; + let input_queue_projection = + session_state.input_queue_projection_for_agent(target_agent_id)?; + Ok(build_agent_observe_snapshot( + lifecycle_status, + &projected, + &input_queue_projection, + )) + } + + async fn get_handle(&self, agent_id: &str) -> Option { + self.agent_control.get(agent_id).await + } + + async fn find_root_handle_for_session( + &self, + session_id: &str, + ) -> Option { + self.agent_control + .find_root_agent_for_session(session_id) + .await + } + + async fn register_root_agent( + &self, + agent_id: String, + session_id: String, + profile_id: String, + ) -> Result { + self.agent_control + .register_root_agent(agent_id, session_id, profile_id) + .await + .map_err(ServerKernelControlError::from) + } + + async fn set_resolved_limits( + &self, + sub_run_or_agent_id: &str, + resolved_limits: ResolvedExecutionLimitsSnapshot, + ) -> Option<()> { + self.agent_control + .set_resolved_limits(sub_run_or_agent_id, resolved_limits) + .await + } + + async fn get_lifecycle(&self, sub_run_or_agent_id: &str) -> Option { + self.agent_control.get_lifecycle(sub_run_or_agent_id).await + } + + async fn get_turn_outcome(&self, sub_run_or_agent_id: &str) -> Option { + self.agent_control + .get_turn_outcome(sub_run_or_agent_id) + .await + .flatten() + } + + async fn resume( + &self, + sub_run_or_agent_id: &str, + parent_turn_id: &str, + ) -> Option { + self.agent_control + .resume(sub_run_or_agent_id, parent_turn_id) + .await + } + + async fn spawn_independent_child( + &self, + profile: &astrcode_core::AgentProfile, + session_id: String, + child_session_id: String, + parent_turn_id: String, + parent_agent_id: String, + ) -> Result { + self.agent_control + .spawn_with_storage( + profile, + session_id, + Some(child_session_id), + parent_turn_id, + Some(parent_agent_id), + astrcode_core::SubRunStorageMode::IndependentSession, + ) + .await + .map_err(ServerKernelControlError::from) + } + + async fn set_lifecycle( + &self, + sub_run_or_agent_id: &str, + new_status: AgentLifecycleStatus, + ) -> Option<()> { + self.agent_control + .set_lifecycle(sub_run_or_agent_id, new_status) + .await + } + + async fn complete_turn( + &self, + sub_run_or_agent_id: &str, + outcome: AgentTurnOutcome, + ) -> Option { + self.agent_control + .complete_turn(sub_run_or_agent_id, outcome) + .await + } + + async fn set_delegation( + &self, + sub_run_or_agent_id: &str, + delegation: Option, + ) -> Option<()> { + self.agent_control + .set_delegation(sub_run_or_agent_id, delegation) + .await + } + + async fn count_children_spawned_for_turn( + &self, + parent_agent_id: &str, + parent_turn_id: &str, + ) -> usize { + self.agent_control + .list() + .await + .into_iter() + .filter(|handle| { + handle.parent_turn_id.as_str() == parent_turn_id + && handle + .parent_agent_id + .as_ref() + .is_some_and(|id| id.as_str() == parent_agent_id) + && matches!( + handle.lineage_kind, + astrcode_core::ChildSessionLineageKind::Spawn + | astrcode_core::ChildSessionLineageKind::Fork + ) + }) + .count() + } + + async fn collect_subtree_handles( + &self, + sub_run_or_agent_id: &str, + ) -> Vec { + self.agent_control + .collect_subtree_handles(sub_run_or_agent_id) + .await + } + + async fn terminate_subtree( + &self, + sub_run_or_agent_id: &str, + ) -> Option { + self.agent_control + .terminate_subtree(sub_run_or_agent_id) + .await + } + + async fn deliver(&self, agent_id: &str, envelope: AgentInboxEnvelope) -> Option<()> { + self.agent_control.push_inbox(agent_id, envelope).await + } + + async fn drain_inbox(&self, agent_id: &str) -> Option> { + self.agent_control.drain_inbox(agent_id).await + } + + async fn enqueue_child_delivery( + &self, + parent_session_id: String, + parent_turn_id: String, + notification: ChildSessionNotification, + ) -> bool { + self.agent_control + .enqueue_parent_delivery(parent_session_id, parent_turn_id, notification) + .await + } + + async fn checkout_parent_delivery_batch( + &self, + parent_session_id: &str, + ) -> Option> { + self.agent_control + .checkout_parent_delivery_batch(parent_session_id) + .await + .map(map_pending_parent_deliveries) + } + + async fn pending_parent_delivery_count(&self, parent_session_id: &str) -> usize { + self.agent_control + .pending_parent_delivery_count(parent_session_id) + .await + } + + async fn requeue_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) { + self.agent_control + .requeue_parent_delivery_batch(parent_session_id, delivery_ids) + .await + } + + async fn consume_parent_delivery_batch( + &self, + parent_session_id: &str, + delivery_ids: &[String], + ) -> bool { + self.agent_control + .consume_parent_delivery_batch(parent_session_id, delivery_ids) + .await + } + + async fn query_subrun_status(&self, agent_id: &str) -> Option { + self.agent_control + .get(agent_id) + .await + .map(|handle| map_runtime_status(&handle)) + } + + async fn query_root_status(&self, session_id: &str) -> Option { + self.agent_control + .find_root_agent_for_session(session_id) + .await + .map(|handle| map_runtime_status(&handle)) + } + + async fn close_subtree( + &self, + agent_id: &str, + ) -> Result { + self.agent_control + .terminate_subtree_and_collect_handles(agent_id) + .await + .map(|handles| ServerCloseAgentSummary { + closed_agent_ids: handles + .into_iter() + .map(|handle| handle.agent_id.to_string()) + .collect(), + }) + .ok_or_else(|| ServerRouteError::not_found(format!("agent '{}' not found", agent_id))) + } +} + +struct RuntimeToolEventSink { + runtime_event_sink: Arc, + mode_catalog: Arc, +} + +#[async_trait] +impl ToolEventSink for RuntimeToolEventSink { + async fn emit(&self, event: StorageEvent) -> astrcode_core::Result<()> { + if let StorageEventPayload::ModeChanged { from, to, .. } = &event.payload { + self.mode_catalog.validate_transition(from, to)?; + } + self.runtime_event_sink + .emit_event(RuntimeTurnEvent::StorageEvent { + event: Box::new(event), + }); + Ok(()) + } +} + +fn spawn_runtime_event_bridge( + session_catalog: Arc, + session_id: SessionId, + turn_id: TurnId, + agent: astrcode_core::AgentEventContext, +) -> (Arc, tokio::task::JoinHandle<()>) { + let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel::(); + let sink = Arc::new(move |event: RuntimeTurnEvent| { + let _ = sender.send(event); + }); + let bridge = tokio::spawn(async move { + let session_state = match session_catalog.session_state(&session_id).await { + Ok(state) => Some(state), + Err(error) => { + log::warn!( + "failed to attach live runtime event bridge for session '{}': {}", + session_id, + error + ); + None + }, + }; + while let Some(event) = receiver.recv().await { + if is_stale_terminal_runtime_event(&session_catalog, &session_id, &turn_id, &event) + .await + { + continue; + } + if let Some(state) = &session_state { + for agent_event in runtime_event_to_live_agent_events(&event, &agent) { + state.broadcast_live_event(agent_event); + } + } + if let Err(error) = session_catalog + .persist_runtime_turn_event( + astrcode_host_session::RuntimeTurnEventPersistenceInput { + session_id: session_id.clone(), + turn_id: turn_id.clone(), + agent: agent.clone(), + runtime_event: event, + }, + ) + .await + { + log::warn!( + "failed to persist runtime event for session '{}' turn '{}': {}", + session_id, + turn_id, + error + ); + } + } + }); + (sink, bridge) +} + +async fn is_stale_terminal_runtime_event( + session_catalog: &SessionCatalog, + session_id: &SessionId, + turn_id: &TurnId, + event: &RuntimeTurnEvent, +) -> bool { + if !matches!( + event, + RuntimeTurnEvent::TurnCompleted { .. } | RuntimeTurnEvent::TurnErrored { .. } + ) { + return false; + } + match session_catalog.session_control_state(session_id).await { + Ok(control) => { + control + .active_turn_id + .as_deref() + .is_some_and(|active| active != turn_id.as_str()) + || control.active_turn_id.is_none() + }, + Err(error) => { + log::warn!( + "failed to read active turn before terminal persistence for session '{}': {}", + session_id, + error + ); + false + }, + } +} + +fn runtime_event_to_live_agent_events( + event: &RuntimeTurnEvent, + agent: &astrcode_core::AgentEventContext, +) -> Vec { + match event { + RuntimeTurnEvent::ProviderStream { identity, event } => match event { + LlmEvent::TextDelta(delta) if !delta.is_empty() => vec![AgentEvent::ModelDelta { + turn_id: identity.turn_id.clone(), + agent: agent.clone(), + delta: delta.clone(), + }], + LlmEvent::ThinkingDelta(delta) if !delta.is_empty() => { + vec![AgentEvent::ThinkingDelta { + turn_id: identity.turn_id.clone(), + agent: agent.clone(), + delta: delta.clone(), + }] + }, + LlmEvent::StreamRetryStarted { + attempt, + max_attempts, + reason, + } => vec![AgentEvent::StreamRetryStarted { + turn_id: identity.turn_id.clone(), + agent: agent.clone(), + attempt: *attempt, + max_attempts: *max_attempts, + reason: reason.clone(), + }], + _ => Vec::new(), + }, + RuntimeTurnEvent::TurnCompleted { identity, .. } => vec![AgentEvent::TurnDone { + turn_id: identity.turn_id.clone(), + agent: agent.clone(), + }], + RuntimeTurnEvent::TurnErrored { identity, message } => vec![AgentEvent::Error { + turn_id: Some(identity.turn_id.clone()), + agent: agent.clone(), + code: "agent_error".to_string(), + message: message.clone(), + }], + RuntimeTurnEvent::StorageEvent { event } => { + runtime_storage_event_to_live_agent_events(event, agent) + }, + _ => Vec::new(), + } +} + +fn runtime_storage_event_to_live_agent_events( + event: &astrcode_core::StorageEvent, + fallback_agent: &astrcode_core::AgentEventContext, +) -> Vec { + let Some(turn_id) = event.turn_id.clone() else { + return Vec::new(); + }; + let agent = if event.agent.is_empty() { + fallback_agent.clone() + } else { + event.agent.clone() + }; + match &event.payload { + StorageEventPayload::ToolCall { + tool_call_id, + tool_name, + args, + } => vec![AgentEvent::ToolCallStart { + turn_id, + agent, + tool_call_id: tool_call_id.clone(), + tool_name: tool_name.clone(), + input: args.clone(), + }], + StorageEventPayload::ToolCallDelta { + tool_call_id, + tool_name, + stream, + delta, + } if !delta.is_empty() => vec![AgentEvent::ToolCallDelta { + turn_id, + agent, + tool_call_id: tool_call_id.clone(), + tool_name: tool_name.clone(), + stream: *stream, + delta: delta.clone(), + }], + StorageEventPayload::ToolResult { + tool_call_id, + tool_name, + output, + success, + error, + metadata, + continuation, + duration_ms, + } => vec![AgentEvent::ToolCallResult { + turn_id, + agent, + result: ToolExecutionResult { + tool_call_id: tool_call_id.clone(), + tool_name: tool_name.clone(), + ok: *success, + output: output.clone(), + error: error.clone(), + metadata: metadata.clone(), + continuation: continuation.clone(), + duration_ms: *duration_ms, + truncated: false, + }, + }], + _ => Vec::new(), + } +} + +async fn finalize_turn_execution( + session_catalog: Arc, + active_sessions: Arc, + begun: astrcode_host_session::BegunAcceptedTurn, + output: TurnOutput, + agent: astrcode_core::AgentEventContext, + source_tool_call_id: Option, +) { + let session_id = begun.summary.session_id.clone(); + let turn_id = begun.summary.turn_id.clone(); + let _ = session_catalog + .append_subrun_finished( + &session_id, + turn_id.as_str(), + agent, + build_subrun_result(&output), + SubRunFinishStats { + step_count: output.step_count as u32, + estimated_tokens: 0, + }, + source_tool_call_id, + ) + .await; + + if let Err(error) = session_catalog.complete_running_turn(&session_id, &turn_id) { + log::warn!( + "failed to complete running turn state for session '{}': {}", + session_id, + error + ); + } + active_sessions.mark_idle(session_id.as_str()); +} + +fn build_turn_messages( + mut messages: Vec, + live_user_input: Option, + queued_inputs: Vec, + injected_messages: Vec, +) -> Vec { + for content in queued_inputs { + messages.push(LlmMessage::User { + content, + origin: UserMessageOrigin::QueuedInput, + }); + } + if let Some(text) = live_user_input { + messages.push(LlmMessage::User { + content: text, + origin: UserMessageOrigin::User, + }); + } + if !injected_messages.is_empty() { + let insert_at = if messages.last().is_some_and(|message| { + matches!( + message, + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } + ) + }) { + messages.len().saturating_sub(1) + } else { + messages.len() + }; + messages.splice(insert_at..insert_at, injected_messages); + } + messages +} + +fn tool_result_replacements_from_events( + events: Vec, +) -> Vec { + events + .into_iter() + .filter_map(|stored| match stored.event.payload { + StorageEventPayload::ToolResultReferenceApplied { + tool_call_id, + persisted_output, + replacement, + original_bytes, + } => Some(ToolResultReplacementRecord { + tool_call_id, + persisted_output, + replacement, + original_bytes, + }), + _ => None, + }) + .collect() +} + +fn build_agent_observe_snapshot( + lifecycle_status: AgentLifecycleStatus, + projected: &astrcode_host_session::AgentState, + input_queue_projection: &InputQueueProjection, +) -> SessionObserveSnapshot { + SessionObserveSnapshot { + phase: projected.phase, + turn_count: projected.turn_count as u32, + active_task: active_task_summary(lifecycle_status, projected, input_queue_projection), + last_output_tail: extract_last_output(&projected.messages), + last_turn_tail: extract_last_turn_tail(&projected.messages), + } +} + +fn extract_last_output(messages: &[LlmMessage]) -> Option { + messages.iter().rev().find_map(|message| match message { + LlmMessage::Assistant { content, .. } if !content.trim().is_empty() => { + Some(truncate_text(content, 200)) + }, + _ => None, + }) +} + +fn active_task_summary( + lifecycle_status: AgentLifecycleStatus, + projected: &astrcode_host_session::AgentState, + input_queue_projection: &InputQueueProjection, +) -> Option { + if !input_queue_projection.active_delivery_ids.is_empty() { + return extract_last_turn_tail(&projected.messages) + .into_iter() + .next(); + } + if matches!( + lifecycle_status, + AgentLifecycleStatus::Pending | AgentLifecycleStatus::Running + ) { + return projected + .messages + .iter() + .rev() + .find_map(|message| match message { + LlmMessage::User { + content, + origin: UserMessageOrigin::User, + } => summarize_inline_text(content, 120), + _ => None, + }); + } + None +} + +fn extract_last_turn_tail(messages: &[LlmMessage]) -> Vec { + messages + .iter() + .rev() + .filter_map(|message| match message { + LlmMessage::User { content, .. } + | LlmMessage::Assistant { content, .. } + | LlmMessage::Tool { content, .. } => summarize_inline_text(content, 120), + }) + .take(3) + .collect::>() + .into_iter() + .rev() + .collect() +} + +fn summarize_inline_text(content: &str, limit: usize) -> Option { + let trimmed = content.trim(); + if trimmed.is_empty() { + return None; + } + Some(truncate_text(trimmed, limit)) +} + +fn truncate_text(content: &str, limit: usize) -> String { + if content.chars().count() <= limit { + return content.to_string(); + } + let prefix = content.chars().take(limit).collect::(); + format!("{prefix}...") +} + +fn build_subrun_result(output: &TurnOutput) -> SubRunResult { + match output.stop_cause.unwrap_or(TurnStopCause::Completed) { + TurnStopCause::Completed => SubRunResult::Completed { + outcome: CompletedSubRunOutcome::Completed, + handoff: SubRunHandoff { + findings: Vec::new(), + artifacts: Vec::new(), + delivery: None, + }, + }, + TurnStopCause::Cancelled => SubRunResult::Failed { + outcome: FailedSubRunOutcome::Cancelled, + failure: SubRunFailure { + code: SubRunFailureCode::Interrupted, + display_message: "child agent cancelled".to_string(), + technical_message: output + .error_message + .clone() + .unwrap_or_else(|| "child agent cancelled".to_string()), + retryable: false, + }, + }, + TurnStopCause::Error => SubRunResult::Failed { + outcome: FailedSubRunOutcome::Failed, + failure: SubRunFailure { + code: SubRunFailureCode::Internal, + display_message: output + .error_message + .clone() + .unwrap_or_else(|| "child agent failed".to_string()), + technical_message: output + .error_message + .clone() + .unwrap_or_else(|| "child agent failed".to_string()), + retryable: true, + }, + }, + } +} + +fn agent_id_for_surface(agent: &astrcode_core::AgentEventContext) -> String { + agent + .agent_id + .clone() + .map(|value| value.to_string()) + .unwrap_or_else(|| "root-agent".to_string()) +} + +fn map_runtime_status(value: &astrcode_host_session::SubRunHandle) -> ServerLiveSubRunStatus { + ServerLiveSubRunStatus { + sub_run_id: value.sub_run_id.to_string(), + agent_id: value.agent_id.to_string(), + agent_profile: value.agent_profile.clone(), + session_id: value.session_id.to_string(), + child_session_id: value.child_session_id.clone().map(Into::into), + depth: value.depth, + parent_agent_id: value.parent_agent_id.clone().map(Into::into), + lifecycle: value.lifecycle, + last_turn_outcome: value.last_turn_outcome, + resolved_limits: value.resolved_limits.clone(), + } +} + +fn map_pending_parent_deliveries( + deliveries: Vec, +) -> Vec { + deliveries + .into_iter() + .map(|value| RecoverableParentDelivery { + delivery_id: value.delivery_id, + parent_session_id: value.parent_session_id, + parent_turn_id: value.parent_turn_id, + queued_at_ms: value.queued_at_ms, + notification: value.notification, + }) + .collect() +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + + use astrcode_adapter_tools::builtin_tools::enter_plan_mode::EnterPlanModeTool; + use astrcode_agent_runtime::{RuntimeEventSink, ToolDispatchRequest, ToolDispatcher}; + use astrcode_core::{ + AgentEvent, AgentEventContext, CancelToken, CapabilityInvoker, ModeId, StorageEvent, + StorageEventPayload, ToolCallRequest, ToolOutputStream, + }; + + use super::{ + RouterToolDispatcher, RuntimeToolEventSink, RuntimeTurnEvent, + runtime_event_to_live_agent_events, + }; + use crate::{ + capability_router::CapabilityRouter, mode::builtin_mode_catalog, + mode_catalog_service::ServerModeCatalog, tool_capability_invoker::ToolCapabilityInvoker, + }; + + #[test] + fn runtime_storage_tool_delta_maps_to_live_agent_event() { + let agent = AgentEventContext::root_execution("agent-root", "default"); + let events = runtime_event_to_live_agent_events( + &RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some("turn-1".to_string()), + agent: agent.clone(), + payload: StorageEventPayload::ToolCallDelta { + tool_call_id: "call-1".to_string(), + tool_name: "shell_command".to_string(), + stream: ToolOutputStream::Stdout, + delta: "live\n".to_string(), + }, + }), + }, + &agent, + ); + + assert_eq!(events.len(), 1); + assert!(matches!( + &events[0], + AgentEvent::ToolCallDelta { + turn_id, + tool_call_id, + tool_name, + stream, + delta, + .. + } if turn_id == "turn-1" + && tool_call_id == "call-1" + && tool_name == "shell_command" + && *stream == ToolOutputStream::Stdout + && delta == "live\n" + )); + } + + #[tokio::test] + async fn router_tool_dispatcher_attaches_event_sink_for_enter_plan_mode() { + let capability_router = CapabilityRouter::builder() + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(EnterPlanModeTool)) + .expect("enterPlanMode should register"), + ) as Arc) + .build() + .expect("capability router should build"); + let (event_tx, mut event_rx) = tokio::sync::mpsc::unbounded_channel(); + let runtime_event_sink: Arc = + Arc::new(move |event: RuntimeTurnEvent| { + let _ = event_tx.send(event); + }); + let dispatcher = RouterToolDispatcher { + capability_router, + working_dir: std::env::temp_dir(), + cancel: CancelToken::new(), + agent: AgentEventContext::root_execution("agent-root", "default"), + current_mode_id: ModeId::code(), + bound_mode_tool_contract: None, + event_sink: Arc::new(RuntimeToolEventSink { + runtime_event_sink, + mode_catalog: builtin_server_mode_catalog(), + }), + }; + + let result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-1".to_string(), + name: "enterPlanMode".to_string(), + args: serde_json::json!({ + "reason": "need a plan" + }), + }, + tool_output_sender: None, + }) + .await + .expect("tool dispatch should succeed"); + + assert!(result.ok, "enterPlanMode should not fail without a sink"); + let event = event_rx.recv().await.expect("mode event should emit"); + assert!(matches!( + event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + &event.payload, + StorageEventPayload::ModeChanged { from, to, .. } + if *from == ModeId::code() && *to == ModeId::plan() + ) + )); + } + + fn builtin_server_mode_catalog() -> Arc { + let builtin_catalog = builtin_mode_catalog().expect("builtin catalog should build"); + let builtin_mode_specs = builtin_catalog + .list() + .into_iter() + .filter_map(|summary| builtin_catalog.get(&summary.id)) + .collect::>(); + ServerModeCatalog::from_mode_specs(builtin_mode_specs, Vec::new()) + .expect("server mode catalog should build") + } +} diff --git a/crates/server/src/session_use_cases.rs b/crates/server/src/session_use_cases.rs new file mode 100644 index 00000000..0a4e3f5f --- /dev/null +++ b/crates/server/src/session_use_cases.rs @@ -0,0 +1,11 @@ +//! server 私有的 session fork 选择枚举。 +//! +//! 只保留 `ports::app_session` 需要的最小类型定义。 + +#[allow(dead_code)] +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum SessionForkSelector { + Latest, + TurnEnd { turn_id: String }, + StorageSeq { storage_seq: u64 }, +} diff --git a/crates/server/src/tests/agent_routes_tests.rs b/crates/server/src/tests/agent_routes_tests.rs index 969de6ee..7b3f68e1 100644 --- a/crates/server/src/tests/agent_routes_tests.rs +++ b/crates/server/src/tests/agent_routes_tests.rs @@ -4,10 +4,7 @@ use std::{ time::{Duration, Instant}, }; -use astrcode_core::{ - AgentEventContext, CancelToken, SpawnAgentParams, ToolContext, - agent::executor::SubAgentExecutor, -}; +use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams, ToolContext}; use axum::{ body::{Body, to_bytes}, http::{Request, StatusCode}, @@ -19,6 +16,7 @@ use crate::{ auth::{AuthSessionManager, BootstrapAuth}, routes::build_api_router, test_support::{ManualWatchHarness, ServerTestContext, test_state, test_state_with_options}, + watch_service::WatchSource, }; async fn json_body(response: axum::http::Response) -> T { @@ -87,8 +85,8 @@ async fn execute_agent_returns_not_found_for_unknown_profile_without_creating_se let (state, _guard) = test_state(None).await; let project = tempfile::tempdir().expect("tempdir should be created"); let before = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -115,8 +113,8 @@ async fn execute_agent_returns_not_found_for_unknown_profile_without_creating_se assert_eq!(response.status(), StatusCode::NOT_FOUND); let after = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -129,8 +127,8 @@ async fn execute_agent_rejects_subagent_only_profile_without_creating_session() let project = tempfile::tempdir().expect("tempdir should be created"); write_agent_profile(project.path(), "reviewer", "仓库审查"); let before = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -157,8 +155,8 @@ async fn execute_agent_rejects_subagent_only_profile_without_creating_session() assert_eq!(response.status(), StatusCode::BAD_REQUEST); let after = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -170,8 +168,8 @@ async fn execute_agent_rejects_invalid_execution_control_before_creating_session let (state, _guard) = test_state(None).await; let project = tempfile::tempdir().expect("tempdir should be created"); let before = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -201,8 +199,8 @@ async fn execute_agent_rejects_invalid_execution_control_before_creating_session assert_eq!(response.status(), StatusCode::BAD_REQUEST); let after = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -214,8 +212,8 @@ async fn execute_agent_rejects_unsupported_context_overrides_before_creating_ses let (state, _guard) = test_state(None).await; let project = tempfile::tempdir().expect("tempdir should be created"); let before = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -245,8 +243,8 @@ async fn execute_agent_rejects_unsupported_context_overrides_before_creating_ses assert_eq!(response.status(), StatusCode::BAD_REQUEST); let after = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -261,13 +259,12 @@ async fn subagent_launch_uses_resolved_profile_and_inherits_parent_working_dir() let project_dir = normalize_path(project.path()); let parent = state - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("parent session should be created"); state - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), parent.session_id.clone(), @@ -288,8 +285,7 @@ async fn subagent_launch_uses_resolved_profile_and_inherits_parent_working_dir() )); let result = state - .app - .agent() + .subagent_executor .launch( SpawnAgentParams { r#type: Some("reviewer".to_string()), @@ -319,7 +315,7 @@ async fn subagent_launch_uses_resolved_profile_and_inherits_parent_working_dir() .expect("child session artifact should exist"); let subrun = state - .app + .agent_api .get_subrun_status(&child_agent_id) .await .expect("subrun query should succeed") @@ -340,8 +336,8 @@ async fn subagent_launch_uses_resolved_profile_and_inherits_parent_working_dir() ); let child_meta = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .into_iter() @@ -359,13 +355,12 @@ async fn subagent_launch_rejects_missing_profile_without_creating_child_session( let project = tempfile::tempdir().expect("tempdir should be created"); let parent = state - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("parent session should be created"); state - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), parent.session_id.clone(), @@ -375,8 +370,8 @@ async fn subagent_launch_rejects_missing_profile_without_creating_child_session( .expect("root agent should be registered"); let before = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -392,8 +387,7 @@ async fn subagent_launch_rejects_missing_profile_without_creating_child_session( )); let error = state - .app - .agent() + .subagent_executor .launch( SpawnAgentParams { r#type: Some("missing".to_string()), @@ -411,8 +405,8 @@ async fn subagent_launch_rejects_missing_profile_without_creating_child_session( ); let after = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list") .len(); @@ -437,13 +431,12 @@ async fn get_subrun_status_falls_back_to_durable_snapshot_with_resolved_limits() let project = tempfile::tempdir().expect("tempdir should be created"); write_agent_profile(project.path(), "reviewer", "仓库审查"); let parent = initial_runtime - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("parent session should be created"); initial_runtime - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), parent.session_id.clone(), @@ -464,8 +457,7 @@ async fn get_subrun_status_falls_back_to_durable_snapshot_with_resolved_limits() )); let result = initial_runtime - .app - .agent() + .subagent_executor .launch( SpawnAgentParams { r#type: Some("reviewer".to_string()), @@ -489,7 +481,7 @@ async fn get_subrun_status_falls_back_to_durable_snapshot_with_resolved_limits() .expect("child agent artifact should exist"); initial_runtime - .app + .agent_api .close_agent(&parent.session_id, &child_agent_id) .await .expect("child should be closable so live handle disappears"); @@ -508,7 +500,16 @@ async fn get_subrun_status_falls_back_to_durable_snapshot_with_resolved_limits() let auth_sessions = std::sync::Arc::new(AuthSessionManager::default()); auth_sessions.issue_test_token("browser-token"); let app = build_api_router().with_state(AppState { - app: std::sync::Arc::clone(&reloaded_runtime.app), + agent_api: std::sync::Arc::clone(&reloaded_runtime.agent_api), + agent_control: std::sync::Arc::clone(&reloaded_runtime.agent_control), + config: std::sync::Arc::clone(&reloaded_runtime.config), + session_catalog: std::sync::Arc::clone(&reloaded_runtime.session_catalog), + profiles: std::sync::Arc::clone(&reloaded_runtime.profiles), + subagent_executor: std::sync::Arc::clone(&reloaded_runtime.subagent_executor), + mcp_service: std::sync::Arc::clone(&reloaded_runtime.mcp_service), + skill_catalog: std::sync::Arc::clone(&reloaded_runtime.skill_catalog), + resource_catalog: std::sync::Arc::clone(&reloaded_runtime.resource_catalog), + mode_catalog: std::sync::Arc::clone(&reloaded_runtime.mode_catalog), governance: std::sync::Arc::clone(&reloaded_runtime.governance), auth_sessions, bootstrap_auth: BootstrapAuth::new( @@ -545,7 +546,7 @@ async fn get_subrun_status_falls_back_to_durable_snapshot_with_resolved_limits() payload .resolved_limits .expect("durable fallback should expose resolved limits"), - astrcode_protocol::http::ResolvedExecutionLimitsDto + astrcode_protocol::http::ResolvedExecutionLimitsDto {} ); } @@ -593,11 +594,11 @@ async fn scoped_agent_profile_watch_refreshes_profiles_without_restart() { let scoped_working_dir = project.path().display().to_string(); write_agent_profile(project.path(), "reviewer", "初始描述"); let session = state - .app + .session_catalog .create_session(scoped_working_dir.clone()) .await .expect("session should be created to register watch source"); - let scoped_source = astrcode_application::WatchSource::AgentDefinitions { + let scoped_source = WatchSource::AgentDefinitions { working_dir: session.working_dir.clone(), }; watch @@ -606,9 +607,11 @@ async fn scoped_agent_profile_watch_refreshes_profiles_without_restart() { .expect("scoped watch source should be registered before emitting changes"); let first = state - .app - .list_agent_profiles_for_working_dir(project.path()) - .expect("profiles should resolve"); + .profiles + .resolve(project.path()) + .expect("profiles should resolve") + .as_ref() + .clone(); let first_reviewer = first .iter() .find(|profile| profile.id == "reviewer") @@ -623,9 +626,10 @@ async fn scoped_agent_profile_watch_refreshes_profiles_without_restart() { wait_until(Duration::from_secs(5), || { state - .app - .list_agent_profiles_for_working_dir(project.path()) + .profiles + .resolve(project.path()) .ok() + .map(|profiles| profiles.as_ref().clone()) .and_then(|profiles| { profiles .into_iter() @@ -652,16 +656,20 @@ async fn global_agent_profile_watch_invalidates_scoped_cache_without_restart() { ) .await .expect("server runtime should bootstrap"); - let app = std::sync::Arc::clone(&runtime.app); let _runtime_handles = std::sync::Arc::clone(&runtime.handles); let project = tempfile::tempdir().expect("tempdir should be created"); - app.create_session(project.path().display().to_string()) + runtime + .session_catalog + .create_session(project.path().display().to_string()) .await .expect("session should be created to register watch source"); - let scoped_before = app - .list_agent_profiles_for_working_dir(project.path()) - .expect("scoped profiles should resolve"); + let scoped_before = runtime + .profiles + .resolve(project.path()) + .expect("scoped profiles should resolve") + .as_ref() + .clone(); assert_eq!( scoped_before .iter() @@ -670,7 +678,8 @@ async fn global_agent_profile_watch_invalidates_scoped_cache_without_restart() { .description, "全局初始描述" ); - let global_before = app + let global_before = runtime + .agent_api .list_global_agent_profiles() .expect("global profiles should resolve"); assert_eq!( @@ -685,14 +694,16 @@ async fn global_agent_profile_watch_invalidates_scoped_cache_without_restart() { tokio::time::sleep(Duration::from_millis(150)).await; write_global_agent_profile(context.home_dir(), "watcher-profile", "全局更新描述"); watch.emit( - astrcode_application::WatchSource::GlobalAgentDefinitions, + WatchSource::GlobalAgentDefinitions, vec![".astrcode/agents/watcher-profile.md".to_string()], ); wait_until(Duration::from_secs(5), || { - let scoped_updated = app - .list_agent_profiles_for_working_dir(project.path()) + let scoped_updated = runtime + .profiles + .resolve(project.path()) .ok() + .map(|profiles| profiles.as_ref().clone()) .and_then(|profiles| { profiles .into_iter() @@ -700,7 +711,8 @@ async fn global_agent_profile_watch_invalidates_scoped_cache_without_restart() { .map(|profile| profile.description == "全局更新描述") }) .unwrap_or(false); - let global_updated = app + let global_updated = runtime + .agent_api .list_global_agent_profiles() .ok() .and_then(|profiles| { @@ -721,13 +733,12 @@ async fn get_subrun_status_rejects_mismatched_root_subrun_id() { let (state, _guard) = test_state(None).await; let project = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("session should be created"); state - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), session.session_id.clone(), @@ -759,18 +770,17 @@ async fn close_agent_rejects_cross_session_requests() { let (state, _guard) = test_state(None).await; let project = tempfile::tempdir().expect("tempdir should be created"); let owner_session = state - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("owner session should be created"); let other_session = state - .app + .session_catalog .create_session(project.path().display().to_string()) .await .expect("other session should be created"); state - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), owner_session.session_id.clone(), @@ -797,7 +807,7 @@ async fn close_agent_rejects_cross_session_requests() { assert_eq!(response.status(), StatusCode::NOT_FOUND); assert!( - state.app.kernel().get_handle("root-agent").await.is_some(), + state.agent_control.get_handle("root-agent").await.is_some(), "跨 session 请求不得关闭目标 agent" ); } diff --git a/crates/server/src/tests/composer_routes_tests.rs b/crates/server/src/tests/composer_routes_tests.rs index 4653ec71..161eeae7 100644 --- a/crates/server/src/tests/composer_routes_tests.rs +++ b/crates/server/src/tests/composer_routes_tests.rs @@ -23,7 +23,7 @@ async fn composer_options_require_authentication() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -50,7 +50,7 @@ async fn composer_options_expose_session_scoped_skill_entries() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -108,7 +108,7 @@ async fn composer_options_include_user_claude_skills_for_session_scope() { let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -141,7 +141,7 @@ async fn composer_options_expose_runtime_command_entries() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -179,7 +179,7 @@ async fn composer_options_reject_unknown_kind_filters() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let session = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); diff --git a/crates/server/src/tests/config_routes_tests.rs b/crates/server/src/tests/config_routes_tests.rs index 31497cb6..333f34e1 100644 --- a/crates/server/src/tests/config_routes_tests.rs +++ b/crates/server/src/tests/config_routes_tests.rs @@ -1,4 +1,4 @@ -use astrcode_core::StorageEventPayload; +use astrcode_core::{Phase, SessionId, StorageEventPayload, UserMessageOrigin}; use astrcode_protocol::http::{ CompactSessionResponse, ConfigReloadResponse, PromptAcceptedResponse, }; @@ -11,7 +11,7 @@ use tower::ServiceExt; use crate::{ AUTH_HEADER_NAME, routes::build_api_router, - test_support::{mark_session_running, stored_events_for_session, test_state}, + test_support::{mark_session_running, test_state}, }; async fn json_body(response: axum::http::Response) -> T { @@ -21,6 +21,26 @@ async fn json_body(response: axum::http::Respons serde_json::from_slice(&bytes).expect("response should deserialize") } +async fn submit_prompt_request( + state: &crate::AppState, + session_id: &str, + request: serde_json::Value, +) -> axum::http::Response { + build_api_router() + .with_state(state.clone()) + .oneshot( + Request::builder() + .method("POST") + .uri(format!("/api/sessions/{session_id}/prompts")) + .header(AUTH_HEADER_NAME, "browser-token") + .header("content-type", "application/json") + .body(Body::from(request.to_string())) + .expect("request should be valid"), + ) + .await + .expect("response should be returned") +} + #[tokio::test] async fn config_reload_returns_runtime_status_when_idle() { let (state, _guard) = test_state(None).await; @@ -41,14 +61,14 @@ async fn config_reload_returns_runtime_status_when_idle() { assert_eq!(response.status(), StatusCode::ACCEPTED); let payload: ConfigReloadResponse = json_body(response).await; assert!(!payload.reloaded_at.is_empty()); - assert_eq!(payload.status.runtime_name, "astrcode-application"); + assert_eq!(payload.status.runtime_name, "astrcode-server"); } #[tokio::test] async fn config_reload_rejects_when_session_is_running() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -61,9 +81,9 @@ async fn config_reload_rejects_when_session_is_running() { assert!( !state ._runtime_handles - .session_runtime - .list_running_sessions() - .contains(&session.session_id.clone().into()) + .session_runtime_test_support + .list_running_session_ids() + .contains(&session.session_id) ); mark_session_running(&state, &session.session_id).await; let app = build_api_router().with_state(state); @@ -84,10 +104,10 @@ async fn config_reload_rejects_when_session_is_running() { } #[tokio::test] -async fn compact_route_defers_when_session_is_busy() { +async fn compact_route_accepts_immediately_when_only_previous_busy_flag_is_set() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -100,9 +120,9 @@ async fn compact_route_defers_when_session_is_busy() { assert!( !state ._runtime_handles - .session_runtime - .list_running_sessions() - .contains(&session.session_id.clone().into()) + .session_runtime_test_support + .list_running_session_ids() + .contains(&session.session_id) ); mark_session_running(&state, &session.session_id).await; let app = build_api_router().with_state(state.clone()); @@ -130,19 +150,9 @@ async fn compact_route_defers_when_session_is_busy() { assert_eq!(response.status(), StatusCode::ACCEPTED); let payload: CompactSessionResponse = json_body(response).await; assert!(payload.accepted); - assert!(payload.deferred); - let terminal_facts = state - .app - .terminal_snapshot_facts(&session.session_id) - .await - .expect("terminal facts should reflect pending compact"); - assert!(terminal_facts.control.manual_compact_pending); assert!( - terminal_facts - .slash_candidates - .iter() - .all(|candidate| candidate.id != "compact"), - "pending compact should be observed through terminal discovery facts" + !payload.deferred, + "session runtime busy state alone should not defer host-session compaction" ); } @@ -150,7 +160,7 @@ async fn compact_route_defers_when_session_is_busy() { async fn prompt_route_roundtrips_accepted_execution_control() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -193,7 +203,7 @@ async fn prompt_route_roundtrips_accepted_execution_control() { async fn prompt_route_accepts_structured_skill_invocation() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -236,7 +246,7 @@ async fn prompt_route_accepts_structured_skill_invocation() { async fn prompt_route_rejects_unknown_skill_invocation() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -273,10 +283,10 @@ async fn prompt_route_rejects_unknown_skill_invocation() { } #[tokio::test] -async fn prompt_submission_registers_session_root_agent_context() { +async fn prompt_submission_starts_root_runtime() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -287,50 +297,52 @@ async fn prompt_submission_registers_session_root_agent_context() { .await .expect("session should be created"); - state - .app - .submit_prompt(&session.session_id, "hello".to_string()) - .await - .expect("prompt should be accepted"); + let response = submit_prompt_request( + &state, + &session.session_id, + serde_json::json!({ "text": "hello" }), + ) + .await; + assert_eq!(response.status(), StatusCode::ACCEPTED); let root_status = state - .app - .get_root_agent_status(&session.session_id) - .await - .expect("root status query should succeed") - .expect("ordinary prompt session should register an implicit root agent"); + .agent_control + .query_root_status(&session.session_id) + .await; assert!( - root_status.agent_id.starts_with("root-agent:"), - "implicit root agent id should be session-scoped: {}", - root_status.agent_id + root_status.is_some(), + "prompt route should materialize the root agent and start the runtime path" ); - assert_eq!(root_status.agent_profile, "default"); - - let events = stored_events_for_session(&state, &session.session_id).await; - let user_message = events - .into_iter() - .find(|stored| { - matches!( - stored.event.payload, - StorageEventPayload::UserMessage { .. } - ) - }) - .expect("user message event should exist"); - assert_eq!( - user_message.event.agent.agent_id.as_deref(), - Some(root_status.agent_id.as_str()) + let stored = state + .session_catalog + .replay_stored_events(&SessionId::from(session.session_id.clone())) + .await + .expect("stored events should replay"); + assert!( + stored.iter().any(|stored| matches!( + &stored.event.payload, + StorageEventPayload::UserMessage { content, origin, .. } + if content == "hello" && *origin == UserMessageOrigin::User + )), + "prompt route should persist user input before the runtime finishes" ); - assert_eq!( - user_message.event.agent.agent_profile.as_deref(), - Some("default") + let control = state + .session_catalog + .session_control_state(&SessionId::from(session.session_id.clone())) + .await + .expect("control state should read"); + assert_eq!(control.phase, Phase::Thinking); + assert!( + control.active_turn_id.is_some(), + "accepted prompt should keep input locked while the turn is active" ); } #[tokio::test] -async fn prompt_route_rejects_invalid_execution_control() { +async fn prompt_route_ignores_unknown_execution_control_fields() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") @@ -363,14 +375,22 @@ async fn prompt_route_rejects_invalid_execution_control() { .await .expect("response should be returned"); - assert_eq!(response.status(), StatusCode::BAD_REQUEST); + assert_eq!(response.status(), StatusCode::ACCEPTED); + let payload: PromptAcceptedResponse = json_body(response).await; + assert_eq!( + payload + .accepted_control + .expect("empty control object should round-trip") + .manual_compact, + None + ); } #[tokio::test] async fn compact_route_rejects_manual_compact_false() { let (state, _guard) = test_state(None).await; let session = state - .app + .session_catalog .create_session( tempfile::tempdir() .expect("tempdir") diff --git a/crates/server/src/tests/session_contract_tests.rs b/crates/server/src/tests/session_contract_tests.rs index 9aa52c6c..620218c5 100644 --- a/crates/server/src/tests/session_contract_tests.rs +++ b/crates/server/src/tests/session_contract_tests.rs @@ -1,10 +1,7 @@ -use astrcode_core::{ - AgentEventContext, CancelToken, SpawnAgentParams, ToolContext, - agent::executor::SubAgentExecutor, -}; +use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams, ToolContext}; use axum::{ body::{Body, to_bytes}, - http::{Request, StatusCode}, + http::{Request, Response, StatusCode}, }; use tower::ServiceExt; @@ -17,14 +14,35 @@ use crate::{ // Why: 这些契约测试是 API 接口稳定性的核心保障， // 防止 server 在重构后回退到隐式容错或启发式行为。 +async fn submit_prompt_request( + state: &crate::AppState, + session_id: &str, + request: serde_json::Value, +) -> Response { + build_api_router() + .with_state(state.clone()) + .oneshot( + Request::builder() + .method("POST") + .uri(format!("/api/sessions/{session_id}/prompts")) + .header(AUTH_HEADER_NAME, "browser-token") + .header("content-type", "application/json") + .body(Body::from( + serde_json::to_vec(&request).expect("request should serialize"), + )) + .expect("request should be valid"), + ) + .await + .expect("response should be returned") +} + async fn spawn_test_child_agent( state: &crate::AppState, session_id: &str, working_dir: &std::path::Path, ) -> String { state - .app - .kernel() + .agent_control .register_root_agent( "root-agent".to_string(), session_id.to_string(), @@ -45,8 +63,7 @@ async fn spawn_test_child_agent( )); state - .app - .agent() + .subagent_executor .launch( SpawnAgentParams { r#type: Some("explore".to_string()), @@ -76,7 +93,7 @@ async fn submit_prompt_contract_returns_accepted_shape() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -114,15 +131,17 @@ async fn fork_session_contract_returns_new_session_meta() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); - state - .app - .submit_prompt(&created.session_id, "hello".to_string()) - .await - .expect("prompt should be accepted"); + let submit_response = submit_prompt_request( + &state, + &created.session_id, + serde_json::json!({ "text": "hello" }), + ) + .await; + assert_eq!(submit_response.status(), StatusCode::ACCEPTED); let app = build_api_router().with_state(state); let response = app @@ -154,7 +173,7 @@ async fn fork_session_contract_accepts_completed_turn_id() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -191,7 +210,7 @@ async fn fork_session_contract_rejects_unfinished_turn_id() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -232,7 +251,7 @@ async fn fork_session_contract_rejects_mutually_exclusive_request() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -302,7 +321,7 @@ async fn delete_project_contract_deletes_sessions_for_canonical_working_dir() { let alias = project.path().join("."); let working_dir_query = alias.display().to_string().replace('\\', "/"); let created = state - .app + .session_catalog .create_session(alias.display().to_string()) .await .expect("session should be created"); @@ -322,8 +341,8 @@ async fn delete_project_contract_deletes_sessions_for_canonical_working_dir() { assert_eq!(response.status(), StatusCode::OK); let list = state - .app - .list_sessions() + .session_catalog + .list_session_metas() .await .expect("sessions should list"); assert!( @@ -342,7 +361,7 @@ async fn subrun_status_contract_returns_default_for_missing_subrun() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -392,7 +411,7 @@ async fn subrun_cancel_contract_returns_not_found_for_missing_subrun() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -442,7 +461,7 @@ async fn conversation_snapshot_contract_rejects_invalid_focus() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -489,7 +508,7 @@ async fn subrun_cancel_route_returns_not_found_after_removal() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -510,7 +529,7 @@ async fn subrun_cancel_route_returns_not_found_after_removal() { .await .expect("response should be returned"); - // 旧 cancel route 已删除，统一走 close + // cancel route 已删除，统一走 close。 assert_eq!(response.status(), StatusCode::NOT_FOUND); } @@ -521,7 +540,7 @@ async fn close_agent_route_closes_target_agent_and_returns_closed_ids() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -566,7 +585,7 @@ async fn close_agent_route_accepts_empty_json_body() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); @@ -601,7 +620,7 @@ async fn close_agent_route_returns_not_found_for_unknown_agent() { let (state, _guard) = test_state(None).await; let temp_dir = tempfile::tempdir().expect("tempdir should be created"); let created = state - .app + .session_catalog .create_session(temp_dir.path().display().to_string()) .await .expect("session should be created"); diff --git a/crates/server/src/tests/test_support.rs b/crates/server/src/tests/test_support.rs index 99c35844..d54862bc 100644 --- a/crates/server/src/tests/test_support.rs +++ b/crates/server/src/tests/test_support.rs @@ -5,17 +5,33 @@ use std::{ time::Duration, }; -use astrcode_application::{ApplicationError, WatchEvent, WatchPort, WatchService, WatchSource}; use astrcode_core::{ - AgentEventContext, EventTranslator, SessionId, StorageEvent, StorageEventPayload, - TurnTerminalKind, UserMessageOrigin, + AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, + DeleteProjectResult, ExecutionAccepted, InputBatchAckedPayload, InputBatchStartedPayload, + InputDiscardedPayload, InputQueuedPayload, LlmMessage, ModeId, PromptDeclaration, + ResolvedRuntimeConfig, SessionId, SessionMeta, SkillCatalog, StorageEvent, StorageEventPayload, + StoredEvent, TaskSnapshot, TurnId, TurnTerminalKind, UserMessageOrigin, }; +use astrcode_host_session::{SessionCatalogEvent, SessionControlStateSnapshot, SessionModeState}; +use async_trait::async_trait; use tokio::sync::broadcast; use crate::{ - AppState, FrontendBuild, + AgentSessionPort, AppAgentPromptSubmission, AppState, FrontendBuild, RecoverableParentDelivery, + SessionTurnOutcomeSummary, + application_error_bridge::ServerRouteError, auth::{AuthSessionManager, BootstrapAuth}, bootstrap::{ServerBootstrapOptions, bootstrap_server_runtime_with_options}, + conversation_read_model::{ + ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionReplay, + SessionTranscriptSnapshot, + }, + ports::{ + AppSessionPort, DurableSubRunStatusSummary, SessionObserveSnapshot, + SessionTurnTerminalState, + }, + session_use_cases::SessionForkSelector, + watch_service::{WatchEvent, WatchPort, WatchService, WatchSource}, }; pub(crate) struct ServerTestContext { @@ -114,7 +130,7 @@ impl WatchPort for ManualWatchPort { &self, sources: Vec, tx: broadcast::Sender, - ) -> Result<(), ApplicationError> { + ) -> Result<(), ServerRouteError> { *self .tx .lock() @@ -127,7 +143,7 @@ impl WatchPort for ManualWatchPort { Ok(()) } - fn stop_all(&self) -> Result<(), ApplicationError> { + fn stop_all(&self) -> Result<(), ServerRouteError> { *self .tx .lock() @@ -139,7 +155,7 @@ impl WatchPort for ManualWatchPort { Ok(()) } - fn add_source(&self, source: WatchSource) -> Result<(), ApplicationError> { + fn add_source(&self, source: WatchSource) -> Result<(), ServerRouteError> { self.sources .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) @@ -147,7 +163,7 @@ impl WatchPort for ManualWatchPort { Ok(()) } - fn remove_source(&self, source: &WatchSource) -> Result<(), ApplicationError> { + fn remove_source(&self, source: &WatchSource) -> Result<(), ServerRouteError> { self.sources .lock() .unwrap_or_else(|poisoned| poisoned.into_inner()) @@ -156,6 +172,409 @@ impl WatchPort for ManualWatchPort { } } +fn unimplemented_for_test(area: &str) -> ! { + panic!("not used in {area}") +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct RecordedPromptSubmission { + pub(crate) session_id: String, + pub(crate) text: String, + pub(crate) prompt_declarations: Vec, + pub(crate) injected_messages: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct RecordedModeSwitch { + pub(crate) session_id: String, + pub(crate) from: ModeId, + pub(crate) to: ModeId, +} + +#[derive(Debug)] +#[allow(dead_code)] +pub(crate) struct StubSessionPort { + pub(crate) stored_events: Vec, + pub(crate) working_dir: Option, + pub(crate) control_state: Option, + pub(crate) active_task_snapshot: Arc>>, + pub(crate) mode_state: Arc>>, + pub(crate) switch_mode_error: Arc>>, + pub(crate) recorded_submissions: Arc>>, + pub(crate) recorded_mode_switches: Arc>>, +} + +impl Default for StubSessionPort { + fn default() -> Self { + Self { + stored_events: Vec::new(), + working_dir: None, + control_state: None, + active_task_snapshot: Arc::new(Mutex::new(None)), + mode_state: Arc::new(Mutex::new(None)), + switch_mode_error: Arc::new(Mutex::new(None)), + recorded_submissions: Arc::new(Mutex::new(Vec::new())), + recorded_mode_switches: Arc::new(Mutex::new(Vec::new())), + } + } +} + +#[async_trait] +impl AppSessionPort for StubSessionPort { + fn subscribe_catalog_events(&self) -> broadcast::Receiver { + let (_tx, rx) = broadcast::channel(1); + rx + } + + async fn list_session_metas(&self) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn create_session(&self, _working_dir: String) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn fork_session( + &self, + _session_id: &str, + _selector: SessionForkSelector, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn delete_session(&self, _session_id: &str) -> astrcode_core::Result<()> { + unimplemented_for_test("server test stub") + } + + async fn delete_project( + &self, + _working_dir: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn get_session_working_dir(&self, _session_id: &str) -> astrcode_core::Result { + Ok(self.working_dir.clone().unwrap_or_else(|| ".".to_string())) + } + + async fn submit_prompt_for_agent( + &self, + session_id: &str, + text: String, + _runtime: ResolvedRuntimeConfig, + submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + self.recorded_submissions + .lock() + .expect("submission record lock should work") + .push(RecordedPromptSubmission { + session_id: session_id.to_string(), + text, + prompt_declarations: submission.prompt_declarations, + injected_messages: submission.injected_messages, + }); + Ok(ExecutionAccepted { + session_id: SessionId::from(session_id.to_string()), + turn_id: TurnId::from("turn-stub".to_string()), + agent_id: None, + branched_from_session_id: None, + }) + } + + async fn interrupt_session(&self, _session_id: &str) -> astrcode_core::Result<()> { + unimplemented_for_test("server test stub") + } + + async fn compact_session( + &self, + _session_id: &str, + _runtime: ResolvedRuntimeConfig, + _instructions: Option, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn session_transcript_snapshot( + &self, + _session_id: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn conversation_snapshot( + &self, + _session_id: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn session_control_state( + &self, + _session_id: &str, + ) -> astrcode_core::Result { + Ok(self + .control_state + .clone() + .unwrap_or(SessionControlStateSnapshot { + phase: astrcode_core::Phase::Idle, + active_turn_id: None, + manual_compact_pending: false, + compacting: false, + last_compact_meta: None, + current_mode_id: ModeId::code(), + last_mode_changed_at: None, + })) + } + + async fn active_task_snapshot( + &self, + _session_id: &str, + _owner: &str, + ) -> astrcode_core::Result> { + Ok(self + .active_task_snapshot + .lock() + .expect("active task snapshot lock should work") + .clone()) + } + + async fn session_mode_state( + &self, + _session_id: &str, + ) -> astrcode_core::Result { + Ok(self + .mode_state + .lock() + .expect("mode state lock should work") + .clone() + .unwrap_or(SessionModeState { + current_mode_id: ModeId::code(), + last_mode_changed_at: None, + })) + } + + async fn switch_mode( + &self, + session_id: &str, + from: ModeId, + to: ModeId, + ) -> astrcode_core::Result { + if let Some(message) = self + .switch_mode_error + .lock() + .expect("mode switch error lock should work") + .clone() + { + return Err(AstrError::Internal(message)); + } + self.recorded_mode_switches + .lock() + .expect("mode switch record lock should work") + .push(RecordedModeSwitch { + session_id: session_id.to_string(), + from: from.clone(), + to: to.clone(), + }); + *self.mode_state.lock().expect("mode state lock should work") = Some(SessionModeState { + current_mode_id: to.clone(), + last_mode_changed_at: None, + }); + Ok(StoredEvent { + storage_seq: 1, + event: StorageEvent { + turn_id: None, + agent: AgentEventContext::default(), + payload: StorageEventPayload::ModeChanged { + from, + to, + timestamp: chrono::Utc::now(), + }, + }, + }) + } + + async fn session_child_nodes( + &self, + _session_id: &str, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn session_stored_events( + &self, + _session_id: &str, + ) -> astrcode_core::Result> { + Ok(self.stored_events.clone()) + } + + async fn durable_subrun_status_snapshot( + &self, + _parent_session_id: &str, + _requested_subrun_id: &str, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn session_replay( + &self, + _session_id: &str, + _last_event_id: Option<&str>, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn conversation_stream_replay( + &self, + _session_id: &str, + _last_event_id: Option<&str>, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } +} + +#[async_trait] +impl AgentSessionPort for StubSessionPort { + async fn create_child_session( + &self, + _working_dir: &str, + _parent_session_id: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn submit_prompt_for_agent_with_submission( + &self, + _session_id: &str, + _text: String, + _runtime: ResolvedRuntimeConfig, + _submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn try_submit_prompt_for_agent_with_turn_id( + &self, + _session_id: &str, + _turn_id: TurnId, + _text: String, + _runtime: ResolvedRuntimeConfig, + _submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn submit_queued_inputs_for_agent_with_turn_id( + &self, + _session_id: &str, + _turn_id: TurnId, + _queued_inputs: Vec, + _runtime: ResolvedRuntimeConfig, + _submission: AppAgentPromptSubmission, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn append_agent_input_queued( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _payload: InputQueuedPayload, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn append_agent_input_discarded( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _payload: InputDiscardedPayload, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn append_agent_input_batch_started( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _payload: InputBatchStartedPayload, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn append_agent_input_batch_acked( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _payload: InputBatchAckedPayload, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn append_child_session_notification( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _notification: astrcode_core::ChildSessionNotification, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn append_agent_collaboration_fact( + &self, + _session_id: &str, + _turn_id: &str, + _agent: AgentEventContext, + _fact: AgentCollaborationFact, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn pending_delivery_ids_for_agent( + &self, + _session_id: &str, + _agent_id: &str, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn recoverable_parent_deliveries( + &self, + _parent_session_id: &str, + ) -> astrcode_core::Result> { + unimplemented_for_test("server test stub") + } + + async fn observe_agent_session( + &self, + _open_session_id: &str, + _target_agent_id: &str, + _lifecycle_status: AgentLifecycleStatus, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn project_turn_outcome( + &self, + _session_id: &str, + _turn_id: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } + + async fn wait_for_turn_terminal_snapshot( + &self, + _session_id: &str, + _turn_id: &str, + ) -> astrcode_core::Result { + unimplemented_for_test("server test stub") + } +} + pub(crate) async fn test_state( frontend_build: Option, ) -> (AppState, ServerTestContext) { @@ -178,14 +597,32 @@ pub(crate) async fn test_state_with_options( let runtime = bootstrap_server_runtime_with_options(options) .await .expect("server runtime should bootstrap in tests"); - let app = Arc::clone(&runtime.app); + let agent_api = Arc::clone(&runtime.agent_api); + let agent_control = Arc::clone(&runtime.agent_control); + let config = Arc::clone(&runtime.config); + let session_catalog = Arc::clone(&runtime.session_catalog); + let profiles = Arc::clone(&runtime.profiles); + let subagent_executor = Arc::clone(&runtime.subagent_executor); + let mcp_service = Arc::clone(&runtime.mcp_service); + let skill_catalog: Arc = Arc::clone(&runtime.skill_catalog); + let resource_catalog = Arc::clone(&runtime.resource_catalog); + let mode_catalog = Arc::clone(&runtime.mode_catalog); let governance = Arc::clone(&runtime.governance); let auth_sessions = Arc::new(AuthSessionManager::default()); auth_sessions.issue_test_token("browser-token"); ( AppState { - app, + agent_api, + agent_control, + config, + session_catalog, + profiles, + subagent_executor, + mcp_service, + skill_catalog, + resource_catalog, + mode_catalog, governance, auth_sessions, bootstrap_auth: BootstrapAuth::new( @@ -206,29 +643,12 @@ pub(crate) async fn test_state_with_options( } async fn append_root_event(state: &crate::AppState, session_id: &str, event: StorageEvent) { - let session_state = state + state ._runtime_handles - .session_runtime - .get_session_state(&SessionId::from(session_id.to_string())) - .await - .expect("session state should load"); - let mut translator = EventTranslator::new( - session_state - .current_phase() - .expect("session phase should be readable"), - ); - let stored = session_state - .writer - .clone() - .append(event) + .session_runtime_test_support + .append_event(session_id, event) .await .expect("event should append"); - let records = session_state - .translate_store_and_cache(&stored, &mut translator) - .expect("event should translate"); - for record in records { - let _ = session_state.broadcaster.send(record); - } } pub(crate) async fn seed_completed_root_turn( @@ -307,20 +727,8 @@ pub(crate) async fn seed_unfinished_root_turn( pub(crate) async fn mark_session_running(state: &crate::AppState, session_id: &str) { state ._runtime_handles - .session_runtime + .session_runtime_test_support .prepare_test_turn_runtime(session_id, "test-running-turn") .await .expect("session should enter running state"); } - -pub(crate) async fn stored_events_for_session( - state: &crate::AppState, - session_id: &str, -) -> Vec { - state - ._runtime_handles - .session_runtime - .replay_stored_events(&SessionId::from(session_id.to_string())) - .await - .expect("events should replay") -} diff --git a/crates/server/src/tool_capability_invoker.rs b/crates/server/src/tool_capability_invoker.rs new file mode 100644 index 00000000..3825e7bf --- /dev/null +++ b/crates/server/src/tool_capability_invoker.rs @@ -0,0 +1,215 @@ +//! server-owned Tool -> CapabilityInvoker bridge。 +//! +//! Why: `server` 需要把 builtin / agent tools 注册到 capability surface。 + +use std::sync::Arc; + +use astrcode_core::{ + AgentEventContext, AstrError, BoundModeToolContractSnapshot, CancelToken, CapabilityContext, + CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, ExecutionOwner, Result, + SessionId, Tool, ToolContext, ToolEventSink, ToolOutputDelta, +}; +use async_trait::async_trait; +use serde_json::Value; +use tokio::sync::mpsc::UnboundedSender; + +const DEFAULT_TOOL_CAPABILITY_PROFILE: &str = "coding"; + +pub(crate) struct ToolCapabilityInvoker { + tool: Arc, + capability_spec: CapabilitySpec, +} + +impl ToolCapabilityInvoker { + pub(crate) fn new(tool: Arc) -> Result { + let capability_spec = tool.capability_spec().map_err(|error| { + let fallback_name = tool.definition().name; + AstrError::Validation(format!( + "invalid tool capability spec '{}': {}", + display_tool_label(&fallback_name), + error + )) + })?; + capability_spec.validate().map_err(|error| { + AstrError::Validation(format!( + "invalid tool capability spec '{}': {}", + display_tool_label(capability_spec.name.as_str()), + error + )) + })?; + Ok(Self { + tool, + capability_spec, + }) + } +} + +#[async_trait] +impl CapabilityInvoker for ToolCapabilityInvoker { + fn capability_spec(&self) -> CapabilitySpec { + self.capability_spec.clone() + } + + async fn invoke( + &self, + payload: Value, + ctx: &CapabilityContext, + ) -> Result { + let tool_ctx = tool_context_from_capability_context(ctx); + let result = self + .tool + .execute( + ctx.request_id + .clone() + .unwrap_or_else(|| "capability-call".to_string()), + payload, + &tool_ctx, + ) + .await; + + match result { + Ok(result) => { + let common = result.common(); + Ok(CapabilityExecutionResult::from_common( + result.tool_name, + result.ok, + Value::String(result.output), + result.continuation, + common, + )) + }, + Err(error) => Ok(CapabilityExecutionResult::failure( + self.capability_spec.name.to_string(), + error.to_string(), + Value::Null, + )), + } + } +} + +#[derive(Clone)] +struct ToolBridgeContext { + session_id: SessionId, + working_dir: std::path::PathBuf, + cancel: CancelToken, + turn_id: Option, + request_id: Option, + agent: AgentEventContext, + current_mode_id: astrcode_core::ModeId, + bound_mode_tool_contract: Option, + execution_owner: Option, + tool_output_sender: Option>, + event_sink: Option>, +} + +impl ToolBridgeContext { + fn from_tool_context(ctx: &ToolContext) -> Self { + Self { + session_id: ctx.session_id().into(), + working_dir: ctx.working_dir().to_path_buf(), + cancel: ctx.cancel().clone(), + turn_id: ctx.turn_id().map(ToString::to_string), + request_id: None, + agent: ctx.agent_context().clone(), + current_mode_id: ctx.current_mode_id().clone(), + bound_mode_tool_contract: ctx.bound_mode_tool_contract().cloned(), + execution_owner: ctx.execution_owner().cloned(), + tool_output_sender: ctx.tool_output_sender(), + event_sink: ctx.event_sink(), + } + } + + fn from_capability_context(ctx: &CapabilityContext) -> Self { + Self { + session_id: ctx.session_id.clone(), + working_dir: ctx.working_dir.clone(), + cancel: ctx.cancel.clone(), + turn_id: ctx.turn_id.clone(), + request_id: ctx.request_id.clone(), + agent: ctx.agent.clone(), + current_mode_id: ctx.current_mode_id.clone(), + bound_mode_tool_contract: ctx.bound_mode_tool_contract.clone(), + execution_owner: ctx.execution_owner.clone(), + tool_output_sender: ctx.tool_output_sender.clone(), + event_sink: ctx.event_sink.clone(), + } + } + + fn into_capability_context(self, request_id: Option) -> CapabilityContext { + CapabilityContext { + request_id, + trace_id: None, + session_id: self.session_id, + working_dir: self.working_dir.clone(), + cancel: self.cancel, + turn_id: self.turn_id, + agent: self.agent, + current_mode_id: self.current_mode_id, + bound_mode_tool_contract: self.bound_mode_tool_contract, + execution_owner: self.execution_owner, + profile: default_tool_capability_profile().to_string(), + profile_context: default_tool_capability_profile_context(&self.working_dir), + metadata: Value::Null, + tool_output_sender: self.tool_output_sender, + event_sink: self.event_sink, + } + } + + fn into_tool_context(self) -> ToolContext { + let mut tool_ctx = ToolContext::new(self.session_id, self.working_dir, self.cancel); + if let Some(turn_id) = self.turn_id { + tool_ctx = tool_ctx.with_turn_id(turn_id); + } + if let Some(tool_call_id) = self.request_id { + tool_ctx = tool_ctx.with_tool_call_id(tool_call_id); + } + tool_ctx = tool_ctx.with_agent_context(self.agent); + tool_ctx = tool_ctx.with_current_mode_id(self.current_mode_id); + if let Some(snapshot) = self.bound_mode_tool_contract { + tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot); + } + if let Some(sender) = self.tool_output_sender { + tool_ctx = tool_ctx.with_tool_output_sender(sender); + } + if let Some(event_sink) = self.event_sink { + tool_ctx = tool_ctx.with_event_sink(event_sink); + } + if let Some(owner) = self.execution_owner { + tool_ctx = tool_ctx.with_execution_owner(owner); + } + tool_ctx + } +} + +pub(crate) fn tool_context_from_capability_context(ctx: &CapabilityContext) -> ToolContext { + ToolBridgeContext::from_capability_context(ctx).into_tool_context() +} + +pub(crate) fn capability_context_from_tool_context( + ctx: &ToolContext, + request_id: Option, +) -> CapabilityContext { + ToolBridgeContext::from_tool_context(ctx).into_capability_context(request_id) +} + +fn display_tool_label(name: &str) -> &str { + let trimmed = name.trim(); + if trimmed.is_empty() { + "" + } else { + trimmed + } +} + +fn default_tool_capability_profile() -> &'static str { + DEFAULT_TOOL_CAPABILITY_PROFILE +} + +fn default_tool_capability_profile_context(working_dir: &std::path::Path) -> Value { + let working_dir = working_dir.to_string_lossy().into_owned(); + serde_json::json!({ + "workingDir": working_dir, + "repoRoot": working_dir, + "approvalMode": "inherit" + }) +} diff --git a/crates/server/src/view_projection.rs b/crates/server/src/view_projection.rs new file mode 100644 index 00000000..2cdbcd68 --- /dev/null +++ b/crates/server/src/view_projection.rs @@ -0,0 +1,193 @@ +//! server-owned HTTP projection inputs。 +//! +//! 负责把共享 runtime/config 真相下沉为 server 自己的投影输入， +//! 避免路由和 mapper 直接依赖 `application` 的 summary 类型。 + +use astrcode_core::{CapabilitySpec, Config, InvocationMode, RuntimeObservabilitySnapshot}; +use astrcode_plugin_host::{PluginEntry, PluginHealth, PluginState}; + +use crate::{config_mode_helpers, governance_service::ServerGovernanceSnapshot}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerConfigProfileSummary { + pub name: String, + pub base_url: String, + pub api_key_preview: String, + pub models: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerResolvedConfigSummary { + pub active_profile: String, + pub active_model: String, + pub profiles: Vec, + pub warning: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerRuntimeCapabilitySummary { + pub name: String, + pub kind: String, + pub description: String, + pub profiles: Vec, + pub streaming: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerRuntimePluginSummary { + pub name: String, + pub version: String, + pub description: String, + pub state: PluginState, + pub health: PluginHealth, + pub failure_count: u32, + pub failure: Option, + pub warnings: Vec, + pub last_checked_at: Option, + pub capabilities: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct ServerResolvedRuntimeStatusSummary { + pub runtime_name: String, + pub runtime_kind: String, + pub loaded_session_count: usize, + pub running_session_ids: Vec, + pub plugin_search_paths: Vec, + pub metrics: RuntimeObservabilitySnapshot, + pub capabilities: Vec, + pub plugins: Vec, +} + +pub(crate) fn resolve_server_config_summary( + config: &Config, +) -> Result { + if config.profiles.is_empty() { + return Ok(ServerResolvedConfigSummary { + active_profile: String::new(), + active_model: String::new(), + profiles: Vec::new(), + warning: Some("no profiles configured".to_string()), + }); + } + + let profiles = config + .profiles + .iter() + .map(|profile| ServerConfigProfileSummary { + name: profile.name.clone(), + base_url: profile.base_url.clone(), + api_key_preview: api_key_preview(profile.api_key.as_deref()), + models: profile + .models + .iter() + .map(|model| model.id.clone()) + .collect(), + }) + .collect(); + + let selection = config_mode_helpers::resolve_active_selection( + &config.active_profile, + &config.active_model, + &config.profiles, + ) + .map_err(|error| error.to_string())?; + + Ok(ServerResolvedConfigSummary { + active_profile: selection.active_profile, + active_model: selection.active_model, + profiles, + warning: selection.warning, + }) +} + +pub(crate) fn resolve_server_runtime_status_summary( + snapshot: ServerGovernanceSnapshot, +) -> ServerResolvedRuntimeStatusSummary { + ServerResolvedRuntimeStatusSummary { + runtime_name: snapshot.runtime_name, + runtime_kind: snapshot.runtime_kind, + loaded_session_count: snapshot.loaded_session_count, + running_session_ids: snapshot.running_session_ids, + plugin_search_paths: snapshot + .plugin_search_paths + .into_iter() + .map(|path| path.display().to_string()) + .collect(), + metrics: snapshot.metrics, + capabilities: snapshot + .capabilities + .into_iter() + .map(resolve_runtime_capability_summary) + .collect(), + plugins: snapshot + .plugins + .into_iter() + .map(resolve_runtime_plugin_summary) + .collect(), + } +} + +fn resolve_runtime_capability_summary(spec: CapabilitySpec) -> ServerRuntimeCapabilitySummary { + ServerRuntimeCapabilitySummary { + name: spec.name.to_string(), + kind: spec.kind.as_str().to_string(), + description: spec.description, + profiles: spec.profiles, + streaming: matches!(spec.invocation_mode, InvocationMode::Streaming), + } +} + +fn resolve_runtime_plugin_summary(entry: PluginEntry) -> ServerRuntimePluginSummary { + ServerRuntimePluginSummary { + name: entry.manifest.name, + version: entry.manifest.version, + description: entry.manifest.description, + state: entry.state, + health: entry.health, + failure_count: entry.failure_count, + failure: entry.failure, + warnings: entry.warnings, + last_checked_at: entry.last_checked_at, + capabilities: entry + .capabilities + .into_iter() + .map(resolve_runtime_capability_summary) + .collect(), + } +} + +fn api_key_preview(api_key: Option<&str>) -> String { + match api_key.map(str::trim) { + None | Some("") => "未配置".to_string(), + Some(value) if value.starts_with("env:") => { + let env_name = value.trim_start_matches("env:").trim(); + if env_name.is_empty() { + "未配置".to_string() + } else { + format!("环境变量: {}", env_name) + } + }, + Some(value) if value.starts_with("literal:") => { + let key = value.trim_start_matches("literal:").trim(); + masked_key_preview(key) + }, + Some(value) + if config_mode_helpers::is_env_var_name(value) && std::env::var_os(value).is_some() => + { + format!("环境变量: {}", value) + }, + Some(value) => masked_key_preview(value), + } +} + +fn masked_key_preview(value: &str) -> String { + let char_starts: Vec = value.char_indices().map(|(index, _)| index).collect(); + + if char_starts.len() <= 4 { + "****".to_string() + } else { + let suffix_start = char_starts[char_starts.len() - 4]; + format!("****{}", &value[suffix_start..]) + } +} diff --git a/crates/server/src/watch_service.rs b/crates/server/src/watch_service.rs new file mode 100644 index 00000000..b410e68a --- /dev/null +++ b/crates/server/src/watch_service.rs @@ -0,0 +1,75 @@ +//! server-owned 文件变更监听 contract。 +//! +//! watch source / event / port / service 类型不经由 `application` 暴露。 + +use std::sync::Arc; + +use tokio::sync::broadcast; + +use crate::application_error_bridge::ServerRouteError; + +const WATCH_EVENT_CAPACITY: usize = 256; + +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub(crate) enum WatchSource { + GlobalAgentDefinitions, + AgentDefinitions { working_dir: String }, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct WatchEvent { + pub source: WatchSource, + pub affected_paths: Vec, +} + +pub(crate) trait WatchPort: Send + Sync { + fn start_watch( + &self, + sources: Vec, + tx: broadcast::Sender, + ) -> Result<(), ServerRouteError>; + + fn stop_all(&self) -> Result<(), ServerRouteError>; + + fn add_source(&self, source: WatchSource) -> Result<(), ServerRouteError>; + + fn remove_source(&self, source: &WatchSource) -> Result<(), ServerRouteError>; +} + +pub(crate) struct WatchService { + port: Arc, + tx: broadcast::Sender, +} + +impl WatchService { + pub(crate) fn new(port: Arc) -> Self { + let (tx, _) = broadcast::channel(WATCH_EVENT_CAPACITY); + Self { port, tx } + } + + pub(crate) fn subscribe(&self) -> broadcast::Receiver { + self.tx.subscribe() + } + + pub(crate) fn start_watch(&self, sources: Vec) -> Result<(), ServerRouteError> { + self.port.start_watch(sources, self.tx.clone()) + } + + pub(crate) fn stop_all(&self) -> Result<(), ServerRouteError> { + self.port.stop_all() + } + + pub(crate) fn add_source(&self, source: WatchSource) -> Result<(), ServerRouteError> { + self.port.add_source(source) + } + + pub(crate) fn remove_source(&self, source: &WatchSource) -> Result<(), ServerRouteError> { + self.port.remove_source(source) + } +} + +impl std::fmt::Debug for WatchService { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("WatchService").finish_non_exhaustive() + } +} diff --git a/crates/session-runtime/src/actor/mod.rs b/crates/session-runtime/src/actor/mod.rs deleted file mode 100644 index ea8809c2..00000000 --- a/crates/session-runtime/src/actor/mod.rs +++ /dev/null @@ -1,395 +0,0 @@ -//! Session actor 与 live truth。 -//! -//! 边界约束： -//! - 这里只负责推进所需的 live state 与 durable writer 桥接 -//! - 不负责 observe 视图拼装 -//! - 不负责外部订阅协议映射 - -use std::sync::Arc; - -use astrcode_core::{ - AgentId, AgentStateProjector, EventStore, EventTranslator, Phase, RecoveredSessionState, - SessionId, StorageEvent, StoredEvent, TurnId, normalize_recovered_phase, replay_records, -}; -#[cfg(test)] -use astrcode_core::{EventLogWriter, StoreResult}; - -use crate::{ - state::{SessionSnapshot, SessionState, SessionWriter}, - turn::TurnRuntimeState, -}; - -/// 空操作 EventLogWriter，仅用于测试态 actor。 -#[cfg(test)] -struct NopEventLogWriter; - -#[cfg(test)] -impl EventLogWriter for NopEventLogWriter { - fn append(&mut self, _event: &astrcode_core::StorageEvent) -> StoreResult { - // 空操作 writer 不持久化，但返回一个虚拟序号以满足调用方契约 - Ok(StoredEvent { - storage_seq: 0, - event: _event.clone(), - }) - } -} - -/// 会话 actor 持有完整的会话真相，不直接持有 tool/llm/prompt/resource provider。 -#[derive(Debug)] -pub struct SessionActor { - state: Arc, - turn_runtime: TurnRuntimeState, - session_id: SessionId, - working_dir: String, -} - -impl SessionActor { - /// 创建一个带 durable writer 的 actor。 - #[cfg(test)] - pub async fn new_persistent( - session_id: SessionId, - working_dir: impl Into, - root_agent_id: AgentId, - event_store: Arc, - ) -> astrcode_core::Result { - Self::new_persistent_with_lineage( - session_id, - working_dir, - root_agent_id, - event_store, - None, - None, - ) - .await - } - - /// 创建一个带 durable writer 的 actor，并写入 lineage 元数据。 - pub async fn new_persistent_with_lineage( - session_id: SessionId, - working_dir: impl Into, - _root_agent_id: AgentId, - event_store: Arc, - parent_session_id: Option, - parent_storage_seq: Option, - ) -> astrcode_core::Result { - let working_dir = working_dir.into(); - let writer = Arc::new(SessionWriter::from_event_store( - Arc::clone(&event_store), - session_id.clone(), - )); - - let session_start = StorageEvent { - turn_id: None, - agent: astrcode_core::AgentEventContext::default(), - payload: astrcode_core::StorageEventPayload::SessionStart { - session_id: session_id.to_string(), - timestamp: chrono::Utc::now(), - working_dir: working_dir.clone(), - parent_session_id, - parent_storage_seq, - }, - }; - let stored = event_store.append(&session_id, &session_start).await?; - let mut translator = EventTranslator::new(Phase::Idle); - let recent_records = translator.translate(&stored); - let mut projector = astrcode_core::AgentStateProjector::default(); - projector.apply(&stored.event); - let state = SessionState::new(Phase::Idle, writer, projector, recent_records, vec![stored]); - - Ok(Self { - state: Arc::new(state), - turn_runtime: TurnRuntimeState::new(), - session_id, - working_dir, - }) - } - - /// 从 durable 事件日志重建一个会话 actor。 - /// - /// Why: `session-runtime` 需要在 application 不持有 shadow state 的前提下， - /// 按需把任意 session 从持久化存储恢复成可执行的 live actor。 - pub fn from_replay( - session_id: SessionId, - working_dir: impl Into, - _root_agent_id: AgentId, - event_store: Arc, - stored_events: Vec, - ) -> astrcode_core::Result { - let working_dir = working_dir.into(); - let writer = Arc::new(SessionWriter::from_event_store( - event_store, - session_id.clone(), - )); - let mut projector = AgentStateProjector::default(); - for stored in &stored_events { - stored.event.validate().map_err(|error| { - astrcode_core::AstrError::Validation(format!( - "session '{}' contains invalid stored event at storage_seq {}: {}", - session_id, stored.storage_seq, error - )) - })?; - projector.apply(&stored.event); - } - let phase = normalize_recovered_phase(projector.snapshot().phase); - let recent_records = replay_records(&stored_events, None); - let state = SessionState::new(phase, writer, projector, recent_records, stored_events); - - Ok(Self { - state: Arc::new(state), - turn_runtime: TurnRuntimeState::new(), - session_id, - working_dir, - }) - } - - pub fn from_recovery( - session_id: SessionId, - working_dir: impl Into, - root_agent_id: AgentId, - event_store: Arc, - recovered: RecoveredSessionState, - ) -> astrcode_core::Result { - let RecoveredSessionState { - checkpoint, - tail_events, - } = recovered; - let working_dir = working_dir.into(); - let Some(checkpoint) = checkpoint else { - return Self::from_replay( - session_id, - working_dir, - root_agent_id, - event_store, - tail_events, - ); - }; - let writer = Arc::new(SessionWriter::from_event_store( - event_store, - session_id.clone(), - )); - let state = SessionState::from_recovery(writer, &checkpoint, tail_events)?; - - Ok(Self { - state: Arc::new(state), - turn_runtime: TurnRuntimeState::new(), - session_id, - working_dir, - }) - } - - /// 创建一个空闲状态的 actor（无事件历史、无持久化）。 - /// - /// 实际生产中应使用带持久化 writer 的 `new()` 构造路径。 - #[cfg(test)] - pub fn new_idle( - session_id: SessionId, - working_dir: impl Into, - _root_agent_id: AgentId, - ) -> Self { - let writer = Arc::new(SessionWriter::new(Box::new(NopEventLogWriter))); - let state = SessionState::new( - astrcode_core::Phase::Idle, - writer, - astrcode_core::AgentStateProjector::default(), - Vec::new(), - Vec::new(), - ); - Self { - state: Arc::new(state), - turn_runtime: TurnRuntimeState::new(), - session_id, - working_dir: working_dir.into(), - } - } - - /// 返回轻量快照用于 observe。 - pub fn snapshot(&self) -> SessionSnapshot { - let turn_count = self - .state - .snapshot_projected_state() - .map(|s| s.turn_count) - .unwrap_or(0); - let active_turn = self - .turn_runtime - .active_turn_id_snapshot() - .ok() - .flatten() - .map(TurnId::from); - SessionSnapshot { - session_id: self.session_id.clone(), - working_dir: self.working_dir.clone(), - latest_turn_id: active_turn, - turn_count, - } - } - - pub fn state(&self) -> &Arc { - &self.state - } - - pub(crate) fn turn_runtime(&self) -> &TurnRuntimeState { - &self.turn_runtime - } - - pub fn working_dir(&self) -> &str { - &self.working_dir - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, EventStore, InvocationKind, Result, SessionMeta, - SessionTurnAcquireResult, StorageEvent, StorageEventPayload, StoredEvent, - SubRunStorageMode, UserMessageOrigin, - }; - use async_trait::async_trait; - - use super::*; - use crate::state::append_and_broadcast; - - #[derive(Debug, Default)] - struct StubEventStore; - - struct StubTurnLease; - - impl astrcode_core::SessionTurnLease for StubTurnLease {} - - #[async_trait] - impl EventStore for StubEventStore { - async fn ensure_session( - &self, - _session_id: &SessionId, - _working_dir: &std::path::Path, - ) -> Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &SessionId, - event: &StorageEvent, - ) -> Result { - Ok(StoredEvent { - storage_seq: 1, - event: event.clone(), - }) - } - - async fn replay(&self, _session_id: &SessionId) -> Result> { - Ok(Vec::new()) - } - - async fn try_acquire_turn( - &self, - _session_id: &SessionId, - _turn_id: &str, - ) -> Result { - Ok(SessionTurnAcquireResult::Acquired(Box::new(StubTurnLease))) - } - - async fn list_sessions(&self) -> Result> { - Ok(Vec::new()) - } - - async fn list_session_metas(&self) -> Result> { - Ok(Vec::new()) - } - - async fn delete_session(&self, _session_id: &SessionId) -> Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> Result { - Ok(astrcode_core::DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } - } - - #[tokio::test] - async fn new_persistent_primes_projector_with_session_start_for_child_sessions() { - let actor = SessionActor::new_persistent( - SessionId::from("session-child".to_string()), - "/tmp/project", - AgentId::from("root-agent".to_string()), - Arc::new(StubEventStore), - ) - .await - .expect("actor should be created"); - - let child_agent = AgentEventContext::sub_run( - "agent-child", - "turn-parent", - "explore", - "subrun-1", - None, - SubRunStorageMode::IndependentSession, - Some("session-child".to_string().into()), - ); - let event = StorageEvent { - turn_id: Some("turn-child".to_string()), - agent: child_agent, - payload: StorageEventPayload::UserMessage { - content: "child task".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - }; - - let mut translator = EventTranslator::new(Phase::Idle); - append_and_broadcast(actor.state(), &event, &mut translator) - .await - .expect("child event should append"); - - let projected = actor - .state() - .snapshot_projected_state() - .expect("snapshot should work"); - assert!(matches!( - projected.messages.as_slice(), - [astrcode_core::LlmMessage::User { content, .. }] if content == "child task" - )); - } - - #[test] - fn from_replay_rejects_invalid_stored_events() { - let malformed = StoredEvent { - storage_seq: 7, - event: StorageEvent { - turn_id: Some("turn-child".to_string()), - agent: AgentEventContext { - agent_id: Some("agent-child".to_string().into()), - parent_turn_id: Some("turn-root".to_string().into()), - agent_profile: Some("explore".to_string()), - sub_run_id: Some("subrun-1".to_string().into()), - parent_sub_run_id: None, - invocation_kind: Some(InvocationKind::SubRun), - storage_mode: Some(SubRunStorageMode::IndependentSession), - child_session_id: None, - }, - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: Some("completed".to_string()), - }, - }, - }; - - let error = SessionActor::from_replay( - SessionId::from("session-parent".to_string()), - "/tmp/project", - AgentId::from("root-agent".to_string()), - Arc::new(StubEventStore), - vec![malformed], - ) - .expect_err("replay should reject malformed stored events"); - - assert!(error.to_string().contains("storage_seq 7")); - assert!(error.to_string().contains("child_session_id")); - } -} diff --git a/crates/session-runtime/src/catalog/mod.rs b/crates/session-runtime/src/catalog/mod.rs deleted file mode 100644 index 67bf362a..00000000 --- a/crates/session-runtime/src/catalog/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Session catalog 事件与生命周期协调。 -//! -//! catalog 事件的 canonical owner 已下沉到 `astrcode_core`； -//! session-runtime 这里只保留 re-export，负责生命周期编排与广播。 - -pub use astrcode_core::SessionCatalogEvent; diff --git a/crates/session-runtime/src/command/input_queue.rs b/crates/session-runtime/src/command/input_queue.rs deleted file mode 100644 index b46e367c..00000000 --- a/crates/session-runtime/src/command/input_queue.rs +++ /dev/null @@ -1,112 +0,0 @@ -use astrcode_core::{ - EventTranslator, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, - InputQueuedPayload, Result, StorageEvent, StorageEventPayload, StoredEvent, -}; - -use crate::{SessionState, state::append_and_broadcast}; - -/// input queue durable 事件追加命令。 -/// -/// 为什么放在 `command`：这是写路径上的命令语义，负责把上层输入变成 durable 事件， -/// 不应继续混在 `state` 的纯投影逻辑里。 -#[derive(Debug, Clone)] -pub enum InputQueueEventAppend { - Queued(InputQueuedPayload), - BatchStarted(InputBatchStartedPayload), - BatchAcked(InputBatchAckedPayload), - Discarded(InputDiscardedPayload), -} - -impl InputQueueEventAppend { - pub(crate) fn into_storage_payload(self) -> StorageEventPayload { - match self { - Self::Queued(payload) => StorageEventPayload::AgentInputQueued { payload }, - Self::BatchStarted(payload) => StorageEventPayload::AgentInputBatchStarted { payload }, - Self::BatchAcked(payload) => StorageEventPayload::AgentInputBatchAcked { payload }, - Self::Discarded(payload) => StorageEventPayload::AgentInputDiscarded { payload }, - } - } -} - -pub async fn append_input_queue_event( - session: &SessionState, - turn_id: &str, - agent: astrcode_core::AgentEventContext, - event: InputQueueEventAppend, - translator: &mut EventTranslator, -) -> Result { - append_and_broadcast( - session, - &StorageEvent { - turn_id: Some(turn_id.to_string()), - agent, - payload: event.into_storage_payload(), - }, - translator, - ) - .await -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentLifecycleStatus, InputBatchAckedPayload, InputBatchStartedPayload, - InputDiscardedPayload, InputQueuedPayload, QueuedInputEnvelope, StorageEventPayload, - }; - - use super::InputQueueEventAppend; - - #[test] - fn input_queue_event_append_maps_to_expected_storage_payload() { - let envelope = QueuedInputEnvelope { - delivery_id: "delivery-1".to_string().into(), - from_agent_id: "agent-parent".to_string(), - to_agent_id: "agent-child".to_string(), - message: "hello".to_string(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Idle, - sender_last_turn_outcome: None, - sender_open_session_id: "session-parent".to_string(), - }; - - assert!(matches!( - InputQueueEventAppend::Queued(InputQueuedPayload { - envelope: envelope.clone(), - }) - .into_storage_payload(), - StorageEventPayload::AgentInputQueued { payload } - if payload.envelope.delivery_id == "delivery-1".into() - )); - assert!(matches!( - InputQueueEventAppend::BatchStarted(InputBatchStartedPayload { - target_agent_id: "agent-child".to_string(), - turn_id: "turn-1".to_string(), - batch_id: "batch-1".to_string(), - delivery_ids: vec!["delivery-1".to_string().into()], - }) - .into_storage_payload(), - StorageEventPayload::AgentInputBatchStarted { payload } - if payload.batch_id == "batch-1" - )); - assert!(matches!( - InputQueueEventAppend::BatchAcked(InputBatchAckedPayload { - target_agent_id: "agent-child".to_string(), - turn_id: "turn-1".to_string(), - batch_id: "batch-1".to_string(), - delivery_ids: vec!["delivery-1".to_string().into()], - }) - .into_storage_payload(), - StorageEventPayload::AgentInputBatchAcked { payload } - if payload.delivery_ids == vec!["delivery-1".to_string().into()] - )); - assert!(matches!( - InputQueueEventAppend::Discarded(InputDiscardedPayload { - target_agent_id: "agent-child".to_string(), - delivery_ids: vec!["delivery-1".to_string().into()], - }) - .into_storage_payload(), - StorageEventPayload::AgentInputDiscarded { payload } - if payload.target_agent_id == "agent-child" - )); - } -} diff --git a/crates/session-runtime/src/command/mod.rs b/crates/session-runtime/src/command/mod.rs deleted file mode 100644 index fcef4da0..00000000 --- a/crates/session-runtime/src/command/mod.rs +++ /dev/null @@ -1,233 +0,0 @@ -mod input_queue; - -use std::path::Path; - -use astrcode_core::{ - AgentCollaborationFact, AgentEventContext, ChildSessionNotification, EventTranslator, - InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, - ModeId, Result, StorageEvent, StorageEventPayload, StoredEvent, -}; -use chrono::Utc; - -pub(crate) use self::input_queue::InputQueueEventAppend; -use self::input_queue::append_input_queue_event; -use crate::{ - SessionRuntime, - state::{append_and_broadcast, checkpoint_if_compacted}, -}; - -pub(crate) struct SessionCommands<'a> { - runtime: &'a SessionRuntime, -} - -impl<'a> SessionCommands<'a> { - pub(crate) fn new(runtime: &'a SessionRuntime) -> Self { - Self { runtime } - } - - pub async fn append_agent_input_queued( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputQueuedPayload, - ) -> Result { - self.append_agent_input_event( - session_id, - turn_id, - agent, - InputQueueEventAppend::Queued(payload), - ) - .await - } - - pub async fn append_agent_input_discarded( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputDiscardedPayload, - ) -> Result { - self.append_agent_input_event( - session_id, - turn_id, - agent, - InputQueueEventAppend::Discarded(payload), - ) - .await - } - - pub async fn append_agent_input_batch_started( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchStartedPayload, - ) -> Result { - self.append_agent_input_event( - session_id, - turn_id, - agent, - InputQueueEventAppend::BatchStarted(payload), - ) - .await - } - - pub async fn append_agent_input_batch_acked( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchAckedPayload, - ) -> Result { - self.append_agent_input_event( - session_id, - turn_id, - agent, - InputQueueEventAppend::BatchAcked(payload), - ) - .await - } - - pub async fn append_child_session_notification( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - notification: ChildSessionNotification, - ) -> Result { - let session_id = - astrcode_core::SessionId::from(crate::state::normalize_session_id(session_id)); - let session_state = self.runtime.query().session_state(&session_id).await?; - let mut translator = EventTranslator::new(session_state.current_phase()?); - append_and_broadcast( - &session_state, - &StorageEvent { - turn_id: Some(turn_id.to_string()), - agent, - payload: StorageEventPayload::ChildSessionNotification { - notification, - timestamp: Some(Utc::now()), - }, - }, - &mut translator, - ) - .await - } - - pub async fn append_agent_collaboration_fact( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - fact: AgentCollaborationFact, - ) -> Result { - let session_id = - astrcode_core::SessionId::from(crate::state::normalize_session_id(session_id)); - let session_state = self.runtime.query().session_state(&session_id).await?; - let mut translator = EventTranslator::new(session_state.current_phase()?); - append_and_broadcast( - &session_state, - &StorageEvent { - turn_id: Some(turn_id.to_string()), - agent, - payload: StorageEventPayload::AgentCollaborationFact { - fact, - timestamp: Some(Utc::now()), - }, - }, - &mut translator, - ) - .await - } - - pub async fn compact_session( - &self, - session_id: &str, - runtime: &astrcode_core::ResolvedRuntimeConfig, - instructions: Option<&str>, - ) -> Result { - let session_id = - astrcode_core::SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - if actor.turn_runtime().is_running() { - actor.turn_runtime().request_manual_compact( - crate::turn::PendingManualCompactRequest { - runtime: runtime.clone(), - instructions: instructions.map(str::to_string), - }, - )?; - return Ok(true); - } - let mut translator = EventTranslator::new(actor.state().current_phase()?); - let compacting_guard = actor.turn_runtime().enter_compacting(); - let built = crate::turn::manual_compact::build_manual_compact_events( - crate::turn::manual_compact::ManualCompactRequest { - gateway: self.runtime.kernel.gateway(), - prompt_facts_provider: self.runtime.prompt_facts_provider.as_ref(), - session_state: actor.state(), - session_id: session_id.as_str(), - working_dir: Path::new(actor.working_dir()), - runtime, - trigger: astrcode_core::CompactTrigger::Manual, - instructions, - }, - ) - .await; - drop(compacting_guard); - if let Some(events) = built? { - let mut persisted = Vec::with_capacity(events.len()); - for event in &events { - persisted.push(append_and_broadcast(actor.state(), event, &mut translator).await?); - } - checkpoint_if_compacted( - &self.runtime.event_store, - &session_id, - actor.state(), - &persisted, - ) - .await; - } - Ok(false) - } - - pub async fn switch_mode( - &self, - session_id: &str, - from: ModeId, - to: ModeId, - ) -> Result { - let session_id = - astrcode_core::SessionId::from(crate::state::normalize_session_id(session_id)); - let session_state = self.runtime.query().session_state(&session_id).await?; - let mut translator = EventTranslator::new(session_state.current_phase()?); - append_and_broadcast( - &session_state, - &StorageEvent { - turn_id: None, - agent: AgentEventContext::default(), - payload: StorageEventPayload::ModeChanged { - from, - to, - timestamp: Utc::now(), - }, - }, - &mut translator, - ) - .await - } - - async fn append_agent_input_event( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - event: InputQueueEventAppend, - ) -> Result { - let session_id = - astrcode_core::SessionId::from(crate::state::normalize_session_id(session_id)); - let session_state = self.runtime.query().session_state(&session_id).await?; - let mut translator = EventTranslator::new(session_state.current_phase()?); - append_input_queue_event(&session_state, turn_id, agent, event, &mut translator).await - } -} diff --git a/crates/session-runtime/src/context_window/compaction/tests.rs b/crates/session-runtime/src/context_window/compaction/tests.rs deleted file mode 100644 index db744637..00000000 --- a/crates/session-runtime/src/context_window/compaction/tests.rs +++ /dev/null @@ -1,574 +0,0 @@ -use super::*; - -fn test_compact_config() -> CompactConfig { - CompactConfig { - keep_recent_turns: 1, - keep_recent_user_messages: 8, - trigger: astrcode_core::CompactTrigger::Manual, - summary_reserve_tokens: 20_000, - max_output_tokens: 20_000, - max_retry_attempts: 3, - history_path: None, - custom_instructions: None, - } -} - -#[test] -fn render_compact_system_prompt_keeps_do_not_continue_instruction_intact() { - let prompt = - render_compact_system_prompt(None, CompactPromptMode::Fresh, 20_000, &[], None, None); - - assert!( - prompt.contains("**Do NOT continue the conversation.**"), - "compact prompt must explicitly instruct the summarizer not to continue the session" - ); -} - -#[test] -fn render_compact_system_prompt_renders_incremental_block() { - let prompt = render_compact_system_prompt( - None, - CompactPromptMode::Incremental { - previous_summary: "older summary".to_string(), - }, - 20_000, - &[], - None, - None, - ); - - assert!(prompt.contains("## Incremental Mode")); - assert!(prompt.contains("")); - assert!(prompt.contains("older summary")); -} - -#[test] -fn render_compact_system_prompt_includes_output_cap_and_recent_user_context_messages() { - let prompt = render_compact_system_prompt( - None, - CompactPromptMode::Fresh, - 12_345, - &[RecentUserContextMessage { - index: 7, - content: "保留这条约束".to_string(), - }], - None, - None, - ); - - assert!(prompt.contains("12345")); - assert!(prompt.contains("Recently Preserved Real User Messages")); - assert!(prompt.contains("保留这条约束")); - assert!(prompt.contains("")); -} - -#[test] -fn render_compact_system_prompt_includes_contract_repair_feedback() { - let prompt = render_compact_system_prompt( - None, - CompactPromptMode::Fresh, - 12_345, - &[], - None, - Some("missing "), - ); - - assert!(prompt.contains("## Contract Repair")); - assert!(prompt.contains("missing ")); -} - -#[test] -fn merge_compact_prompt_context_appends_hook_suffix_after_runtime_prompt() { - let merged = merge_compact_prompt_context(Some("base"), Some("hook")) - .expect("merged compact prompt context should exist"); - - assert_eq!(merged, "base\n\nhook"); -} - -#[test] -fn merge_compact_prompt_context_returns_none_when_both_empty() { - assert!(merge_compact_prompt_context(None, None).is_none()); - assert!(merge_compact_prompt_context(Some(" "), Some(" \n\t ")).is_none()); -} - -#[test] -fn parse_compact_output_requires_non_empty_content() { - let error = parse_compact_output(" ").expect_err("empty compact output should fail"); - assert!(error.to_string().contains("missing

block")); -} - -#[test] -fn parse_compact_output_requires_closed_summary_block() { - let error = parse_compact_output("open").expect_err("unclosed summary should fail"); - assert!(error.to_string().contains("closing ")); -} - -#[test] -fn parse_compact_output_prefers_summary_block() { - let parsed = parse_compact_output( - "draft\nSection\n(none)", - ) - .expect("summary should parse"); - - assert_eq!(parsed.summary, "Section"); - assert_eq!(parsed.recent_user_context_digest.as_deref(), Some("(none)")); - assert!(parsed.has_analysis); - assert!(parsed.has_recent_user_context_digest_block); -} - -#[test] -fn parse_compact_output_accepts_case_insensitive_summary_block() { - let parsed = parse_compact_output( - "draftSectiondigest", - ) - .expect("summary should parse"); - - assert_eq!(parsed.summary, "Section"); - assert_eq!(parsed.recent_user_context_digest.as_deref(), Some("digest")); - assert!(parsed.has_analysis); - assert!(parsed.has_recent_user_context_digest_block); -} - -#[test] -fn parse_compact_output_falls_back_to_plain_text_summary() { - let parsed = parse_compact_output("## Goal\n- preserve current task") - .expect("plain text summary should parse"); - - assert_eq!(parsed.summary, "## Goal\n- preserve current task"); - assert!(!parsed.has_analysis); - assert!(!parsed.has_recent_user_context_digest_block); -} - -#[test] -fn parse_compact_output_strips_outer_code_fence_before_parsing() { - let parsed = - parse_compact_output("```xml\ndraft\nSection\n```") - .expect("fenced xml summary should parse"); - - assert_eq!(parsed.summary, "Section"); - assert!(parsed.has_analysis); - assert!(!parsed.has_recent_user_context_digest_block); -} - -#[test] -fn compact_contract_violation_flags_missing_digest_block() { - let violation = CompactContractViolation::from_parsed_output(&ParsedCompactOutput { - summary: "Section".to_string(), - recent_user_context_digest: None, - has_analysis: true, - has_recent_user_context_digest_block: false, - used_fallback: false, - }) - .expect("missing digest block should violate contract"); - - assert!(violation.detail.contains("recent_user_context_digest")); -} - -#[test] -fn parse_compact_output_strips_common_summary_preamble_in_fallback() { - let parsed = parse_compact_output("Summary:\n## Goal\n- preserve current task") - .expect("summary preamble fallback should parse"); - - assert_eq!(parsed.summary, "## Goal\n- preserve current task"); -} - -#[test] -fn parse_compact_output_accepts_summary_tag_attributes() { - let parsed = parse_compact_output( - "draftSection", - ) - .expect("tag attributes should parse"); - - assert_eq!(parsed.summary, "Section"); - assert!(parsed.has_analysis); -} - -#[test] -fn parse_compact_output_does_not_treat_analysis_only_as_summary() { - let error = parse_compact_output("draft") - .expect_err("analysis-only output should still fail"); - - assert!(error.to_string().contains("missing block")); -} - -#[test] -fn split_for_compaction_preserves_recent_real_user_turns() { - let messages = vec![ - LlmMessage::User { - content: "older".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "ack".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::User { - content: format_compact_summary("older"), - origin: UserMessageOrigin::CompactSummary, - }, - LlmMessage::User { - content: "newer".to_string(), - origin: UserMessageOrigin::User, - }, - ]; - - let split = split_for_compaction(&messages, 1).expect("split should exist"); - - assert_eq!(split.keep_start, 3); - assert_eq!(split.prefix.len(), 3); - assert_eq!(split.suffix.len(), 1); -} - -#[test] -fn split_for_compaction_falls_back_to_assistant_boundary_for_single_turn() { - let messages = vec![ - LlmMessage::User { - content: "task".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "step 1".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::Assistant { - content: "step 2".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]; - - let split = split_for_compaction(&messages, 1).expect("single turn should still split"); - assert_eq!(split.keep_start, 2); -} - -#[test] -fn compacted_messages_inserts_summary_as_compact_user_message() { - let compacted = compacted_messages("Older history", None, &[], 0, Vec::new()); - - assert!(matches!( - &compacted[0], - LlmMessage::User { - origin: UserMessageOrigin::CompactSummary, - .. - } - )); - assert_eq!(compacted.len(), 1); -} - -#[test] -fn prepare_compact_input_strips_history_note_from_previous_summary() { - let filtered = prepare_compact_input(&[LlmMessage::User { - content: CompactSummaryEnvelope::new("older summary") - .with_history_path("~/.astrcode/projects/demo/sessions/abc/session-abc.jsonl") - .render(), - origin: UserMessageOrigin::CompactSummary, - }]); - - assert!(matches!( - filtered.prompt_mode, - CompactPromptMode::Incremental { ref previous_summary } - if previous_summary == "older summary" - )); -} - -#[test] -fn prepare_compact_input_skips_synthetic_user_messages() { - let filtered = prepare_compact_input(&[ - LlmMessage::User { - content: "summary".to_string(), - origin: UserMessageOrigin::CompactSummary, - }, - LlmMessage::User { - content: "wake up".to_string(), - origin: UserMessageOrigin::ReactivationPrompt, - }, - LlmMessage::User { - content: "digest".to_string(), - origin: UserMessageOrigin::RecentUserContextDigest, - }, - LlmMessage::User { - content: "preserved".to_string(), - origin: UserMessageOrigin::RecentUserContext, - }, - LlmMessage::User { - content: "real user".to_string(), - origin: UserMessageOrigin::User, - }, - ]); - - assert_eq!(filtered.messages.len(), 1); - assert!(matches!( - &filtered.messages[0], - LlmMessage::User { - content, - origin: UserMessageOrigin::User - } if content == "real user" - )); -} - -#[test] -fn build_compact_result_marks_incremental_mode_when_previous_summary_exists() { - let prepared_input = prepare_compact_input(&[ - LlmMessage::User { - content: CompactSummaryEnvelope::new("older summary").render(), - origin: UserMessageOrigin::CompactSummary, - }, - LlmMessage::User { - content: "current task".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "latest step".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]); - - let result = build_compact_result( - CompactResultInput { - compacted_messages: compacted_messages( - "refreshed summary", - Some("- keep current objective"), - &[], - 2, - vec![LlmMessage::Assistant { - content: "latest step".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }], - ), - summary: "refreshed summary".to_string(), - recent_user_context_digest: Some("- keep current objective".to_string()), - recent_user_context_messages: Vec::new(), - preserved_recent_turns: 1, - pre_tokens: 256, - messages_removed: 2, - }, - None, - &test_compact_config(), - CompactExecutionResult { - parsed_output: ParsedCompactOutput { - summary: "refreshed summary".to_string(), - recent_user_context_digest: Some("- keep current objective".to_string()), - has_analysis: true, - has_recent_user_context_digest_block: true, - used_fallback: false, - }, - prepared_input, - retry_state: CompactRetryState::default(), - }, - ); - - assert_eq!(result.meta.mode, CompactMode::Incremental); - assert_eq!(result.meta.retry_count, 0); - assert!(!result.meta.fallback_used); - assert_eq!(result.meta.input_units, 2); -} - -#[test] -fn normalize_compaction_tool_content_removes_exact_child_identifiers() { - let normalized = normalize_compaction_tool_content( - "spawn 已在后台启动。\n\nChild agent reference:\n- agentId: agent-1\n- subRunId: \ - subrun-1\n- sessionId: session-parent\n- openSessionId: session-child\n- status: \ - running\nUse this exact `agentId` value in later send/observe/close calls.", - ); - - assert!(normalized.contains("spawn 已在后台启动。")); - assert!(normalized.contains("Do not reuse any agentId")); - assert!(!normalized.contains("agent-1")); - assert!(!normalized.contains("subrun-1")); - assert!(!normalized.contains("session-child")); -} - - -#[test] -fn sanitize_compact_summary_replaces_stale_route_identifiers_with_boundary_guidance() { - let sanitized = sanitize_compact_summary( - "## Progress\n- Spawned agent-3 and later called observe(agent-2).\n- Error: agent \ - 'agent-2' is not a direct child of caller 'agent-root:session-parent' (actual parent: \ - agent-1); send/observe/close only support direct children.\n- Child ref payload: \ - agentId=agent-2 subRunId=subrun-2 openSessionId=session-child-2", - ); - - assert!(sanitized.contains("## Compact Boundary")); - assert!(sanitized.contains("live direct-child snapshot")); - assert!(sanitized.contains("")); - assert!(sanitized.contains("") || sanitized.contains("")); - assert!(sanitized.contains("") || sanitized.contains("")); - assert!(!sanitized.contains("agent-2")); - assert!(!sanitized.contains("subrun-2")); - assert!(!sanitized.contains("session-child-2")); - assert!(!sanitized.contains("not a direct child of caller")); -} - -#[test] -fn drop_oldest_compaction_unit_is_deterministic() { - let mut prefix = vec![ - LlmMessage::User { - content: "task".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "step-1".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::Assistant { - content: "step-2".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]; - - assert!(drop_oldest_compaction_unit(&mut prefix)); - assert!(matches!( - &prefix[0], - LlmMessage::Assistant { content, .. } if content == "step-1" - )); -} - -#[test] -fn trim_prefix_until_compact_request_fits_drops_oldest_units_before_calling_llm() { - let mut prefix = vec![ - LlmMessage::User { - content: "very old request ".repeat(1200), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "first step".repeat(1200), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::Assistant { - content: "latest step".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]; - - let trimmed = trim_prefix_until_compact_request_fits( - &mut prefix, - None, - ModelLimits { - context_window: 23_000, - max_output_tokens: 2_000, - }, - &test_compact_config(), - &[], - ); - - assert!(trimmed); - assert!(matches!( - prefix.as_slice(), - [LlmMessage::Assistant { content, .. }] if content == "latest step" - )); -} - -#[test] -fn can_compact_returns_false_for_empty_messages() { - assert!(!can_compact(&[], 2)); -} - -#[test] -fn can_compact_returns_true_when_enough_turns() { - let messages = vec![ - LlmMessage::User { - content: "turn-1".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "reply".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::User { - content: "turn-2".to_string(), - origin: UserMessageOrigin::User, - }, - ]; - assert!(can_compact(&messages, 1)); -} - -#[test] -fn collect_recent_user_context_messages_only_keeps_real_users() { - let recent = collect_recent_user_context_messages( - &[ - LlmMessage::User { - content: "summary".to_string(), - origin: UserMessageOrigin::CompactSummary, - }, - LlmMessage::User { - content: "recent".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::User { - content: "digest".to_string(), - origin: UserMessageOrigin::RecentUserContextDigest, - }, - LlmMessage::User { - content: "latest".to_string(), - origin: UserMessageOrigin::User, - }, - ], - 8, - ); - - assert_eq!(recent.len(), 2); - assert_eq!(recent[0].content, "recent"); - assert_eq!(recent[1].content, "latest"); -} - -#[test] -fn compacted_messages_put_recent_user_context_before_suffix_without_duplicates() { - let messages = compacted_messages( - "Older history", - Some("- keep current objective"), - &[RecentUserContextMessage { - index: 1, - content: "latest user".to_string(), - }], - 1, - vec![ - LlmMessage::User { - content: "latest user".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "latest assistant".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ], - ); - - assert!(matches!( - &messages[0], - LlmMessage::User { - origin: UserMessageOrigin::CompactSummary, - .. - } - )); - assert!(matches!( - &messages[1], - LlmMessage::User { - origin: UserMessageOrigin::RecentUserContextDigest, - .. - } - )); - assert!(matches!( - &messages[2], - LlmMessage::User { - origin: UserMessageOrigin::RecentUserContext, - content, - } if content == "latest user" - )); - assert!(matches!( - &messages[3], - LlmMessage::Assistant { content, .. } if content == "latest assistant" - )); - assert_eq!(messages.len(), 4); -} diff --git a/crates/session-runtime/src/context_window/micro_compact.rs b/crates/session-runtime/src/context_window/micro_compact.rs deleted file mode 100644 index bec86dfe..00000000 --- a/crates/session-runtime/src/context_window/micro_compact.rs +++ /dev/null @@ -1,422 +0,0 @@ -//! # Micro Compact -//! -//! 在完整 compaction 之前，先用本地规则清理“已经冷掉”的旧工具结果， -//! 避免每次都因为几段历史工具输出而触发昂贵的摘要压缩。 - -use std::{ - collections::{HashSet, VecDeque}, - time::{Duration, Instant}, -}; - -use astrcode_core::LlmMessage; -use chrono::{DateTime, Utc}; - -use super::tool_results::tool_call_name_map; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) struct MicroCompactConfig { - pub gap_threshold: Duration, - pub keep_recent_results: usize, -} - -#[derive(Debug, Clone)] -pub(crate) struct MicroCompactOutcome { - pub messages: Vec, -} - -#[derive(Debug, Clone)] -struct TrackedToolResult { - tool_call_id: String, - recorded_at: Instant, -} - -#[derive(Debug, Clone, Default)] -pub(crate) struct MicroCompactState { - tracked_results: VecDeque, - last_prompt_activity: Option, -} - -impl MicroCompactState { - pub fn seed_from_messages( - messages: &[LlmMessage], - config: MicroCompactConfig, - now: Instant, - last_assistant_at: Option>, - ) -> Self { - let mut state = Self::default(); - let stale_at = now.checked_sub(config.gap_threshold).unwrap_or(now); - let restored_activity = last_assistant_at - .and_then(|timestamp| instant_from_timestamp(now, timestamp)) - .unwrap_or(stale_at); - - for message in messages { - match message { - LlmMessage::Assistant { .. } | LlmMessage::Tool { .. } => { - state.last_prompt_activity = Some(restored_activity); - }, - _ => {}, - } - - let LlmMessage::Tool { tool_call_id, .. } = message else { - continue; - }; - state.tracked_results.push_back(TrackedToolResult { - tool_call_id: tool_call_id.clone(), - recorded_at: stale_at, - }); - } - - state - } - - pub fn record_tool_result(&mut self, tool_call_id: impl Into, now: Instant) { - let tool_call_id = tool_call_id.into(); - self.tracked_results - .retain(|entry| entry.tool_call_id != tool_call_id); - self.tracked_results.push_back(TrackedToolResult { - tool_call_id, - recorded_at: now, - }); - self.last_prompt_activity = Some(now); - } - - pub fn record_assistant_activity(&mut self, now: Instant) { - self.last_prompt_activity = Some(now); - } - - pub fn apply_if_idle( - &mut self, - messages: &[LlmMessage], - clearable_tools: &HashSet, - config: MicroCompactConfig, - now: Instant, - ) -> MicroCompactOutcome { - self.retain_live_tool_results(messages); - - let Some(last_activity) = self.last_prompt_activity else { - return MicroCompactOutcome { - messages: messages.to_vec(), - }; - }; - - if now.duration_since(last_activity) < config.gap_threshold { - return MicroCompactOutcome { - messages: messages.to_vec(), - }; - } - - let keep_recent_results = config.keep_recent_results.max(1); - if self.tracked_results.len() <= keep_recent_results { - return MicroCompactOutcome { - messages: messages.to_vec(), - }; - } - - let tool_call_names = tool_call_name_map(messages); - let protected_ids = self - .tracked_results - .iter() - .rev() - .take(keep_recent_results) - .map(|entry| entry.tool_call_id.as_str()) - .collect::>(); - - let stale_ids = self - .tracked_results - .iter() - .filter(|entry| !protected_ids.contains(entry.tool_call_id.as_str())) - .filter(|entry| now.duration_since(entry.recorded_at) >= config.gap_threshold) - .filter_map(|entry| { - tool_call_names - .get(&entry.tool_call_id) - .filter(|tool_name| clearable_tools.contains(*tool_name)) - .map(|_| entry.tool_call_id.clone()) - }) - .collect::>(); - - if stale_ids.is_empty() { - return MicroCompactOutcome { - messages: messages.to_vec(), - }; - } - - let mut compacted = messages.to_vec(); - for message in &mut compacted { - let LlmMessage::Tool { - tool_call_id, - content, - } = message - else { - continue; - }; - - if !stale_ids.contains(tool_call_id) || is_micro_compacted(content) { - continue; - } - - let tool_name = tool_call_names - .get(tool_call_id) - .map(String::as_str) - .unwrap_or("tool"); - *content = format!( - "[micro-compacted stale tool result from '{tool_name}' after idle gap; rerun the \ - tool if exact output is needed]" - ); - } - - MicroCompactOutcome { - messages: compacted, - } - } - - fn retain_live_tool_results(&mut self, messages: &[LlmMessage]) { - let live_tool_ids = messages - .iter() - .filter_map(|message| match message { - LlmMessage::Tool { tool_call_id, .. } => Some(tool_call_id.as_str()), - _ => None, - }) - .collect::>(); - self.tracked_results - .retain(|entry| live_tool_ids.contains(entry.tool_call_id.as_str())); - } -} - -fn is_micro_compacted(content: &str) -> bool { - content.contains("[micro-compacted stale tool result") -} - -fn instant_from_timestamp(now: Instant, timestamp: DateTime) -> Option { - let elapsed = (Utc::now() - timestamp).to_std().ok()?; - now.checked_sub(elapsed).or(Some(now)) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{LlmMessage, ToolCallRequest, UserMessageOrigin}; - use serde_json::json; - - use super::*; - - #[test] - fn micro_compact_clears_stale_tool_results_but_preserves_recent_entries() { - let now = Instant::now(); - let config = MicroCompactConfig { - gap_threshold: Duration::from_secs(30), - keep_recent_results: 1, - }; - let messages = vec![ - LlmMessage::User { - content: "inspect".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/lib.rs"}), - }, - ToolCallRequest { - id: "call-2".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/main.rs"}), - }, - ], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "older result".to_string(), - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "recent result".to_string(), - }, - ]; - - let mut state = MicroCompactState::seed_from_messages(&messages, config, now, None); - state.record_tool_result("call-2", now); - - let mut clearable_tools = HashSet::new(); - clearable_tools.insert("readFile".to_string()); - let outcome = state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(31), - ); - - assert!(matches!( - &outcome.messages[2], - LlmMessage::Tool { content, .. } if content.contains("micro-compacted") - )); - assert!(matches!( - &outcome.messages[3], - LlmMessage::Tool { content, .. } if content == "recent result" - )); - } - - #[test] - fn micro_compact_skips_when_idle_gap_not_reached() { - let now = Instant::now(); - let config = MicroCompactConfig { - gap_threshold: Duration::from_secs(30), - keep_recent_results: 1, - }; - let messages = vec![ - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/lib.rs"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "fresh".to_string(), - }, - ]; - - let mut state = MicroCompactState::default(); - state.record_tool_result("call-1", now); - - let mut clearable_tools = HashSet::new(); - clearable_tools.insert("readFile".to_string()); - let outcome = state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(5), - ); - - assert_eq!(outcome.messages, messages); - } - - #[test] - fn micro_compact_uses_recent_assistant_activity_as_idle_anchor() { - let now = Instant::now(); - let config = MicroCompactConfig { - gap_threshold: Duration::from_secs(30), - keep_recent_results: 1, - }; - let messages = vec![ - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/old.rs"}), - }, - ToolCallRequest { - id: "call-2".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/new.rs"}), - }, - ], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "old".to_string(), - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "new".to_string(), - }, - ]; - - let mut state = MicroCompactState::default(); - state.record_tool_result("call-1", now); - state.record_tool_result("call-2", now); - state.record_assistant_activity(now + Duration::from_secs(10)); - - let mut clearable_tools = HashSet::new(); - clearable_tools.insert("readFile".to_string()); - - let early = state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(35), - ); - assert_eq!(early.messages, messages); - - let late = state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(41), - ); - assert!(matches!( - &late.messages[1], - LlmMessage::Tool { content, .. } if content.contains("micro-compacted") - )); - } - - #[test] - fn micro_compact_seed_uses_last_assistant_timestamp_when_available() { - let now = Instant::now(); - let config = MicroCompactConfig { - gap_threshold: Duration::from_secs(30), - keep_recent_results: 1, - }; - let messages = vec![ - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/old.rs"}), - }, - ToolCallRequest { - id: "call-2".to_string(), - name: "readFile".to_string(), - args: json!({"path":"src/new.rs"}), - }, - ], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "old".to_string(), - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "new".to_string(), - }, - ]; - let assistant_at = Utc::now() - chrono::Duration::seconds(10); - let state = - MicroCompactState::seed_from_messages(&messages, config, now, Some(assistant_at)); - - let mut clearable_tools = HashSet::new(); - clearable_tools.insert("readFile".to_string()); - - let mut early_state = state.clone(); - let early = early_state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(15), - ); - assert_eq!(early.messages, messages); - - let mut late_state = state; - let late = late_state.apply_if_idle( - &messages, - &clearable_tools, - config, - now + Duration::from_secs(25), - ); - assert!(matches!( - &late.messages[1], - LlmMessage::Tool { content, .. } if content.contains("micro-compacted") - )); - } -} diff --git a/crates/session-runtime/src/context_window/mod.rs b/crates/session-runtime/src/context_window/mod.rs deleted file mode 100644 index ca3cd72b..00000000 --- a/crates/session-runtime/src/context_window/mod.rs +++ /dev/null @@ -1,22 +0,0 @@ -//! Context window management. -//! -//! It owns token budgeting and message trimming/compaction operations: -//! - `token_usage`: token estimation, budget tracking and compaction threshold metrics -//! - `prune_pass`: lightweight truncation of clearable tool results (no LLM) -//! - `compaction`: context compaction (LLM-required summarization) -//! - `micro_compact`: idle-time cleanup of stale tool-result traces -//! - `file_access`: replaying recovered file-context messages -//! - `settings`: window/compaction parameter mapping -//! -//! Final request assembly must not be implemented here. -//! That flow is implemented in `session-runtime::turn::request`. - -pub(crate) mod compaction; -pub(crate) mod file_access; -pub(crate) mod micro_compact; -pub(crate) mod prune_pass; -pub(crate) mod settings; -pub(crate) mod token_usage; -pub(crate) mod tool_results; - -pub(crate) use settings::ContextWindowSettings; diff --git a/crates/session-runtime/src/context_window/prune_pass.rs b/crates/session-runtime/src/context_window/prune_pass.rs deleted file mode 100644 index 63add324..00000000 --- a/crates/session-runtime/src/context_window/prune_pass.rs +++ /dev/null @@ -1,229 +0,0 @@ -//! # Prune Pass -//! -//! 轻量级上下文优化，不需要调用 LLM，直接在本地执行： -//! - 截断过长的工具结果（超过 `max_tool_result_bytes`） -//! - 清除标记为 `compact_clearable` 的旧工具结果 -//! -//! ## 与完整压缩的区别 -//! -//! | 特性 | Prune Pass | 完整压缩 | -//! |------|-----------|----------| -//! | 是否需要 LLM | 否 | 是 | -//! | 触发条件 | 每个 step | 配置阈值 | -//! | 操作 | 截断/清除 | 摘要替换 | -//! | 速度 | 即时 | 需要 LLM 调用 | - -use std::collections::HashSet; - -use astrcode_core::{LlmMessage, UserMessageOrigin}; - -use super::tool_results::tool_call_name_map; - -/// Prune pass 执行统计。 -#[derive(Debug, Clone, Default, PartialEq, Eq)] -pub(crate) struct PruneStats { - pub truncated_tool_results: usize, - pub cleared_tool_results: usize, -} - -/// Prune pass 执行结果。 -#[derive(Debug, Clone)] -pub(crate) struct PruneOutcome { - pub messages: Vec, - pub stats: PruneStats, -} - -/// 执行轻量级上下文优化。 -/// -/// - 截断超过 `max_tool_result_bytes` 的工具结果 -/// - 清除 `clearable_tools` 中指定的旧工具结果（保留最近 `keep_recent_turns` 轮） -pub fn apply_prune_pass( - messages: &[LlmMessage], - clearable_tools: &HashSet, - max_tool_result_bytes: usize, - keep_recent_turns: usize, -) -> PruneOutcome { - // tool_call_id → tool_name 映射 - let tool_call_names = tool_call_name_map(messages); - // 保留最近的 keep_recent_turns 个用户 turn 不受 prune 影响 - let keep_start = recent_turn_start_index(messages, keep_recent_turns.max(1)); - let mut truncated_tool_results = 0usize; - let mut cleared_tool_results = 0usize; - let mut compacted = messages.to_vec(); - - for (index, message) in compacted.iter_mut().enumerate() { - let LlmMessage::Tool { - tool_call_id, - content, - } = message - else { - continue; - }; - - if content.len() > max_tool_result_bytes { - *content = truncate_tool_content(content, max_tool_result_bytes); - truncated_tool_results += 1; - } - - if index >= keep_start { - continue; - } - - let Some(tool_name) = tool_call_names.get(tool_call_id) else { - continue; - }; - if clearable_tools.contains(tool_name) { - *content = format!( - "[cleared older tool result from '{tool_name}' to reduce prompt size; reload it \ - if needed]" - ); - cleared_tool_results += 1; - } - } - - PruneOutcome { - messages: compacted, - stats: PruneStats { - truncated_tool_results, - cleared_tool_results, - }, - } -} - -fn truncate_tool_content(content: &str, max_bytes: usize) -> String { - let total_bytes = content.len(); - let mut visible_bytes = max_bytes.saturating_sub(96).max(64).min(total_bytes); - while !content.is_char_boundary(visible_bytes) { - visible_bytes = visible_bytes.saturating_sub(1); - } - let visible = &content[..visible_bytes]; - format!( - "[truncated: original {total_bytes} bytes, showing first {visible_bytes} bytes]\n{visible}" - ) -} - -/// 找到保留区域的起始索引（最近 `requested_recent_turns` 个用户 turn 之前的第一个位置）。 -fn recent_turn_start_index(messages: &[LlmMessage], requested_recent_turns: usize) -> usize { - let user_turn_indices = messages - .iter() - .enumerate() - .filter_map(|(index, message)| match message { - LlmMessage::User { - origin: UserMessageOrigin::User, - .. - } => Some(index), - _ => None, - }) - .collect::>(); - if user_turn_indices.is_empty() { - return messages.len(); - } - - let keep_turns = requested_recent_turns.min(user_turn_indices.len()).max(1); - user_turn_indices[user_turn_indices.len() - keep_turns] -} - -#[cfg(test)] -mod tests { - use astrcode_core::ToolCallRequest; - use serde_json::json; - - use super::*; - - #[test] - fn prune_pass_truncates_large_tool_results_and_clears_old_safe_tools() { - let messages = vec![ - LlmMessage::User { - content: "inspect".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"Cargo.toml"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "x".repeat(512), - }, - LlmMessage::User { - content: "follow up".to_string(), - origin: UserMessageOrigin::User, - }, - ]; - - let mut clearable = HashSet::new(); - clearable.insert("readFile".to_string()); - let result = apply_prune_pass(&messages, &clearable, 128, 1); - - assert_eq!(result.stats.truncated_tool_results, 1); - assert_eq!(result.stats.cleared_tool_results, 1); - match &result.messages[2] { - LlmMessage::Tool { content, .. } => { - assert!(content.contains("[cleared older tool result")); - }, - other => panic!("expected tool message, got {other:?}"), - } - } - - #[test] - fn prune_pass_does_not_reduce_requested_recent_turns_when_suffix_is_large() { - let protected_tool = "protected result ".repeat(200); - let messages = vec![ - LlmMessage::User { - content: "turn-1".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path":"old.rs"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: protected_tool.clone(), - }, - LlmMessage::User { - content: "turn-2".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-2".to_string(), - name: "readFile".to_string(), - args: json!({"path":"recent.rs"}), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-2".to_string(), - content: "latest result ".repeat(200), - }, - ]; - - let mut clearable = HashSet::new(); - clearable.insert("readFile".to_string()); - let result = apply_prune_pass(&messages, &clearable, usize::MAX, 2); - - match &result.messages[2] { - LlmMessage::Tool { content, .. } => { - assert_eq!( - content, &protected_tool, - "when the caller requests the recent two turns, prune pass must not degrade \ - that guarantee to one turn just because the suffix is large" - ); - }, - other => panic!("expected tool message, got {other:?}"), - } - assert_eq!(result.stats.cleared_tool_results, 0); - } -} diff --git a/crates/session-runtime/src/context_window/token_usage.rs b/crates/session-runtime/src/context_window/token_usage.rs deleted file mode 100644 index 6c3b832d..00000000 --- a/crates/session-runtime/src/context_window/token_usage.rs +++ /dev/null @@ -1,259 +0,0 @@ -//! # Token 使用跟踪 -//! -//! 提供 Token 估算和跟踪能力，用于： -//! - 构建 Prompt Token 快照（当前上下文大小、预算、窗口限制） -//! - 估算消息和文本的 Token 数量 -//! - 判断是否需要触发压缩 -//! -//! ## Token 估算启发式 -//! -//! 当前使用简化的启发式估算： -//! - 每条消息基础开销: 6 tokens -//! - 每个工具调用基础开销: 12 tokens -//! - 文本内容: 按字符数估算（4 chars/token） -//! -//! ## 为什么不用精确 Tokenizer -//! -//! 精确 Token 计数需要 Provider 原生的 Tokenizer，当前后端未暴露此能力。 -//! 一旦后端暴露精确 Token 计算和上下文窗口元数据，应替换此启发式。 - -use astrcode_core::{LlmMessage, LlmUsage, ModelLimits, UserMessageOrigin}; - -use crate::heuristics::{MESSAGE_BASE_TOKENS, TOOL_CALL_BASE_TOKENS}; - -const REQUEST_ESTIMATE_PADDING_NUMERATOR: usize = 4; -const REQUEST_ESTIMATE_PADDING_DENOMINATOR: usize = 3; - -/// Prompt token 使用快照。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) struct PromptTokenSnapshot { - /// 估算的上下文 token 数。 - pub context_tokens: usize, - /// 已确认的预算 token 数（优先使用 Provider 报告值）。 - pub budget_tokens: usize, - /// 模型上下文窗口大小。 - pub context_window: usize, - /// 有效上下文窗口（扣除压缩预留）。 - pub effective_window: usize, - /// 触发压缩的阈值 token 数。 - pub threshold_tokens: usize, - /// 剩余可用 token 数（已经扣除 compact 输出预留）。 - pub remaining_context_tokens: usize, - /// 当剩余空间低于该值时应触发 compact。 - pub reserved_context_size: usize, -} - -/// Token 使用跟踪器。 -/// -/// 优先使用 Provider 报告的 usage 数据（最接近计费 Token）， -/// 若 Provider 未报告则回退到估算值。 -#[derive(Debug, Default, Clone, Copy)] -pub(crate) struct TokenUsageTracker { - anchored_budget_tokens: usize, -} - -impl TokenUsageTracker { - /// 记录 Provider 报告的 token 使用量。 - pub fn record_usage(&mut self, usage: Option) { - let Some(usage) = usage else { - return; - }; - self.anchored_budget_tokens = self - .anchored_budget_tokens - .saturating_add(usage.total_tokens()); - } - - /// 返回当前预算 token 数，优先使用 Provider 报告值。 - pub fn budget_tokens(&self, estimated_context_tokens: usize) -> usize { - if self.anchored_budget_tokens > 0 { - self.anchored_budget_tokens - } else { - estimated_context_tokens - } - } -} - -/// 构建 Prompt Token 快照。 -pub fn build_prompt_snapshot( - tracker: &TokenUsageTracker, - messages: &[LlmMessage], - system_prompt: Option<&str>, - limits: ModelLimits, - threshold_percent: u8, - summary_reserve_tokens: usize, - reserved_context_size: usize, -) -> PromptTokenSnapshot { - let context_tokens = estimate_request_tokens(messages, system_prompt); - let effective_window = effective_context_window(limits, summary_reserve_tokens); - PromptTokenSnapshot { - context_tokens, - budget_tokens: tracker.budget_tokens(context_tokens), - context_window: limits.context_window, - effective_window, - threshold_tokens: compact_threshold_tokens(effective_window, threshold_percent), - remaining_context_tokens: effective_window.saturating_sub(context_tokens), - reserved_context_size, - } -} - -/// 计算有效上下文窗口（扣除压缩预留）。 -pub fn effective_context_window(limits: ModelLimits, summary_reserve_tokens: usize) -> usize { - limits - .context_window - .saturating_sub(summary_reserve_tokens.min(limits.context_window)) -} - -/// 计算压缩阈值 token 数。 -pub fn compact_threshold_tokens(effective_window: usize, threshold_percent: u8) -> usize { - effective_window - .saturating_mul(threshold_percent as usize) - .saturating_div(100) -} - -/// 判断是否需要触发压缩。 -pub fn should_compact(snapshot: PromptTokenSnapshot) -> bool { - snapshot.context_tokens >= snapshot.threshold_tokens - || snapshot.remaining_context_tokens <= snapshot.reserved_context_size -} - -/// 估算完整 LLM 请求的 token 数（messages + system prompt）。 -pub fn estimate_request_tokens(messages: &[LlmMessage], system_prompt: Option<&str>) -> usize { - let system_tokens = system_prompt.map_or(0, estimate_text_tokens); - let raw_total = system_tokens + messages.iter().map(estimate_message_tokens).sum::(); - raw_total - .saturating_mul(REQUEST_ESTIMATE_PADDING_NUMERATOR) - .div_ceil(REQUEST_ESTIMATE_PADDING_DENOMINATOR) -} - -/// 估算单条消息的 token 数。 -pub fn estimate_message_tokens(message: &LlmMessage) -> usize { - match message { - LlmMessage::User { content, origin } => { - MESSAGE_BASE_TOKENS - + estimate_text_tokens(content) - + match origin { - UserMessageOrigin::User => 0, - UserMessageOrigin::QueuedInput => 8, - UserMessageOrigin::ContinuationPrompt => 10, - UserMessageOrigin::ReactivationPrompt => 8, - UserMessageOrigin::RecentUserContextDigest => 8, - UserMessageOrigin::RecentUserContext => 8, - UserMessageOrigin::CompactSummary => 16, - } - }, - LlmMessage::Assistant { - content, - tool_calls, - reasoning, - } => { - MESSAGE_BASE_TOKENS - + estimate_text_tokens(content) - + reasoning - .as_ref() - .map_or(0, |r| estimate_text_tokens(&r.content)) - + tool_calls - .iter() - .map(|call| { - TOOL_CALL_BASE_TOKENS - + estimate_text_tokens(&call.id) - + estimate_text_tokens(&call.name) - + estimate_json_tokens(&call.args.to_string()) - }) - .sum::() - }, - LlmMessage::Tool { - tool_call_id, - content, - } => { - MESSAGE_BASE_TOKENS + estimate_text_tokens(tool_call_id) + estimate_text_tokens(content) - }, - } -} - -/// 文本 token 估算（4 chars/token）。 -pub fn estimate_text_tokens(text: &str) -> usize { - let chars = text.chars().count(); - chars.div_ceil(4).max(1) -} - -fn estimate_json_tokens(json: &str) -> usize { - estimate_text_tokens(json) + 4 -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ReasoningContent, ToolCallRequest}; - use serde_json::json; - - use super::*; - - #[test] - fn request_estimate_includes_system_and_message_content() { - let messages = vec![ - LlmMessage::User { - content: "inspect src/main.rs".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "I will inspect it.".to_string(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: json!({"path": "src/main.rs"}), - }], - reasoning: Some(ReasoningContent { - content: "Need file contents first.".to_string(), - signature: None, - }), - }, - ]; - - let estimate = estimate_request_tokens(&messages, Some("system")); - assert!(estimate > 0); - } - - #[test] - fn compact_threshold_uses_effective_window() { - let limits = ModelLimits { - context_window: 100_000, - max_output_tokens: 8_000, - }; - - assert_eq!(effective_context_window(limits, 20_000), 80_000); - assert_eq!(compact_threshold_tokens(80_000, 90), 72_000); - } - - #[test] - fn should_compact_when_remaining_context_is_below_reserved_size() { - assert!(should_compact(PromptTokenSnapshot { - context_tokens: 40_000, - budget_tokens: 40_000, - context_window: 100_000, - effective_window: 80_000, - threshold_tokens: 72_000, - remaining_context_tokens: 10_000, - reserved_context_size: 20_000, - })); - } - - #[test] - fn tracker_prefers_provider_usage_over_estimate() { - let mut tracker = TokenUsageTracker::default(); - let usage = LlmUsage { - input_tokens: 1000, - output_tokens: 200, - cache_creation_input_tokens: 0, - cache_read_input_tokens: 0, - }; - tracker.record_usage(Some(usage)); - - // 即使估算值不同，也应使用 Provider 报告值（total = input + output = 1200） - assert_eq!(tracker.budget_tokens(5000), 1200); - } - - #[test] - fn tracker_falls_back_to_estimate_when_no_provider_usage() { - let tracker = TokenUsageTracker::default(); - assert_eq!(tracker.budget_tokens(5000), 5000); - } -} diff --git a/crates/session-runtime/src/heuristics.rs b/crates/session-runtime/src/heuristics.rs deleted file mode 100644 index 1f24b128..00000000 --- a/crates/session-runtime/src/heuristics.rs +++ /dev/null @@ -1,10 +0,0 @@ -//! 运行时启发式常量。 -//! -//! 这些值当前服务于 prompt 预算估算。 -//! 它们不是用户配置项，但应集中管理，避免 magic number 分散。 - -/// 单条消息的固定估算开销。 -pub(crate) const MESSAGE_BASE_TOKENS: usize = 6; - -/// 单个工具调用元数据的固定估算开销。 -pub(crate) const TOOL_CALL_BASE_TOKENS: usize = 12; diff --git a/crates/session-runtime/src/identity.rs b/crates/session-runtime/src/identity.rs deleted file mode 100644 index 8ef969d2..00000000 --- a/crates/session-runtime/src/identity.rs +++ /dev/null @@ -1,9 +0,0 @@ -//! 面向外层输入的 session 标识桥接。 -//! -//! Why: runtime 仍然是 session key 规范化语义的唯一 owner， -//! 但上层 blanket impl 偶尔需要把原始字符串转换成 runtime key。 - -/// 规范化外部传入的 session 标识。 -pub fn normalize_external_session_id(session_id: &str) -> String { - crate::state::normalize_session_id(session_id) -} diff --git a/crates/session-runtime/src/lib.rs b/crates/session-runtime/src/lib.rs deleted file mode 100644 index 9710b82f..00000000 --- a/crates/session-runtime/src/lib.rs +++ /dev/null @@ -1,621 +0,0 @@ -use std::{ - path::{Path, PathBuf}, - sync::Arc, -}; - -use astrcode_core::{ - AgentCollaborationFact, AgentEventContext, AgentId, AgentLifecycleStatus, ChildSessionNode, - ChildSessionNotification, DeleteProjectResult, EventStore, InputBatchAckedPayload, - InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, Phase, - PromptFactsProvider, ResolvedRuntimeConfig, Result, RuntimeMetricsRecorder, SessionId, - SessionMeta, StoredEvent, event::generate_session_id, -}; -use astrcode_kernel::{Kernel, PendingParentDelivery}; -use chrono::Utc; -use dashmap::DashMap; -use thiserror::Error; -use tokio::sync::broadcast; - -mod actor; -mod catalog; -mod command; -mod context_window; -mod heuristics; -pub mod identity; -mod observe; -mod query; -mod state; -mod turn; - -use actor::SessionActor; -pub use catalog::SessionCatalogEvent; -pub use observe::{ - SessionEventFilterSpec, SessionObserveSnapshot, SubRunEventScope, SubRunStatusSnapshot, - SubRunStatusSource, -}; -pub use query::{ - AgentObserveSnapshot, ConversationAssistantBlockFacts, ConversationBlockFacts, - ConversationBlockPatchFacts, ConversationBlockStatus, ConversationChildHandoffBlockFacts, - ConversationChildHandoffKind, ConversationDeltaFacts, ConversationDeltaFrameFacts, - ConversationDeltaProjector, ConversationErrorBlockFacts, ConversationPlanBlockFacts, - ConversationPlanBlockersFacts, ConversationPlanEventKind, ConversationPlanReviewFacts, - ConversationPlanReviewKind, ConversationPromptMetricsBlockFacts, ConversationSnapshotFacts, - ConversationStepCursorFacts, ConversationStepProgressFacts, ConversationStreamProjector, - ConversationStreamReplayFacts, ConversationSystemNoteBlockFacts, ConversationSystemNoteKind, - ConversationThinkingBlockFacts, ConversationTranscriptErrorKind, ConversationUserBlockFacts, - LastCompactMetaSnapshot, ProjectedTurnOutcome, SessionControlStateSnapshot, - SessionModeSnapshot, SessionReplay, SessionTranscriptSnapshot, ToolCallBlockFacts, - ToolCallStreamsFacts, TurnTerminalSnapshot, recoverable_parent_deliveries, -}; -#[cfg(test)] -pub(crate) use state::SessionStateEventSink; -pub use state::{ - SessionSnapshot, SessionState, display_name_from_working_dir, normalize_working_dir, -}; -pub use turn::{ - AgentPromptSubmission, ForkPoint, ForkResult, TurnCollaborationSummary, TurnFinishReason, - TurnSummary, -}; -pub(crate) use turn::{TurnOutcome, TurnRunResult, run_turn}; - -pub const ROOT_AGENT_ID: &str = "root-agent"; - -#[derive(Debug)] -struct LoadedSession { - actor: Arc, -} - -#[derive(Debug, Error)] -pub enum SessionRuntimeError { - #[error("session '{0}' already exists")] - SessionAlreadyExists(String), - #[error("session '{0}' not found")] - SessionNotFound(String), - #[error("session '{session_id}' initialization failed: {message}")] - SessionInitializationFailed { session_id: String, message: String }, -} - -impl From for astrcode_core::AstrError { - fn from(value: SessionRuntimeError) -> Self { - match value { - SessionRuntimeError::SessionAlreadyExists(session_id) => { - astrcode_core::AstrError::Validation(format!( - "session '{}' already exists", - session_id - )) - }, - SessionRuntimeError::SessionNotFound(session_id) => { - astrcode_core::AstrError::SessionNotFound(session_id) - }, - SessionRuntimeError::SessionInitializationFailed { - session_id, - message, - } => astrcode_core::AstrError::Internal(format!( - "session '{}' initialization failed: {}", - session_id, message - )), - } - } -} - -/// 单 session 真相面。 -pub struct SessionRuntime { - pub(crate) kernel: Arc, - pub(crate) prompt_facts_provider: Arc, - metrics: Arc, - sessions: DashMap>, - pub(crate) event_store: Arc, - catalog_events: broadcast::Sender, -} - -impl SessionRuntime { - pub fn new( - kernel: Arc, - prompt_facts_provider: Arc, - event_store: Arc, - metrics: Arc, - ) -> Self { - let (catalog_events, _) = broadcast::channel(256); - Self { - kernel, - prompt_facts_provider, - metrics, - sessions: DashMap::new(), - event_store, - catalog_events, - } - } - - pub fn subscribe_catalog_events(&self) -> broadcast::Receiver { - self.catalog_events.subscribe() - } - - pub(crate) fn query(&self) -> query::SessionQueries<'_> { - query::SessionQueries::new(self) - } - - pub(crate) fn command(&self) -> command::SessionCommands<'_> { - command::SessionCommands::new(self) - } - - /// 返回当前已加载到内存中的 session ID。 - /// - /// Why: 治理视图关心的是 live runtime 负载，而不是磁盘上全部 durable session。 - pub fn list_sessions(&self) -> Vec { - let mut sessions = self - .sessions - .iter() - .map(|entry| entry.key().clone()) - .collect::>(); - sessions.sort(); - sessions - } - - pub fn list_running_sessions(&self) -> Vec { - let mut sessions = self - .sessions - .iter() - .filter(|entry| entry.value().actor.turn_runtime().is_running()) - .map(|entry| entry.key().clone()) - .collect::>(); - sessions.sort(); - sessions - } - - pub async fn list_session_metas(&self) -> Result> { - let mut metas = self.event_store.list_session_metas().await?; - for meta in &mut metas { - let session_id: SessionId = meta.session_id.clone().into(); - if let Some(entry) = self.sessions.get(&session_id) { - meta.phase = entry.actor.state().current_phase()?; - } - } - metas.sort_by_key(|meta| meta.updated_at); - Ok(metas) - } - - pub async fn create_session(&self, working_dir: impl Into) -> Result { - self.create_session_with_parent(working_dir, None).await - } - - pub async fn create_child_session( - &self, - working_dir: impl Into, - parent_session_id: impl Into, - ) -> Result { - self.create_session_with_parent(working_dir, Some(parent_session_id.into())) - .await - } - - async fn create_session_with_parent( - &self, - working_dir: impl Into, - parent_session_id: Option, - ) -> Result { - let working_dir = normalize_working_dir(PathBuf::from(working_dir.into()))?; - let session_id_raw = generate_session_id(); - let session_id: SessionId = session_id_raw.clone().into(); - if self.sessions.contains_key(&session_id) { - return Err(SessionRuntimeError::SessionAlreadyExists(session_id_raw).into()); - } - - self.event_store - .ensure_session(&session_id, &working_dir) - .await?; - - let created_at = Utc::now(); - let lineage_parent_session_id = parent_session_id.clone(); - let actor = Arc::new( - SessionActor::new_persistent_with_lineage( - session_id.clone(), - working_dir.display().to_string(), - AgentId::from(ROOT_AGENT_ID.to_string()), - Arc::clone(&self.event_store), - lineage_parent_session_id, - None, - ) - .await - .map_err(|error| SessionRuntimeError::SessionInitializationFailed { - session_id: session_id.to_string(), - message: error.to_string(), - })?, - ); - self.sessions.insert( - session_id.clone(), - Arc::new(LoadedSession { - actor: Arc::clone(&actor), - }), - ); - - let meta = SessionMeta { - session_id: session_id.to_string(), - working_dir: actor.working_dir().to_string(), - display_name: display_name_from_working_dir(Path::new(actor.working_dir())), - title: "New Session".to_string(), - created_at, - updated_at: created_at, - parent_session_id, - parent_storage_seq: None, - phase: Phase::Idle, - }; - let _ = self - .catalog_events - .send(SessionCatalogEvent::SessionCreated { - session_id: session_id.to_string(), - }); - Ok(meta) - } - - pub async fn observe(&self, session_id: &SessionId) -> Result { - self.query().observe(session_id).await - } - - /// 按需加载 session 并返回内部状态引用。 - /// - /// 用于 agent 编排层需要直接操作 SessionState 的场景 - /// （如 input queue 追加、对话投影读取等）。 - pub async fn get_session_state(&self, session_id: &SessionId) -> Result> { - self.query().session_state(session_id).await - } - - /// 读取会话控制态快照，供 application / conversation surface 编排使用。 - pub async fn session_control_state( - &self, - session_id: &str, - ) -> Result { - self.query().session_control_state(session_id).await - } - - pub async fn conversation_snapshot( - &self, - session_id: &str, - ) -> Result { - self.query().conversation_snapshot(session_id).await - } - - pub async fn conversation_stream_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> Result { - self.query() - .conversation_stream_replay(session_id, last_event_id) - .await - } - - /// 返回当前 session durable 可见的 direct child lineage 节点。 - pub async fn session_child_nodes(&self, session_id: &str) -> Result> { - self.query().session_child_nodes(session_id).await - } - - pub async fn session_mode_state(&self, session_id: &str) -> Result { - self.query().session_mode_state(session_id).await - } - - pub async fn active_task_snapshot( - &self, - session_id: &str, - owner: &str, - ) -> Result> { - self.query().active_task_snapshot(session_id, owner).await - } - - /// 读取指定 session 的工作目录。 - pub async fn get_session_working_dir(&self, session_id: &str) -> Result { - self.query().session_working_dir(session_id).await - } - - /// 回放指定 session 的全部持久化事件。 - /// - /// 用于 agent 编排层需要从 durable 事件中提取 input queue 信封等场景。 - pub async fn replay_stored_events(&self, session_id: &SessionId) -> Result> { - self.query().stored_events(session_id).await - } - - /// 等待指定 turn 进入可判定终态，并返回该 turn 的 durable 事件快照。 - pub async fn wait_for_turn_terminal_snapshot( - &self, - session_id: &str, - turn_id: &str, - ) -> Result { - turn::wait_for_turn_terminal_snapshot(self, session_id, turn_id).await - } - - /// 仅供跨 crate 集成测试设置单 session 的 runtime running 状态。 - /// - /// Why: application/server 测试需要快速制造“busy session”场景，但不应继续直接操作 - /// `SessionState` 的 turn runtime proxy。 - #[doc(hidden)] - pub async fn prepare_test_turn_runtime(&self, session_id: &str, turn_id: &str) -> Result { - let session_id = SessionId::from(state::normalize_session_id(session_id)); - let actor = self.ensure_loaded_session(&session_id).await?; - let lease = match self - .event_store - .try_acquire_turn(&session_id, turn_id) - .await? - { - astrcode_core::SessionTurnAcquireResult::Acquired(lease) => lease, - astrcode_core::SessionTurnAcquireResult::Busy(busy) => { - return Err(astrcode_core::AstrError::Validation(format!( - "session '{}' unexpectedly busy while preparing test turn '{}': {}", - session_id, turn_id, busy.turn_id - ))); - }, - }; - actor.turn_runtime().prepare( - session_id.as_str(), - turn_id, - astrcode_core::CancelToken::new(), - lease, - ) - } - - /// 仅供跨 crate 集成测试清理通过 `prepare_test_turn_runtime()` 创建的 runtime running 状态。 - #[doc(hidden)] - pub async fn complete_test_turn_runtime( - &self, - session_id: &str, - generation: u64, - ) -> Result<()> { - let session_id = SessionId::from(state::normalize_session_id(session_id)); - let actor = self.ensure_loaded_session(&session_id).await?; - let _ = actor.turn_runtime().complete(generation)?; - Ok(()) - } - - /// 生成面向 agent 编排的单 session observe 快照。 - pub async fn observe_agent_session( - &self, - open_session_id: &str, - target_agent_id: &str, - lifecycle_status: AgentLifecycleStatus, - ) -> Result { - self.query() - .observe_agent_session(open_session_id, target_agent_id, lifecycle_status) - .await - } - - /// 读取指定 agent 当前 input queue durable 投影中的待处理 delivery id。 - pub async fn pending_delivery_ids_for_agent( - &self, - session_id: &str, - agent_id: &str, - ) -> Result> { - self.query() - .pending_delivery_ids_for_agent(session_id, agent_id) - .await - } - - /// 读取 durable child session 事件并投影指定 sub-run 的稳定状态快照。 - pub async fn durable_subrun_status_snapshot( - &self, - parent_session_id: &str, - requested_subrun_id: &str, - ) -> Result> { - self.query() - .durable_subrun_status_snapshot(parent_session_id, requested_subrun_id) - .await - } - - pub async fn append_agent_input_queued( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputQueuedPayload, - ) -> Result { - self.command() - .append_agent_input_queued(session_id, turn_id, agent, payload) - .await - } - - pub async fn append_agent_input_discarded( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputDiscardedPayload, - ) -> Result { - self.command() - .append_agent_input_discarded(session_id, turn_id, agent, payload) - .await - } - - pub async fn append_agent_input_batch_started( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchStartedPayload, - ) -> Result { - self.command() - .append_agent_input_batch_started(session_id, turn_id, agent, payload) - .await - } - - pub async fn append_agent_input_batch_acked( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - payload: InputBatchAckedPayload, - ) -> Result { - self.command() - .append_agent_input_batch_acked(session_id, turn_id, agent, payload) - .await - } - - /// 向指定父 session 追加 `ChildSessionNotification` durable 事件。 - pub async fn append_child_session_notification( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - notification: ChildSessionNotification, - ) -> Result { - self.command() - .append_child_session_notification(session_id, turn_id, agent, notification) - .await - } - - /// 向指定 session 追加 agent collaboration durable 事实。 - pub async fn append_agent_collaboration_fact( - &self, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - fact: AgentCollaborationFact, - ) -> Result { - self.command() - .append_agent_collaboration_fact(session_id, turn_id, agent, fact) - .await - } - - /// 从 durable input queue + child notification 中恢复仍可重试的父级 delivery。 - pub async fn recoverable_parent_deliveries( - &self, - parent_session_id: &str, - ) -> Result> { - self.query() - .recoverable_parent_deliveries(parent_session_id) - .await - } - - /// 基于单 session terminal 事件投影出结构化 turn outcome。 - pub async fn project_turn_outcome( - &self, - session_id: &str, - turn_id: &str, - ) -> Result { - turn::wait_and_project_turn_outcome(self, session_id, turn_id).await - } - - pub async fn delete_session(&self, session_id: &str) -> Result<()> { - let session_id = SessionId::from(state::normalize_session_id(session_id)); - self.ensure_session_exists(&session_id).await?; - self.event_store.delete_session(&session_id).await?; - self.sessions.remove(&session_id); - let _ = self - .catalog_events - .send(SessionCatalogEvent::SessionDeleted { - session_id: session_id.to_string(), - }); - Ok(()) - } - - pub async fn delete_project(&self, working_dir: &str) -> Result { - let deleted = self - .event_store - .delete_sessions_by_working_dir(working_dir) - .await?; - - let target = normalize_path(working_dir); - let to_remove = self - .sessions - .iter() - .filter_map(|entry| { - (normalize_path(entry.value().actor.working_dir()) == target) - .then_some(entry.key().clone()) - }) - .collect::>(); - for session_id in to_remove { - self.sessions.remove(&session_id); - } - - let _ = self - .catalog_events - .send(SessionCatalogEvent::ProjectDeleted { - working_dir: working_dir.to_string(), - }); - Ok(deleted) - } - - pub async fn compact_session( - &self, - session_id: &str, - runtime: ResolvedRuntimeConfig, - instructions: Option, - ) -> Result { - self.command() - .compact_session(session_id, &runtime, instructions.as_deref()) - .await - } - - pub async fn switch_mode( - &self, - session_id: &str, - from: astrcode_core::ModeId, - to: astrcode_core::ModeId, - ) -> Result { - self.command().switch_mode(session_id, from, to).await - } - - async fn session_phase(&self, session_id: &SessionId) -> Result { - if let Some(entry) = self.sessions.get(session_id) { - return entry.actor.state().current_phase(); - } - let meta = self - .event_store - .list_session_metas() - .await? - .into_iter() - .find(|meta| state::normalize_session_id(&meta.session_id) == session_id.as_str()) - .ok_or_else(|| SessionRuntimeError::SessionNotFound(session_id.to_string()))?; - Ok(meta.phase) - } - - pub(crate) async fn ensure_loaded_session( - &self, - session_id: &SessionId, - ) -> Result> { - if let Some(entry) = self.sessions.get(session_id) { - return Ok(Arc::clone(&entry.actor)); - } - let meta = self - .event_store - .list_session_metas() - .await? - .into_iter() - .find(|meta| state::normalize_session_id(&meta.session_id) == session_id.as_str()) - .ok_or_else(|| SessionRuntimeError::SessionNotFound(session_id.to_string()))?; - let recovered = self.event_store.recover_session(session_id).await?; - let actor = Arc::new(SessionActor::from_recovery( - session_id.clone(), - meta.working_dir, - AgentId::from(ROOT_AGENT_ID.to_string()), - Arc::clone(&self.event_store), - recovered, - )?); - let loaded = Arc::new(LoadedSession { - actor: Arc::clone(&actor), - }); - match self.sessions.entry(session_id.clone()) { - dashmap::mapref::entry::Entry::Occupied(entry) => Ok(Arc::clone(&entry.get().actor)), - dashmap::mapref::entry::Entry::Vacant(entry) => { - entry.insert(loaded); - Ok(actor) - }, - } - } - - pub(crate) async fn ensure_session_exists(&self, session_id: &SessionId) -> Result<()> { - if self.sessions.contains_key(session_id) { - return Ok(()); - } - let exists = self - .event_store - .list_session_metas() - .await? - .into_iter() - .any(|meta| state::normalize_session_id(&meta.session_id) == session_id.as_str()); - if exists { - Ok(()) - } else { - Err(SessionRuntimeError::SessionNotFound(session_id.to_string()).into()) - } - } -} - -fn normalize_path(value: &str) -> String { - value.replace('\\', "/").trim_end_matches('/').to_string() -} diff --git a/crates/session-runtime/src/observe/mod.rs b/crates/session-runtime/src/observe/mod.rs deleted file mode 100644 index b14b3650..00000000 --- a/crates/session-runtime/src/observe/mod.rs +++ /dev/null @@ -1,55 +0,0 @@ -//! 会话观测与事件过滤。 -//! -//! 从 `runtime/service/agent/` 和 `runtime/service/session/` 迁入 -//! observe/view 相关的类型定义。实际执行逻辑在 Phase 10 组合根接线。 -//! -//! 边界约束： -//! - `observe` 只承载 replay/live 订阅语义、scope/filter 与状态来源 -//! - 同步快照投影算法统一留在 `query` - -use astrcode_core::{ResolvedSubagentContextOverrides, SubRunHandle}; - -use crate::state::SessionSnapshot; - -/// 会话观测快照。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionObserveSnapshot { - pub state: SessionSnapshot, -} - -/// 事件过滤范围：按谱系层级过滤 sub-run 事件。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum SubRunEventScope { - /// 仅指定 sub-run 自身的事件。 - SelfOnly, - /// 指定 sub-run 的直接子节点事件。 - DirectChildren, - /// 指定 sub-run 的整棵子树事件。 - Subtree, -} - -/// 事件过滤参数。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionEventFilterSpec { - pub target_sub_run_id: String, - pub scope: SubRunEventScope, -} - -/// Sub-run 状态来源。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum SubRunStatusSource { - Live, - Durable, -} - -/// Sub-run 状态快照。 -#[derive(Debug, Clone)] -pub struct SubRunStatusSnapshot { - pub handle: SubRunHandle, - pub tool_call_id: Option, - pub source: SubRunStatusSource, - pub result: Option, - pub step_count: Option, - pub estimated_tokens: Option, - pub resolved_overrides: Option, -} diff --git a/crates/session-runtime/src/query/agent.rs b/crates/session-runtime/src/query/agent.rs deleted file mode 100644 index 04c0841d..00000000 --- a/crates/session-runtime/src/query/agent.rs +++ /dev/null @@ -1,191 +0,0 @@ -//! Agent 只读观察投影。 -//! -//! Why: `observe` 只负责读侧快照，不再暴露 input queue 的建议字段。 - -use astrcode_core::{AgentLifecycleStatus, AgentState, InputQueueProjection, LlmMessage}; - -use crate::query::text::{summarize_inline_text, truncate_text}; - -#[derive(Debug, Clone)] -pub struct AgentObserveSnapshot { - pub phase: astrcode_core::Phase, - pub turn_count: u32, - pub active_task: Option, - pub last_output_tail: Option, - pub last_turn_tail: Vec, -} - -pub(crate) fn build_agent_observe_snapshot( - lifecycle_status: AgentLifecycleStatus, - projected: &AgentState, - input_queue_projection: &InputQueueProjection, -) -> AgentObserveSnapshot { - AgentObserveSnapshot { - phase: projected.phase, - turn_count: projected.turn_count as u32, - active_task: active_task_summary(lifecycle_status, projected, input_queue_projection), - last_output_tail: extract_last_output(&projected.messages), - last_turn_tail: extract_last_turn_tail(&projected.messages), - } -} - -fn extract_last_output(messages: &[LlmMessage]) -> Option { - messages.iter().rev().find_map(|msg| match msg { - LlmMessage::Assistant { content, .. } if !content.is_empty() => truncate_text(content, 200), - _ => None, - }) -} - -fn active_task_summary( - lifecycle_status: AgentLifecycleStatus, - projected: &AgentState, - input_queue_projection: &InputQueueProjection, -) -> Option { - if !input_queue_projection.active_delivery_ids.is_empty() { - return extract_last_turn_tail(&projected.messages) - .into_iter() - .next(); - } - - if matches!( - lifecycle_status, - AgentLifecycleStatus::Pending | AgentLifecycleStatus::Running - ) { - return projected - .messages - .iter() - .rev() - .find_map(|message| match message { - LlmMessage::User { - content, - origin: astrcode_core::UserMessageOrigin::User, - } => summarize_inline_text(content, 120), - _ => None, - }); - } - - None -} - -fn extract_last_turn_tail(messages: &[LlmMessage]) -> Vec { - messages - .iter() - .rev() - .filter_map(|message| match message { - LlmMessage::User { content, .. } => summarize_inline_text(content, 120), - LlmMessage::Assistant { content, .. } => summarize_inline_text(content, 120), - LlmMessage::Tool { content, .. } => summarize_inline_text(content, 120), - }) - .take(3) - .collect::>() - .into_iter() - .rev() - .collect() -} - -#[cfg(test)] -mod tests { - use std::path::PathBuf; - - use astrcode_core::{AgentState, LlmMessage, ModeId, Phase, UserMessageOrigin}; - - use super::{build_agent_observe_snapshot, extract_last_turn_tail}; - - fn projected(messages: Vec, phase: Phase) -> AgentState { - AgentState { - session_id: "session-1".into(), - working_dir: PathBuf::from("/tmp"), - phase, - turn_count: 2, - mode_id: ModeId::code(), - messages, - last_assistant_at: None, - } - } - - #[test] - fn extract_last_turn_tail_returns_recent_message_tail() { - let tail = extract_last_turn_tail(&[ - LlmMessage::User { - content: "first".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "second".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-1".to_string(), - content: "third".to_string(), - }, - LlmMessage::Assistant { - content: "fourth".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]); - - assert_eq!(tail, vec!["second", "third", "fourth"]); - } - - #[test] - fn build_agent_observe_snapshot_prefers_latest_user_task_for_running_agent() { - let snapshot = build_agent_observe_snapshot( - astrcode_core::AgentLifecycleStatus::Running, - &projected( - vec![ - LlmMessage::User { - content: "请检查 input queue 路径".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "处理中".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ], - Phase::Streaming, - ), - &astrcode_core::InputQueueProjection::default(), - ); - - assert_eq!( - snapshot.active_task.as_deref(), - Some("请检查 input queue 路径") - ); - assert_eq!(snapshot.last_output_tail.as_deref(), Some("处理中")); - } - - #[test] - fn build_agent_observe_snapshot_uses_turn_tail_when_active_delivery_exists() { - let input_queue_projection = astrcode_core::InputQueueProjection { - active_delivery_ids: vec!["delivery-1".into()], - ..Default::default() - }; - - let snapshot = build_agent_observe_snapshot( - astrcode_core::AgentLifecycleStatus::Idle, - &projected( - vec![ - LlmMessage::User { - content: "继续整理父级需要的结论".to_string(), - origin: UserMessageOrigin::QueuedInput, - }, - LlmMessage::Assistant { - content: "正在合并结果".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ], - Phase::Thinking, - ), - &input_queue_projection, - ); - - assert_eq!( - snapshot.active_task.as_deref(), - Some("继续整理父级需要的结论") - ); - } -} diff --git a/crates/session-runtime/src/query/conversation/projection_support.rs b/crates/session-runtime/src/query/conversation/projection_support.rs deleted file mode 100644 index b71a8fa3..00000000 --- a/crates/session-runtime/src/query/conversation/projection_support.rs +++ /dev/null @@ -1,473 +0,0 @@ -use std::collections::HashSet; - -use super::*; - -mod plan_projection; - -impl ConversationStreamProjector { - pub fn new(last_sent_cursor: Option, facts: &ConversationStreamReplayFacts) -> Self { - let mut projector = ConversationDeltaProjector::new(); - projector.seed(&facts.seed_records); - let step_progress = durable_step_progress_from_blocks(projector.blocks()); - Self { - projector, - last_sent_cursor, - fallback_live_cursor: fallback_live_cursor(facts), - step_progress, - } - } - - pub fn last_sent_cursor(&self) -> Option<&str> { - self.last_sent_cursor.as_deref() - } - - pub fn step_progress(&self) -> &ConversationStepProgressFacts { - &self.step_progress - } - - pub fn seed_initial_replay( - &mut self, - facts: &ConversationStreamReplayFacts, - ) -> Vec { - let frames = facts.replay_frames.clone(); - self.observe_durable_frames(&frames); - frames - } - - pub fn project_durable_record( - &mut self, - record: &SessionEventRecord, - ) -> Vec { - let deltas = self.projector.project_record(record); - self.wrap_durable_deltas(record.event_id.as_str(), deltas) - } - - pub fn project_live_event(&mut self, event: &AgentEvent) -> Vec { - self.observe_live_event_step(event); - let cursor = self.live_cursor(); - self.projector - .project_live_event(event) - .into_iter() - .map(|delta| ConversationDeltaFrameFacts { - cursor: cursor.clone(), - step_progress: self.step_progress.clone(), - delta, - }) - .collect() - } - - pub fn recover_from( - &mut self, - recovered: &ConversationStreamReplayFacts, - ) -> Vec { - self.fallback_live_cursor = fallback_live_cursor(recovered); - let mut frames = Vec::new(); - for record in &recovered.replay.history { - frames.extend(self.project_durable_record(record)); - } - frames - } - - fn wrap_durable_deltas( - &mut self, - cursor: &str, - deltas: Vec, - ) -> Vec { - if deltas.is_empty() { - return Vec::new(); - } - let cursor_owned = cursor.to_string(); - self.last_sent_cursor = Some(cursor_owned.clone()); - deltas - .into_iter() - .map(|delta| { - self.observe_durable_delta_step(&delta); - ConversationDeltaFrameFacts { - cursor: cursor_owned.clone(), - step_progress: self.step_progress.clone(), - delta, - } - }) - .collect() - } - - fn observe_durable_frames(&mut self, frames: &[ConversationDeltaFrameFacts]) { - if let Some(cursor) = frames.last().map(|frame| frame.cursor.clone()) { - self.last_sent_cursor = Some(cursor); - } - if let Some(step_progress) = frames.last().map(|frame| frame.step_progress.clone()) { - self.step_progress = step_progress; - } - } - - fn live_cursor(&self) -> String { - self.last_sent_cursor - .clone() - .or_else(|| self.fallback_live_cursor.clone()) - .unwrap_or_else(|| "0.0".to_string()) - } -} - -pub(crate) fn project_conversation_snapshot( - records: &[SessionEventRecord], - phase: Phase, -) -> ConversationSnapshotFacts { - let mut projector = ConversationDeltaProjector::new(); - projector.seed(records); - let blocks = suppress_draft_approval_plan_leakage(projector.into_blocks()); - ConversationSnapshotFacts { - cursor: records.last().map(|record| record.event_id.clone()), - phase, - step_progress: durable_step_progress_from_blocks(&blocks), - blocks, - } -} - -pub(crate) fn build_conversation_replay_frames( - seed_records: &[SessionEventRecord], - history: &[SessionEventRecord], -) -> Vec { - let mut projector = ConversationDeltaProjector::new(); - projector.seed(seed_records); - let mut step_progress = durable_step_progress_from_blocks(projector.blocks()); - let mut raw_frames = Vec::new(); - for record in history { - raw_frames.extend( - projector - .project_record(record) - .into_iter() - .map(|delta| (record.event_id.clone(), delta)), - ); - } - let hidden_block_ids = draft_approval_leakage_hidden_block_ids(projector.blocks()); - - let mut frames = Vec::new(); - for (cursor, delta) in raw_frames { - if delta_block_id(&delta).is_some_and(|block_id| hidden_block_ids.contains(block_id)) { - continue; - } - observe_durable_delta_step(&mut step_progress, &delta); - frames.push(ConversationDeltaFrameFacts { - cursor, - step_progress: step_progress.clone(), - delta, - }); - } - frames -} - -fn suppress_draft_approval_plan_leakage( - blocks: Vec, -) -> Vec { - let hidden_block_ids = draft_approval_leakage_hidden_block_ids(&blocks); - blocks - .into_iter() - .filter(|block| !hidden_block_ids.contains(block_id(block))) - .collect() -} - -fn draft_approval_leakage_hidden_block_ids(blocks: &[ConversationBlockFacts]) -> HashSet { - let mut turn_facts = HashMap::::new(); - for block in blocks { - match block { - ConversationBlockFacts::User(block) => { - let Some(turn_id) = block.turn_id.as_deref() else { - continue; - }; - let facts = turn_facts - .entry(turn_id.to_string()) - .or_insert((false, false)); - if is_approval_like_turn_text(&block.markdown) { - facts.0 = true; - } - }, - ConversationBlockFacts::Plan(block) => { - let Some(turn_id) = block.turn_id.as_deref() else { - continue; - }; - let facts = turn_facts - .entry(turn_id.to_string()) - .or_insert((false, false)); - if block.status.as_deref() == Some("awaiting_approval") - || matches!( - block.event_kind, - ConversationPlanEventKind::Presented - | ConversationPlanEventKind::ReviewPending - ) - { - facts.1 = true; - } - }, - _ => {}, - } - } - - blocks - .iter() - .filter_map(|block| { - let turn_id = turn_id(block)?; - let (approval_like_user, has_review_plan) = turn_facts.get(turn_id).copied()?; - if !approval_like_user || !has_review_plan { - return None; - } - matches!( - block, - ConversationBlockFacts::Assistant(_) | ConversationBlockFacts::Thinking(_) - ) - .then(|| block_id(block).to_string()) - }) - .collect() -} - -fn delta_block_id(delta: &ConversationDeltaFacts) -> Option<&str> { - match delta { - ConversationDeltaFacts::AppendBlock { block } => Some(block_id(block.as_ref())), - ConversationDeltaFacts::PatchBlock { block_id, .. } - | ConversationDeltaFacts::CompleteBlock { block_id, .. } => Some(block_id.as_str()), - } -} - -fn turn_id(block: &ConversationBlockFacts) -> Option<&str> { - match block { - ConversationBlockFacts::User(block) => block.turn_id.as_deref(), - ConversationBlockFacts::Assistant(block) => block.turn_id.as_deref(), - ConversationBlockFacts::Thinking(block) => block.turn_id.as_deref(), - ConversationBlockFacts::PromptMetrics(block) => block.turn_id.as_deref(), - ConversationBlockFacts::Plan(block) => block.turn_id.as_deref(), - ConversationBlockFacts::ToolCall(block) => block.turn_id.as_deref(), - ConversationBlockFacts::Error(block) => block.turn_id.as_deref(), - ConversationBlockFacts::SystemNote(_) => None, - ConversationBlockFacts::ChildHandoff(_) => None, - } -} - -fn is_approval_like_turn_text(text: &str) -> bool { - let normalized_english = text - .split_whitespace() - .collect::>() - .join(" ") - .to_ascii_lowercase(); - for phrase in ["approved", "go ahead", "implement it"] { - if normalized_english == phrase - || (phrase != "implement it" && normalized_english.starts_with(&format!("{phrase} "))) - { - return true; - } - } - - let normalized_chinese = text - .chars() - .filter(|ch| { - !ch.is_whitespace() - && !matches!( - ch, - ',' | '.' - | '!' - | '?' - | ';' - | ':' - | '，' - | '。' - | '！' - | '？' - | '；' - | '：' - | '【' - | '】' - | '、' - ) - }) - .collect::(); - for phrase in ["同意", "可以", "按这个做", "开始实现"] { - let matched = if matches!(phrase, "同意" | "可以") { - normalized_chinese == phrase - } else { - normalized_chinese == phrase || normalized_chinese.starts_with(phrase) - }; - if matched { - return true; - } - } - - false -} - -pub(crate) fn fallback_live_cursor(facts: &ConversationStreamReplayFacts) -> Option { - facts - .seed_records - .last() - .map(|record| record.event_id.clone()) - .or_else(|| { - facts - .replay - .history - .last() - .map(|record| record.event_id.clone()) - }) -} - -pub(super) fn block_id(block: &ConversationBlockFacts) -> &str { - match block { - ConversationBlockFacts::User(block) => &block.id, - ConversationBlockFacts::Assistant(block) => &block.id, - ConversationBlockFacts::Thinking(block) => &block.id, - ConversationBlockFacts::PromptMetrics(block) => &block.id, - ConversationBlockFacts::Plan(block) => &block.id, - ConversationBlockFacts::ToolCall(block) => &block.id, - ConversationBlockFacts::Error(block) => &block.id, - ConversationBlockFacts::SystemNote(block) => &block.id, - ConversationBlockFacts::ChildHandoff(block) => &block.id, - } -} - -fn durable_step_progress_from_blocks( - blocks: &[ConversationBlockFacts], -) -> ConversationStepProgressFacts { - let mut step_progress = ConversationStepProgressFacts::default(); - for block in blocks { - observe_durable_block_step(&mut step_progress, block); - } - step_progress -} - -fn observe_durable_delta_step( - step_progress: &mut ConversationStepProgressFacts, - delta: &ConversationDeltaFacts, -) { - if let ConversationDeltaFacts::AppendBlock { block } = delta { - observe_durable_block_step(step_progress, block.as_ref()); - } -} - -fn observe_durable_block_step( - step_progress: &mut ConversationStepProgressFacts, - block: &ConversationBlockFacts, -) { - let step_cursor = match block { - ConversationBlockFacts::PromptMetrics(block) => Some(ConversationStepCursorFacts { - turn_id: block - .turn_id - .clone() - .unwrap_or_else(|| "session".to_string()), - step_index: block.step_index, - }), - ConversationBlockFacts::Assistant(block) => { - block - .step_index - .map(|step_index| ConversationStepCursorFacts { - turn_id: block - .turn_id - .clone() - .unwrap_or_else(|| "session".to_string()), - step_index, - }) - }, - _ => None, - }; - - if let Some(step_cursor) = step_cursor { - step_progress.durable = Some(step_cursor.clone()); - if let Some(live) = step_progress.live.as_ref() { - if live.turn_id != step_cursor.turn_id || live.step_index <= step_cursor.step_index { - step_progress.live = None; - } - } - } -} - -impl ConversationStreamProjector { - fn observe_durable_delta_step(&mut self, delta: &ConversationDeltaFacts) { - observe_durable_delta_step(&mut self.step_progress, delta); - } - - fn observe_live_event_step(&mut self, event: &AgentEvent) { - let turn_id = match event { - AgentEvent::ThinkingDelta { turn_id, .. } - | AgentEvent::ModelDelta { turn_id, .. } - | AgentEvent::ToolCallStart { turn_id, .. } - | AgentEvent::ToolCallDelta { turn_id, .. } - | AgentEvent::ToolCallResult { turn_id, .. } => Some(turn_id.as_str()), - AgentEvent::TurnDone { turn_id, .. } => { - if self - .step_progress - .live - .as_ref() - .is_some_and(|cursor| cursor.turn_id == *turn_id) - { - self.step_progress.live = None; - } - None - }, - _ => None, - }; - let Some(turn_id) = turn_id else { - return; - }; - - let step_index = self - .step_progress - .durable - .as_ref() - .filter(|cursor| cursor.turn_id == turn_id) - .map(|cursor| cursor.step_index.saturating_add(1)) - .unwrap_or(0); - let next_live = ConversationStepCursorFacts { - turn_id: turn_id.to_string(), - step_index, - }; - if self.step_progress.durable.as_ref().is_some_and(|cursor| { - cursor.turn_id == next_live.turn_id && cursor.step_index >= next_live.step_index - }) { - return; - } - if self.step_progress.live.as_ref() == Some(&next_live) { - return; - } - self.step_progress.live = Some(next_live); - } -} - -pub(super) fn should_suppress_tool_call_block(tool_name: &str, _input: Option<&Value>) -> bool { - matches!(tool_name, "upsertSessionPlan" | "exitPlanMode") -} - -pub(super) fn plan_block_from_tool_result( - turn_id: &str, - result: &ToolExecutionResult, -) -> Option { - plan_projection::plan_block_from_tool_result(turn_id, result) -} - -pub(super) fn tool_result_summary(result: &ToolExecutionResult) -> String { - const MAX_SUMMARY_CHARS: usize = 120; - - if result.ok { - if !result.output.trim().is_empty() { - crate::query::text::summarize_inline_text(&result.output, MAX_SUMMARY_CHARS) - .unwrap_or_else(|| format!("{} completed", result.tool_name)) - } else { - format!("{} completed", result.tool_name) - } - } else if let Some(error) = &result.error { - crate::query::text::summarize_inline_text(error, MAX_SUMMARY_CHARS) - .unwrap_or_else(|| format!("{} failed", result.tool_name)) - } else if !result.output.trim().is_empty() { - crate::query::text::summarize_inline_text(&result.output, MAX_SUMMARY_CHARS) - .unwrap_or_else(|| format!("{} failed", result.tool_name)) - } else { - format!("{} failed", result.tool_name) - } -} - -pub(super) fn classify_transcript_error(message: &str) -> ConversationTranscriptErrorKind { - let lower = message.to_lowercase(); - if lower.contains("context window") || lower.contains("token limit") { - ConversationTranscriptErrorKind::ContextWindowExceeded - } else if lower.contains("rate limit") { - ConversationTranscriptErrorKind::RateLimit - } else if lower.contains("tool") { - ConversationTranscriptErrorKind::ToolFatal - } else { - ConversationTranscriptErrorKind::ProviderError - } -} diff --git a/crates/session-runtime/src/query/conversation/tests.rs b/crates/session-runtime/src/query/conversation/tests.rs deleted file mode 100644 index 334aeeb1..00000000 --- a/crates/session-runtime/src/query/conversation/tests.rs +++ /dev/null @@ -1,1172 +0,0 @@ -use std::{path::Path, sync::Arc}; - -use astrcode_core::{ - AgentEvent, AgentEventContext, AgentLifecycleStatus, ChildAgentRef, ChildSessionNotification, - ChildSessionNotificationKind, DeleteProjectResult, EventStore, ParentDelivery, - ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, Phase, - PromptMetricsPayload, SessionEventRecord, SessionId, SessionMeta, SessionTurnAcquireResult, - StorageEvent, StorageEventPayload, StoredEvent, ToolExecutionResult, ToolOutputStream, - UserMessageOrigin, -}; -use async_trait::async_trait; -use chrono::Utc; -use serde_json::json; -use tokio::sync::broadcast; - -use super::{ - ConversationBlockFacts, ConversationBlockPatchFacts, ConversationBlockStatus, - ConversationChildHandoffKind, ConversationDeltaFacts, ConversationDeltaProjector, - ConversationPlanEventKind, ConversationStreamProjector, ConversationStreamReplayFacts, - build_conversation_replay_frames, fallback_live_cursor, project_conversation_snapshot, -}; -use crate::{ - SessionReplay, SessionRuntime, - state::sample_spawn_child_ref, - turn::test_support::{NoopMetrics, NoopPromptFactsProvider, test_kernel}, -}; - -#[test] -fn snapshot_projects_tool_call_block_with_streams_and_terminal_fields() { - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - input: json!({ "command": "pwd" }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallDelta { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - stream: ToolOutputStream::Stdout, - delta: "line-1\n".to_string(), - }, - ), - record( - "1.3", - AgentEvent::ToolCallDelta { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - stream: ToolOutputStream::Stderr, - delta: "warn\n".to_string(), - }, - ), - record( - "1.4", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - ok: false, - output: "line-1\n".to_string(), - error: Some("permission denied".to_string()), - metadata: Some(json!({ "path": "/tmp", "truncated": true })), - continuation: None, - duration_ms: 42, - truncated: true, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::CallingTool); - let tool = snapshot - .blocks - .iter() - .find_map(|block| match block { - ConversationBlockFacts::ToolCall(block) => Some(block), - _ => None, - }) - .expect("tool block should exist"); - - assert_eq!(tool.tool_call_id, "call-1"); - assert_eq!(tool.status, ConversationBlockStatus::Failed); - assert_eq!(tool.streams.stdout, "line-1\n"); - assert_eq!(tool.streams.stderr, "warn\n"); - assert_eq!(tool.error.as_deref(), Some("permission denied")); - assert_eq!(tool.duration_ms, Some(42)); - assert!(tool.truncated); -} - -#[test] -fn snapshot_preserves_failed_tool_status_after_turn_done() { - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - input: json!({ "command": "missing-command" }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - ok: false, - output: String::new(), - error: Some("command not found".to_string()), - metadata: None, - continuation: None, - duration_ms: 127, - truncated: false, - }, - }, - ), - record( - "1.3", - AgentEvent::TurnDone { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::Idle); - let tool = snapshot - .blocks - .iter() - .find_map(|block| match block { - ConversationBlockFacts::ToolCall(block) => Some(block), - _ => None, - }) - .expect("tool block should exist"); - - assert_eq!(tool.status, ConversationBlockStatus::Failed); - assert_eq!(tool.error.as_deref(), Some("command not found")); - assert_eq!(tool.duration_ms, Some(127)); -} - -#[test] -fn snapshot_projects_plan_blocks_in_durable_event_order() { - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-plan-save".to_string(), - tool_name: "upsertSessionPlan".to_string(), - input: json!({ - "title": "Cleanup crates", - "content": "# Plan: Cleanup crates" - }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-save".to_string(), - tool_name: "upsertSessionPlan".to_string(), - ok: true, - output: "updated session plan".to_string(), - error: None, - metadata: Some(json!({ - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "slug": "cleanup-crates", - "status": "draft", - "title": "Cleanup crates", - "updatedAt": "2026-04-19T09:00:00Z" - })), - continuation: None, - duration_ms: 7, - truncated: false, - }, - }, - ), - record( - "1.3", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-shell".to_string(), - tool_name: "shell_command".to_string(), - input: json!({ "command": "pwd" }), - }, - ), - record( - "1.4", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-shell".to_string(), - tool_name: "shell_command".to_string(), - ok: true, - output: "D:/GitObjectsOwn/Astrcode".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 9, - truncated: false, - }, - }, - ), - record( - "1.5", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-plan-exit".to_string(), - tool_name: "exitPlanMode".to_string(), - input: json!({}), - }, - ), - record( - "1.6", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-exit".to_string(), - tool_name: "exitPlanMode".to_string(), - ok: true, - output: "Before exiting plan mode, do one final self-review.".to_string(), - error: None, - metadata: Some(json!({ - "schema": "sessionPlanExitReviewPending", - "plan": { - "title": "Cleanup crates", - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md" - }, - "review": { - "kind": "final_review", - "checklist": [ - "Re-check assumptions against the code you already inspected." - ] - }, - "blockers": { - "missingHeadings": ["## Verification"], - "invalidSections": [] - } - })), - continuation: None, - duration_ms: 5, - truncated: false, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::Idle); - assert_eq!(snapshot.blocks.len(), 3); - assert!(matches!( - &snapshot.blocks[0], - ConversationBlockFacts::Plan(block) - if block.tool_call_id == "call-plan-save" - && block.event_kind == ConversationPlanEventKind::Saved - )); - assert!(matches!( - &snapshot.blocks[1], - ConversationBlockFacts::ToolCall(block) if block.tool_call_id == "call-shell" - )); - assert!(matches!( - &snapshot.blocks[2], - ConversationBlockFacts::Plan(block) - if block.tool_call_id == "call-plan-exit" - && block.event_kind == ConversationPlanEventKind::ReviewPending - )); -} - -#[test] -fn snapshot_keeps_task_write_as_normal_tool_call_block() { - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-task-write".to_string(), - tool_name: "taskWrite".to_string(), - input: json!({ - "items": [ - { - "content": "实现 authoritative task panel", - "status": "in_progress", - "activeForm": "正在实现 authoritative task panel" - } - ] - }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-task-write".to_string(), - tool_name: "taskWrite".to_string(), - ok: true, - output: "updated execution tasks".to_string(), - error: None, - metadata: Some(json!({ - "schema": "executionTaskSnapshot", - "owner": "root-agent", - "cleared": false, - "items": [ - { - "content": "实现 authoritative task panel", - "status": "in_progress", - "activeForm": "正在实现 authoritative task panel" - } - ] - })), - continuation: None, - duration_ms: 5, - truncated: false, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::CallingTool); - assert_eq!(snapshot.blocks.len(), 1); - assert!(matches!( - &snapshot.blocks[0], - ConversationBlockFacts::ToolCall(block) - if block.tool_name == "taskWrite" - && block.tool_call_id == "call-task-write" - && block.summary.as_deref() == Some("updated execution tasks") - )); - assert!( - snapshot - .blocks - .iter() - .all(|block| !matches!(block, ConversationBlockFacts::Plan(_))), - "taskWrite must not be projected onto the canonical plan surface" - ); -} - -#[test] -fn snapshot_suppresses_failed_upsert_session_plan_retry_noise() { - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-plan-save-failed".to_string(), - tool_name: "upsertSessionPlan".to_string(), - input: json!({ - "title": "Cleanup crates", - "content": "# Plan: Cleanup crates" - }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-save-failed".to_string(), - tool_name: "upsertSessionPlan".to_string(), - ok: false, - output: String::new(), - error: Some( - "validation error: session plan does not satisfy artifact contract \ - 'canonical-plan': missing headings [## Existing Code To Reuse]" - .to_string(), - ), - metadata: None, - continuation: None, - duration_ms: 1, - truncated: false, - }, - }, - ), - record( - "1.3", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-plan-save-success".to_string(), - tool_name: "upsertSessionPlan".to_string(), - input: json!({ - "title": "Cleanup crates", - "content": "# Plan: Cleanup crates\n\n## Existing Code To Reuse\n\n- None" - }), - }, - ), - record( - "1.4", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-save-success".to_string(), - tool_name: "upsertSessionPlan".to_string(), - ok: true, - output: "updated session plan".to_string(), - error: None, - metadata: Some(json!({ - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "slug": "cleanup-crates", - "status": "awaiting_approval", - "title": "Cleanup crates", - "updatedAt": "2026-04-22T01:26:30Z" - })), - continuation: None, - duration_ms: 7, - truncated: false, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::Idle); - assert_eq!(snapshot.blocks.len(), 1); - assert!(matches!( - &snapshot.blocks[0], - ConversationBlockFacts::Plan(block) - if block.tool_call_id == "call-plan-save-success" - && block.event_kind == ConversationPlanEventKind::Saved - && block.status.as_deref() == Some("awaiting_approval") - )); - assert!( - snapshot - .blocks - .iter() - .all(|block| !matches!(block, ConversationBlockFacts::ToolCall(_))), - "suppressed plan tools must not leak retry noise onto the generic tool surface" - ); -} - -#[test] -fn snapshot_suppresses_draft_approval_assistant_leakage_even_after_mode_switch() { - let records = vec![ - record( - "1.1", - AgentEvent::UserMessage { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - content: "按这个做，开始吧".to_string(), - }, - ), - record( - "1.2", - AgentEvent::AssistantMessage { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - content: "计划已呈递。这是一个纯只读总结任务……".to_string(), - reasoning_content: Some("先补全草稿，再正式呈递审批。".to_string()), - step_index: Some(0), - }, - ), - record( - "1.3", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-save".to_string(), - tool_name: "upsertSessionPlan".to_string(), - ok: true, - output: "updated session plan".to_string(), - error: None, - metadata: Some(json!({ - "schema": "sessionPlanResult", - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "title": "PROJECT_ARCHITECTURE.md 核心约束只读总结", - "status": "awaiting_approval", - "summary": "总结核心约束" - })), - continuation: None, - duration_ms: 11, - truncated: false, - }, - }, - ), - record( - "1.4", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-exit".to_string(), - tool_name: "exitPlanMode".to_string(), - ok: true, - output: "Before exiting plan mode, do one final self-review.".to_string(), - error: None, - metadata: Some(json!({ - "schema": "planModeExit", - "eventKind": "presented", - "plan": { - "title": "PROJECT_ARCHITECTURE.md 核心约束只读总结", - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "status": "awaiting_approval" - } - })), - continuation: None, - duration_ms: 5, - truncated: false, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::Idle); - - assert!(snapshot.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::User(block) - if block.turn_id.as_deref() == Some("turn-1") - ))); - assert!(snapshot.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::Plan(block) - if block.turn_id.as_deref() == Some("turn-1") - && block.status.as_deref() == Some("awaiting_approval") - ))); - assert!(snapshot.blocks.iter().all(|block| !matches!( - block, - ConversationBlockFacts::Assistant(block) - if block.turn_id.as_deref() == Some("turn-1") - ))); - assert!(snapshot.blocks.iter().all(|block| !matches!( - block, - ConversationBlockFacts::Thinking(block) - if block.turn_id.as_deref() == Some("turn-1") - ))); -} - -#[test] -fn replay_frames_suppress_draft_approval_assistant_leakage() { - let history = vec![ - record( - "1.1", - AgentEvent::UserMessage { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - content: "按这个做，开始吧".to_string(), - }, - ), - record( - "1.2", - AgentEvent::AssistantMessage { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - content: "计划已呈递。这是一个纯只读总结任务……".to_string(), - reasoning_content: Some("先补全草稿，再正式呈递审批。".to_string()), - step_index: Some(0), - }, - ), - record( - "1.3", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-save".to_string(), - tool_name: "upsertSessionPlan".to_string(), - ok: true, - output: "updated session plan".to_string(), - error: None, - metadata: Some(json!({ - "schema": "sessionPlanResult", - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "title": "PROJECT_ARCHITECTURE.md 核心约束只读总结", - "status": "awaiting_approval", - "summary": "总结核心约束" - })), - continuation: None, - duration_ms: 11, - truncated: false, - }, - }, - ), - record( - "1.4", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-plan-exit".to_string(), - tool_name: "exitPlanMode".to_string(), - ok: true, - output: "Before exiting plan mode, do one final self-review.".to_string(), - error: None, - metadata: Some(json!({ - "schema": "planModeExit", - "eventKind": "presented", - "plan": { - "title": "PROJECT_ARCHITECTURE.md 核心约束只读总结", - "planPath": "C:/Users/demo/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md", - "status": "awaiting_approval" - } - })), - continuation: None, - duration_ms: 5, - truncated: false, - }, - }, - ), - ]; - - let frames = build_conversation_replay_frames(&[], &history); - - assert!(frames.iter().any(|frame| matches!( - &frame.delta, - ConversationDeltaFacts::AppendBlock { block } - if matches!(block.as_ref(), ConversationBlockFacts::Plan(_)) - ))); - assert!(frames.iter().all(|frame| !matches!( - &frame.delta, - ConversationDeltaFacts::AppendBlock { block } - if matches!( - block.as_ref(), - ConversationBlockFacts::Assistant(block) - if block.turn_id.as_deref() == Some("turn-1") - ) - ))); - assert!(frames.iter().all(|frame| !matches!( - &frame.delta, - ConversationDeltaFacts::AppendBlock { block } - if matches!( - block.as_ref(), - ConversationBlockFacts::Thinking(block) - if block.turn_id.as_deref() == Some("turn-1") - ) - ))); -} - -#[test] -fn live_then_durable_tool_delta_dedupes_chunk_on_same_tool_block() { - let facts = sample_stream_replay_facts( - vec![record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - input: json!({ "command": "pwd" }), - }, - )], - vec![record( - "1.2", - AgentEvent::ToolCallDelta { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - stream: ToolOutputStream::Stdout, - delta: "line-1\n".to_string(), - }, - )], - ); - let mut stream = ConversationStreamProjector::new(Some("1.1".to_string()), &facts); - - let live_frames = stream.project_live_event(&AgentEvent::ToolCallDelta { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - stream: ToolOutputStream::Stdout, - delta: "line-1\n".to_string(), - }); - assert_eq!(live_frames.len(), 1); - - let replayed = stream.recover_from(&facts); - assert!( - replayed.is_empty(), - "durable replay should not duplicate the live-emitted chunk" - ); -} - -#[test] -fn snapshot_tracks_last_durable_step_cursor_from_prompt_metrics() { - let records = vec![ - record( - "1.1", - AgentEvent::PromptMetrics { - turn_id: Some("turn-1".to_string()), - agent: sample_agent_context(), - metrics: PromptMetricsPayload { - step_index: 0, - estimated_tokens: 1200, - context_window: 200_000, - effective_window: 180_000, - threshold_tokens: 144_000, - truncated_tool_results: 0, - provider_input_tokens: Some(800), - provider_output_tokens: Some(120), - cache_creation_input_tokens: Some(0), - cache_read_input_tokens: Some(640), - provider_cache_metrics_supported: true, - prompt_cache_reuse_hits: 2, - prompt_cache_reuse_misses: 0, - prompt_cache_unchanged_layers: Vec::new(), - prompt_cache_diagnostics: None, - }, - }, - ), - record( - "1.2", - AgentEvent::AssistantMessage { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - content: "first step".to_string(), - reasoning_content: None, - step_index: Some(0), - }, - ), - record( - "1.3", - AgentEvent::PromptMetrics { - turn_id: Some("turn-1".to_string()), - agent: sample_agent_context(), - metrics: PromptMetricsPayload { - step_index: 1, - estimated_tokens: 1600, - context_window: 200_000, - effective_window: 180_000, - threshold_tokens: 144_000, - truncated_tool_results: 0, - provider_input_tokens: Some(1100), - provider_output_tokens: Some(96), - cache_creation_input_tokens: Some(0), - cache_read_input_tokens: Some(896), - provider_cache_metrics_supported: true, - prompt_cache_reuse_hits: 3, - prompt_cache_reuse_misses: 0, - prompt_cache_unchanged_layers: Vec::new(), - prompt_cache_diagnostics: None, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::Streaming); - - assert_eq!( - snapshot - .step_progress - .durable - .as_ref() - .map(|cursor| (cursor.turn_id.as_str(), cursor.step_index,)), - Some(("turn-1", 1)) - ); - assert!(snapshot.step_progress.live.is_none()); -} - -#[test] -fn stream_projector_marks_live_step_after_last_durable_step() { - let facts = sample_stream_replay_facts( - vec![record( - "1.1", - AgentEvent::PromptMetrics { - turn_id: Some("turn-1".to_string()), - agent: sample_agent_context(), - metrics: PromptMetricsPayload { - step_index: 0, - estimated_tokens: 1200, - context_window: 200_000, - effective_window: 180_000, - threshold_tokens: 144_000, - truncated_tool_results: 0, - provider_input_tokens: Some(800), - provider_output_tokens: Some(120), - cache_creation_input_tokens: Some(0), - cache_read_input_tokens: Some(640), - provider_cache_metrics_supported: true, - prompt_cache_reuse_hits: 2, - prompt_cache_reuse_misses: 0, - prompt_cache_unchanged_layers: Vec::new(), - prompt_cache_diagnostics: None, - }, - }, - )], - Vec::new(), - ); - let mut stream = ConversationStreamProjector::new(Some("1.1".to_string()), &facts); - - let live_frames = stream.project_live_event(&AgentEvent::ModelDelta { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - delta: "next step".to_string(), - }); - - assert_eq!(live_frames.len(), 1); - assert_eq!( - live_frames[0] - .step_progress - .durable - .as_ref() - .map(|cursor| (cursor.turn_id.as_str(), cursor.step_index)), - Some(("turn-1", 0)) - ); - assert_eq!( - live_frames[0] - .step_progress - .live - .as_ref() - .map(|cursor| (cursor.turn_id.as_str(), cursor.step_index)), - Some(("turn-1", 1)) - ); -} - -#[test] -fn child_notification_patches_tool_block_and_appends_handoff_block() { - let mut projector = ConversationDeltaProjector::new(); - projector.seed(&[record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-spawn".to_string(), - tool_name: "spawn_agent".to_string(), - input: json!({ "task": "inspect" }), - }, - )]); - - let deltas = projector.project_record(&record( - "1.2", - AgentEvent::ChildSessionNotification { - turn_id: Some("turn-1".to_string()), - agent: sample_agent_context(), - notification: sample_child_notification(), - }, - )); - - assert!(deltas.iter().any(|delta| matches!( - delta, - ConversationDeltaFacts::PatchBlock { - block_id, - patch: ConversationBlockPatchFacts::ReplaceChildRef { .. }, - } if block_id == "tool:call-spawn:call" - ))); - assert!(deltas.iter().any(|delta| matches!( - delta, - ConversationDeltaFacts::AppendBlock { - block, - } if matches!( - block.as_ref(), - ConversationBlockFacts::ChildHandoff(block) - if block.handoff_kind == ConversationChildHandoffKind::Returned - ) - ))); -} - -#[test] -fn tool_result_continuation_alone_patches_tool_block() { - let child_ref = sample_child_ref(); - let records = vec![ - record( - "1.1", - AgentEvent::ToolCallStart { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - tool_call_id: "call-spawn".to_string(), - tool_name: "spawn".to_string(), - input: json!({ "description": "inspect" }), - }, - ), - record( - "1.2", - AgentEvent::ToolCallResult { - turn_id: "turn-1".to_string(), - agent: sample_agent_context(), - result: ToolExecutionResult { - tool_call_id: "call-spawn".to_string(), - tool_name: "spawn".to_string(), - ok: true, - output: "子 Agent 已启动：inspect".to_string(), - error: None, - metadata: Some(json!({ "schema": "subRunResult" })), - continuation: Some(astrcode_core::ExecutionContinuation::child_agent( - child_ref.clone(), - )), - duration_ms: 12, - truncated: false, - }, - }, - ), - ]; - - let snapshot = project_conversation_snapshot(&records, Phase::CallingTool); - let tool = snapshot - .blocks - .iter() - .find_map(|block| match block { - ConversationBlockFacts::ToolCall(block) => Some(block), - _ => None, - }) - .expect("tool block should exist"); - - assert_eq!(tool.tool_call_id, "call-spawn"); - assert_eq!(tool.child_ref.as_ref(), Some(&child_ref)); -} - -#[tokio::test] -async fn runtime_query_builds_snapshot_and_stream_replay_facts() { - let event_store = Arc::new(ReplayOnlyEventStore::new(vec![ - stored( - 1, - storage_event( - Some("turn-1"), - StorageEventPayload::UserMessage { - content: "inspect repo".to_string(), - origin: UserMessageOrigin::User, - timestamp: Utc::now(), - }, - ), - ), - stored( - 2, - storage_event( - Some("turn-1"), - StorageEventPayload::ToolCall { - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - args: json!({ "command": "pwd" }), - }, - ), - ), - stored( - 3, - storage_event( - Some("turn-1"), - StorageEventPayload::ToolCallDelta { - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - stream: ToolOutputStream::Stdout, - delta: "D:/GitObjectsOwn/Astrcode\n".to_string(), - }, - ), - ), - stored( - 4, - storage_event( - Some("turn-1"), - StorageEventPayload::ToolResult { - tool_call_id: "call-1".to_string(), - tool_name: "shell_command".to_string(), - output: "D:/GitObjectsOwn/Astrcode\n".to_string(), - success: true, - error: None, - metadata: None, - continuation: None, - duration_ms: 7, - }, - ), - ), - stored( - 5, - storage_event( - Some("turn-1"), - StorageEventPayload::AssistantFinal { - content: "done".to_string(), - reasoning_content: Some("think".to_string()), - reasoning_signature: None, - step_index: None, - timestamp: None, - }, - ), - ), - ])); - let runtime = SessionRuntime::new( - Arc::new(test_kernel(8192)), - Arc::new(NoopPromptFactsProvider), - event_store, - Arc::new(NoopMetrics), - ); - - let snapshot = runtime - .conversation_snapshot("session-1") - .await - .expect("snapshot should build"); - assert!(snapshot.blocks.iter().any(|block| matches!( - block, - ConversationBlockFacts::ToolCall(block) - if block.tool_call_id == "call-1" - ))); - - let transcript = runtime - .session_transcript_snapshot("session-1") - .await - .expect("transcript snapshot should build"); - assert!(transcript.records.len() > 4); - let cursor = transcript.records[3].event_id.clone(); - - let replay = runtime - .conversation_stream_replay("session-1", Some(cursor.as_str())) - .await - .expect("replay facts should build"); - assert_eq!( - replay - .seed_records - .last() - .map(|record| record.event_id.as_str()), - Some(cursor.as_str()) - ); - assert!(!replay.replay_frames.is_empty()); - assert_eq!( - fallback_live_cursor(&replay).as_deref(), - Some(cursor.as_str()) - ); -} - -fn sample_stream_replay_facts( - seed_records: Vec, - history: Vec, -) -> ConversationStreamReplayFacts { - let (_, receiver) = broadcast::channel(8); - let (_, live_receiver) = broadcast::channel(8); - ConversationStreamReplayFacts { - cursor: history.last().map(|record| record.event_id.clone()), - phase: Phase::CallingTool, - seed_records: seed_records.clone(), - replay_frames: build_conversation_replay_frames(&seed_records, &history), - replay: SessionReplay { - history, - receiver, - live_receiver, - }, - } -} - -fn sample_agent_context() -> AgentEventContext { - AgentEventContext::root_execution("agent-root", "default") -} - -fn sample_child_ref() -> ChildAgentRef { - sample_spawn_child_ref(AgentLifecycleStatus::Running) -} - -fn sample_child_notification() -> ChildSessionNotification { - ChildSessionNotification { - notification_id: "child-note-1".to_string().into(), - child_ref: sample_child_ref(), - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: Some("call-spawn".to_string().into()), - delivery: Some(ParentDelivery { - idempotency_key: "delivery-1".to_string(), - origin: ParentDeliveryOrigin::Explicit, - terminal_semantics: ParentDeliveryTerminalSemantics::Terminal, - source_turn_id: Some("turn-1".to_string()), - payload: ParentDeliveryPayload::Progress( - astrcode_core::ProgressParentDeliveryPayload { - message: "child finished".to_string(), - }, - ), - }), - } -} - -fn record(event_id: &str, event: AgentEvent) -> SessionEventRecord { - SessionEventRecord { - event_id: event_id.to_string(), - event, - } -} - -fn stored(storage_seq: u64, event: StorageEvent) -> StoredEvent { - StoredEvent { storage_seq, event } -} - -fn storage_event(turn_id: Option<&str>, payload: StorageEventPayload) -> StorageEvent { - StorageEvent { - turn_id: turn_id.map(ToString::to_string), - agent: sample_agent_context(), - payload, - } -} - -struct ReplayOnlyEventStore { - events: Vec, -} - -impl ReplayOnlyEventStore { - fn new(events: Vec) -> Self { - Self { events } - } -} - -struct StubTurnLease; - -impl astrcode_core::SessionTurnLease for StubTurnLease {} - -#[async_trait] -impl EventStore for ReplayOnlyEventStore { - async fn ensure_session( - &self, - _session_id: &SessionId, - _working_dir: &Path, - ) -> astrcode_core::Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &SessionId, - _event: &astrcode_core::StorageEvent, - ) -> astrcode_core::Result { - panic!("append should not be called in replay-only test store"); - } - - async fn replay(&self, _session_id: &SessionId) -> astrcode_core::Result> { - Ok(self.events.clone()) - } - - async fn try_acquire_turn( - &self, - _session_id: &SessionId, - _turn_id: &str, - ) -> astrcode_core::Result { - Ok(SessionTurnAcquireResult::Acquired(Box::new(StubTurnLease))) - } - - async fn list_sessions(&self) -> astrcode_core::Result> { - Ok(vec![SessionId::from("session-1".to_string())]) - } - - async fn list_session_metas(&self) -> astrcode_core::Result> { - Ok(vec![SessionMeta { - session_id: "session-1".to_string(), - working_dir: ".".to_string(), - display_name: "session-1".to_string(), - title: "session-1".to_string(), - created_at: Utc::now(), - updated_at: Utc::now(), - parent_session_id: None, - parent_storage_seq: None, - phase: Phase::Done, - }]) - } - - async fn delete_session(&self, _session_id: &SessionId) -> astrcode_core::Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> astrcode_core::Result { - Ok(DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } -} diff --git a/crates/session-runtime/src/query/input_queue.rs b/crates/session-runtime/src/query/input_queue.rs deleted file mode 100644 index f4b9be5a..00000000 --- a/crates/session-runtime/src/query/input_queue.rs +++ /dev/null @@ -1,167 +0,0 @@ -//! input queue 相关只读恢复投影。 -//! -//! Why: input queue 的 durable 恢复规则属于只读投影，不应该散落在 -//! `application` 的父子编排流程里重复实现。 - -use std::collections::{HashMap, HashSet}; - -use astrcode_core::{StorageEventPayload, StoredEvent}; -use astrcode_kernel::PendingParentDelivery; - -use crate::state::replay_input_queue_projection_index; - -pub fn recoverable_parent_deliveries(events: &[StoredEvent]) -> Vec { - let projection_index = replay_input_queue_projection_index(events); - let mut recoverable_by_agent = HashMap::>::new(); - for (agent_id, projection) in projection_index { - let active_ids = projection - .active_delivery_ids - .into_iter() - .collect::>(); - let recoverable = projection - .pending_delivery_ids - .into_iter() - .filter(|delivery_id| !active_ids.contains(delivery_id)) - .map(|delivery_id| delivery_id.to_string()) - .collect::>(); - if !recoverable.is_empty() { - recoverable_by_agent.insert(agent_id.to_string(), recoverable); - } - } - - let mut recovered = Vec::new(); - let mut seen = HashSet::new(); - let queued_at_by_delivery = events - .iter() - .filter_map(|stored| match &stored.event.payload { - StorageEventPayload::AgentInputQueued { payload } => Some(( - payload.envelope.delivery_id.clone(), - payload.envelope.queued_at, - )), - _ => None, - }) - .collect::>(); - for stored in events { - let StorageEventPayload::ChildSessionNotification { notification, .. } = - &stored.event.payload - else { - continue; - }; - let Some(parent_agent_id) = notification.child_ref.parent_agent_id() else { - continue; - }; - let Some(recoverable_ids) = recoverable_by_agent.get(parent_agent_id.as_str()) else { - continue; - }; - if !recoverable_ids.contains(notification.notification_id.as_str()) { - continue; - } - if !seen.insert(notification.notification_id.clone()) { - continue; - } - let Some(parent_turn_id) = stored.event.turn_id().map(ToString::to_string) else { - continue; - }; - recovered.push(PendingParentDelivery { - delivery_id: notification.notification_id.to_string(), - parent_session_id: notification.child_ref.session_id().to_string(), - parent_turn_id, - queued_at_ms: queued_at_by_delivery - .get(¬ification.notification_id) - .map(|queued_at| queued_at.timestamp_millis()) - .unwrap_or_default(), - notification: notification.clone(), - }); - } - recovered -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, AgentLifecycleStatus, AgentTurnOutcome, ChildAgentRef, - ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNotification, - ChildSessionNotificationKind, InputQueuedPayload, ParentExecutionRef, QueuedInputEnvelope, - StorageEvent, StorageEventPayload, StoredEvent, - }; - - use super::recoverable_parent_deliveries; - - #[test] - fn recoverable_parent_deliveries_skips_active_batch_entries() { - let notification = ChildSessionNotification { - notification_id: "delivery-1".to_string().into(), - child_ref: ChildAgentRef { - identity: ChildExecutionIdentity { - agent_id: "agent-child".to_string().into(), - session_id: "session-parent".to_string().into(), - sub_run_id: "subrun-child".to_string().into(), - }, - parent: ParentExecutionRef { - parent_agent_id: Some("agent-parent".to_string().into()), - parent_sub_run_id: Some("subrun-parent".to_string().into()), - }, - lineage_kind: ChildSessionLineageKind::Spawn, - status: AgentLifecycleStatus::Idle, - open_session_id: "session-child".to_string().into(), - }, - kind: ChildSessionNotificationKind::Delivered, - source_tool_call_id: None, - delivery: Some(astrcode_core::ParentDelivery { - idempotency_key: "delivery-1".to_string(), - origin: astrcode_core::ParentDeliveryOrigin::Explicit, - terminal_semantics: astrcode_core::ParentDeliveryTerminalSemantics::Terminal, - source_turn_id: Some("turn-parent".to_string()), - payload: astrcode_core::ParentDeliveryPayload::Completed( - astrcode_core::CompletedParentDeliveryPayload { - message: "done".to_string(), - findings: Vec::new(), - artifacts: Vec::new(), - }, - ), - }), - }; - let events = vec![ - StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-parent".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::ChildSessionNotification { - notification: notification.clone(), - timestamp: Some(chrono::Utc::now()), - }, - }, - }, - StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("turn-parent".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: notification.notification_id.clone(), - from_agent_id: notification.child_ref.agent_id().to_string(), - to_agent_id: "agent-parent".to_string(), - message: "done".to_string(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Idle, - sender_last_turn_outcome: Some(AgentTurnOutcome::Completed), - sender_open_session_id: notification - .child_ref - .open_session_id - .to_string(), - }, - }, - }, - }, - }, - ]; - - let recovered = recoverable_parent_deliveries(&events); - - assert_eq!(recovered.len(), 1); - assert_eq!(recovered[0].delivery_id, "delivery-1"); - } -} diff --git a/crates/session-runtime/src/query/mod.rs b/crates/session-runtime/src/query/mod.rs deleted file mode 100644 index 4d5affbc..00000000 --- a/crates/session-runtime/src/query/mod.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! 会话查询视图。 -//! -//! 这些类型表达的是 session-runtime 对外提供的只读快照， -//! 让 `application` 只消费稳定视图，不再自己拼装会话真相。 -//! 异步等待 turn 终态的 watcher 归 `turn/` 拥有，`query/` 只保留纯读 / replay / snapshot 语义。 - -mod agent; -mod conversation; -mod input_queue; -mod replay; -mod service; -mod subrun; -mod terminal; -mod text; -mod transcript; -pub(crate) mod turn; - -pub use agent::AgentObserveSnapshot; -pub use conversation::{ - ConversationAssistantBlockFacts, ConversationBlockFacts, ConversationBlockPatchFacts, - ConversationBlockStatus, ConversationChildHandoffBlockFacts, ConversationChildHandoffKind, - ConversationDeltaFacts, ConversationDeltaFrameFacts, ConversationDeltaProjector, - ConversationErrorBlockFacts, ConversationPlanBlockFacts, ConversationPlanBlockersFacts, - ConversationPlanEventKind, ConversationPlanReviewFacts, ConversationPlanReviewKind, - ConversationPromptMetricsBlockFacts, ConversationSnapshotFacts, ConversationStepCursorFacts, - ConversationStepProgressFacts, ConversationStreamProjector, ConversationStreamReplayFacts, - ConversationSystemNoteBlockFacts, ConversationSystemNoteKind, ConversationThinkingBlockFacts, - ConversationTranscriptErrorKind, ConversationUserBlockFacts, ToolCallBlockFacts, - ToolCallStreamsFacts, -}; -pub use input_queue::recoverable_parent_deliveries; -pub(crate) use service::SessionQueries; -pub use terminal::{LastCompactMetaSnapshot, SessionControlStateSnapshot, SessionModeSnapshot}; -pub use transcript::{SessionReplay, SessionTranscriptSnapshot}; -pub use turn::{ProjectedTurnOutcome, TurnTerminalSnapshot}; diff --git a/crates/session-runtime/src/query/replay.rs b/crates/session-runtime/src/query/replay.rs deleted file mode 100644 index 16db1c79..00000000 --- a/crates/session-runtime/src/query/replay.rs +++ /dev/null @@ -1,72 +0,0 @@ -use std::time::Instant; - -use astrcode_core::{Result, SessionId, replay_records}; - -use crate::{SessionReplay, SessionRuntime, SessionTranscriptSnapshot}; - -impl SessionRuntime { - pub async fn session_transcript_snapshot( - &self, - session_id: &str, - ) -> Result { - let started_at = Instant::now(); - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let result = async { - let records = self.replay_history(&session_id, None).await?; - let phase = self.session_phase(&session_id).await?; - Ok(SessionTranscriptSnapshot { - cursor: records.last().map(|record| record.event_id.clone()), - records, - phase, - }) - } - .await; - self.metrics - .record_session_rehydrate(started_at.elapsed().as_millis() as u64, result.is_ok()); - result - } - - pub async fn session_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> Result { - let started_at = Instant::now(); - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let result = async { - let actor = self.ensure_loaded_session(&session_id).await?; - let history = self.replay_history(&session_id, last_event_id).await?; - Ok(SessionReplay { - history, - receiver: actor.state().broadcaster.subscribe(), - live_receiver: actor.state().subscribe_live(), - }) - } - .await; - let recovered_events = result - .as_ref() - .map(|replay| replay.history.len() as u64) - .unwrap_or(0); - self.metrics.record_sse_catch_up( - started_at.elapsed().as_millis() as u64, - result.is_ok(), - last_event_id.is_some(), - recovered_events, - ); - result - } - - pub(crate) async fn replay_history( - &self, - session_id: &SessionId, - last_event_id: Option<&str>, - ) -> Result> { - let actor = self.ensure_loaded_session(session_id).await?; - if let Some(history) = actor.state().recent_records_after(last_event_id)? { - return Ok(history); - } - - let stored = self.event_store.replay(session_id).await?; - Ok(replay_records(&stored, last_event_id)) - } -} diff --git a/crates/session-runtime/src/query/service.rs b/crates/session-runtime/src/query/service.rs deleted file mode 100644 index 000516f8..00000000 --- a/crates/session-runtime/src/query/service.rs +++ /dev/null @@ -1,493 +0,0 @@ -use std::sync::Arc; - -use astrcode_core::{ - AgentLifecycleStatus, ChildSessionNode, Result, SessionEventRecord, SessionId, - StorageEventPayload, StoredEvent, TaskSnapshot, -}; - -use crate::{ - AgentObserveSnapshot, ConversationSnapshotFacts, ConversationStreamReplayFacts, - LastCompactMetaSnapshot, SessionControlStateSnapshot, SessionModeSnapshot, SessionReplay, - SessionRuntime, SessionState, SubRunStatusSnapshot, - query::{ - agent::build_agent_observe_snapshot, - conversation::{build_conversation_replay_frames, project_conversation_snapshot}, - input_queue::recoverable_parent_deliveries, - subrun::project_durable_subrun_status_snapshot, - }, -}; - -pub(crate) struct SessionQueries<'a> { - runtime: &'a SessionRuntime, -} - -impl<'a> SessionQueries<'a> { - pub fn new(runtime: &'a SessionRuntime) -> Self { - Self { runtime } - } - - pub async fn observe( - &self, - session_id: &SessionId, - ) -> Result { - let actor = self.runtime.ensure_loaded_session(session_id).await?; - Ok(crate::observe::SessionObserveSnapshot { - state: actor.snapshot(), - }) - } - - pub async fn session_state(&self, session_id: &SessionId) -> Result> { - let actor = self.runtime.ensure_loaded_session(session_id).await?; - Ok(Arc::clone(actor.state())) - } - - pub async fn session_control_state( - &self, - session_id: &str, - ) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - let last_compact_meta = actor - .state() - .snapshot_recent_stored_events()? - .into_iter() - .rev() - .find_map(|stored| match stored.event.payload { - StorageEventPayload::CompactApplied { trigger, meta, .. } => { - Some(LastCompactMetaSnapshot { trigger, meta }) - }, - _ => None, - }); - Ok(SessionControlStateSnapshot { - phase: actor.state().current_phase()?, - active_turn_id: actor.turn_runtime().active_turn_id_snapshot()?, - manual_compact_pending: actor.turn_runtime().has_pending_manual_compact()?, - compacting: actor.turn_runtime().compacting(), - last_compact_meta, - current_mode_id: actor.state().current_mode_id()?, - last_mode_changed_at: actor.state().last_mode_changed_at()?, - }) - } - - pub async fn session_child_nodes(&self, session_id: &str) -> Result> { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - actor.state().list_child_session_nodes() - } - - pub async fn session_mode_state(&self, session_id: &str) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - Ok(SessionModeSnapshot { - current_mode_id: actor.state().current_mode_id()?, - last_mode_changed_at: actor.state().last_mode_changed_at()?, - }) - } - - pub async fn session_working_dir(&self, session_id: &str) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - Ok(actor.working_dir().to_string()) - } - - pub async fn active_task_snapshot( - &self, - session_id: &str, - owner: &str, - ) -> Result> { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - actor.state().active_tasks_for(owner) - } - - pub async fn stored_events(&self, session_id: &SessionId) -> Result> { - self.runtime.ensure_session_exists(session_id).await?; - self.runtime.event_store.replay(session_id).await - } - - pub async fn durable_subrun_status_snapshot( - &self, - parent_session_id: &str, - requested_subrun_id: &str, - ) -> Result> { - for meta in self.runtime.list_session_metas().await? { - if meta.parent_session_id.as_deref() != Some(parent_session_id) { - continue; - } - - let child_session_id = SessionId::from(meta.session_id.clone()); - let stored_events = self.stored_events(&child_session_id).await?; - if let Some(snapshot) = project_durable_subrun_status_snapshot( - parent_session_id, - meta.session_id.as_str(), - requested_subrun_id, - &stored_events, - ) { - return Ok(Some(snapshot)); - } - } - - Ok(None) - } - - pub async fn observe_agent_session( - &self, - open_session_id: &str, - target_agent_id: &str, - lifecycle_status: AgentLifecycleStatus, - ) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(open_session_id)); - let session_state = self.session_state(&session_id).await?; - let projected = session_state.snapshot_projected_state()?; - let input_queue_projection = - session_state.input_queue_projection_for_agent(target_agent_id)?; - Ok(build_agent_observe_snapshot( - lifecycle_status, - &projected, - &input_queue_projection, - )) - } - - pub async fn conversation_snapshot( - &self, - session_id: &str, - ) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let records = self.runtime.replay_history(&session_id, None).await?; - let phase = self.runtime.session_phase(&session_id).await?; - Ok(project_conversation_snapshot(&records, phase)) - } - - pub async fn conversation_stream_replay( - &self, - session_id: &str, - last_event_id: Option<&str>, - ) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.runtime.ensure_loaded_session(&session_id).await?; - let full_history = self.runtime.replay_history(&session_id, None).await?; - let (seed_records, replay_history) = split_records_at_cursor(full_history, last_event_id); - let phase = self.runtime.session_phase(&session_id).await?; - - Ok(ConversationStreamReplayFacts { - cursor: replay_history.last().map(|record| record.event_id.clone()), - phase, - replay_frames: build_conversation_replay_frames(&seed_records, &replay_history), - seed_records, - replay: SessionReplay { - history: replay_history, - receiver: actor.state().broadcaster.subscribe(), - live_receiver: actor.state().subscribe_live(), - }, - }) - } - - pub async fn pending_delivery_ids_for_agent( - &self, - session_id: &str, - agent_id: &str, - ) -> Result> { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let session_state = self.session_state(&session_id).await?; - Ok(session_state - .input_queue_projection_for_agent(agent_id)? - .pending_delivery_ids - .into_iter() - .map(Into::into) - .collect()) - } - - pub async fn recoverable_parent_deliveries( - &self, - parent_session_id: &str, - ) -> Result> { - let session_id = SessionId::from(crate::state::normalize_session_id(parent_session_id)); - let events = self.stored_events(&session_id).await?; - Ok(recoverable_parent_deliveries(&events)) - } -} - -fn split_records_at_cursor( - mut records: Vec, - last_event_id: Option<&str>, -) -> (Vec, Vec) { - let Some(last_event_id) = last_event_id else { - return (Vec::new(), records); - }; - - let Some(index) = records - .iter() - .position(|record| record.event_id == last_event_id) - else { - return (Vec::new(), records); - }; - - let replay_records = records.split_off(index + 1); - (records, replay_records) -} - -#[cfg(test)] -mod tests { - use std::{ - path::Path, - sync::{ - Arc, Mutex, - atomic::{AtomicU64, AtomicUsize, Ordering}, - }, - }; - - use astrcode_core::{ - AgentEventContext, DeleteProjectResult, EventStore, ExecutionTaskItem, ExecutionTaskStatus, - Phase, Result, SessionEventRecord, SessionId, SessionMeta, SessionTurnAcquireResult, - StorageEvent, StorageEventPayload, StoredEvent, UserMessageOrigin, - }; - use async_trait::async_trait; - - use super::split_records_at_cursor; - use crate::turn::test_support::{StubEventStore, test_runtime}; - - #[test] - fn split_records_at_cursor_keeps_seed_prefix_and_replay_suffix() { - let records = vec![ - SessionEventRecord { - event_id: "1.0".to_string(), - event: astrcode_core::AgentEvent::SessionStarted { - session_id: "session-1".to_string(), - }, - }, - SessionEventRecord { - event_id: "2.0".to_string(), - event: astrcode_core::AgentEvent::SessionStarted { - session_id: "session-1".to_string(), - }, - }, - SessionEventRecord { - event_id: "3.0".to_string(), - event: astrcode_core::AgentEvent::SessionStarted { - session_id: "session-1".to_string(), - }, - }, - ]; - - let (seed, replay) = split_records_at_cursor(records, Some("2.0")); - - assert_eq!( - seed.iter() - .map(|record| record.event_id.as_str()) - .collect::>(), - vec!["1.0", "2.0"] - ); - assert_eq!( - replay - .iter() - .map(|record| record.event_id.as_str()) - .collect::>(), - vec!["3.0"] - ); - } - - #[tokio::test] - async fn conversation_stream_replay_reuses_single_history_load_when_cache_is_truncated() { - let event_store = Arc::new(CountingEventStore::with_events(build_large_history())); - let runtime = test_runtime(event_store.clone()); - - runtime - .get_session_state(&SessionId::from("1".to_string())) - .await - .expect("state should load from durable history"); - event_store.reset_replay_count(); - - let replay = runtime - .conversation_stream_replay("session-1", Some("1.0")) - .await - .expect("replay facts should build"); - - assert_eq!( - replay - .seed_records - .last() - .map(|record| record.event_id.as_str()), - Some("1.0") - ); - assert_eq!( - event_store.replay_count(), - 1, - "truncated cache should trigger only one durable replay for stream recovery" - ); - } - - #[tokio::test] - async fn active_task_snapshot_reads_authoritative_owner_snapshot() { - let runtime = test_runtime(Arc::new(StubEventStore::default())); - let session = runtime - .create_session(".") - .await - .expect("session should be created"); - let session_id = session.session_id.clone(); - let state = runtime - .get_session_state(&session_id.clone().into()) - .await - .expect("state should load"); - - state - .replace_active_task_snapshot(astrcode_core::TaskSnapshot { - owner: "owner-a".to_string(), - items: vec![ExecutionTaskItem { - content: "实现 prompt 注入".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在实现 prompt 注入".to_string()), - }], - }) - .expect("task snapshot should store"); - - let snapshot = runtime - .query() - .active_task_snapshot(&session_id, "owner-a") - .await - .expect("query should succeed") - .expect("snapshot should exist"); - - assert_eq!(snapshot.owner, "owner-a"); - assert_eq!(snapshot.items[0].content, "实现 prompt 注入"); - } - - fn build_large_history() -> Vec { - let mut events = Vec::with_capacity(16_386); - events.push(StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: None, - agent: AgentEventContext::default(), - payload: StorageEventPayload::SessionStart { - session_id: "1".to_string(), - timestamp: chrono::Utc::now(), - working_dir: ".".to_string(), - parent_session_id: None, - parent_storage_seq: None, - }, - }, - }); - for storage_seq in 2..=16_386 { - events.push(StoredEvent { - storage_seq, - event: StorageEvent { - turn_id: Some(format!("turn-{storage_seq}")), - agent: AgentEventContext::default(), - payload: StorageEventPayload::UserMessage { - content: format!("message {storage_seq}"), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - }, - }); - } - events - } - - #[derive(Debug, Default)] - struct CountingEventStore { - events: Mutex>, - next_seq: AtomicU64, - replay_count: AtomicUsize, - } - - impl CountingEventStore { - fn with_events(events: Vec) -> Self { - let next_seq = events - .last() - .map(|stored| stored.storage_seq) - .unwrap_or_default(); - Self { - events: Mutex::new(events), - next_seq: AtomicU64::new(next_seq), - replay_count: AtomicUsize::new(0), - } - } - - fn replay_count(&self) -> usize { - self.replay_count.load(Ordering::SeqCst) - } - - fn reset_replay_count(&self) { - self.replay_count.store(0, Ordering::SeqCst); - } - } - - #[async_trait] - impl EventStore for CountingEventStore { - async fn ensure_session(&self, _session_id: &SessionId, _working_dir: &Path) -> Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &SessionId, - event: &StorageEvent, - ) -> Result { - let stored = StoredEvent { - storage_seq: self.next_seq.fetch_add(1, Ordering::SeqCst) + 1, - event: event.clone(), - }; - self.events - .lock() - .expect("counting event store should lock") - .push(stored.clone()); - Ok(stored) - } - - async fn replay(&self, _session_id: &SessionId) -> Result> { - self.replay_count.fetch_add(1, Ordering::SeqCst); - Ok(self - .events - .lock() - .expect("counting event store should lock") - .clone()) - } - - async fn try_acquire_turn( - &self, - _session_id: &SessionId, - _turn_id: &str, - ) -> Result { - Ok(SessionTurnAcquireResult::Busy( - astrcode_core::SessionTurnBusy { - turn_id: "busy".to_string(), - owner_pid: 1, - acquired_at: chrono::Utc::now(), - }, - )) - } - - async fn list_sessions(&self) -> Result> { - Ok(vec![SessionId::from("1".to_string())]) - } - - async fn list_session_metas(&self) -> Result> { - Ok(vec![SessionMeta { - session_id: "1".to_string(), - working_dir: ".".to_string(), - display_name: "session-1".to_string(), - title: "session-1".to_string(), - created_at: chrono::Utc::now(), - updated_at: chrono::Utc::now(), - parent_session_id: None, - parent_storage_seq: None, - phase: Phase::Idle, - }]) - } - - async fn delete_session(&self, _session_id: &SessionId) -> Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> Result { - Ok(DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } - } -} diff --git a/crates/session-runtime/src/query/subrun.rs b/crates/session-runtime/src/query/subrun.rs deleted file mode 100644 index d3d21997..00000000 --- a/crates/session-runtime/src/query/subrun.rs +++ /dev/null @@ -1,298 +0,0 @@ -use astrcode_core::{ - AgentEventContext, AgentLifecycleStatus, InvocationKind, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, StorageEventPayload, StoredEvent, SubRunHandle, - SubRunStorageMode, -}; - -use crate::{SubRunStatusSnapshot, SubRunStatusSource}; - -#[derive(Debug, Clone)] -struct DurableSubRunStatusProjection { - handle: SubRunHandle, - tool_call_id: Option, - result: Option, - step_count: Option, - estimated_tokens: Option, - resolved_overrides: Option, -} - -pub(crate) fn project_durable_subrun_status_snapshot( - parent_session_id: &str, - child_session_id: &str, - requested_subrun_id: &str, - stored_events: &[StoredEvent], -) -> Option { - let mut projection: Option = None; - - for stored in stored_events { - let agent = &stored.event.agent; - if !matches_requested_subrun(agent, requested_subrun_id) { - continue; - } - - match &stored.event.payload { - StorageEventPayload::SubRunStarted { - tool_call_id, - resolved_overrides, - resolved_limits, - .. - } => { - projection = Some(DurableSubRunStatusProjection { - handle: build_subrun_handle( - parent_session_id, - child_session_id, - requested_subrun_id, - agent, - AgentLifecycleStatus::Running, - None, - resolved_limits.clone(), - ), - tool_call_id: tool_call_id.clone(), - result: None, - step_count: None, - estimated_tokens: None, - resolved_overrides: Some(resolved_overrides.clone()), - }); - }, - StorageEventPayload::SubRunFinished { - tool_call_id, - result, - step_count, - estimated_tokens, - .. - } => { - let entry = projection.get_or_insert_with(|| DurableSubRunStatusProjection { - handle: build_subrun_handle( - parent_session_id, - child_session_id, - requested_subrun_id, - agent, - result.status().lifecycle(), - result.status().last_turn_outcome(), - ResolvedExecutionLimitsSnapshot, - ), - tool_call_id: None, - result: None, - step_count: None, - estimated_tokens: None, - resolved_overrides: None, - }); - entry.tool_call_id = tool_call_id.clone().or_else(|| entry.tool_call_id.clone()); - entry.handle.lifecycle = result.status().lifecycle(); - entry.handle.last_turn_outcome = result.status().last_turn_outcome(); - entry.result = Some(result.clone()); - entry.step_count = Some(*step_count); - entry.estimated_tokens = Some(*estimated_tokens); - }, - _ => {}, - } - } - - projection.map(|projection| SubRunStatusSnapshot { - handle: projection.handle, - tool_call_id: projection.tool_call_id, - source: SubRunStatusSource::Durable, - result: projection.result, - step_count: projection.step_count, - estimated_tokens: projection.estimated_tokens, - resolved_overrides: projection.resolved_overrides, - }) -} - -fn build_subrun_handle( - parent_session_id: &str, - child_session_id: &str, - requested_subrun_id: &str, - agent: &AgentEventContext, - lifecycle: AgentLifecycleStatus, - last_turn_outcome: Option, - resolved_limits: ResolvedExecutionLimitsSnapshot, -) -> SubRunHandle { - SubRunHandle { - sub_run_id: agent - .sub_run_id - .clone() - .unwrap_or_else(|| requested_subrun_id.to_string().into()), - agent_id: agent - .agent_id - .clone() - .unwrap_or_else(|| requested_subrun_id.to_string().into()), - session_id: parent_session_id.to_string().into(), - child_session_id: Some( - agent - .child_session_id - .clone() - .unwrap_or_else(|| child_session_id.to_string().into()), - ), - depth: 1, - parent_turn_id: agent.parent_turn_id.clone().unwrap_or_default(), - parent_agent_id: None, - parent_sub_run_id: agent.parent_sub_run_id.clone(), - lineage_kind: astrcode_core::ChildSessionLineageKind::Spawn, - agent_profile: agent - .agent_profile - .clone() - .unwrap_or_else(|| "unknown".to_string()), - storage_mode: agent - .storage_mode - .unwrap_or(SubRunStorageMode::IndependentSession), - lifecycle, - last_turn_outcome, - resolved_limits, - delegation: None, - } -} - -fn matches_requested_subrun(agent: &AgentEventContext, requested_subrun_id: &str) -> bool { - if agent.invocation_kind != Some(InvocationKind::SubRun) { - return false; - } - - agent.sub_run_id.as_deref() == Some(requested_subrun_id) - || agent.agent_id.as_deref() == Some(requested_subrun_id) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - ArtifactRef, CompletedParentDeliveryPayload, CompletedSubRunOutcome, ForkMode, - ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, - ParentDeliveryTerminalSemantics, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, StorageEvent, StorageEventPayload, SubRunHandoff, - SubRunResult, SubRunStorageMode, - }; - - use super::project_durable_subrun_status_snapshot; - use crate::{AgentEventContext, StoredEvent}; - - #[test] - fn durable_subrun_projection_preserves_typed_handoff_delivery() { - let child_agent = AgentEventContext::sub_run( - "agent-child", - "turn-parent", - "reviewer", - "subrun-child", - Some("subrun-parent".into()), - SubRunStorageMode::IndependentSession, - Some("session-child".into()), - ); - let explicit_delivery = ParentDelivery { - idempotency_key: "delivery-explicit".to_string(), - origin: ParentDeliveryOrigin::Explicit, - terminal_semantics: ParentDeliveryTerminalSemantics::Terminal, - source_turn_id: Some("turn-child".to_string()), - payload: ParentDeliveryPayload::Completed(CompletedParentDeliveryPayload { - message: "显式交付".to_string(), - findings: vec!["finding-1".to_string()], - artifacts: vec![ArtifactRef { - kind: "session".to_string(), - id: "session-child".to_string(), - label: "Child Session".to_string(), - session_id: Some("session-child".to_string()), - storage_seq: None, - uri: None, - }], - }), - }; - let stored_events = vec![StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-child".to_string()), - agent: child_agent.clone(), - payload: StorageEventPayload::SubRunFinished { - tool_call_id: Some("call-1".to_string()), - result: SubRunResult::Completed { - outcome: CompletedSubRunOutcome::Completed, - handoff: SubRunHandoff { - findings: vec!["finding-1".to_string()], - artifacts: vec![ArtifactRef { - kind: "session".to_string(), - id: "session-child".to_string(), - label: "Child Session".to_string(), - session_id: Some("session-child".to_string()), - storage_seq: None, - uri: None, - }], - delivery: Some(explicit_delivery.clone()), - }, - }, - timestamp: Some(chrono::Utc::now()), - step_count: 3, - estimated_tokens: 120, - }, - }, - }]; - - let projection = project_durable_subrun_status_snapshot( - "session-parent", - "session-child", - "subrun-child", - &stored_events, - ) - .expect("projection should exist"); - - let result = projection.result.expect("durable result should exist"); - let handoff = match result { - SubRunResult::Running { handoff } | SubRunResult::Completed { handoff, .. } => handoff, - SubRunResult::Failed { .. } => panic!("expected successful durable handoff"), - }; - let delivery = handoff - .delivery - .expect("typed delivery should survive durable projection"); - assert_eq!(delivery.idempotency_key, "delivery-explicit"); - assert_eq!(delivery.origin, ParentDeliveryOrigin::Explicit); - assert_eq!( - delivery.terminal_semantics, - ParentDeliveryTerminalSemantics::Terminal - ); - match delivery.payload { - ParentDeliveryPayload::Completed(payload) => { - assert_eq!(payload.message, "显式交付"); - assert_eq!(payload.findings, vec!["finding-1".to_string()]); - }, - payload => panic!("unexpected delivery payload: {payload:?}"), - } - } - - #[test] - fn resolved_overrides_projection_preserves_fork_mode() { - let projection = project_durable_subrun_status_snapshot( - "session-parent", - "session-child", - "subrun-child", - &[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-child".to_string()), - agent: AgentEventContext::sub_run( - "agent-child", - "turn-parent", - "reviewer", - "subrun-child", - Some("subrun-parent".into()), - SubRunStorageMode::IndependentSession, - Some("session-child".into()), - ), - payload: StorageEventPayload::SubRunStarted { - tool_call_id: Some("call-1".to_string()), - resolved_overrides: ResolvedSubagentContextOverrides { - fork_mode: Some(ForkMode::LastNTurns(7)), - ..ResolvedSubagentContextOverrides::default() - }, - resolved_limits: ResolvedExecutionLimitsSnapshot, - timestamp: Some(chrono::Utc::now()), - }, - }, - }], - ) - .expect("projection should exist"); - - assert_eq!( - projection - .resolved_overrides - .expect("resolved overrides should exist") - .fork_mode, - Some(ForkMode::LastNTurns(7)) - ); - } -} diff --git a/crates/session-runtime/src/query/terminal.rs b/crates/session-runtime/src/query/terminal.rs deleted file mode 100644 index 88322f91..00000000 --- a/crates/session-runtime/src/query/terminal.rs +++ /dev/null @@ -1,29 +0,0 @@ -use astrcode_core::{CompactAppliedMeta, CompactTrigger, Phase}; -use chrono::{DateTime, Utc}; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct LastCompactMetaSnapshot { - pub trigger: CompactTrigger, - pub meta: CompactAppliedMeta, -} - -/// terminal / interactive surface 需要的稳定控制态快照。 -/// -/// Why: application 只应消费可序列化、可测试的读模型事实， -/// 不能透过 `SessionState` 直接读取内部 mutex 字段。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionControlStateSnapshot { - pub phase: Phase, - pub active_turn_id: Option, - pub manual_compact_pending: bool, - pub compacting: bool, - pub last_compact_meta: Option, - pub current_mode_id: astrcode_core::ModeId, - pub last_mode_changed_at: Option>, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct SessionModeSnapshot { - pub current_mode_id: astrcode_core::ModeId, - pub last_mode_changed_at: Option>, -} diff --git a/crates/session-runtime/src/query/text.rs b/crates/session-runtime/src/query/text.rs deleted file mode 100644 index a3c02be2..00000000 --- a/crates/session-runtime/src/query/text.rs +++ /dev/null @@ -1,45 +0,0 @@ -//! query 层共享的文本规整与截断规则。 -//! -//! Why: 各类只读快照都需要输出短摘要，统一到这里可以避免 -//! 不同查询面各自复制 whitespace normalize / truncate 逻辑后逐渐漂移。 - -const DEFAULT_ELLIPSIS: &str = "..."; - -pub(crate) fn summarize_inline_text(text: &str, max_chars: usize) -> Option { - let normalized = text.split_whitespace().collect::>().join(" "); - truncate_text(&normalized, max_chars) -} - -pub(crate) fn truncate_text(text: &str, max_chars: usize) -> Option { - let trimmed = text.trim(); - if trimmed.is_empty() { - return None; - } - - let char_count = trimmed.chars().count(); - if char_count <= max_chars { - return Some(trimmed.to_string()); - } - - Some(trimmed.chars().take(max_chars).collect::() + DEFAULT_ELLIPSIS) -} - -#[cfg(test)] -mod tests { - use super::{summarize_inline_text, truncate_text}; - - #[test] - fn summarize_inline_text_normalizes_whitespace_before_truncating() { - assert_eq!( - summarize_inline_text(" review input queue \n state ", 120), - Some("review input queue state".to_string()) - ); - } - - #[test] - fn truncate_text_trims_and_truncates_with_ascii_ellipsis() { - assert_eq!(truncate_text(" hello ", 10), Some("hello".to_string())); - assert_eq!(truncate_text(" ", 10), None); - assert_eq!(truncate_text(&"a".repeat(5), 3), Some("aaa...".to_string())); - } -} diff --git a/crates/session-runtime/src/query/transcript.rs b/crates/session-runtime/src/query/transcript.rs deleted file mode 100644 index 0bad288f..00000000 --- a/crates/session-runtime/src/query/transcript.rs +++ /dev/null @@ -1,43 +0,0 @@ -//! 只读 transcript 查询与会话快照类型。 -//! -//! Why: 这里集中表达“从单 session 真相里能读到什么 transcript/快照”， -//! 避免把这类只读投影继续塞回 `factory` 或 `application`。 - -use astrcode_core::{AgentEvent, Phase, SessionEventRecord}; -use tokio::sync::broadcast; - -#[derive(Debug)] -pub struct SessionReplay { - pub history: Vec, - pub receiver: broadcast::Receiver, - pub live_receiver: broadcast::Receiver, -} - -#[derive(Debug, Clone)] -pub struct SessionTranscriptSnapshot { - pub records: Vec, - pub cursor: Option, - pub phase: Phase, -} - -#[cfg(test)] -mod tests { - use astrcode_core::SessionId; - - use crate::actor::SessionActor; - - #[test] - fn current_turn_messages_returns_projected_messages() { - let actor = SessionActor::new_idle( - SessionId::from("session-1".to_string()), - ".", - "root-agent".into(), - ); - - let messages = actor - .state() - .current_turn_messages() - .expect("projection should succeed"); - assert!(messages.is_empty()); - } -} diff --git a/crates/session-runtime/src/query/turn.rs b/crates/session-runtime/src/query/turn.rs deleted file mode 100644 index 503c25d1..00000000 --- a/crates/session-runtime/src/query/turn.rs +++ /dev/null @@ -1,238 +0,0 @@ -//! Turn 终态投影。 -//! -//! Why: 这里专门表达“某个 turn 最终发生了什么”， -//! 不让这类终态推断逻辑回流到 `application`。 - -use astrcode_core::{ - AgentTurnOutcome, Phase, StoredEvent, TurnProjectionSnapshot, TurnTerminalKind, -}; - -use crate::turn::projector::{ - last_non_empty_assistant_event, last_non_empty_error_event, project_turn_projection, -}; - -#[derive(Debug, Clone)] -pub struct TurnTerminalSnapshot { - pub phase: Phase, - pub projection: Option, - pub events: Vec, -} - -#[derive(Debug, Clone)] -pub struct ProjectedTurnOutcome { - pub outcome: AgentTurnOutcome, - pub summary: String, - pub technical_message: String, -} - -pub(crate) fn project_turn_outcome( - phase: Phase, - projection: Option<&TurnProjectionSnapshot>, - events: &[StoredEvent], -) -> ProjectedTurnOutcome { - let replayed_projection = project_turn_projection(events); - let projection = projection.or(replayed_projection.as_ref()); - let last_assistant = last_non_empty_assistant_event(events); - let last_error = last_non_empty_error_event(events); - let terminal_kind = resolve_terminal_kind(phase, projection, last_error.as_deref()); - let outcome = project_agent_turn_outcome(terminal_kind.as_ref()); - - let summary = match outcome { - AgentTurnOutcome::Completed => last_assistant - .clone() - .unwrap_or_else(|| "子 Agent 已完成，但没有返回可读总结。".to_string()), - AgentTurnOutcome::Failed => last_error - .clone() - .or(last_assistant.clone()) - .unwrap_or_else(|| "子 Agent 失败，且没有返回可读错误信息。".to_string()), - AgentTurnOutcome::Cancelled => last_error - .clone() - .unwrap_or_else(|| "子 Agent 已关闭。".to_string()), - }; - let technical_message = match terminal_kind { - Some(TurnTerminalKind::Error { message }) => last_error.unwrap_or_else(|| message.clone()), - _ => last_error.unwrap_or(summary.clone()), - }; - - ProjectedTurnOutcome { - outcome, - summary: summary.clone(), - technical_message, - } -} - -fn resolve_terminal_kind( - phase: Phase, - projection: Option<&TurnProjectionSnapshot>, - last_error: Option<&str>, -) -> Option { - if let Some(turn_done_kind) = projection.and_then(|projection| projection.terminal_kind.clone()) - { - return Some(turn_done_kind); - } - - if matches!(phase, Phase::Interrupted) { - return Some(TurnTerminalKind::Cancelled); - } - - projection - .and_then(|projection| projection.last_error.as_deref()) - .or(last_error) - .map(str::trim) - .filter(|message| !message.is_empty()) - .map(|message| TurnTerminalKind::Error { - message: message.to_string(), - }) -} - -fn project_agent_turn_outcome(terminal_kind: Option<&TurnTerminalKind>) -> AgentTurnOutcome { - match terminal_kind { - Some(TurnTerminalKind::Completed) | None => AgentTurnOutcome::Completed, - Some(TurnTerminalKind::Cancelled) => AgentTurnOutcome::Cancelled, - Some(TurnTerminalKind::Error { .. }) => AgentTurnOutcome::Failed, - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, AgentTurnOutcome, Phase, StorageEvent, StorageEventPayload, StoredEvent, - TurnProjectionSnapshot, - }; - - use super::project_turn_outcome; - use crate::turn::projector::{has_terminal_projection, project_turn_projection}; - - #[test] - fn has_terminal_projection_detects_typed_terminal_kind() { - assert!(has_terminal_projection(Some(&TurnProjectionSnapshot { - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - last_error: None, - }))); - } - - #[test] - fn project_turn_projection_reads_typed_turn_done_terminal_kind() { - let projection = project_turn_projection(&[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: None, - }, - }, - }]) - .expect("projection should replay"); - - assert_eq!( - projection.terminal_kind, - Some(astrcode_core::TurnTerminalKind::Completed) - ); - } - - #[test] - fn project_turn_outcome_prefers_assistant_summary_on_success() { - let outcome = project_turn_outcome( - Phase::Idle, - None, - &[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AssistantFinal { - content: "完成总结".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - }, - }], - ); - - assert_eq!(outcome.outcome, AgentTurnOutcome::Completed); - assert_eq!(outcome.summary, "完成总结"); - } - - #[test] - fn project_turn_outcome_prefers_typed_terminal_kind_over_reason() { - let outcome = project_turn_outcome( - Phase::Idle, - Some(&TurnProjectionSnapshot { - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - last_error: None, - }), - &[], - ); - - assert_eq!(outcome.outcome, AgentTurnOutcome::Completed); - } - - #[test] - fn project_turn_outcome_treats_unknown_turn_done_reason_as_completed() { - let outcome = project_turn_outcome( - Phase::Idle, - Some(&TurnProjectionSnapshot { - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - last_error: None, - }), - &[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AssistantFinal { - content: "普通完成".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - }, - }], - ); - - assert_eq!(outcome.outcome, AgentTurnOutcome::Completed); - assert_eq!(outcome.summary, "普通完成"); - } - - #[test] - fn project_turn_outcome_treats_interrupted_phase_without_typed_terminal_as_cancelled() { - let outcome = project_turn_outcome( - Phase::Interrupted, - Some(&TurnProjectionSnapshot { - terminal_kind: None, - last_error: None, - }), - &[], - ); - - assert_eq!(outcome.outcome, AgentTurnOutcome::Cancelled); - } - - #[test] - fn project_turn_outcome_uses_turn_done_event_when_projection_is_missing() { - let outcome = project_turn_outcome( - Phase::Idle, - None, - &[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: None, - }, - }, - }], - ); - - assert_eq!(outcome.outcome, AgentTurnOutcome::Completed); - } -} diff --git a/crates/session-runtime/src/state/child_sessions.rs b/crates/session-runtime/src/state/child_sessions.rs deleted file mode 100644 index e9ec0134..00000000 --- a/crates/session-runtime/src/state/child_sessions.rs +++ /dev/null @@ -1,122 +0,0 @@ -use std::collections::HashMap; - -use astrcode_core::{ChildSessionNode, Result, StorageEventPayload, StoredEvent, support}; - -use super::SessionState; - -pub(crate) fn rebuild_child_nodes(events: &[StoredEvent]) -> HashMap { - let mut nodes = HashMap::new(); - for stored in events { - if let Some(node) = child_node_from_stored_event(stored) { - nodes.insert(node.sub_run_id().to_string(), node); - } - } - nodes -} - -pub(crate) fn child_node_from_stored_event(stored: &StoredEvent) -> Option { - match &stored.event.payload { - StorageEventPayload::ChildSessionNotification { notification, .. } => { - Some(notification.child_ref.to_child_session_node( - stored.event.turn_id.clone().unwrap_or_default().into(), - astrcode_core::ChildSessionStatusSource::Durable, - notification.source_tool_call_id.clone(), - None, - )) - }, - _ => None, - } -} - -impl SessionState { - /// 写入或覆盖一个 child-session durable 节点（按 sub_run_id 去重）。 - pub fn upsert_child_session_node(&self, node: ChildSessionNode) -> Result<()> { - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .children - .upsert(node); - Ok(()) - } - - /// 查询某个 sub-run 对应的 child-session 节点快照。 - pub fn child_session_node(&self, sub_run_id: &str) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .child_session_node(sub_run_id), - ) - } - - /// 列出当前 session 所有 child-session 节点快照（按 sub_run_id 排序）。 - pub fn list_child_session_nodes(&self) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .list_child_session_nodes(), - ) - } - - /// 查找某个 agent 的直接子节点。 - pub fn child_nodes_for_parent(&self, parent_agent_id: &str) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .child_nodes_for_parent(parent_agent_id), - ) - } - - /// 收集指定 agent 子树的所有后代节点（不含自身）。 - pub fn subtree_nodes(&self, root_agent_id: &str) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .subtree_nodes(root_agent_id), - ) - } -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - AgentLifecycleStatus, AgentStateProjector, ChildSessionNotificationKind, Phase, - }; - - use super::*; - use crate::state::{ - SessionWriter, - test_support::{NoopEventLogWriter, child_notification_event, stored}, - }; - - #[test] - fn session_state_rehydrates_child_nodes_from_stored_notifications() { - let session = SessionState::new( - Phase::Idle, - Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter))), - AgentStateProjector::default(), - Vec::new(), - vec![ - stored( - 1, - child_notification_event( - ChildSessionNotificationKind::Started, - AgentLifecycleStatus::Running, - ), - ), - stored( - 2, - child_notification_event( - ChildSessionNotificationKind::Delivered, - AgentLifecycleStatus::Idle, - ), - ), - ], - ); - - let node = session - .child_session_node("subrun-1") - .expect("child node lookup should succeed") - .expect("child node should exist"); - - assert_eq!(node.child_session_id, "session-child".into()); - assert_eq!(node.parent_session_id, "session-parent".into()); - assert_eq!(node.status, AgentLifecycleStatus::Idle); - assert_eq!(node.created_by_tool_call_id.as_deref(), Some("call-1")); - } -} diff --git a/crates/session-runtime/src/state/compaction.rs b/crates/session-runtime/src/state/compaction.rs deleted file mode 100644 index dc41a347..00000000 --- a/crates/session-runtime/src/state/compaction.rs +++ /dev/null @@ -1,254 +0,0 @@ -use std::collections::VecDeque; - -use astrcode_core::{ - InvocationKind, StorageEvent, StorageEventPayload, StoredEvent, UserMessageOrigin, -}; - -/// Manual / auto compact 都应该基于 durable tail，而不是投影后的消息列表。 -pub fn recent_turn_event_tail( - events: &[StoredEvent], - keep_recent_turns: usize, -) -> Vec { - let keep_recent_turns = keep_recent_turns.max(1); - let mut tail_refs = Vec::new(); - let mut kept_turn_starts = VecDeque::with_capacity(keep_recent_turns); - - for stored in events { - if !should_record_compaction_tail_event(&stored.event) { - continue; - } - if matches!( - &stored.event.payload, - StorageEventPayload::UserMessage { - origin: UserMessageOrigin::User, - .. - } - ) { - kept_turn_starts.push_back(tail_refs.len()); - if kept_turn_starts.len() > keep_recent_turns { - kept_turn_starts.pop_front(); - } - } - tail_refs.push(stored); - } - - let keep_start = kept_turn_starts.front().copied().unwrap_or(0); - tail_refs.into_iter().skip(keep_start).cloned().collect() -} - -/// 判断事件是否应纳入 compaction tail 记录。 -pub fn should_record_compaction_tail_event(event: &StorageEvent) -> bool { - matches!( - &event.payload, - StorageEventPayload::UserMessage { .. } - | StorageEventPayload::AssistantFinal { .. } - | StorageEventPayload::ToolCall { .. } - | StorageEventPayload::ToolResult { .. } - ) && should_include_in_compaction_tail(event) -} - -fn should_include_in_compaction_tail(event: &StorageEvent) -> bool { - let Some(agent) = event.agent_context() else { - return true; - }; - - if agent.invocation_kind != Some(InvocationKind::SubRun) { - return true; - } - - // 只有语义完整的独立子会话事件才属于子会话自身，应纳入 compaction tail。 - agent.is_independent_sub_run() -} - -#[cfg(test)] -mod tests { - use astrcode_core::{AgentEventContext, StorageEventPayload}; - - use super::*; - use crate::state::test_support::{event, stored}; - - #[test] - fn recent_turn_event_tail_keeps_latest_turn_when_keep_recent_turns_is_zero() { - let events = vec![ - stored( - 1, - event( - Some("turn-1"), - AgentEventContext::default(), - StorageEventPayload::UserMessage { - content: "first".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 2, - event( - Some("turn-1"), - AgentEventContext::default(), - StorageEventPayload::AssistantFinal { - content: "reply-1".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - ), - ), - stored( - 3, - event( - Some("turn-2"), - AgentEventContext::default(), - StorageEventPayload::UserMessage { - content: "second".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 4, - event( - Some("turn-2"), - AgentEventContext::default(), - StorageEventPayload::AssistantFinal { - content: "reply-2".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - ), - ), - ]; - - let tail = recent_turn_event_tail(&events, 0); - - assert_eq!(tail.len(), 2); - assert_eq!(tail[0].storage_seq, 3); - assert_eq!(tail[1].storage_seq, 4); - } - - #[test] - fn recent_turn_event_tail_excludes_malformed_subrun_events_without_child_session() { - let malformed_child_agent = AgentEventContext { - agent_id: Some("agent-child".to_string().into()), - parent_turn_id: Some("turn-root".to_string().into()), - agent_profile: Some("explore".to_string()), - sub_run_id: Some("subrun-malformed".to_string().into()), - parent_sub_run_id: None, - invocation_kind: Some(InvocationKind::SubRun), - storage_mode: Some(astrcode_core::SubRunStorageMode::IndependentSession), - child_session_id: None, - }; - let events = vec![ - stored( - 1, - event( - Some("turn-root"), - AgentEventContext::default(), - StorageEventPayload::UserMessage { - content: "root".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 2, - event( - Some("turn-root"), - AgentEventContext::default(), - StorageEventPayload::AssistantFinal { - content: "root-answer".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - ), - ), - stored( - 3, - event( - Some("turn-child"), - malformed_child_agent.clone(), - StorageEventPayload::UserMessage { - content: "child".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 4, - event( - Some("turn-child"), - malformed_child_agent, - StorageEventPayload::AssistantFinal { - content: "child-answer".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - ), - ), - ]; - - let tail = recent_turn_event_tail(&events, 1); - - assert_eq!(tail.len(), 2); - assert_eq!(tail[0].storage_seq, 1); - assert_eq!(tail[1].storage_seq, 2); - } - - #[test] - fn recent_turn_event_tail_keeps_independent_session_subrun_events() { - let child_agent = AgentEventContext::sub_run( - "agent-child", - "turn-root", - "explore", - "subrun-independent", - None, - astrcode_core::SubRunStorageMode::IndependentSession, - Some("session-child".to_string().into()), - ); - let events = vec![ - stored( - 1, - event( - Some("turn-child"), - child_agent.clone(), - StorageEventPayload::UserMessage { - content: "child".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 2, - event( - Some("turn-child"), - child_agent, - StorageEventPayload::AssistantFinal { - content: "child-answer".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - ), - ), - ]; - - let tail = recent_turn_event_tail(&events, 1); - - assert_eq!(tail.len(), 2); - assert_eq!(tail[0].storage_seq, 1); - assert_eq!(tail[1].storage_seq, 2); - } -} diff --git a/crates/session-runtime/src/state/execution.rs b/crates/session-runtime/src/state/execution.rs deleted file mode 100644 index 7ba11283..00000000 --- a/crates/session-runtime/src/state/execution.rs +++ /dev/null @@ -1,91 +0,0 @@ -use std::sync::Arc; - -#[cfg(test)] -use astrcode_core::ToolEventSink; -use astrcode_core::{ - EventStore, EventTranslator, Result, SessionId, StorageEvent, StorageEventPayload, StoredEvent, -}; -#[cfg(test)] -use async_trait::async_trait; -#[cfg(test)] -use tokio::sync::Mutex; - -use super::SessionState; - -/// 广播并缓存一条事件到 session 的 durable event log。 -pub async fn append_and_broadcast( - session: &SessionState, - event: &StorageEvent, - translator: &mut EventTranslator, -) -> Result { - session.append_and_broadcast(event, translator).await -} - -pub async fn checkpoint_if_compacted( - event_store: &Arc, - session_id: &SessionId, - session_state: &Arc, - persisted_events: &[StoredEvent], -) { - let Some(checkpoint_storage_seq) = persisted_events.last().map(|stored| stored.storage_seq) - else { - return; - }; - if !persisted_events.iter().any(|stored| { - matches!( - stored.event.payload, - StorageEventPayload::CompactApplied { .. } - ) - }) { - return; - } - let checkpoint = match session_state.recovery_checkpoint(checkpoint_storage_seq) { - Ok(checkpoint) => checkpoint, - Err(error) => { - log::warn!( - "failed to build recovery checkpoint for session '{}': {}", - session_id, - error - ); - return; - }, - }; - if let Err(error) = event_store - .checkpoint_session(session_id, &checkpoint) - .await - { - log::warn!( - "failed to persist recovery checkpoint for session '{}': {}", - session_id, - error - ); - } -} - -#[cfg(test)] -pub struct SessionStateEventSink { - session: Arc, - translator: Mutex, -} - -#[cfg(test)] -impl SessionStateEventSink { - pub fn new(session: Arc) -> Result { - let phase = session.current_phase()?; - Ok(Self { - session, - translator: Mutex::new(EventTranslator::new(phase)), - }) - } -} - -#[cfg(test)] -#[async_trait] -impl ToolEventSink for SessionStateEventSink { - async fn emit(&self, event: StorageEvent) -> astrcode_core::Result<()> { - let mut translator = self.translator.lock().await; - append_and_broadcast(&self.session, &event, &mut translator) - .await - .map(|_| ()) - } -} diff --git a/crates/session-runtime/src/state/input_queue.rs b/crates/session-runtime/src/state/input_queue.rs deleted file mode 100644 index d5c093de..00000000 --- a/crates/session-runtime/src/state/input_queue.rs +++ /dev/null @@ -1,396 +0,0 @@ -use std::collections::{HashMap, HashSet}; - -use astrcode_core::{InputQueueProjection, Result, StorageEventPayload, StoredEvent, support}; - -use super::SessionState; - -pub(crate) fn input_queue_projection_target_agent_id( - payload: &StorageEventPayload, -) -> Option<&str> { - match payload { - StorageEventPayload::AgentInputQueued { payload } => Some(&payload.envelope.to_agent_id), - StorageEventPayload::AgentInputBatchStarted { payload } => Some(&payload.target_agent_id), - StorageEventPayload::AgentInputBatchAcked { payload } => Some(&payload.target_agent_id), - StorageEventPayload::AgentInputDiscarded { payload } => Some(&payload.target_agent_id), - _ => None, - } -} - -impl SessionState { - /// 读取指定 agent 的 input queue durable 投影。 - pub fn input_queue_projection_for_agent(&self, agent_id: &str) -> Result { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .input_queue_projection_for_agent(agent_id), - ) - } -} - -pub(crate) fn apply_input_queue_event_to_index( - index: &mut HashMap, - stored: &StoredEvent, -) { - let Some(target_agent_id) = input_queue_projection_target_agent_id(&stored.event.payload) - else { - return; - }; - let projection = index.entry(target_agent_id.to_string()).or_default(); - apply_input_queue_event_for_agent(projection, stored, target_agent_id); -} - -#[cfg_attr(not(test), allow(dead_code))] -pub(crate) fn replay_input_queue_projection_for_agent( - events: &[StoredEvent], - target_agent_id: &str, -) -> InputQueueProjection { - let mut projection = InputQueueProjection::default(); - for stored in events { - apply_input_queue_event_for_agent(&mut projection, stored, target_agent_id); - } - projection -} - -pub(crate) fn replay_input_queue_projection_index( - events: &[StoredEvent], -) -> HashMap { - let mut index = HashMap::new(); - for stored in events { - match &stored.event.payload { - StorageEventPayload::AgentInputQueued { payload } => { - let target_agent_id = payload.envelope.to_agent_id.as_str(); - let projection = index.entry(target_agent_id.to_string()).or_default(); - apply_input_queue_event_for_agent(projection, stored, target_agent_id); - }, - StorageEventPayload::AgentInputBatchStarted { payload } => { - let target_agent_id = payload.target_agent_id.as_str(); - let projection = index.entry(target_agent_id.to_string()).or_default(); - apply_input_queue_event_for_agent(projection, stored, target_agent_id); - }, - StorageEventPayload::AgentInputBatchAcked { payload } => { - let target_agent_id = payload.target_agent_id.as_str(); - let projection = index.entry(target_agent_id.to_string()).or_default(); - apply_input_queue_event_for_agent(projection, stored, target_agent_id); - }, - StorageEventPayload::AgentInputDiscarded { payload } => { - let target_agent_id = payload.target_agent_id.as_str(); - let projection = index.entry(target_agent_id.to_string()).or_default(); - apply_input_queue_event_for_agent(projection, stored, target_agent_id); - }, - _ => {}, - } - } - index -} - -pub(crate) fn apply_input_queue_event_for_agent( - projection: &mut InputQueueProjection, - stored: &StoredEvent, - target_agent_id: &str, -) { - match &stored.event.payload { - StorageEventPayload::AgentInputQueued { payload } => { - if payload.envelope.to_agent_id != target_agent_id { - return; - } - let id = &payload.envelope.delivery_id; - if !projection.discarded_delivery_ids.contains(id) - && !projection.pending_delivery_ids.contains(id) - { - projection.pending_delivery_ids.push(id.clone()); - } - }, - StorageEventPayload::AgentInputBatchStarted { payload } => { - if payload.target_agent_id != target_agent_id { - return; - } - projection.active_batch_id = Some(payload.batch_id.clone()); - projection.active_delivery_ids = payload.delivery_ids.clone(); - }, - StorageEventPayload::AgentInputBatchAcked { payload } => { - if payload.target_agent_id != target_agent_id { - return; - } - let acked_set: HashSet<_> = payload.delivery_ids.iter().collect(); - projection.pending_delivery_ids.retain(|id| { - !acked_set.contains(id) && !projection.discarded_delivery_ids.contains(id) - }); - if projection.active_batch_id.as_deref() == Some(payload.batch_id.as_str()) { - projection.active_batch_id = None; - projection.active_delivery_ids.clear(); - } - }, - StorageEventPayload::AgentInputDiscarded { payload } => { - if payload.target_agent_id != target_agent_id { - return; - } - for id in &payload.delivery_ids { - if !projection.discarded_delivery_ids.contains(id) { - projection.discarded_delivery_ids.push(id.clone()); - } - } - projection - .pending_delivery_ids - .retain(|id| !projection.discarded_delivery_ids.contains(id)); - let discarded_set: HashSet<_> = projection.discarded_delivery_ids.iter().collect(); - if projection - .active_delivery_ids - .iter() - .any(|id| discarded_set.contains(id)) - { - projection.active_batch_id = None; - projection.active_delivery_ids.clear(); - } - }, - _ => {}, - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, AgentLifecycleStatus, AgentTurnOutcome, InputBatchAckedPayload, - InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, QueuedInputEnvelope, - StorageEvent, StorageEventPayload, - }; - - use super::*; - - #[test] - fn input_queue_projection_target_agent_id_reads_supported_payloads() { - let payload = StorageEventPayload::AgentInputBatchStarted { - payload: astrcode_core::InputBatchStartedPayload { - target_agent_id: "agent-child".to_string(), - turn_id: "turn-1".to_string(), - batch_id: "batch-1".to_string(), - delivery_ids: vec!["delivery-1".to_string().into()], - }, - }; - - assert_eq!( - input_queue_projection_target_agent_id(&payload), - Some("agent-child") - ); - } - - #[test] - fn replay_for_agent_tracks_full_lifecycle() { - let agent = AgentEventContext::default(); - let queued = StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("t1".into()), - agent: agent.clone(), - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: "d1".into(), - from_agent_id: "parent".into(), - to_agent_id: "child".into(), - message: "hello".into(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Running, - sender_last_turn_outcome: None, - sender_open_session_id: "s-parent".into(), - }, - }, - }, - }, - }; - let started = StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("t2".into()), - agent: agent.clone(), - payload: StorageEventPayload::AgentInputBatchStarted { - payload: InputBatchStartedPayload { - target_agent_id: "child".into(), - turn_id: "t2".into(), - batch_id: "b1".into(), - delivery_ids: vec!["d1".into()], - }, - }, - }, - }; - let acked = StoredEvent { - storage_seq: 3, - event: StorageEvent { - turn_id: Some("t2".into()), - agent, - payload: StorageEventPayload::AgentInputBatchAcked { - payload: InputBatchAckedPayload { - target_agent_id: "child".into(), - turn_id: "t2".into(), - batch_id: "b1".into(), - delivery_ids: vec!["d1".into()], - }, - }, - }, - }; - - let projection = - replay_input_queue_projection_for_agent(&[queued, started, acked], "child"); - assert!(projection.pending_delivery_ids.is_empty()); - assert!(projection.active_batch_id.is_none()); - assert!(projection.active_delivery_ids.is_empty()); - assert_eq!(projection.pending_input_count(), 0); - } - - #[test] - fn replay_for_agent_tracks_discarded_entries() { - let agent = AgentEventContext::default(); - let events = vec![ - StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("t1".into()), - agent: agent.clone(), - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: "d1".into(), - from_agent_id: "parent".into(), - to_agent_id: "child".into(), - message: "hello".into(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Running, - sender_last_turn_outcome: None, - sender_open_session_id: "s-parent".into(), - }, - }, - }, - }, - }, - StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("t1".into()), - agent, - payload: StorageEventPayload::AgentInputDiscarded { - payload: InputDiscardedPayload { - target_agent_id: "child".into(), - delivery_ids: vec!["d1".into()], - }, - }, - }, - }, - ]; - - let projection = replay_input_queue_projection_for_agent(&events, "child"); - assert!(projection.pending_delivery_ids.is_empty()); - assert!(projection.discarded_delivery_ids.contains(&"d1".into())); - } - - #[test] - fn replay_for_agent_keeps_started_but_unacked_delivery_pending() { - let agent = AgentEventContext::default(); - let events = vec![ - StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("t1".into()), - agent: agent.clone(), - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: "d1".into(), - from_agent_id: "parent".into(), - to_agent_id: "child".into(), - message: "hello".into(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Running, - sender_last_turn_outcome: None, - sender_open_session_id: "s-parent".into(), - }, - }, - }, - }, - }, - StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("t2".into()), - agent, - payload: StorageEventPayload::AgentInputBatchStarted { - payload: InputBatchStartedPayload { - target_agent_id: "child".into(), - turn_id: "t2".into(), - batch_id: "b1".into(), - delivery_ids: vec!["d1".into()], - }, - }, - }, - }, - ]; - - let projection = replay_input_queue_projection_for_agent(&events, "child"); - assert!(projection.pending_delivery_ids.contains(&"d1".into())); - assert_eq!(projection.active_batch_id.as_deref(), Some("b1")); - assert_eq!(projection.pending_input_count(), 1); - } - - #[test] - fn replay_index_isolates_agents() { - let agent = AgentEventContext::default(); - let events = vec![ - StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("t1".into()), - agent: agent.clone(), - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: "d-a".into(), - from_agent_id: "parent".into(), - to_agent_id: "agent-a".into(), - message: "for a".into(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Running, - sender_last_turn_outcome: Some(AgentTurnOutcome::Completed), - sender_open_session_id: "s-parent".into(), - }, - }, - }, - }, - }, - StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("t1".into()), - agent, - payload: StorageEventPayload::AgentInputQueued { - payload: InputQueuedPayload { - envelope: QueuedInputEnvelope { - delivery_id: "d-b".into(), - from_agent_id: "parent".into(), - to_agent_id: "agent-b".into(), - message: "for b".into(), - queued_at: chrono::Utc::now(), - sender_lifecycle_status: AgentLifecycleStatus::Running, - sender_last_turn_outcome: None, - sender_open_session_id: "s-parent".into(), - }, - }, - }, - }, - }, - ]; - - let projection_index = replay_input_queue_projection_index(&events); - assert_eq!( - projection_index - .get("agent-a") - .expect("agent-a projection") - .pending_delivery_ids, - vec!["d-a".into()] - ); - assert_eq!( - projection_index - .get("agent-b") - .expect("agent-b projection") - .pending_delivery_ids, - vec!["d-b".into()] - ); - assert!(!projection_index.contains_key("agent-c")); - } -} diff --git a/crates/session-runtime/src/state/mod.rs b/crates/session-runtime/src/state/mod.rs deleted file mode 100644 index 35213ba6..00000000 --- a/crates/session-runtime/src/state/mod.rs +++ /dev/null @@ -1,482 +0,0 @@ -//! 会话真相状态：事件投影、child-session 节点跟踪、input queue 投影、writer 与广播基础设施。 -//! -//! `SessionState` 只拥有 durable truth 与 projection/cache/broadcast 基础设施， -//! 不再承担 turn runtime control；运行时锁、CancelToken 与 compact 控制统一归 `turn/runtime.rs`。 - -mod cache; -mod child_sessions; -#[cfg(test)] -mod compaction; -mod execution; -mod input_queue; -mod paths; -mod projection_registry; -mod tasks; -#[cfg(test)] -mod test_support; -#[cfg(test)] -pub(crate) use test_support::sample_spawn_child_ref; -mod writer; - -use std::sync::{Arc, Mutex as StdMutex}; - -use astrcode_core::{ - AgentEvent, AgentState, AgentStateProjector, EventTranslator, LlmMessage, ModeId, Phase, - Result, SessionEventRecord, SessionRecoveryCheckpoint, StoredEvent, TurnProjectionSnapshot, - normalize_recovered_phase, - support::{self}, -}; -use chrono::Utc; -#[cfg(test)] -pub(crate) use execution::SessionStateEventSink; -pub(crate) use execution::append_and_broadcast; -pub use execution::checkpoint_if_compacted; -pub(crate) use input_queue::replay_input_queue_projection_index; -pub(crate) use paths::compact_history_event_log_path; -pub use paths::{display_name_from_working_dir, normalize_session_id, normalize_working_dir}; -use projection_registry::ProjectionRegistry; -use tokio::sync::broadcast; -pub(crate) use writer::SessionWriter; - -const SESSION_BROADCAST_CAPACITY: usize = 2048; -const SESSION_LIVE_BROADCAST_CAPACITY: usize = 2048; - -pub struct SessionState { - projection_registry: StdMutex, - pub broadcaster: broadcast::Sender, - live_broadcaster: broadcast::Sender, - pub writer: Arc, -} - -impl std::fmt::Debug for SessionState { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("SessionState").finish_non_exhaustive() - } -} - -/// 轻量会话快照，用于 observe 返回值（仅包含可序列化的聚合字段）。 -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct SessionSnapshot { - pub session_id: astrcode_core::SessionId, - pub working_dir: String, - pub latest_turn_id: Option, - pub turn_count: usize, -} - -impl SessionState { - pub fn new( - phase: Phase, - writer: Arc, - projector: AgentStateProjector, - recent_records: Vec, - recent_stored: Vec, - ) -> Self { - Self::from_parts(phase, writer, projector, recent_records, recent_stored) - } - - pub fn from_recovery( - writer: Arc, - checkpoint: &SessionRecoveryCheckpoint, - tail_events: Vec, - ) -> Result { - let phase = normalize_recovered_phase(checkpoint.agent_state.phase); - let mut projection_registry = ProjectionRegistry::from_recovery( - phase, - &checkpoint.agent_state, - checkpoint.projection_registry_snapshot(), - Vec::new(), - Vec::new(), - ); - for stored in &tail_events { - stored.event.validate().map_err(|error| { - astrcode_core::AstrError::Validation(format!( - "session '{}' contains invalid stored event at storage_seq {}: {}", - checkpoint.agent_state.session_id, stored.storage_seq, error - )) - })?; - projection_registry.apply(stored)?; - } - projection_registry.cache_records(&astrcode_core::replay_records(&tail_events, None)); - let (broadcaster, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); - let (live_broadcaster, _) = broadcast::channel(SESSION_LIVE_BROADCAST_CAPACITY); - - Ok(Self { - projection_registry: StdMutex::new(projection_registry), - broadcaster, - live_broadcaster, - writer, - }) - } - - fn from_parts( - phase: Phase, - writer: Arc, - projector: AgentStateProjector, - recent_records: Vec, - recent_stored: Vec, - ) -> Self { - let (broadcaster, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); - let (live_broadcaster, _) = broadcast::channel(SESSION_LIVE_BROADCAST_CAPACITY); - Self { - projection_registry: StdMutex::new(ProjectionRegistry::new( - phase, - projector, - recent_records, - recent_stored, - )), - broadcaster, - live_broadcaster, - writer, - } - } - - pub fn recovery_checkpoint( - &self, - checkpoint_storage_seq: u64, - ) -> Result { - let projection_registry = - support::lock_anyhow(&self.projection_registry, "session projection registry")?; - Ok(SessionRecoveryCheckpoint::new( - projection_registry.snapshot_projected_state(), - projection_registry.projection_snapshot(), - checkpoint_storage_seq, - )) - } - - pub fn snapshot_projected_state(&self) -> Result { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .snapshot_projected_state(), - ) - } - - pub fn current_turn_messages(&self) -> Result> { - Ok(self.snapshot_projected_state()?.messages) - } - - /// 订阅 live-only 事件流（token 级 delta 等瞬时事件，不参与 durable replay）。 - pub fn subscribe_live(&self) -> broadcast::Receiver { - self.live_broadcaster.subscribe() - } - - /// 广播一条 live-only 事件（无订阅者时不视为错误）。 - pub fn broadcast_live_event(&self, event: AgentEvent) { - let _ = self.live_broadcaster.send(event); - } - - pub fn current_phase(&self) -> Result { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .current_phase(), - ) - } - - pub fn current_mode_id(&self) -> Result { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .current_mode_id(), - ) - } - - pub fn last_mode_changed_at(&self) -> Result>> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .last_mode_changed_at(), - ) - } - - pub fn translate_store_and_cache( - &self, - stored: &StoredEvent, - translator: &mut EventTranslator, - ) -> Result> { - stored.event.validate()?; - let mut projection_registry = - support::lock_anyhow(&self.projection_registry, "session projection registry")?; - projection_registry.apply(stored)?; - let records = translator.translate(stored); - projection_registry.cache_records(&records); - Ok(records) - } - - pub fn recent_records_after( - &self, - last_event_id: Option<&str>, - ) -> Result>> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .recent_records_after(last_event_id), - ) - } - - pub fn snapshot_recent_stored_events(&self) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .snapshot_recent_stored_events(), - ) - } - - pub fn turn_projection(&self, turn_id: &str) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .turn_projection(turn_id), - ) - } - - pub async fn append_and_broadcast( - &self, - event: &astrcode_core::StorageEvent, - translator: &mut EventTranslator, - ) -> Result { - let stored = self.writer.clone().append(event.clone()).await?; - let records = self.translate_store_and_cache(&stored, translator)?; - for record in records { - let _ = self.broadcaster.send(record); - } - Ok(stored) - } -} - -// ── 辅助函数 ────────────────────────────────────────────── - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - AgentEventContext, ExecutionTaskItem, ExecutionTaskStatus, InvocationKind, ModeId, Phase, - SessionRecoveryCheckpoint, StorageEventPayload, SubRunStorageMode, UserMessageOrigin, - }; - use chrono::Utc; - - use super::{ - SessionState, SessionWriter, - test_support::{ - NoopEventLogWriter, event, independent_session_sub_run_agent, root_agent, stored, - test_session_state, - }, - }; - - #[test] - fn translate_store_and_cache_keeps_sub_run_events_out_of_parent_snapshot() { - let session = test_session_state(); - let mut translator = astrcode_core::EventTranslator::new(Phase::Idle); - - let events = vec![ - stored( - 1, - event( - None, - root_agent(), - StorageEventPayload::SessionStart { - session_id: "session-1".into(), - timestamp: chrono::Utc::now(), - working_dir: "/tmp".into(), - parent_session_id: None, - parent_storage_seq: None, - }, - ), - ), - stored( - 2, - event( - Some("turn-root"), - root_agent(), - StorageEventPayload::UserMessage { - content: "root task".into(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 3, - event( - Some("turn-root"), - root_agent(), - StorageEventPayload::AssistantFinal { - content: "root answer".into(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: None, - }, - ), - ), - stored( - 4, - event( - Some("turn-root"), - root_agent(), - StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: Some("completed".into()), - }, - ), - ), - stored( - 5, - event( - Some("turn-child"), - independent_session_sub_run_agent(), - StorageEventPayload::UserMessage { - content: "child task".into(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ), - stored( - 6, - event( - Some("turn-child"), - independent_session_sub_run_agent(), - StorageEventPayload::AssistantFinal { - content: "child answer".into(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: None, - }, - ), - ), - stored( - 7, - event( - Some("turn-child"), - independent_session_sub_run_agent(), - StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: Some("completed".into()), - }, - ), - ), - ]; - - for stored in &events { - session - .translate_store_and_cache(stored, &mut translator) - .expect("event should translate into session cache"); - } - - let projected = session - .snapshot_projected_state() - .expect("snapshot should be available"); - - assert_eq!(projected.turn_count, 1); - assert_eq!(projected.messages.len(), 2); - assert!(matches!( - &projected.messages[0], - astrcode_core::LlmMessage::User { content, .. } if content == "root task" - )); - assert!(matches!( - &projected.messages[1], - astrcode_core::LlmMessage::Assistant { content, .. } if content == "root answer" - )); - } - - #[test] - fn translate_store_and_cache_rejects_invalid_stored_event() { - let session = test_session_state(); - let mut translator = astrcode_core::EventTranslator::new(Phase::Idle); - let malformed = stored( - 1, - event( - Some("turn-child"), - AgentEventContext { - agent_id: Some("agent-child".to_string().into()), - parent_turn_id: Some("turn-root".to_string().into()), - agent_profile: Some("explore".to_string()), - sub_run_id: Some("subrun-1".to_string().into()), - parent_sub_run_id: None, - invocation_kind: Some(InvocationKind::SubRun), - storage_mode: Some(SubRunStorageMode::IndependentSession), - child_session_id: None, - }, - StorageEventPayload::UserMessage { - content: "child task".into(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - ), - ); - - let error = session - .translate_store_and_cache(&malformed, &mut translator) - .expect_err("invalid stored event should be rejected"); - - assert!(error.to_string().contains("child_session_id")); - } - - #[test] - fn legacy_checkpoint_fields_migrate_into_projection_registry_snapshot() { - let checkpoint_json = serde_json::json!({ - "agentState": { - "session_id": "session-legacy", - "working_dir": "/tmp", - "messages": [], - "phase": "idle", - "mode_id": ModeId::default(), - "turn_count": 0, - "last_assistant_at": serde_json::Value::Null, - }, - "phase": "idle", - "lastModeChangedAt": "2026-04-21T00:00:00Z", - "childNodes": {}, - "activeTasks": { - "owner-a": { - "owner": "owner-a", - "items": [{ - "content": "迁移旧 checkpoint", - "status": "in_progress", - "activeForm": "正在迁移旧 checkpoint" - }] - } - }, - "inputQueueProjectionIndex": {}, - "checkpointStorageSeq": 9 - }); - let checkpoint: SessionRecoveryCheckpoint = - serde_json::from_value(checkpoint_json).expect("legacy checkpoint should deserialize"); - - let projection_snapshot = checkpoint.projection_registry_snapshot(); - assert_eq!( - projection_snapshot.last_mode_changed_at, - Some( - chrono::DateTime::parse_from_rfc3339("2026-04-21T00:00:00Z") - .expect("timestamp should parse") - .with_timezone(&Utc) - ) - ); - assert!(projection_snapshot.active_tasks.contains_key("owner-a")); - - let recovered = SessionState::from_recovery( - Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter))), - &checkpoint, - Vec::new(), - ) - .expect("legacy checkpoint should recover"); - - let recovered_task = recovered - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .expect("legacy task should survive migration"); - assert_eq!( - recovered_task.items, - vec![ExecutionTaskItem { - content: "迁移旧 checkpoint".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在迁移旧 checkpoint".to_string()), - }] - ); - assert_eq!( - recovered - .last_mode_changed_at() - .expect("mode timestamp should exist"), - projection_snapshot.last_mode_changed_at - ); - } -} diff --git a/crates/session-runtime/src/state/paths.rs b/crates/session-runtime/src/state/paths.rs deleted file mode 100644 index 12b11051..00000000 --- a/crates/session-runtime/src/state/paths.rs +++ /dev/null @@ -1,176 +0,0 @@ -//! Session key 规范化与工作目录校验。 - -use std::path::{Path, PathBuf}; - -use astrcode_core::AstrError; -use astrcode_support::hostpaths::{project_dir_name, projects_dir, resolve_home_dir}; - -const SESSIONS_DIR_NAME: &str = "sessions"; - -/// 规范化会话 ID，去除首尾空白并剥离最外层 `session-` 前缀。 -pub fn normalize_session_id(session_id: &str) -> String { - let trimmed = session_id.trim(); - trimmed - .strip_prefix("session-") - .unwrap_or(trimmed) - .to_string() -} - -/// 生成供 compact 摘要引用的 session event log 路径提示。 -/// -/// Why: 路径协议应该收口在单一 helper 中，而不是散落在 compact prompt 拼接逻辑里。 -pub(crate) fn compact_history_event_log_path( - session_id: &str, - working_dir: &Path, -) -> Result { - let session_id = normalize_session_id(session_id); - let path = projects_dir() - .map_err(|error| AstrError::Internal(format!("failed to resolve projects dir: {error}")))? - .join(project_dir_name(working_dir)) - .join(SESSIONS_DIR_NAME) - .join(&session_id) - .join(format!("session-{session_id}.jsonl")); - - Ok(render_home_relative_path(&path)) -} - -/// 规范化工作目录路径，要求路径存在且必须是目录。 -pub fn normalize_working_dir(working_dir: PathBuf) -> Result { - let path = if working_dir.is_absolute() { - working_dir - } else { - std::env::current_dir() - .map_err(|error| AstrError::io("failed to get current directory", error))? - .join(working_dir) - }; - - let metadata = std::fs::metadata(&path).map_err(|error| { - AstrError::Validation(format!( - "workingDir '{}' is invalid: {}", - path.display(), - error - )) - })?; - if !metadata.is_dir() { - return Err(AstrError::Validation(format!( - "workingDir '{}' is not a directory", - path.display() - ))); - } - - // canonicalize 折叠大小写/符号链接等路径别名，保证同一物理目录只对应一个 - // session project bucket，避免会话被拆散到多份路径表示里。 - std::fs::canonicalize(&path).map_err(|error| { - AstrError::io( - format!("failed to canonicalize workingDir '{}'", path.display()), - error, - ) - }) -} - -/// 从工作目录提取展示名。 -pub fn display_name_from_working_dir(path: &Path) -> String { - path.file_name() - .and_then(|name| name.to_str()) - .filter(|name| !name.is_empty()) - .unwrap_or("默认项目") - .to_string() -} - -fn render_home_relative_path(path: &Path) -> String { - let display = resolve_home_dir() - .ok() - .and_then(|home| { - path.strip_prefix(home) - .ok() - .map(|relative| PathBuf::from("~").join(relative)) - }) - .unwrap_or_else(|| path.to_path_buf()); - display.to_string_lossy().replace('\\', "/") -} - -#[cfg(test)] -mod tests { - use std::path::Path; - - use astrcode_core::AstrError; - - use super::{ - compact_history_event_log_path, display_name_from_working_dir, normalize_session_id, - normalize_working_dir, - }; - - #[test] - fn normalize_session_id_only_removes_outer_prefix() { - assert_eq!( - normalize_session_id("session-session-2026-03-08T10-00-00-aaaaaaaa"), - "session-2026-03-08T10-00-00-aaaaaaaa" - ); - } - - #[test] - fn normalize_session_id_trims_outer_whitespace_before_removing_prefix() { - assert_eq!(normalize_session_id("session-abc "), "abc"); - assert_eq!(normalize_session_id(" session-abc"), "abc"); - assert_eq!(normalize_session_id(" abc "), "abc"); - } - - #[test] - fn compact_history_event_log_path_uses_tilde_and_canonical_session_file_name() { - let temp_dir = tempfile::tempdir().expect("tempdir should be created"); - let path = compact_history_event_log_path("session-abc", temp_dir.path()) - .expect("compact history path should build"); - - assert!(path.starts_with("~/.astrcode/projects/")); - assert!(path.ends_with("/sessions/abc/session-abc.jsonl")); - } - - #[test] - fn normalize_working_dir_rejects_file_paths() { - let temp_dir = tempfile::tempdir().expect("tempdir should be created"); - let file = temp_dir.path().join("file.txt"); - std::fs::write(&file, "demo").expect("file should be created"); - - let err = - normalize_working_dir(file).expect_err("file paths should not be accepted as workdir"); - - assert!(matches!(err, AstrError::Validation(_))); - assert!(err.to_string().contains("is not a directory")); - } - - #[test] - fn normalize_working_dir_rejects_missing_paths() { - let temp_dir = tempfile::tempdir().expect("tempdir should be created"); - let missing = temp_dir.path().join("missing"); - - let err = normalize_working_dir(missing).expect_err("missing workdir should fail"); - - assert!(matches!(err, AstrError::Validation(_))); - assert!(err.to_string().contains("is invalid")); - } - - #[test] - fn display_name_from_working_dir_uses_default_for_root() { - #[cfg(windows)] - let root = Path::new(r"C:\"); - #[cfg(not(windows))] - let root = Path::new("/"); - - assert_eq!(display_name_from_working_dir(root), "默认项目"); - } - - #[test] - fn display_name_from_working_dir_ignores_trailing_separator() { - let temp_dir = tempfile::tempdir().expect("tempdir should be created"); - let rendered = format!("{}{}", temp_dir.path().display(), std::path::MAIN_SEPARATOR); - - assert_eq!( - display_name_from_working_dir(Path::new(&rendered)), - temp_dir - .path() - .file_name() - .and_then(|name| name.to_str()) - .expect("tempdir name should be utf-8") - ); - } -} diff --git a/crates/session-runtime/src/state/tasks.rs b/crates/session-runtime/src/state/tasks.rs deleted file mode 100644 index 16f7ec0f..00000000 --- a/crates/session-runtime/src/state/tasks.rs +++ /dev/null @@ -1,261 +0,0 @@ -use std::collections::HashMap; - -use astrcode_core::{ - EXECUTION_TASK_SNAPSHOT_SCHEMA, ExecutionTaskSnapshotMetadata, Result, StorageEventPayload, - StoredEvent, TaskSnapshot, support, -}; - -use super::SessionState; - -pub(crate) fn rebuild_active_tasks(events: &[StoredEvent]) -> HashMap { - let mut tasks = HashMap::new(); - for stored in events { - if let Some(snapshot) = task_snapshot_from_stored_event(stored) { - apply_snapshot_to_map(&mut tasks, snapshot); - } - } - tasks -} - -pub(crate) fn task_snapshot_from_stored_event(stored: &StoredEvent) -> Option { - let StorageEventPayload::ToolResult { - tool_name, - metadata: Some(metadata), - .. - } = &stored.event.payload - else { - return None; - }; - - if tool_name != "taskWrite" { - return None; - } - - let parsed = serde_json::from_value::(metadata.clone()).ok()?; - if parsed.schema != EXECUTION_TASK_SNAPSHOT_SCHEMA { - return None; - } - - Some(parsed.into_snapshot()) -} - -pub(crate) fn apply_snapshot_to_map( - tasks: &mut HashMap, - snapshot: TaskSnapshot, -) { - if snapshot.should_clear() { - tasks.remove(snapshot.owner.as_str()); - } else { - tasks.insert(snapshot.owner.clone(), snapshot); - } -} - -impl SessionState { - #[cfg(test)] - pub(crate) fn replace_active_task_snapshot(&self, snapshot: TaskSnapshot) -> Result<()> { - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .replace_active_task_snapshot(snapshot); - Ok(()) - } - - pub fn active_tasks_for(&self, owner: &str) -> Result> { - Ok( - support::lock_anyhow(&self.projection_registry, "session projection registry")? - .active_tasks_for(owner), - ) - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{EventTranslator, ExecutionTaskItem, ExecutionTaskStatus, ModeId, Phase}; - use chrono::Utc; - - use super::*; - use crate::state::test_support::{ - event, root_agent, root_task_write_stored, stored, test_session_state, - }; - - #[test] - fn session_state_rehydrates_active_tasks_from_replay() { - let session = SessionState::new( - Phase::Idle, - test_session_state().writer.clone(), - astrcode_core::AgentStateProjector::default(), - Vec::new(), - vec![root_task_write_stored( - 1, - "owner-a", - vec![ExecutionTaskItem { - content: "补充 task 投影".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在补充 task 投影".to_string()), - }], - )], - ); - - let snapshot = session - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .expect("task snapshot should exist"); - assert_eq!(snapshot.items.len(), 1); - assert_eq!(snapshot.items[0].content, "补充 task 投影"); - } - - #[test] - fn translate_store_and_cache_clears_task_snapshot_when_latest_snapshot_is_completed_only() { - let session = test_session_state(); - let mut translator = EventTranslator::new(Phase::Idle); - - for stored in [ - root_task_write_stored( - 1, - "owner-a", - vec![ExecutionTaskItem { - content: "实现 runtime 投影".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在实现 runtime 投影".to_string()), - }], - ), - root_task_write_stored( - 2, - "owner-a", - vec![ExecutionTaskItem { - content: "实现 runtime 投影".to_string(), - status: ExecutionTaskStatus::Completed, - active_form: Some("已完成 runtime 投影".to_string()), - }], - ), - ] { - session - .translate_store_and_cache(&stored, &mut translator) - .expect("task event should translate"); - } - - assert!( - session - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .is_none() - ); - } - - #[test] - fn translate_store_and_cache_isolates_task_snapshots_by_owner() { - let session = test_session_state(); - let mut translator = EventTranslator::new(Phase::Idle); - - let stored_events = [ - root_task_write_stored( - 1, - "owner-a", - vec![ExecutionTaskItem { - content: "任务 A".to_string(), - status: ExecutionTaskStatus::Pending, - active_form: None, - }], - ), - root_task_write_stored( - 2, - "owner-b", - vec![ExecutionTaskItem { - content: "任务 B".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在处理任务 B".to_string()), - }], - ), - root_task_write_stored(3, "owner-a", Vec::new()), - ]; - - for event in stored_events { - session - .translate_store_and_cache(&event, &mut translator) - .expect("task event should translate"); - } - - assert!( - session - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .is_none() - ); - let owner_b = session - .active_tasks_for("owner-b") - .expect("task lookup should succeed") - .expect("owner-b snapshot should exist"); - assert_eq!(owner_b.items[0].content, "任务 B"); - } - - #[test] - fn translate_store_and_cache_does_not_create_task_snapshot_from_mode_change() { - let session = test_session_state(); - let mut translator = EventTranslator::new(Phase::Idle); - let stored = stored( - 1, - event( - None, - root_agent(), - StorageEventPayload::ModeChanged { - from: ModeId::plan(), - to: ModeId::code(), - timestamp: Utc::now(), - }, - ), - ); - - session - .translate_store_and_cache(&stored, &mut translator) - .expect("mode change should translate"); - - assert!( - session - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .is_none() - ); - } - - #[test] - fn translate_store_and_cache_keeps_existing_task_snapshot_across_mode_change() { - let session = test_session_state(); - let mut translator = EventTranslator::new(Phase::Idle); - - session - .translate_store_and_cache( - &root_task_write_stored( - 1, - "owner-a", - vec![ExecutionTaskItem { - content: "保持 task snapshot".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在保持 task snapshot".to_string()), - }], - ), - &mut translator, - ) - .expect("task write should translate"); - session - .translate_store_and_cache( - &stored( - 2, - event( - None, - root_agent(), - StorageEventPayload::ModeChanged { - from: ModeId::code(), - to: ModeId::plan(), - timestamp: Utc::now(), - }, - ), - ), - &mut translator, - ) - .expect("mode change should translate"); - - let snapshot = session - .active_tasks_for("owner-a") - .expect("task lookup should succeed") - .expect("task snapshot should remain"); - assert_eq!(snapshot.items[0].content, "保持 task snapshot"); - } -} diff --git a/crates/session-runtime/src/state/test_support.rs b/crates/session-runtime/src/state/test_support.rs deleted file mode 100644 index 465d54d9..00000000 --- a/crates/session-runtime/src/state/test_support.rs +++ /dev/null @@ -1,162 +0,0 @@ -#![cfg(test)] - -use std::sync::Arc; - -use astrcode_core::{ - AgentEventContext, AgentLifecycleStatus, AgentStateProjector, ChildAgentRef, - ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNotification, - ChildSessionNotificationKind, EventLogWriter, ExecutionTaskItem, ExecutionTaskSnapshotMetadata, - InvocationKind, ParentExecutionRef, Phase, StorageEvent, StorageEventPayload, StoreResult, - StoredEvent, SubRunStorageMode, TaskSnapshot, -}; - -use super::{SessionState, SessionWriter}; - -pub(crate) struct NoopEventLogWriter; - -impl EventLogWriter for NoopEventLogWriter { - fn append(&mut self, _event: &StorageEvent) -> StoreResult { - unreachable!("session_state tests do not persist through the writer") - } -} - -pub(crate) fn test_session_state() -> SessionState { - SessionState::new( - Phase::Idle, - Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter))), - AgentStateProjector::default(), - Vec::new(), - Vec::new(), - ) -} - -pub(crate) fn root_agent() -> AgentEventContext { - AgentEventContext::default() -} - -pub(crate) fn independent_session_sub_run_agent() -> AgentEventContext { - AgentEventContext { - agent_id: Some("agent-child".to_string().into()), - parent_turn_id: Some("turn-root".to_string().into()), - parent_sub_run_id: None, - agent_profile: Some("explore".to_string()), - sub_run_id: Some("subrun-1".to_string().into()), - invocation_kind: Some(InvocationKind::SubRun), - storage_mode: Some(SubRunStorageMode::IndependentSession), - child_session_id: Some("session-child".to_string().into()), - } -} - -pub(crate) fn event( - turn_id: Option<&str>, - agent: AgentEventContext, - payload: StorageEventPayload, -) -> StorageEvent { - StorageEvent { - turn_id: turn_id.map(str::to_string), - agent, - payload, - } -} - -pub(crate) fn stored(storage_seq: u64, event: StorageEvent) -> StoredEvent { - StoredEvent { storage_seq, event } -} - -pub(crate) fn child_notification_event( - kind: ChildSessionNotificationKind, - status: AgentLifecycleStatus, -) -> StorageEvent { - event( - Some("turn-root"), - independent_session_sub_run_agent(), - StorageEventPayload::ChildSessionNotification { - notification: ChildSessionNotification { - notification_id: format!("child:{kind:?}").into(), - child_ref: sample_spawn_child_ref(status), - kind, - source_tool_call_id: Some("call-1".into()), - delivery: Some(astrcode_core::ParentDelivery { - idempotency_key: format!("child:{kind:?}"), - origin: astrcode_core::ParentDeliveryOrigin::Explicit, - terminal_semantics: match kind { - ChildSessionNotificationKind::Started - | ChildSessionNotificationKind::ProgressSummary - | ChildSessionNotificationKind::Waiting - | ChildSessionNotificationKind::Resumed => { - astrcode_core::ParentDeliveryTerminalSemantics::NonTerminal - }, - ChildSessionNotificationKind::Delivered - | ChildSessionNotificationKind::Closed - | ChildSessionNotificationKind::Failed => { - astrcode_core::ParentDeliveryTerminalSemantics::Terminal - }, - }, - source_turn_id: Some("turn-root".to_string()), - payload: astrcode_core::ParentDeliveryPayload::Progress( - astrcode_core::ProgressParentDeliveryPayload { - message: "child summary".to_string(), - }, - ), - }), - }, - timestamp: Some(chrono::Utc::now()), - }, - ) -} - -pub(crate) fn sample_spawn_child_ref(status: AgentLifecycleStatus) -> ChildAgentRef { - ChildAgentRef { - identity: ChildExecutionIdentity { - agent_id: "agent-child".into(), - session_id: "session-parent".into(), - sub_run_id: "subrun-1".into(), - }, - parent: ParentExecutionRef { - parent_agent_id: Some("agent-parent".into()), - parent_sub_run_id: Some("subrun-parent".into()), - }, - lineage_kind: ChildSessionLineageKind::Spawn, - status, - open_session_id: "session-child".into(), - } -} - -pub(crate) fn root_task_tool_result_event( - turn_id: &str, - owner: &str, - items: Vec, -) -> StorageEvent { - let snapshot = TaskSnapshot { - owner: owner.to_string(), - items, - }; - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::ToolResult { - tool_call_id: format!("call-{turn_id}"), - tool_name: "taskWrite".to_string(), - output: "updated execution tasks".to_string(), - success: true, - error: None, - metadata: Some( - serde_json::to_value(ExecutionTaskSnapshotMetadata::from_snapshot(&snapshot)) - .expect("task metadata should serialize"), - ), - continuation: None, - duration_ms: 1, - }, - } -} - -pub(crate) fn root_task_write_stored( - storage_seq: u64, - owner: &str, - items: Vec, -) -> StoredEvent { - stored( - storage_seq, - root_task_tool_result_event(&format!("turn-{storage_seq}"), owner, items), - ) -} diff --git a/crates/session-runtime/src/turn/compact_events.rs b/crates/session-runtime/src/turn/compact_events.rs deleted file mode 100644 index d852c21c..00000000 --- a/crates/session-runtime/src/turn/compact_events.rs +++ /dev/null @@ -1,129 +0,0 @@ -use astrcode_core::{ - AgentEventContext, CompactTrigger, LlmMessage, StorageEvent, StorageEventPayload, - UserMessageOrigin, -}; - -use crate::{ - context_window::{ - compaction::CompactResult, - file_access::{FileAccessTracker, FileRecoveryConfig}, - }, - turn::events::{CompactAppliedStats, compact_applied_event}, -}; - -pub(crate) fn build_post_compact_events( - turn_id: Option<&str>, - agent: &AgentEventContext, - trigger: CompactTrigger, - compaction: &CompactResult, -) -> Vec { - let mut events = vec![compact_applied_event( - turn_id, - agent, - trigger, - compaction.summary.clone(), - CompactAppliedStats { - meta: compaction.meta.clone(), - preserved_recent_turns: compaction.preserved_recent_turns, - pre_tokens: compaction.pre_tokens, - post_tokens_estimate: compaction.post_tokens_estimate, - messages_removed: compaction.messages_removed, - tokens_freed: compaction.tokens_freed, - }, - compaction.timestamp, - )]; - - if let Some(digest) = compaction.recent_user_context_digest.clone() { - events.push(StorageEvent { - turn_id: turn_id.map(str::to_string), - agent: agent.clone(), - payload: StorageEventPayload::UserMessage { - content: digest, - origin: UserMessageOrigin::RecentUserContextDigest, - timestamp: compaction.timestamp, - }, - }); - } - for content in &compaction.recent_user_context_messages { - events.push(StorageEvent { - turn_id: turn_id.map(str::to_string), - agent: agent.clone(), - payload: StorageEventPayload::UserMessage { - content: content.clone(), - origin: UserMessageOrigin::RecentUserContext, - timestamp: compaction.timestamp, - }, - }); - } - - events -} - -pub(crate) fn build_post_compact_recovery_messages( - file_access_tracker: &FileAccessTracker, - config: FileRecoveryConfig, -) -> Vec { - file_access_tracker.build_recovery_messages(config) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, StorageEventPayload, - }; - use chrono::{TimeZone, Utc}; - - use super::build_post_compact_events; - - #[test] - fn build_post_compact_events_emits_summary_and_recent_user_context() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 21, 11, 0, 0) - .single() - .expect("timestamp should build"); - let events = build_post_compact_events( - Some("turn-1"), - &AgentEventContext::default(), - CompactTrigger::Manual, - &crate::context_window::compaction::CompactResult { - messages: Vec::new(), - summary: "summary".to_string(), - recent_user_context_digest: Some("digest".to_string()), - recent_user_context_messages: vec!["ctx-1".to_string()], - meta: CompactAppliedMeta { - mode: CompactMode::Full, - instructions_present: false, - fallback_used: false, - retry_count: 0, - input_units: 0, - output_summary_chars: 7, - }, - preserved_recent_turns: 1, - pre_tokens: 10, - post_tokens_estimate: 5, - messages_removed: 2, - tokens_freed: 5, - timestamp, - }, - ); - - assert_eq!(events.len(), 3); - assert!(matches!( - &events[0].payload, - StorageEventPayload::CompactApplied { trigger, summary, .. } - if *trigger == CompactTrigger::Manual && summary == "summary" - )); - assert!(matches!( - &events[1].payload, - StorageEventPayload::UserMessage { origin, content, .. } - if *origin == astrcode_core::UserMessageOrigin::RecentUserContextDigest - && content == "digest" - )); - assert!(matches!( - &events[2].payload, - StorageEventPayload::UserMessage { origin, content, .. } - if *origin == astrcode_core::UserMessageOrigin::RecentUserContext - && content == "ctx-1" - )); - } -} diff --git a/crates/session-runtime/src/turn/compaction_cycle.rs b/crates/session-runtime/src/turn/compaction_cycle.rs deleted file mode 100644 index 854a223e..00000000 --- a/crates/session-runtime/src/turn/compaction_cycle.rs +++ /dev/null @@ -1,265 +0,0 @@ -//! 压缩周期 -//! -//! 封装 reactive compact 错误恢复逻辑。 -//! -//! 当 LLM 返回 prompt-too-long 错误时，自动触发上下文压缩。 -//! 这与 proactive compact（基于阈值的预防性压缩）不同—— -//! reactive compact 是 LLM 实际拒绝后的被动恢复。 -//! -//! ## 重试策略 -//! -//! 最多重试 `MAX_REACTIVE_COMPACT_ATTEMPTS` 次，每次压缩会减少历史消息。 -//! 超过上限则终止 turn，避免无限循环。 - -use astrcode_core::{ - AgentEventContext, CancelToken, CompactTrigger, LlmMessage, PromptFactsProvider, Result, - StorageEvent, -}; -use astrcode_kernel::KernelGateway; - -use crate::{ - context_window::{ - ContextWindowSettings, - compaction::{CompactConfig, CompactResult, auto_compact}, - file_access::FileAccessTracker, - }, - state::compact_history_event_log_path, - turn::{ - compact_events::{build_post_compact_events, build_post_compact_recovery_messages}, - request::{PromptOutputRequest, build_prompt_output}, - }, -}; - -/// reactive compact 恢复成功后的结果。 -pub(crate) struct RecoveryResult { - /// 压缩后的消息历史（含文件恢复消息）。 - pub messages: Vec, - /// 压缩期间产生的事件。 - pub events: Vec, -} - -/// reactive compact 调用上下文。 -/// -/// 将分散的参数聚合为结构体，避免函数签名过长。 -pub(crate) struct ReactiveCompactContext<'a> { - pub gateway: &'a KernelGateway, - pub prompt_facts_provider: &'a dyn PromptFactsProvider, - pub messages: &'a [LlmMessage], - pub session_id: &'a str, - pub working_dir: &'a str, - pub turn_id: &'a str, - pub step_index: usize, - pub agent: &'a AgentEventContext, - pub cancel: CancelToken, - pub settings: &'a ContextWindowSettings, - pub file_access_tracker: &'a FileAccessTracker, -} - -fn recovery_result_from_compaction( - turn_id: &str, - agent: &AgentEventContext, - settings: &ContextWindowSettings, - file_access_tracker: &FileAccessTracker, - compaction: CompactResult, -) -> RecoveryResult { - let events = build_post_compact_events(Some(turn_id), agent, CompactTrigger::Auto, &compaction); - let mut messages = compaction.messages; - messages.extend(build_post_compact_recovery_messages( - file_access_tracker, - settings.file_recovery_config(), - )); - - RecoveryResult { messages, events } -} - -/// 尝试通过 reactive compact 从 prompt-too-long 错误恢复。 -/// -/// 返回 `Some(RecoveryResult)` 表示恢复成功，调用方应替换消息历史并 continue。 -/// 返回 `None` 表示无可压缩内容，无法恢复。 -pub async fn try_reactive_compact( - ctx: &ReactiveCompactContext<'_>, -) -> Result> { - let prompt_output = build_prompt_output(PromptOutputRequest { - gateway: ctx.gateway, - prompt_facts_provider: ctx.prompt_facts_provider, - session_id: ctx.session_id, - turn_id: ctx.turn_id, - working_dir: ctx.working_dir.as_ref(), - step_index: ctx.step_index, - messages: ctx.messages, - session_state: None, - current_agent_id: ctx.agent.agent_id.as_ref().map(|id| id.as_str()), - submission_prompt_declarations: &[], - prompt_governance: None, - }) - .await?; - - match auto_compact( - ctx.gateway, - ctx.messages, - Some(&prompt_output.system_prompt), - CompactConfig { - keep_recent_turns: ctx.settings.compact_keep_recent_turns, - keep_recent_user_messages: ctx.settings.compact_keep_recent_user_messages, - trigger: CompactTrigger::Auto, - summary_reserve_tokens: ctx.settings.summary_reserve_tokens, - max_output_tokens: ctx.settings.compact_max_output_tokens, - max_retry_attempts: ctx.settings.compact_max_retry_attempts, - history_path: Some(compact_history_event_log_path( - ctx.session_id, - std::path::Path::new(ctx.working_dir), - )?), - custom_instructions: None, - }, - ctx.cancel.clone(), - ) - .await? - { - Some(compaction) => Ok(Some(recovery_result_from_compaction( - ctx.turn_id, - ctx.agent, - ctx.settings, - ctx.file_access_tracker, - compaction, - ))), - None => Ok(None), - } -} - -#[cfg(test)] -mod tests { - use std::{fs, time::Duration}; - - use astrcode_core::{ - AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, LlmMessage, - StorageEventPayload, ToolCallRequest, UserMessageOrigin, - }; - use chrono::{TimeZone, Utc}; - use serde_json::json; - use tempfile::tempdir; - - use super::{CompactResult, recovery_result_from_compaction}; - use crate::context_window::{ContextWindowSettings, file_access::FileAccessTracker}; - - fn test_settings() -> ContextWindowSettings { - ContextWindowSettings { - auto_compact_enabled: true, - compact_threshold_percent: 80, - reserved_context_size: 20_000, - summary_reserve_tokens: 20_000, - compact_max_output_tokens: 20_000, - compact_max_retry_attempts: 3, - tool_result_max_bytes: 16_384, - compact_keep_recent_turns: 1, - compact_keep_recent_user_messages: 8, - max_tracked_files: 8, - max_recovered_files: 2, - recovery_token_budget: 512, - aggregate_result_bytes_budget: 16_384, - micro_compact_gap_threshold: Duration::from_secs(30), - micro_compact_keep_recent_results: 2, - } - } - - #[test] - fn recovery_result_from_compaction_emits_event_and_appends_file_recovery_messages() { - let tempdir = tempdir().expect("tempdir should exist"); - let working_dir = tempdir.path(); - let file_path = working_dir.join("src").join("lib.rs"); - fs::create_dir_all(file_path.parent().expect("parent dir should exist")) - .expect("parent dir should write"); - fs::write(&file_path, "pub fn recovered() {}\n").expect("file should write"); - - let file_access_messages = vec![ - LlmMessage::Assistant { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-read-1".to_string(), - name: "readFile".to_string(), - args: json!({ "path": "src/lib.rs" }), - }], - reasoning: None, - }, - LlmMessage::Tool { - tool_call_id: "call-read-1".to_string(), - content: "pub fn recovered() {}".to_string(), - }, - ]; - let tracker = FileAccessTracker::seed_from_messages(&file_access_messages, 8, working_dir); - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 8, 0, 0) - .single() - .expect("timestamp should build"); - let compacted_message = LlmMessage::User { - content: "compressed history".to_string(), - origin: UserMessageOrigin::CompactSummary, - }; - let result = recovery_result_from_compaction( - "turn-compact-1", - &AgentEventContext::default(), - &test_settings(), - &tracker, - CompactResult { - messages: vec![compacted_message.clone()], - summary: "older context summary".to_string(), - recent_user_context_digest: None, - recent_user_context_messages: Vec::new(), - meta: CompactAppliedMeta { - mode: CompactMode::RetrySalvage, - instructions_present: false, - fallback_used: true, - retry_count: 2, - input_units: 5, - output_summary_chars: 21, - }, - preserved_recent_turns: 2, - pre_tokens: 1_500, - post_tokens_estimate: 400, - messages_removed: 6, - tokens_freed: 1_100, - timestamp, - }, - ); - - assert_eq!(result.events.len(), 1); - assert_eq!(result.events[0].turn_id.as_deref(), Some("turn-compact-1")); - assert!(matches!( - &result.events[0].payload, - StorageEventPayload::CompactApplied { - trigger, - summary, - meta, - preserved_recent_turns, - pre_tokens, - post_tokens_estimate, - messages_removed, - tokens_freed, - timestamp: event_timestamp, - } if *trigger == CompactTrigger::Auto - && summary == "older context summary" - && meta.mode == CompactMode::RetrySalvage - && !meta.instructions_present - && meta.fallback_used - && meta.retry_count == 2 - && meta.input_units == 5 - && meta.output_summary_chars == 21 - && *preserved_recent_turns == 2 - && *pre_tokens == 1_500 - && *post_tokens_estimate == 400 - && *messages_removed == 6 - && *tokens_freed == 1_100 - && *event_timestamp == timestamp - )); - - assert_eq!(result.messages.len(), 2); - assert_eq!(result.messages[0], compacted_message); - assert!(matches!( - &result.messages[1], - LlmMessage::User { content, origin } - if *origin == UserMessageOrigin::ReactivationPrompt - && content.contains("Recovered file context after compaction.") - && content.contains("lib.rs") - && content.contains("recovered") - )); - } -} diff --git a/crates/session-runtime/src/turn/continuation_cycle.rs b/crates/session-runtime/src/turn/continuation_cycle.rs deleted file mode 100644 index cbe4c2f6..00000000 --- a/crates/session-runtime/src/turn/continuation_cycle.rs +++ /dev/null @@ -1,76 +0,0 @@ -//! 输出截断后的 continuation 恢复语义。 -//! -//! Why: `max_tokens` 截断不是普通完成，也不该只停留在 warning。 -//! 这里把“是否继续、何时停止”做成稳定的内部决策层，供 turn loop 复用。 - -use astrcode_core::{LlmFinishReason, LlmOutput, ResolvedRuntimeConfig}; - -use super::TurnLoopTransition; - -/// 输出截断 continuation 的稳定提示文本。 -pub const OUTPUT_CONTINUATION_PROMPT: &str = "Continue from the exact point where the previous \ - response was cut off. Do not restart, recap, or \ - apologize."; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) enum OutputContinuationDecision { - Continue, - NotNeeded, -} - -pub fn decide_output_continuation( - output: &LlmOutput, - continuation_attempts: usize, - _runtime: &ResolvedRuntimeConfig, -) -> OutputContinuationDecision { - if !matches!(output.finish_reason, LlmFinishReason::MaxTokens) { - return OutputContinuationDecision::NotNeeded; - } - if !output.tool_calls.is_empty() { - return OutputContinuationDecision::NotNeeded; - } - let _ = continuation_attempts; - OutputContinuationDecision::Continue -} - -pub fn continuation_transition() -> TurnLoopTransition { - TurnLoopTransition::OutputContinuationRequested -} - -#[cfg(test)] -mod tests { - use astrcode_core::{LlmUsage, ReasoningContent}; - - use super::*; - - fn output(finish_reason: LlmFinishReason) -> LlmOutput { - LlmOutput { - content: "partial".to_string(), - tool_calls: Vec::new(), - reasoning: Some(ReasoningContent { - content: "thinking".to_string(), - signature: None, - }), - usage: Some(LlmUsage { - input_tokens: 12, - output_tokens: 24, - cache_creation_input_tokens: 0, - cache_read_input_tokens: 0, - }), - finish_reason, - prompt_cache_diagnostics: None, - } - } - - #[test] - fn output_continuation_continues_when_attempts_remain() { - assert_eq!( - decide_output_continuation( - &output(LlmFinishReason::MaxTokens), - 0, - &ResolvedRuntimeConfig::default() - ), - OutputContinuationDecision::Continue - ); - } -} diff --git a/crates/session-runtime/src/turn/events.rs b/crates/session-runtime/src/turn/events.rs deleted file mode 100644 index 1a190a28..00000000 --- a/crates/session-runtime/src/turn/events.rs +++ /dev/null @@ -1,740 +0,0 @@ -#[cfg(test)] -use astrcode_core::ToolOutputStream; -use astrcode_core::{ - AgentEventContext, CompactAppliedMeta, CompactTrigger, LlmUsage, PromptMetricsPayload, - StorageEvent, StorageEventPayload, ToolCallRequest, ToolExecutionResult, UserMessageOrigin, - ports::{PromptBuildCacheMetrics, PromptCacheDiagnostics}, -}; -use chrono::{DateTime, Utc}; - -use crate::context_window::token_usage::PromptTokenSnapshot; - -fn saturating_u32(value: usize) -> u32 { - value.min(u32::MAX as usize) as u32 -} - -pub(crate) struct CompactAppliedStats { - pub meta: CompactAppliedMeta, - pub preserved_recent_turns: usize, - pub pre_tokens: usize, - pub post_tokens_estimate: usize, - pub messages_removed: usize, - pub tokens_freed: usize, -} - -pub(crate) fn session_start_event( - session_id: impl Into, - working_dir: impl Into, - parent_session_id: Option, - parent_storage_seq: Option, - timestamp: DateTime, -) -> StorageEvent { - StorageEvent { - turn_id: None, - agent: AgentEventContext::default(), - payload: StorageEventPayload::SessionStart { - session_id: session_id.into(), - timestamp, - working_dir: working_dir.into(), - parent_session_id, - parent_storage_seq, - }, - } -} - -pub(crate) fn user_message_event( - turn_id: &str, - agent: &AgentEventContext, - content: String, - origin: UserMessageOrigin, - timestamp: DateTime, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::UserMessage { - content, - origin, - timestamp, - }, - } -} - -pub(crate) fn assistant_final_event( - turn_id: &str, - agent: &AgentEventContext, - content: String, - reasoning_content: Option, - reasoning_signature: Option, - step_index: usize, - timestamp: Option>, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::AssistantFinal { - content, - reasoning_content, - reasoning_signature, - step_index: Some(saturating_u32(step_index)), - timestamp, - }, - } -} - -pub(crate) fn turn_done_event( - turn_id: &str, - agent: &AgentEventContext, - terminal_kind: Option, - reason: Option, - timestamp: DateTime, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::TurnDone { - timestamp, - terminal_kind, - reason, - }, - } -} - -pub(crate) fn turn_terminal_event( - turn_id: &str, - agent: &AgentEventContext, - stop_cause: crate::turn::loop_control::TurnStopCause, - timestamp: DateTime, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::TurnDone { - timestamp, - terminal_kind: Some(stop_cause.terminal_kind(None)), - reason: None, - }, - } -} - -pub(crate) fn error_event( - turn_id: Option<&str>, - agent: &AgentEventContext, - message: String, - timestamp: Option>, -) -> StorageEvent { - StorageEvent { - turn_id: turn_id.map(str::to_string), - agent: agent.clone(), - payload: StorageEventPayload::Error { message, timestamp }, - } -} - -pub(crate) fn compact_applied_event( - turn_id: Option<&str>, - agent: &AgentEventContext, - trigger: CompactTrigger, - summary: String, - stats: CompactAppliedStats, - timestamp: DateTime, -) -> StorageEvent { - StorageEvent { - turn_id: turn_id.map(str::to_string), - agent: agent.clone(), - payload: StorageEventPayload::CompactApplied { - trigger, - summary, - meta: stats.meta, - preserved_recent_turns: saturating_u32(stats.preserved_recent_turns), - pre_tokens: saturating_u32(stats.pre_tokens), - post_tokens_estimate: saturating_u32(stats.post_tokens_estimate), - messages_removed: saturating_u32(stats.messages_removed), - tokens_freed: saturating_u32(stats.tokens_freed), - timestamp, - }, - } -} - -pub(crate) fn prompt_metrics_event( - turn_id: &str, - agent: &AgentEventContext, - step_index: usize, - snapshot: PromptTokenSnapshot, - truncated_tool_results: usize, - cache_metrics: PromptBuildCacheMetrics, - provider_cache_metrics_supported: bool, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::PromptMetrics { - metrics: PromptMetricsPayload { - step_index: saturating_u32(step_index), - estimated_tokens: saturating_u32(snapshot.context_tokens), - context_window: saturating_u32(snapshot.context_window), - effective_window: saturating_u32(snapshot.effective_window), - threshold_tokens: saturating_u32(snapshot.threshold_tokens), - truncated_tool_results: saturating_u32(truncated_tool_results), - provider_input_tokens: None, - provider_output_tokens: None, - cache_creation_input_tokens: None, - cache_read_input_tokens: None, - provider_cache_metrics_supported, - prompt_cache_reuse_hits: cache_metrics.reuse_hits, - prompt_cache_reuse_misses: cache_metrics.reuse_misses, - prompt_cache_unchanged_layers: cache_metrics.unchanged_layers, - prompt_cache_diagnostics: None, - }, - }, - } -} - -pub(crate) fn apply_prompt_metrics_usage( - events: &mut [StorageEvent], - step_index: usize, - usage: Option, - diagnostics: Option, -) { - if usage.is_none() && diagnostics.is_none() { - return; - } - - let step_index = saturating_u32(step_index); - let Some(StorageEvent { - payload: StorageEventPayload::PromptMetrics { metrics }, - .. - }) = events.iter_mut().rev().find(|event| { - matches!( - &event.payload, - StorageEventPayload::PromptMetrics { metrics } - if metrics.step_index == step_index - ) - }) - else { - return; - }; - - if let Some(usage) = usage { - metrics.provider_input_tokens = Some(saturating_u32(usage.input_tokens)); - metrics.provider_output_tokens = Some(saturating_u32(usage.output_tokens)); - metrics.cache_creation_input_tokens = - Some(saturating_u32(usage.cache_creation_input_tokens)); - metrics.cache_read_input_tokens = Some(saturating_u32(usage.cache_read_input_tokens)); - } - if let Some(diagnostics) = diagnostics { - metrics.prompt_cache_diagnostics = Some(diagnostics); - } -} - -pub(crate) fn tool_call_event( - turn_id: &str, - agent: &AgentEventContext, - tool_call: &ToolCallRequest, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::ToolCall { - tool_call_id: tool_call.id.clone(), - tool_name: tool_call.name.clone(), - args: tool_call.args.clone(), - }, - } -} - -#[cfg(test)] -pub(crate) fn tool_call_delta_event( - turn_id: &str, - agent: &AgentEventContext, - tool_call_id: String, - tool_name: String, - stream: ToolOutputStream, - delta: String, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::ToolCallDelta { - tool_call_id, - tool_name, - stream, - delta, - }, - } -} - -pub(crate) fn tool_result_event( - turn_id: &str, - agent: &AgentEventContext, - result: &ToolExecutionResult, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::ToolResult { - tool_call_id: result.tool_call_id.clone(), - tool_name: result.tool_name.clone(), - output: result.output.clone(), - success: result.ok, - error: result.error.clone(), - metadata: result.metadata.clone(), - continuation: result.continuation.clone(), - duration_ms: result.duration_ms, - }, - } -} - -pub(crate) fn tool_result_reference_applied_event( - turn_id: &str, - agent: &AgentEventContext, - tool_call_id: &str, - persisted_output: &astrcode_core::PersistedToolOutput, - replacement: &str, - original_bytes: u64, -) -> StorageEvent { - StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::ToolResultReferenceApplied { - tool_call_id: tool_call_id.to_string(), - persisted_output: persisted_output.clone(), - replacement: replacement.to_string(), - original_bytes, - }, - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, LlmUsage, - StorageEventPayload, ToolCallRequest, ToolExecutionResult, ToolOutputStream, - UserMessageOrigin, ports::PromptBuildCacheMetrics, - }; - use chrono::{TimeZone, Utc}; - use serde_json::json; - - use super::{ - CompactAppliedStats, apply_prompt_metrics_usage, assistant_final_event, - compact_applied_event, error_event, prompt_metrics_event, session_start_event, - tool_call_delta_event, tool_call_event, tool_result_event, turn_done_event, - turn_terminal_event, user_message_event, - }; - use crate::context_window::token_usage::PromptTokenSnapshot; - - #[test] - fn session_start_event_preserves_parent_lineage_fields() { - let timestamp = Utc::now(); - let event = session_start_event( - "session-child", - "/workspace/project", - Some("session-parent".to_string()), - Some(42), - timestamp, - ); - - assert!(event.turn_id.is_none()); - assert!(matches!( - event.payload, - StorageEventPayload::SessionStart { - session_id, - timestamp: event_timestamp, - working_dir, - parent_session_id, - parent_storage_seq, - } if session_id == "session-child" - && event_timestamp == timestamp - && working_dir == "/workspace/project" - && parent_session_id.as_deref() == Some("session-parent") - && parent_storage_seq == Some(42) - )); - } - - #[test] - fn user_message_event_preserves_origin_and_timestamp() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 10, 0, 0) - .single() - .expect("timestamp should build"); - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = user_message_event( - "turn-user-1", - &agent, - "please inspect the diff".to_string(), - UserMessageOrigin::ReactivationPrompt, - timestamp, - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-user-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::UserMessage { - content, - origin, - timestamp: event_timestamp, - } if content == "please inspect the diff" - && origin == UserMessageOrigin::ReactivationPrompt - && event_timestamp == timestamp - )); - } - - #[test] - fn assistant_final_event_preserves_reasoning_fields_and_optional_timestamp() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 10, 5, 0) - .single() - .expect("timestamp should build"); - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = assistant_final_event( - "turn-assistant-1", - &agent, - "done".to_string(), - Some("reasoned path".to_string()), - Some("sig-1".to_string()), - 3, - Some(timestamp), - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-assistant-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::AssistantFinal { - content, - reasoning_content, - reasoning_signature, - step_index, - timestamp: event_timestamp, - } if content == "done" - && reasoning_content.as_deref() == Some("reasoned path") - && reasoning_signature.as_deref() == Some("sig-1") - && step_index == Some(3) - && event_timestamp == Some(timestamp) - )); - } - - #[test] - fn turn_done_event_preserves_reason_and_timestamp() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 10, 10, 0) - .single() - .expect("timestamp should build"); - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = turn_done_event( - "turn-done-1", - &agent, - Some(astrcode_core::TurnTerminalKind::Completed), - Some("completed".to_string()), - timestamp, - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-done-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::TurnDone { - timestamp: event_timestamp, - terminal_kind, - reason, - } if event_timestamp == timestamp - && terminal_kind == Some(astrcode_core::TurnTerminalKind::Completed) - && reason.as_deref() == Some("completed") - )); - } - - #[test] - fn turn_terminal_event_preserves_explicit_terminal_kind_without_reason() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 10, 12, 0) - .single() - .expect("timestamp should build"); - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = turn_terminal_event( - "turn-done-2", - &agent, - crate::turn::loop_control::TurnStopCause::Cancelled, - timestamp, - ); - - assert!(matches!( - event.payload, - StorageEventPayload::TurnDone { - timestamp: event_timestamp, - terminal_kind, - reason, - } if event_timestamp == timestamp - && terminal_kind == Some(astrcode_core::TurnTerminalKind::Cancelled) - && reason.is_none() - )); - } - - #[test] - fn error_event_supports_missing_turn_id_and_timestamp() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = error_event(None, &agent, "compact failed".to_string(), None); - - assert!(event.turn_id.is_none()); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::Error { message, timestamp } - if message == "compact failed" && timestamp.is_none() - )); - } - - #[test] - fn compact_applied_event_saturates_large_stats_and_preserves_metadata() { - let timestamp = Utc - .with_ymd_and_hms(2026, 4, 14, 9, 30, 0) - .single() - .expect("timestamp should build"); - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = compact_applied_event( - Some("turn-compact-1"), - &agent, - CompactTrigger::Auto, - "condensed older work".to_string(), - CompactAppliedStats { - meta: CompactAppliedMeta { - mode: CompactMode::RetrySalvage, - instructions_present: true, - fallback_used: true, - retry_count: u32::MAX, - input_units: u32::MAX, - output_summary_chars: u32::MAX, - }, - preserved_recent_turns: usize::MAX, - pre_tokens: usize::MAX, - post_tokens_estimate: 512, - messages_removed: usize::MAX, - tokens_freed: usize::MAX, - }, - timestamp, - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-compact-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::CompactApplied { - trigger, - summary, - meta, - preserved_recent_turns, - pre_tokens, - post_tokens_estimate, - messages_removed, - tokens_freed, - timestamp: event_timestamp, - } if trigger == CompactTrigger::Auto - && summary == "condensed older work" - && meta.mode == CompactMode::RetrySalvage - && meta.instructions_present - && meta.fallback_used - && meta.retry_count == u32::MAX - && meta.input_units == u32::MAX - && meta.output_summary_chars == u32::MAX - && preserved_recent_turns == u32::MAX - && pre_tokens == u32::MAX - && post_tokens_estimate == 512 - && messages_removed == u32::MAX - && tokens_freed == u32::MAX - && event_timestamp == timestamp - )); - } - - #[test] - fn prompt_metrics_event_maps_snapshot_fields_without_provider_metrics() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = prompt_metrics_event( - "turn-prompt-1", - &agent, - 7, - PromptTokenSnapshot { - context_tokens: 12_345, - budget_tokens: 9_999, - context_window: 128_000, - effective_window: 108_000, - threshold_tokens: 97_200, - remaining_context_tokens: 95_655, - reserved_context_size: 20_000, - }, - 3, - PromptBuildCacheMetrics { - reuse_hits: 4, - reuse_misses: 1, - unchanged_layers: vec![astrcode_core::SystemPromptLayer::Stable], - }, - true, - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-prompt-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::PromptMetrics { metrics } - if metrics.step_index == 7 - && metrics.estimated_tokens == 12_345 - && metrics.context_window == 128_000 - && metrics.effective_window == 108_000 - && metrics.threshold_tokens == 97_200 - && metrics.truncated_tool_results == 3 - && metrics.prompt_cache_unchanged_layers - == vec![astrcode_core::SystemPromptLayer::Stable] - && metrics.provider_input_tokens.is_none() - && metrics.provider_output_tokens.is_none() - && metrics.cache_creation_input_tokens.is_none() - && metrics.cache_read_input_tokens.is_none() - && metrics.provider_cache_metrics_supported - && metrics.prompt_cache_reuse_hits == 4 - && metrics.prompt_cache_reuse_misses == 1 - )); - } - - #[test] - fn apply_prompt_metrics_usage_backfills_provider_cache_fields() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let mut events = vec![prompt_metrics_event( - "turn-prompt-1", - &agent, - 2, - PromptTokenSnapshot { - context_tokens: 1_024, - budget_tokens: 900, - context_window: 128_000, - effective_window: 108_000, - threshold_tokens: 97_200, - remaining_context_tokens: 106_976, - reserved_context_size: 20_000, - }, - 0, - PromptBuildCacheMetrics::default(), - true, - )]; - - apply_prompt_metrics_usage( - &mut events, - 2, - Some(LlmUsage { - input_tokens: 900, - output_tokens: 120, - cache_creation_input_tokens: 700, - cache_read_input_tokens: 650, - }), - None, - ); - - assert!(matches!( - &events[0].payload, - StorageEventPayload::PromptMetrics { metrics } - if metrics.provider_input_tokens == Some(900) - && metrics.provider_output_tokens == Some(120) - && metrics.cache_creation_input_tokens == Some(700) - && metrics.cache_read_input_tokens == Some(650) - )); - } - - #[test] - fn tool_call_event_preserves_request_id_name_and_args() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let tool_call = ToolCallRequest { - id: "call-42".to_string(), - name: "readFile".to_string(), - args: json!({ - "path": "src/lib.rs", - "offset": 10 - }), - }; - let event = tool_call_event("turn-tool-call-1", &agent, &tool_call); - - assert_eq!(event.turn_id.as_deref(), Some("turn-tool-call-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::ToolCall { - tool_call_id, - tool_name, - args, - } if tool_call_id == "call-42" - && tool_name == "readFile" - && args == json!({ - "path": "src/lib.rs", - "offset": 10 - }) - )); - } - - #[test] - fn tool_call_delta_event_preserves_stream_and_delta_text() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let event = tool_call_delta_event( - "turn-tool-call-1", - &agent, - "call-42".to_string(), - "readFile".to_string(), - ToolOutputStream::Stderr, - "permission denied".to_string(), - ); - - assert_eq!(event.turn_id.as_deref(), Some("turn-tool-call-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::ToolCallDelta { - tool_call_id, - tool_name, - stream, - delta, - } if tool_call_id == "call-42" - && tool_name == "readFile" - && stream == ToolOutputStream::Stderr - && delta == "permission denied" - )); - } - - #[test] - fn tool_result_event_preserves_error_and_metadata_payload() { - let agent = AgentEventContext::root_execution("root-agent", "planner"); - let result = ToolExecutionResult { - tool_call_id: "call-7".to_string(), - tool_name: "readFile".to_string(), - ok: false, - output: "partial output".to_string(), - error: Some("permission denied".to_string()), - metadata: Some(json!({ - "path": "/workspace/src/lib.rs", - "truncated": true - })), - continuation: None, - duration_ms: 88, - truncated: true, - }; - let event = tool_result_event("turn-tool-1", &agent, &result); - - assert_eq!(event.turn_id.as_deref(), Some("turn-tool-1")); - assert_eq!(event.agent, agent); - assert!(matches!( - event.payload, - StorageEventPayload::ToolResult { - tool_call_id, - tool_name, - output, - success, - error, - metadata, - continuation: _, - duration_ms, - } if tool_call_id == "call-7" - && tool_name == "readFile" - && output == "partial output" - && !success - && error.as_deref() == Some("permission denied") - && metadata == Some(json!({ - "path": "/workspace/src/lib.rs", - "truncated": true - })) - && duration_ms == 88 - )); - } -} diff --git a/crates/session-runtime/src/turn/finalize.rs b/crates/session-runtime/src/turn/finalize.rs deleted file mode 100644 index b7e7f93a..00000000 --- a/crates/session-runtime/src/turn/finalize.rs +++ /dev/null @@ -1,222 +0,0 @@ -use std::{sync::Arc, time::Duration}; - -use astrcode_core::{ - AgentEventContext, EventStore, EventTranslator, Phase, Result, SessionId, StorageEvent, - StoredEvent, TurnTerminalKind, -}; -use chrono::Utc; - -use crate::{ - SessionState, - state::{append_and_broadcast, checkpoint_if_compacted}, - turn::{ - TurnCollaborationSummary, TurnFinishReason, TurnOutcome, TurnRunResult, TurnStopCause, - TurnSummary, - events::{error_event, turn_done_event}, - manual_compact::{ManualCompactRequest, build_manual_compact_events}, - subrun_events::subrun_finished_event, - }, -}; - -pub(crate) async fn persist_storage_events( - event_store: &Arc, - session_state: &Arc, - session_id: &str, - translator: &mut EventTranslator, - events: &[StorageEvent], -) -> Result> { - let mut persisted_events = Vec::::new(); - for event in events { - persisted_events.push(append_and_broadcast(session_state, event, translator).await?); - } - checkpoint_if_compacted( - event_store, - &SessionId::from(session_id.to_string()), - session_state, - &persisted_events, - ) - .await; - Ok(persisted_events) -} - -pub(crate) async fn persist_subrun_finished_event( - session_state: &Arc, - translator: &mut EventTranslator, - persisted_turn_id: &str, - persisted_agent: &AgentEventContext, - turn_result: &crate::TurnRunResult, - source_tool_call_id: Option, -) -> Result<()> { - let Some(event) = subrun_finished_event( - persisted_turn_id, - persisted_agent, - turn_result, - source_tool_call_id, - ) else { - return Ok(()); - }; - append_and_broadcast(session_state, &event, translator).await?; - Ok(()) -} - -pub(crate) async fn persist_turn_failure( - session_state: &Arc, - session_id: &str, - turn_id: &str, - agent: AgentEventContext, - translator: &mut EventTranslator, - source_tool_call_id: Option, - message: String, -) { - let turn_done = turn_done_event( - turn_id, - &agent, - Some(TurnTerminalKind::Error { - message: message.clone(), - }), - None, - Utc::now(), - ); - if let Err(append_error) = append_and_broadcast(session_state, &turn_done, translator).await { - log::error!( - "failed to persist turn failure for session '{}': {}", - session_id, - append_error - ); - return; - } - - let failure = error_event(Some(turn_id), &agent, message.clone(), Some(Utc::now())); - if let Err(append_error) = append_and_broadcast(session_state, &failure, translator).await { - log::error!( - "failed to persist turn error details for session '{}': {}", - session_id, - append_error - ); - } - - let Some(subrun_finished) = subrun_finished_event( - turn_id, - &agent, - &failed_turn_result(message), - source_tool_call_id, - ) else { - return; - }; - if let Err(append_error) = - append_and_broadcast(session_state, &subrun_finished, translator).await - { - log::error!( - "failed to persist failed subrun result for session '{}': {}", - session_id, - append_error - ); - } -} - -fn failed_turn_result(message: String) -> TurnRunResult { - TurnRunResult { - outcome: TurnOutcome::Error { message }, - messages: Vec::new(), - events: Vec::new(), - summary: TurnSummary { - finish_reason: TurnFinishReason::Error, - stop_cause: TurnStopCause::Error, - last_transition: None, - wall_duration: Duration::default(), - step_count: 0, - total_tokens_used: 0, - cache_read_input_tokens: 0, - cache_creation_input_tokens: 0, - auto_compaction_count: 0, - reactive_compact_count: 0, - max_output_continuation_count: 0, - tool_result_replacement_count: 0, - tool_result_reapply_count: 0, - tool_result_bytes_saved: 0, - tool_result_over_budget_message_count: 0, - streaming_tool_launch_count: 0, - streaming_tool_match_count: 0, - streaming_tool_fallback_count: 0, - streaming_tool_discard_count: 0, - streaming_tool_overlap_ms: 0, - collaboration: TurnCollaborationSummary::default(), - }, - } -} - -pub(crate) struct DeferredManualCompactContext<'a> { - pub(crate) gateway: &'a astrcode_kernel::KernelGateway, - pub(crate) prompt_facts_provider: &'a dyn astrcode_core::PromptFactsProvider, - pub(crate) event_store: &'a Arc, - pub(crate) working_dir: &'a str, - pub(crate) turn_runtime: &'a crate::turn::TurnRuntimeState, - pub(crate) session_state: &'a Arc, - pub(crate) session_id: &'a str, -} - -async fn persist_deferred_manual_compact( - context: DeferredManualCompactContext<'_>, - request: &crate::turn::PendingManualCompactRequest, -) { - let DeferredManualCompactContext { - gateway, - prompt_facts_provider, - event_store, - working_dir, - turn_runtime, - session_state, - session_id, - } = context; - let compacting_guard = turn_runtime.enter_compacting(); - let built = build_manual_compact_events(ManualCompactRequest { - gateway, - prompt_facts_provider, - session_state, - session_id, - working_dir: std::path::Path::new(working_dir), - runtime: &request.runtime, - trigger: astrcode_core::CompactTrigger::Deferred, - instructions: request.instructions.as_deref(), - }) - .await; - drop(compacting_guard); - let events = match built { - Ok(Some(events)) => events, - Ok(None) => return, - Err(error) => { - log::warn!( - "failed to build deferred compact for session '{}': {}", - session_id, - error - ); - return; - }, - }; - let mut compact_translator = - EventTranslator::new(session_state.current_phase().unwrap_or(Phase::Idle)); - if let Err(error) = persist_storage_events( - event_store, - session_state, - session_id, - &mut compact_translator, - &events, - ) - .await - { - log::warn!( - "failed to persist deferred compact for session '{}': {}", - session_id, - error - ); - } -} - -pub(crate) async fn persist_pending_manual_compact_if_any( - context: DeferredManualCompactContext<'_>, - pending_runtime: Option, -) { - if let Some(request) = pending_runtime { - persist_deferred_manual_compact(context, &request).await; - } -} diff --git a/crates/session-runtime/src/turn/fork.rs b/crates/session-runtime/src/turn/fork.rs deleted file mode 100644 index d574732b..00000000 --- a/crates/session-runtime/src/turn/fork.rs +++ /dev/null @@ -1,430 +0,0 @@ -use std::path::PathBuf; - -use astrcode_core::{AstrError, SessionId, StorageEventPayload, StoredEvent}; - -use crate::{SessionRuntime, state::normalize_working_dir}; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum ForkPoint { - StorageSeq(u64), - TurnEnd(String), - Latest, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ForkResult { - pub new_session_id: SessionId, - pub fork_point_storage_seq: u64, - pub events_copied: usize, -} - -impl SessionRuntime { - pub async fn fork_session( - &self, - source_session_id: &SessionId, - fork_point: ForkPoint, - ) -> astrcode_core::Result { - self.ensure_session_exists(source_session_id).await?; - - let source_events = self.event_store.replay(source_session_id).await?; - let fork_point_storage_seq = - resolve_fork_point_storage_seq(source_session_id, &source_events, &fork_point)?; - let events_to_copy = - stable_events_up_to_storage_seq(&source_events, fork_point_storage_seq)?; - - let source_actor = self.ensure_loaded_session(source_session_id).await?; - let working_dir = normalize_working_dir(PathBuf::from(source_actor.working_dir()))?; - let new_session_id = self - .fork_events_up_to( - source_session_id, - &working_dir, - &events_to_copy, - Some(fork_point_storage_seq), - ) - .await?; - - Ok(ForkResult { - new_session_id, - fork_point_storage_seq, - events_copied: events_to_copy - .iter() - .filter(|stored| { - !matches!( - stored.event.payload, - StorageEventPayload::SessionStart { .. } - ) - }) - .count(), - }) - } -} - -fn resolve_fork_point_storage_seq( - source_session_id: &SessionId, - events: &[StoredEvent], - fork_point: &ForkPoint, -) -> astrcode_core::Result { - match fork_point { - ForkPoint::Latest => latest_stable_storage_seq(events).ok_or_else(|| { - AstrError::Validation(format!( - "session '{}' has no stable fork point", - source_session_id - )) - }), - ForkPoint::StorageSeq(storage_seq) => { - if !events - .iter() - .any(|stored| stored.storage_seq == *storage_seq) - { - return Err(AstrError::Validation(format!( - "storage_seq {} is out of range for session '{}'", - storage_seq, source_session_id - ))); - } - let _ = stable_events_up_to_storage_seq(events, *storage_seq)?; - Ok(*storage_seq) - }, - ForkPoint::TurnEnd(turn_id) => { - resolve_turn_end_storage_seq(source_session_id, events, turn_id) - }, - } -} - -fn resolve_turn_end_storage_seq( - source_session_id: &SessionId, - events: &[StoredEvent], - turn_id: &str, -) -> astrcode_core::Result { - let turn_exists = events - .iter() - .any(|stored| stored.event.turn_id.as_deref() == Some(turn_id)); - if !turn_exists { - return Err(AstrError::SessionNotFound(format!( - "turn '{}' in session '{}'", - turn_id, source_session_id - ))); - } - - events - .iter() - .find_map(|stored| match &stored.event.payload { - StorageEventPayload::TurnDone { .. } - if stored.event.turn_id.as_deref() == Some(turn_id) => - { - Some(stored.storage_seq) - }, - _ => None, - }) - .ok_or_else(|| { - AstrError::Validation(format!( - "turn '{}' has not completed and cannot be used as a fork point", - turn_id - )) - }) -} - -fn latest_stable_storage_seq(events: &[StoredEvent]) -> Option { - let mut latest = None; - for stored in events { - if matches!( - stored.event.payload, - StorageEventPayload::SessionStart { .. } - ) { - latest = Some(stored.storage_seq); - } - if matches!( - stored.event.payload, - StorageEventPayload::TurnDone { .. } | StorageEventPayload::Error { .. } - ) { - latest = Some(stored.storage_seq); - } - } - latest -} - -fn stable_events_up_to_storage_seq( - events: &[StoredEvent], - storage_seq: u64, -) -> astrcode_core::Result> { - let cutoff = events - .iter() - .position(|stored| stored.storage_seq == storage_seq) - .ok_or_else(|| { - AstrError::Validation(format!("storage_seq {} is out of range", storage_seq)) - })?; - let candidate = events[..=cutoff].to_vec(); - - if is_stable_prefix(&candidate) { - Ok(candidate) - } else { - Err(AstrError::Validation(format!( - "storage_seq {} is inside an unfinished turn and cannot be used as a fork point", - storage_seq - ))) - } -} - -fn is_stable_prefix(events: &[StoredEvent]) -> bool { - let mut active_turn_id: Option<&str> = None; - for stored in events { - let Some(turn_id) = stored.event.turn_id.as_deref() else { - continue; - }; - match &stored.event.payload { - StorageEventPayload::TurnDone { .. } | StorageEventPayload::Error { .. } => { - if active_turn_id == Some(turn_id) { - active_turn_id = None; - } - }, - _ => { - if active_turn_id.is_none() { - active_turn_id = Some(turn_id); - } - }, - } - } - active_turn_id.is_none() -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{AstrError, SessionId, StoredEvent}; - use chrono::Utc; - - use super::{ForkPoint, latest_stable_storage_seq}; - use crate::{ - SessionRuntime, - turn::{ - events::session_start_event, - test_support::{ - BranchingTestEventStore, root_assistant_final_event, root_turn_done_event, - root_turn_event, root_user_message_event, test_runtime, - }, - }, - }; - - fn seed_runtime_with_events( - events: Vec, - ) -> (SessionRuntime, Arc) { - let event_store = Arc::new(BranchingTestEventStore::default()); - event_store.seed_session("source", ".", events); - (test_runtime(event_store.clone()), event_store) - } - - #[test] - fn latest_stable_storage_seq_stops_before_active_turn() { - let events = vec![ - StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }, - StoredEvent { - storage_seq: 2, - event: root_user_message_event("turn-1", "hello"), - }, - StoredEvent { - storage_seq: 3, - event: root_turn_done_event("turn-1", Some("completed".to_string())), - }, - StoredEvent { - storage_seq: 4, - event: root_user_message_event("turn-2", "still running"), - }, - ]; - - assert_eq!(latest_stable_storage_seq(&events), Some(3)); - } - - #[tokio::test] - async fn fork_session_latest_on_idle_copies_all_stable_events() { - let events = vec![ - StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }, - StoredEvent { - storage_seq: 2, - event: root_user_message_event("turn-1", "hello"), - }, - StoredEvent { - storage_seq: 3, - event: root_assistant_final_event("turn-1", "world"), - }, - StoredEvent { - storage_seq: 4, - event: root_turn_done_event("turn-1", Some("completed".to_string())), - }, - ]; - let (runtime, event_store) = seed_runtime_with_events(events); - - let result = runtime - .fork_session(&SessionId::from("source".to_string()), ForkPoint::Latest) - .await - .expect("fork latest should succeed"); - - assert_eq!(result.fork_point_storage_seq, 4); - assert_eq!(result.events_copied, 3); - - let new_events = event_store.stored_events_for(result.new_session_id.as_str()); - assert_eq!(new_events.len(), 4); - let metas = runtime - .list_session_metas() - .await - .expect("metas should be listable"); - let new_meta = metas - .into_iter() - .find(|meta| meta.session_id == result.new_session_id.as_str()) - .expect("new session meta should exist"); - assert_eq!(new_meta.parent_session_id.as_deref(), Some("source")); - assert_eq!(new_meta.parent_storage_seq, Some(4)); - assert_eq!(new_meta.phase, astrcode_core::Phase::Idle); - } - - #[tokio::test] - async fn fork_session_accepts_completed_turn_end_and_stable_storage_seq() { - let events = vec![ - StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }, - StoredEvent { - storage_seq: 2, - event: root_user_message_event("turn-1", "hello"), - }, - StoredEvent { - storage_seq: 3, - event: root_assistant_final_event("turn-1", "world"), - }, - StoredEvent { - storage_seq: 4, - event: root_turn_done_event("turn-1", Some("completed".to_string())), - }, - StoredEvent { - storage_seq: 5, - event: root_user_message_event("turn-2", "next"), - }, - StoredEvent { - storage_seq: 6, - event: root_turn_done_event("turn-2", Some("completed".to_string())), - }, - ]; - let (runtime, _) = seed_runtime_with_events(events); - - let from_turn = runtime - .fork_session( - &SessionId::from("source".to_string()), - ForkPoint::TurnEnd("turn-1".to_string()), - ) - .await - .expect("completed turn should be accepted"); - assert_eq!(from_turn.fork_point_storage_seq, 4); - - let from_seq = runtime - .fork_session( - &SessionId::from("source".to_string()), - ForkPoint::StorageSeq(4), - ) - .await - .expect("stable storage seq should be accepted"); - assert_eq!(from_seq.fork_point_storage_seq, 4); - } - - #[tokio::test] - async fn fork_session_latest_on_thinking_truncates_to_last_stable_turn() { - let events = vec![ - StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }, - StoredEvent { - storage_seq: 2, - event: root_user_message_event("turn-1", "hello"), - }, - StoredEvent { - storage_seq: 3, - event: root_turn_done_event("turn-1", Some("completed".to_string())), - }, - StoredEvent { - storage_seq: 4, - event: root_user_message_event("turn-2", "unfinished"), - }, - StoredEvent { - storage_seq: 5, - event: root_turn_event( - Some("turn-2"), - astrcode_core::StorageEventPayload::AssistantFinal { - content: "partial".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(Utc::now()), - }, - ), - }, - ]; - let (runtime, event_store) = seed_runtime_with_events(events); - - let result = runtime - .fork_session(&SessionId::from("source".to_string()), ForkPoint::Latest) - .await - .expect("fork latest should succeed"); - - assert_eq!(result.fork_point_storage_seq, 3); - let new_events = event_store.stored_events_for(result.new_session_id.as_str()); - assert_eq!(new_events.len(), 3); - } - - #[tokio::test] - async fn fork_session_rejects_unfinished_turn_and_active_storage_seq() { - let events = vec![ - StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }, - StoredEvent { - storage_seq: 2, - event: root_user_message_event("turn-1", "hello"), - }, - ]; - let (runtime, _) = seed_runtime_with_events(events); - - let unfinished_turn = runtime - .fork_session( - &SessionId::from("source".to_string()), - ForkPoint::TurnEnd("turn-1".to_string()), - ) - .await - .expect_err("unfinished turn should be rejected"); - assert!(matches!(unfinished_turn, AstrError::Validation(_))); - - let active_seq = runtime - .fork_session( - &SessionId::from("source".to_string()), - ForkPoint::StorageSeq(2), - ) - .await - .expect_err("active storage seq should be rejected"); - assert!(matches!(active_seq, AstrError::Validation(_))); - } - - #[tokio::test] - async fn fork_session_rejects_unknown_turn_id() { - let events = vec![StoredEvent { - storage_seq: 1, - event: session_start_event("source", ".", None, None, Utc::now()), - }]; - let (runtime, _) = seed_runtime_with_events(events); - - let error = runtime - .fork_session( - &SessionId::from("source".to_string()), - ForkPoint::TurnEnd("turn-missing".to_string()), - ) - .await - .expect_err("missing turn should be rejected"); - - assert!(matches!(error, AstrError::SessionNotFound(_))); - } -} diff --git a/crates/session-runtime/src/turn/interrupt.rs b/crates/session-runtime/src/turn/interrupt.rs deleted file mode 100644 index 7000d910..00000000 --- a/crates/session-runtime/src/turn/interrupt.rs +++ /dev/null @@ -1,233 +0,0 @@ -use astrcode_core::{AgentEventContext, EventTranslator, Result, SessionId}; -use chrono::Utc; - -use crate::{ - SessionRuntime, - state::append_and_broadcast, - turn::{ - TurnStopCause, - events::turn_terminal_event, - finalize::{DeferredManualCompactContext, persist_pending_manual_compact_if_any}, - }, -}; - -impl SessionRuntime { - pub async fn interrupt_session(&self, session_id: &str) -> Result<()> { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = self.ensure_loaded_session(&session_id).await?; - let Some(interrupted) = actor.turn_runtime().interrupt_if_running()? else { - return Ok(()); - }; - let active_turn_id = interrupted.turn_id.clone(); - - if let Some(active_turn_id) = active_turn_id.as_deref() { - let cancelled = self - .kernel - .agent() - .cancel_subruns_for_turn(active_turn_id) - .await; - if !cancelled.is_empty() { - log::info!( - "cancelled {} subruns for interrupted turn '{}'", - cancelled.len(), - active_turn_id - ); - } - } - - let mut translator = EventTranslator::new(actor.state().current_phase()?); - if let Some(active_turn_id) = active_turn_id.as_deref() { - let event = turn_terminal_event( - active_turn_id, - &AgentEventContext::default(), - TurnStopCause::Cancelled, - Utc::now(), - ); - append_and_broadcast(actor.state(), &event, &mut translator).await?; - } - persist_pending_manual_compact_if_any( - DeferredManualCompactContext { - gateway: self.kernel.gateway(), - prompt_facts_provider: self.prompt_facts_provider.as_ref(), - event_store: &self.event_store, - working_dir: actor.working_dir(), - turn_runtime: actor.turn_runtime(), - session_state: actor.state(), - session_id: session_id.as_str(), - }, - interrupted.pending_request, - ) - .await; - Ok(()) - } -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, Phase, PromptBuildOutput, - PromptBuildRequest, PromptFacts, PromptFactsProvider, PromptFactsRequest, PromptProvider, - ResolvedRuntimeConfig, ResourceProvider, ResourceReadResult, ResourceRequestContext, - Result, SessionTurnLease, - }; - use astrcode_kernel::Kernel; - use async_trait::async_trait; - - use crate::turn::test_support::{ - BranchingTestEventStore, append_root_turn_event_to_actor, assert_contains_compact_summary, - }; - - #[derive(Debug)] - struct SummaryLlmProvider; - - #[async_trait] - impl LlmProvider for SummaryLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Ok(LlmOutput { - content: "okmanual compact summary" - .to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 64_000, - max_output_tokens: 8_000, - } - } - } - - #[derive(Debug)] - struct TestPromptProvider; - - #[async_trait] - impl PromptProvider for TestPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: serde_json::Value::Null, - }) - } - } - - #[derive(Debug)] - struct TestResourceProvider; - - #[async_trait] - impl ResourceProvider for TestResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: serde_json::Value::Null, - metadata: serde_json::Value::Null, - }) - } - } - - #[derive(Debug)] - struct NoopPromptFactsProvider; - - struct StubTurnLease; - - impl SessionTurnLease for StubTurnLease {} - - #[async_trait] - impl PromptFactsProvider for NoopPromptFactsProvider { - async fn resolve_prompt_facts(&self, _request: &PromptFactsRequest) -> Result { - Ok(PromptFacts::default()) - } - } - - fn summary_runtime(event_store: Arc) -> crate::SessionRuntime { - crate::SessionRuntime::new( - Arc::new( - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(SummaryLlmProvider)) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ), - Arc::new(NoopPromptFactsProvider), - event_store, - Arc::new(crate::turn::test_support::NoopMetrics), - ) - } - - #[tokio::test] - async fn interrupt_session_persists_pending_manual_compact() { - let runtime = summary_runtime(Arc::new(BranchingTestEventStore::default())); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - let session_id = session.session_id.clone(); - let actor = runtime - .ensure_loaded_session(&astrcode_core::SessionId::from(session_id.clone())) - .await - .expect("session should load"); - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_user_message_event("turn-0", "hello"), - ) - .await; - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_assistant_final_event("turn-0", "latest answer"), - ) - .await; - actor - .turn_runtime() - .request_manual_compact(crate::turn::PendingManualCompactRequest { - runtime: ResolvedRuntimeConfig::default(), - instructions: None, - }) - .expect("manual compact flag should set"); - actor - .turn_runtime() - .prepare( - session_id.as_str(), - "turn-1", - astrcode_core::CancelToken::new(), - Box::new(StubTurnLease), - ) - .expect("turn runtime should enter running state"); - - runtime - .interrupt_session(&session_id) - .await - .expect("interrupt should succeed"); - - assert_eq!( - actor - .state() - .current_phase() - .expect("phase should be readable"), - Phase::Interrupted - ); - let stored = actor - .state() - .snapshot_recent_stored_events() - .expect("stored events should be available"); - assert_contains_compact_summary(&stored, "manual compact summary"); - } -} diff --git a/crates/session-runtime/src/turn/journal.rs b/crates/session-runtime/src/turn/journal.rs deleted file mode 100644 index 06f8c6cd..00000000 --- a/crates/session-runtime/src/turn/journal.rs +++ /dev/null @@ -1,39 +0,0 @@ -use astrcode_core::StorageEvent; - -#[derive(Debug, Clone, Default)] -pub(crate) struct TurnJournal { - events: Vec, -} - -impl TurnJournal { - pub(crate) fn is_empty(&self) -> bool { - self.events.is_empty() - } - - pub(crate) fn events_mut(&mut self) -> &mut Vec { - &mut self.events - } - - pub(crate) fn push(&mut self, event: StorageEvent) { - self.events.push(event); - } - - pub(crate) fn extend(&mut self, events: I) - where - I: IntoIterator, - { - self.events.extend(events); - } - - pub(crate) fn clear(&mut self) { - self.events.clear(); - } - - pub(crate) fn take_events(&mut self) -> Vec { - std::mem::take(&mut self.events) - } - - pub(crate) fn iter(&self) -> impl DoubleEndedIterator { - self.events.iter() - } -} diff --git a/crates/session-runtime/src/turn/llm_cycle.rs b/crates/session-runtime/src/turn/llm_cycle.rs deleted file mode 100644 index 63233a28..00000000 --- a/crates/session-runtime/src/turn/llm_cycle.rs +++ /dev/null @@ -1,409 +0,0 @@ -//! LLM 调用周期 -//! -//! 封装流式 LLM 调用和 prompt-too-long 错误检测。 -//! -//! ## 架构模式：unbounded channel + select + drain -//! -//! 使用 `tokio::select!` 同时等待 LLM 完成和实时转发流式事件。 -//! LLM 完成后用 `try_recv()` 排空 channel 中残余事件。 -//! -//! 为什么使用 unbounded channel：生产者（LLM 流式传输）受网络 I/O 带宽约束， -//! 消费者（select 循环）以同等速度处理事件，缓冲区积压始终是少量 delta。 -//! 使用 bounded channel 会不必要地复杂化反压逻辑。 - -use std::sync::Arc; - -use astrcode_core::{ - AgentEvent, AgentEventContext, AstrError, CancelToken, LlmEvent, LlmOutput, LlmRequest, - ReasoningContent, Result, -}; -use astrcode_kernel::{KernelError, KernelGateway}; -use tokio::sync::mpsc; - -use crate::SessionState; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) struct StreamedToolCallDelta { - pub index: usize, - pub id: Option, - pub name: Option, - pub arguments_delta: String, -} - -pub(crate) type ToolCallDeltaSink = Arc; - -/// 调用 LLM，并把流式 thinking 片段回填到最终 `LlmOutput.reasoning`。 -/// -/// LLM 完成前推送的最后几个 delta 可能还在 channel 缓冲中， -/// 因此在 LLM 返回后还需 `try_recv()` 排空残余事件。 -pub async fn call_llm_streaming( - gateway: &KernelGateway, - request: LlmRequest, - turn_id: &str, - agent: &AgentEventContext, - session_state: &SessionState, - cancel: &CancelToken, - tool_delta_sink: Option, -) -> Result { - let (event_tx, mut event_rx) = mpsc::unbounded_channel::(); - - let sink: astrcode_core::LlmEventSink = Arc::new(move |event| { - let _ = event_tx.send(event); - }); - - let generate_future = gateway.call_llm(request, Some(sink)); - tokio::pin!(generate_future); - - let mut event_rx_open = true; - let mut thinking_deltas = Vec::new(); - let mut thinking_signature = None; - let output = loop { - tokio::select! { - result = &mut generate_future => break result, - maybe_event = event_rx.recv(), if event_rx_open => { - match maybe_event { - Some(event) => emit_llm_delta_live( - event, - turn_id, - agent, - session_state, - tool_delta_sink.as_ref(), - &mut thinking_deltas, - &mut thinking_signature, - ), - None => event_rx_open = false, - } - } - } - - if cancel.is_cancelled() { - return Err(AstrError::LlmInterrupted); - } - }; - - // 排空 channel 中残余事件：LLM 完成前推送的最后几个 delta - while let Ok(event) = event_rx.try_recv() { - emit_llm_delta_live( - event, - turn_id, - agent, - session_state, - tool_delta_sink.as_ref(), - &mut thinking_deltas, - &mut thinking_signature, - ); - } - - let mut output = output.map_err(map_kernel_error)?; - hydrate_reasoning_from_stream(&mut output, &thinking_deltas, thinking_signature.as_deref()); - - Ok(output) -} - -fn hydrate_reasoning_from_stream( - output: &mut LlmOutput, - thinking_deltas: &[String], - thinking_signature: Option<&str>, -) { - if output.reasoning.is_none() && !thinking_deltas.is_empty() { - output.reasoning = Some(ReasoningContent { - content: thinking_deltas.concat(), - signature: thinking_signature.map(ToString::to_string), - }); - return; - } - - if let Some(reasoning) = output.reasoning.as_mut() { - if reasoning.signature.is_none() { - reasoning.signature = thinking_signature.map(ToString::to_string); - } - } -} - -/// 将 LLM 流式增量发到 live 广播，并收集 thinking 片段用于最终 output 回填。 -/// -/// Why: -/// - live 广播负责“即时吐字”，避免前端只能在 turn 结束后一次性看到内容 -/// - durable 真相只保留 `AssistantFinal.reasoning_content`，因此这里需要兜底补齐 -fn emit_llm_delta_live( - event: LlmEvent, - turn_id: &str, - agent: &AgentEventContext, - session_state: &SessionState, - tool_delta_sink: Option<&ToolCallDeltaSink>, - thinking_deltas: &mut Vec, - thinking_signature: &mut Option, -) { - match event { - LlmEvent::TextDelta(text) => { - session_state.broadcast_live_event(AgentEvent::ModelDelta { - turn_id: turn_id.to_string(), - agent: agent.clone(), - delta: text, - }); - }, - LlmEvent::ThinkingDelta(text) => { - thinking_deltas.push(text.clone()); - session_state.broadcast_live_event(AgentEvent::ThinkingDelta { - turn_id: turn_id.to_string(), - agent: agent.clone(), - delta: text, - }); - }, - LlmEvent::ToolCallDelta { - index, - id, - name, - arguments_delta, - } => { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index, - id, - name, - arguments_delta, - }); - } - }, - // ThinkingSignature 预留给带推理完整性令牌的 provider。 - // live UI 不消费它，但 durable AssistantFinal 仍保留这份事实。 - LlmEvent::ThinkingSignature(signature) => { - *thinking_signature = Some(signature); - }, - } -} - -fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool { - let needle = needle.as_bytes(); - haystack - .as_bytes() - .windows(needle.len()) - .any(|window| window.eq_ignore_ascii_case(needle)) -} - -/// 将 kernel 层的 `KernelError` 映射回 `AstrError`。 -/// -/// kernel 通过字符串前缀区分 LLM 错误类型（"LLM request failed"、"LLM stream error" 等）， -/// 这里重建类型化的 `AstrError` 变体，让上层能精确匹配。 -fn map_kernel_error(error: KernelError) -> AstrError { - match error { - KernelError::Validation(message) => AstrError::Validation(message), - KernelError::NotFound(message) => AstrError::Internal(message), - KernelError::Invoke(message) => { - if contains_ascii_case_insensitive(&message, "llm request interrupted") - || contains_ascii_case_insensitive(&message, "operation cancelled") - || contains_ascii_case_insensitive(&message, "cancelled") - { - return AstrError::LlmInterrupted; - } - - if let Some(raw) = message.strip_prefix("LLM request failed: ") { - if let Some((status_raw, body)) = raw.split_once(" - ") { - if let Ok(status) = status_raw.trim().parse::() { - return AstrError::LlmRequestFailed { - status, - body: body.to_string(), - }; - } - } - return AstrError::LlmRequestFailed { - status: 400, - body: raw.to_string(), - }; - } - - if let Some(raw) = message.strip_prefix("LLM stream error: ") { - return AstrError::LlmStreamError(raw.to_string()); - } - - if let Some(raw) = message.strip_prefix("network error: ") { - return AstrError::Network(raw.to_string()); - } - - if let Some(raw) = message.strip_prefix("invalid api key for provider: ") { - AstrError::InvalidApiKey(raw.to_string()) - } else { - AstrError::Internal(message) - } - }, - } -} - -#[cfg(test)] -mod tests { - use std::sync::{Arc, Mutex}; - - use astrcode_core::{ - AgentEventContext, AstrError, LlmFinishReason, LlmOutput, ReasoningContent, - }; - use astrcode_kernel::KernelError; - - use super::{ - StreamedToolCallDelta, emit_llm_delta_live, hydrate_reasoning_from_stream, map_kernel_error, - }; - use crate::turn::test_support::test_session_state; - - #[test] - fn map_kernel_error_restores_llm_request_failed_variant() { - let mapped = map_kernel_error(KernelError::Invoke( - "LLM request failed: 400 - invalid_request_error: messages 参数非法".to_string(), - )); - - match mapped { - AstrError::LlmRequestFailed { status, body } => { - assert_eq!(status, 400); - assert!(body.contains("messages 参数非法")); - }, - other => panic!("unexpected error variant: {other:?}"), - } - } - - #[test] - fn map_kernel_error_restores_llm_stream_error_variant() { - let mapped = map_kernel_error(KernelError::Invoke( - "LLM stream error: invalid_request_error: messages 参数非法".to_string(), - )); - - match mapped { - AstrError::LlmStreamError(message) => { - assert!(message.contains("messages 参数非法")); - }, - other => panic!("unexpected error variant: {other:?}"), - } - } - - #[test] - fn map_kernel_error_restores_llm_interrupted_variant_for_cancelled_messages() { - let mapped = map_kernel_error(KernelError::Invoke( - "operation cancelled: parent requested shutdown".to_string(), - )); - - match mapped { - AstrError::LlmInterrupted => {}, - other => panic!("unexpected error variant: {other:?}"), - } - } - - #[test] - fn emit_llm_delta_live_forwards_tool_call_delta_to_runner_sink() { - let received = Arc::new(Mutex::new(Vec::new())); - let sink_received = Arc::clone(&received); - let sink: super::ToolCallDeltaSink = Arc::new(move |delta: StreamedToolCallDelta| { - sink_received - .lock() - .expect("tool delta sink lock should work") - .push(delta); - }); - - let mut thinking_deltas = Vec::new(); - let mut thinking_signature = None; - emit_llm_delta_live( - astrcode_core::LlmEvent::ToolCallDelta { - index: 0, - id: Some("call-1".to_string()), - name: Some("readFile".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }, - "turn-1", - &AgentEventContext::default(), - &test_session_state(), - Some(&sink), - &mut thinking_deltas, - &mut thinking_signature, - ); - - assert_eq!( - received - .lock() - .expect("tool delta sink lock should work") - .as_slice(), - &[StreamedToolCallDelta { - index: 0, - id: Some("call-1".to_string()), - name: Some("readFile".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }] - ); - assert!(thinking_deltas.is_empty()); - assert_eq!(thinking_signature, None); - } - - #[test] - fn emit_llm_delta_live_collects_thinking_for_durable_persistence() { - let mut thinking_deltas = Vec::new(); - let mut thinking_signature = None; - - emit_llm_delta_live( - astrcode_core::LlmEvent::ThinkingDelta("先检查状态".to_string()), - "turn-1", - &AgentEventContext::default(), - &test_session_state(), - None, - &mut thinking_deltas, - &mut thinking_signature, - ); - emit_llm_delta_live( - astrcode_core::LlmEvent::ThinkingSignature("sig-1".to_string()), - "turn-1", - &AgentEventContext::default(), - &test_session_state(), - None, - &mut thinking_deltas, - &mut thinking_signature, - ); - - assert_eq!(thinking_deltas, vec!["先检查状态".to_string()]); - assert_eq!(thinking_signature.as_deref(), Some("sig-1")); - } - - #[test] - fn hydrate_reasoning_from_stream_backfills_missing_reasoning_content() { - let mut output = LlmOutput { - content: "done".to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }; - - hydrate_reasoning_from_stream( - &mut output, - &["先检查".to_string(), "再修改".to_string()], - Some("sig-1"), - ); - - assert_eq!( - output.reasoning, - Some(ReasoningContent { - content: "先检查再修改".to_string(), - signature: Some("sig-1".to_string()), - }) - ); - } - - #[test] - fn hydrate_reasoning_from_stream_preserves_existing_reasoning_and_backfills_signature() { - let mut output = LlmOutput { - content: "done".to_string(), - tool_calls: Vec::new(), - reasoning: Some(ReasoningContent { - content: "最终 reasoning".to_string(), - signature: None, - }), - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }; - - hydrate_reasoning_from_stream(&mut output, &["流式 reasoning".to_string()], Some("sig-2")); - - assert_eq!( - output.reasoning, - Some(ReasoningContent { - content: "最终 reasoning".to_string(), - signature: Some("sig-2".to_string()), - }) - ); - } -} diff --git a/crates/session-runtime/src/turn/loop_control.rs b/crates/session-runtime/src/turn/loop_control.rs deleted file mode 100644 index bfab45ca..00000000 --- a/crates/session-runtime/src/turn/loop_control.rs +++ /dev/null @@ -1,58 +0,0 @@ -//! turn loop 的显式过渡/停止语义。 -//! -//! Why: `request -> llm -> tool` 的编排已经模块化，但“为什么继续/停止” -//! 仍需要一个稳定骨架，否则后续输出截断恢复和流式工具调度 -//! 都会退化成新的局部布尔值。 - -use astrcode_core::TurnTerminalKind; - -/// 内部 loop 的“继续下一轮”原因。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TurnLoopTransition { - ToolCycleCompleted, - ReactiveCompactRecovered, - OutputContinuationRequested, -} - -/// turn 停止的细粒度原因。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TurnStopCause { - Completed, - Cancelled, - Error, -} - -impl TurnStopCause { - pub fn terminal_kind(self, error_message: Option<&str>) -> TurnTerminalKind { - match self { - Self::Completed => TurnTerminalKind::Completed, - Self::Cancelled => TurnTerminalKind::Cancelled, - Self::Error => TurnTerminalKind::Error { - message: error_message.unwrap_or("turn failed").to_string(), - }, - } - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::TurnTerminalKind; - - use super::*; - - #[test] - fn error_stop_cause_maps_to_error_terminal_kind() { - assert_eq!( - TurnStopCause::Error.terminal_kind(Some("boom")), - TurnTerminalKind::Error { - message: "boom".to_string() - } - ); - assert_eq!( - TurnStopCause::Error.terminal_kind(None), - TurnTerminalKind::Error { - message: "turn failed".to_string() - } - ); - } -} diff --git a/crates/session-runtime/src/turn/manual_compact.rs b/crates/session-runtime/src/turn/manual_compact.rs deleted file mode 100644 index bec284b1..00000000 --- a/crates/session-runtime/src/turn/manual_compact.rs +++ /dev/null @@ -1,289 +0,0 @@ -use std::path::Path; - -use astrcode_core::{ - AgentEventContext, CancelToken, ResolvedRuntimeConfig, Result, StorageEvent, - StorageEventPayload, -}; -use astrcode_kernel::KernelGateway; -use chrono::Utc; - -use crate::{ - SessionState, - context_window::{ - ContextWindowSettings, - compaction::{CompactConfig, auto_compact}, - file_access::FileAccessTracker, - }, - state::compact_history_event_log_path, - turn::{ - compact_events::{build_post_compact_events, build_post_compact_recovery_messages}, - request::{PromptOutputRequest, build_prompt_output}, - }, -}; - -pub(crate) struct ManualCompactRequest<'a> { - pub gateway: &'a KernelGateway, - pub prompt_facts_provider: &'a dyn astrcode_core::PromptFactsProvider, - pub session_state: &'a SessionState, - pub session_id: &'a str, - pub working_dir: &'a Path, - pub runtime: &'a ResolvedRuntimeConfig, - pub trigger: astrcode_core::CompactTrigger, - pub instructions: Option<&'a str>, -} - -pub(crate) async fn build_manual_compact_events( - request: ManualCompactRequest<'_>, -) -> Result>> { - let settings = ContextWindowSettings::from(request.runtime); - let projected = request.session_state.snapshot_projected_state()?; - let file_access_tracker = FileAccessTracker::seed_from_messages( - &projected.messages, - settings.max_tracked_files, - request.working_dir, - ); - let prompt_output = build_prompt_output(PromptOutputRequest { - gateway: request.gateway, - prompt_facts_provider: request.prompt_facts_provider, - session_id: request.session_id, - turn_id: "manual-compact", - working_dir: request.working_dir, - step_index: 0, - messages: &projected.messages, - session_state: Some(request.session_state), - current_agent_id: None, - submission_prompt_declarations: &[], - prompt_governance: None, - }) - .await?; - - let Some(compaction) = auto_compact( - request.gateway, - &projected.messages, - Some(&prompt_output.system_prompt), - CompactConfig { - keep_recent_turns: settings.compact_keep_recent_turns, - keep_recent_user_messages: settings.compact_keep_recent_user_messages, - trigger: request.trigger, - summary_reserve_tokens: settings.summary_reserve_tokens, - max_output_tokens: settings.compact_max_output_tokens, - max_retry_attempts: settings.compact_max_retry_attempts, - history_path: Some(compact_history_event_log_path( - request.session_id, - request.working_dir, - )?), - custom_instructions: request.instructions.map(str::to_string), - }, - CancelToken::new(), - ) - .await? - else { - return Ok(None); - }; - - let mut events = build_post_compact_events( - None, - &AgentEventContext::default(), - request.trigger, - &compaction, - ); - - for message in - build_post_compact_recovery_messages(&file_access_tracker, settings.file_recovery_config()) - { - let astrcode_core::LlmMessage::User { content, origin } = message else { - continue; - }; - events.push(StorageEvent { - turn_id: None, - agent: AgentEventContext::default(), - payload: StorageEventPayload::UserMessage { - content, - origin, - timestamp: Utc::now(), - }, - }); - } - - Ok(Some(events)) -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - CompactMode, EventTranslator, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, - ModelLimits, Phase, PromptBuildOutput, PromptBuildRequest, PromptFactsProvider, - PromptFactsRequest, PromptProvider, ResourceProvider, ResourceReadResult, - ResourceRequestContext, Result, SessionId, StorageEventPayload, UserMessageOrigin, - }; - use astrcode_kernel::Kernel; - use async_trait::async_trait; - - use super::*; - use crate::{ - actor::SessionActor, state::append_and_broadcast, turn::test_support::StubEventStore, - }; - - #[derive(Debug)] - struct SummaryLlmProvider; - - #[async_trait] - impl LlmProvider for SummaryLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Ok(LlmOutput { - content: "okmanual compact summary" - .to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 64_000, - max_output_tokens: 8_000, - } - } - } - - #[derive(Debug)] - struct ManualCompactPromptFactsProvider; - - #[async_trait] - impl PromptFactsProvider for ManualCompactPromptFactsProvider { - async fn resolve_prompt_facts( - &self, - _request: &PromptFactsRequest, - ) -> Result { - Ok(astrcode_core::PromptFacts::default()) - } - } - - #[derive(Debug)] - struct TestPromptProvider; - - #[async_trait] - impl PromptProvider for TestPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: serde_json::Value::Null, - }) - } - } - - #[derive(Debug)] - struct TestResourceProvider; - - #[async_trait] - impl ResourceProvider for TestResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: serde_json::Value::Null, - metadata: serde_json::Value::Null, - }) - } - } - - fn summary_kernel() -> Arc { - Arc::new( - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(SummaryLlmProvider)) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ) - } - - #[tokio::test] - async fn build_manual_compact_events_generates_real_summary_event() { - let event_store = Arc::new(StubEventStore::default()); - let actor = SessionActor::new_persistent_with_lineage( - SessionId::from("session-1".to_string()), - ".".to_string(), - "root-agent".into(), - event_store, - None, - None, - ) - .await - .expect("actor should build"); - let mut translator = EventTranslator::new(Phase::Idle); - - append_and_broadcast( - actor.state(), - &StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::UserMessage { - content: "hello".to_string(), - origin: UserMessageOrigin::User, - timestamp: Utc::now(), - }, - }, - &mut translator, - ) - .await - .expect("user event should persist"); - append_and_broadcast( - actor.state(), - &StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AssistantFinal { - content: "latest answer".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(Utc::now()), - }, - }, - &mut translator, - ) - .await - .expect("assistant event should persist"); - - let kernel = summary_kernel(); - let events = build_manual_compact_events(ManualCompactRequest { - gateway: kernel.gateway(), - prompt_facts_provider: &ManualCompactPromptFactsProvider, - session_state: actor.state(), - session_id: "session-1", - working_dir: Path::new("."), - runtime: &ResolvedRuntimeConfig::default(), - trigger: astrcode_core::CompactTrigger::Manual, - instructions: Some("保留错误和文件路径"), - }) - .await - .expect("manual compact should succeed") - .expect("manual compact should produce events"); - - assert!(matches!( - &events[0].payload, - StorageEventPayload::CompactApplied { summary, meta, .. } - if summary.contains("manual compact summary") - && summary.contains("session-1.jsonl") - && meta.mode == CompactMode::Full - && meta.instructions_present - )); - } -} diff --git a/crates/session-runtime/src/turn/mod.rs b/crates/session-runtime/src/turn/mod.rs deleted file mode 100644 index e4c3f5d4..00000000 --- a/crates/session-runtime/src/turn/mod.rs +++ /dev/null @@ -1,65 +0,0 @@ -//! Turn 用例与执行核心。 -//! -//! `session-runtime::turn` 只承接“单次 turn 如何开始、如何中断、如何分支、如何执行”。 -//! `runtime` 拥有运行时控制状态，`watcher` 拥有等待终态的异步监听循环， -//! `runner` 负责 step 循环，`submit/interrupt/branch` 负责对外 façade。 - -mod branch; -mod compact_events; -mod compaction_cycle; -mod continuation_cycle; -mod events; -mod finalize; -mod fork; -mod interrupt; -mod journal; -pub(crate) mod llm_cycle; -mod loop_control; -pub(crate) mod manual_compact; -mod post_llm_policy; -pub(crate) mod projector; -mod request; -mod runner; -mod runtime; -mod submit; -mod subrun_events; -#[cfg(test)] -pub(crate) mod test_support; -// pub mod subagent; -mod summary; -pub(crate) mod tool_cycle; -mod tool_result_budget; -mod watcher; - -pub use fork::{ForkPoint, ForkResult}; -pub use loop_control::{TurnLoopTransition, TurnStopCause}; -pub(crate) use runtime::{PendingManualCompactRequest, TurnRuntimeState}; -pub use submit::AgentPromptSubmission; -pub use summary::{TurnCollaborationSummary, TurnFinishReason, TurnSummary}; -pub(crate) use watcher::{wait_and_project_turn_outcome, wait_for_turn_terminal_snapshot}; - -/// Turn 结束原因。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) enum TurnOutcome { - /// LLM 返回纯文本（无 tool_calls），自然结束。 - Completed, - /// 用户取消或 CancelToken 触发。 - Cancelled, - /// 不可恢复错误。 - Error { message: String }, -} - -impl TurnOutcome { - pub(crate) fn terminal_kind( - &self, - stop_cause: TurnStopCause, - ) -> astrcode_core::TurnTerminalKind { - match self { - Self::Completed => stop_cause.terminal_kind(None), - Self::Cancelled => astrcode_core::TurnTerminalKind::Cancelled, - Self::Error { message } => stop_cause.terminal_kind(Some(message)), - } - } -} - -pub(crate) use runner::{TurnRunRequest as RunnerRequest, TurnRunResult, run_turn}; diff --git a/crates/session-runtime/src/turn/post_llm_policy.rs b/crates/session-runtime/src/turn/post_llm_policy.rs deleted file mode 100644 index 51e580c9..00000000 --- a/crates/session-runtime/src/turn/post_llm_policy.rs +++ /dev/null @@ -1,166 +0,0 @@ -//! step 级 LLM 后置决策策略。 -//! -//! Why: 把“无工具输出后是否继续、何时停止”的判断收敛到单一决策层， -//! 避免 `continuation_cycle`、`step` 与后续扩展通过执行顺序隐式耦合。 - -use astrcode_core::{LlmOutput, ModelLimits, ResolvedRuntimeConfig, UserMessageOrigin}; - -use crate::turn::{ - continuation_cycle::{ - OUTPUT_CONTINUATION_PROMPT, OutputContinuationDecision, continuation_transition, - decide_output_continuation, - }, - loop_control::{TurnLoopTransition, TurnStopCause}, -}; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) enum PostLlmDecision { - ContinueWithPrompt { - nudge: &'static str, - origin: UserMessageOrigin, - transition: TurnLoopTransition, - }, - Stop(TurnStopCause), - ExecuteTools, -} - -#[derive(Debug, Clone)] -pub(crate) struct PostLlmDecisionPolicy { - runtime: ResolvedRuntimeConfig, -} - -#[derive(Debug, Clone, Copy)] -pub(crate) struct PostLlmDecisionInput<'a> { - pub(crate) output: &'a LlmOutput, - pub(crate) max_output_continuation_count: usize, -} - -impl PostLlmDecisionPolicy { - pub(crate) fn new(runtime: &ResolvedRuntimeConfig, _limits: ModelLimits) -> Self { - Self { - runtime: runtime.clone(), - } - } - - pub(crate) fn decide(&self, input: PostLlmDecisionInput<'_>) -> PostLlmDecision { - if !input.output.tool_calls.is_empty() { - return PostLlmDecision::ExecuteTools; - } - - match decide_output_continuation( - input.output, - input.max_output_continuation_count, - &self.runtime, - ) { - OutputContinuationDecision::Continue => PostLlmDecision::ContinueWithPrompt { - nudge: OUTPUT_CONTINUATION_PROMPT, - origin: UserMessageOrigin::ContinuationPrompt, - transition: continuation_transition(), - }, - OutputContinuationDecision::NotNeeded => { - PostLlmDecision::Stop(TurnStopCause::Completed) - }, - } - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{LlmFinishReason, LlmUsage, ReasoningContent}; - - use super::*; - - fn output( - content: &str, - finish_reason: LlmFinishReason, - output_tokens: usize, - tool_calls: Vec, - ) -> LlmOutput { - LlmOutput { - content: content.to_string(), - tool_calls, - reasoning: Some(ReasoningContent { - content: "thinking".to_string(), - signature: None, - }), - usage: Some(LlmUsage { - input_tokens: 20, - output_tokens, - cache_creation_input_tokens: 0, - cache_read_input_tokens: 0, - }), - finish_reason, - prompt_cache_diagnostics: None, - } - } - - #[test] - fn policy_prefers_execute_tools_when_tool_calls_exist() { - let policy = PostLlmDecisionPolicy::new( - &ResolvedRuntimeConfig::default(), - ModelLimits { - context_window: 128_000, - max_output_tokens: 8_000, - }, - ); - - let decision = policy.decide(PostLlmDecisionInput { - output: &output( - "", - LlmFinishReason::ToolCalls, - 0, - vec![astrcode_core::ToolCallRequest { - id: "call-1".to_string(), - name: "readFile".to_string(), - args: serde_json::json!({"path":"src/lib.rs"}), - }], - ), - max_output_continuation_count: 0, - }); - - assert_eq!(decision, PostLlmDecision::ExecuteTools); - } - - #[test] - fn policy_requests_output_continuation_before_completion() { - let policy = PostLlmDecisionPolicy::new( - &ResolvedRuntimeConfig::default(), - ModelLimits { - context_window: 128_000, - max_output_tokens: 8_000, - }, - ); - - let decision = policy.decide(PostLlmDecisionInput { - output: &output("partial", LlmFinishReason::MaxTokens, 24, Vec::new()), - max_output_continuation_count: 0, - }); - - assert_eq!( - decision, - PostLlmDecision::ContinueWithPrompt { - nudge: OUTPUT_CONTINUATION_PROMPT, - origin: UserMessageOrigin::ContinuationPrompt, - transition: TurnLoopTransition::OutputContinuationRequested, - } - ); - } - - #[test] - fn policy_falls_back_to_completed_when_no_continuation_is_needed() { - let policy = PostLlmDecisionPolicy::new( - &ResolvedRuntimeConfig::default(), - ModelLimits { - context_window: 128_000, - max_output_tokens: 8_000, - }, - ); - - let decision = policy.decide(PostLlmDecisionInput { - output: &output("done", LlmFinishReason::Stop, 128, Vec::new()), - max_output_continuation_count: 0, - }); - - assert_eq!(decision, PostLlmDecision::Stop(TurnStopCause::Completed)); - } -} diff --git a/crates/session-runtime/src/turn/projector.rs b/crates/session-runtime/src/turn/projector.rs deleted file mode 100644 index 30bf6cde..00000000 --- a/crates/session-runtime/src/turn/projector.rs +++ /dev/null @@ -1,198 +0,0 @@ -use astrcode_core::{LlmMessage, StorageEventPayload, StoredEvent, TurnProjectionSnapshot}; - -pub(crate) fn apply_turn_projection_event( - projection: &mut TurnProjectionSnapshot, - stored: &StoredEvent, -) { - match &stored.event.payload { - StorageEventPayload::TurnDone { terminal_kind, .. } => { - projection.terminal_kind = terminal_kind.clone() - }, - StorageEventPayload::Error { message, .. } => { - let message = message.trim(); - if !message.is_empty() { - projection.last_error = Some(message.to_string()); - } - }, - _ => {}, - } -} - -pub(crate) fn project_turn_projection(events: &[StoredEvent]) -> Option { - if events.is_empty() { - return None; - } - - let mut projection = TurnProjectionSnapshot { - terminal_kind: None, - last_error: None, - }; - for stored in events { - apply_turn_projection_event(&mut projection, stored); - } - Some(projection) -} - -pub(crate) fn has_terminal_projection(projection: Option<&TurnProjectionSnapshot>) -> bool { - projection.is_some_and(|projection| { - projection.terminal_kind.is_some() || projection.last_error.is_some() - }) -} - -pub(crate) fn last_non_empty_assistant_message(messages: &[LlmMessage]) -> Option { - messages.iter().rev().find_map(|message| match message { - LlmMessage::Assistant { content, .. } if !content.trim().is_empty() => { - Some(content.trim().to_string()) - }, - _ => None, - }) -} - -pub(crate) fn last_non_empty_assistant_event(events: &[StoredEvent]) -> Option { - events - .iter() - .rev() - .find_map(|stored| match &stored.event.payload { - StorageEventPayload::AssistantFinal { content, .. } if !content.trim().is_empty() => { - Some(content.trim().to_string()) - }, - _ => None, - }) -} - -pub(crate) fn last_non_empty_error_event(events: &[StoredEvent]) -> Option { - events - .iter() - .rev() - .find_map(|stored| match &stored.event.payload { - StorageEventPayload::Error { message, .. } if !message.trim().is_empty() => { - Some(message.trim().to_string()) - }, - _ => None, - }) -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentEventContext, StorageEvent, StorageEventPayload, StoredEvent, UserMessageOrigin, - }; - - use super::{ - apply_turn_projection_event, has_terminal_projection, last_non_empty_assistant_event, - last_non_empty_assistant_message, project_turn_projection, - }; - - #[test] - fn project_turn_projection_preserves_empty_terminal_state_for_observed_turn() { - let projection = project_turn_projection(&[StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::UserMessage { - content: "hello".to_string(), - origin: UserMessageOrigin::User, - timestamp: chrono::Utc::now(), - }, - }, - }]) - .expect("projection should exist"); - - assert!(projection.terminal_kind.is_none()); - assert!(projection.last_error.is_none()); - } - - #[test] - fn apply_turn_projection_event_reads_typed_terminal_kind() { - let mut projection = astrcode_core::TurnProjectionSnapshot { - terminal_kind: None, - last_error: None, - }; - - apply_turn_projection_event( - &mut projection, - &StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: None, - }, - }, - }, - ); - - assert_eq!( - projection.terminal_kind, - Some(astrcode_core::TurnTerminalKind::Completed) - ); - } - - #[test] - fn has_terminal_projection_detects_terminal_kind() { - assert!(has_terminal_projection(Some( - &astrcode_core::TurnProjectionSnapshot { - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - last_error: None, - } - ))); - } - - #[test] - fn last_non_empty_assistant_message_skips_blank_entries() { - let summary = last_non_empty_assistant_message(&[ - astrcode_core::LlmMessage::Assistant { - content: " ".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - astrcode_core::LlmMessage::Assistant { - content: "ok".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]); - - assert_eq!(summary.as_deref(), Some("ok")); - } - - #[test] - fn last_non_empty_assistant_event_skips_blank_entries() { - let summary = last_non_empty_assistant_event(&[ - StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AssistantFinal { - content: " ".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - }, - }, - StoredEvent { - storage_seq: 2, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::AssistantFinal { - content: "ready".to_string(), - reasoning_content: None, - reasoning_signature: None, - step_index: None, - timestamp: Some(chrono::Utc::now()), - }, - }, - }, - ]); - - assert_eq!(summary.as_deref(), Some("ready")); - } -} diff --git a/crates/session-runtime/src/turn/request.rs b/crates/session-runtime/src/turn/request.rs deleted file mode 100644 index 12a6bbf8..00000000 --- a/crates/session-runtime/src/turn/request.rs +++ /dev/null @@ -1,949 +0,0 @@ -//! Turn prompt request assembly. -//! -//! This module keeps the boundary between context-window sizing and final prompt -//! request construction. It composes prompt metadata, runs prune/micro-compact, -//! emits metrics, and finally builds `LlmRequest`. - -use std::{collections::HashSet, path::Path, sync::Arc, time::Instant}; - -use astrcode_core::{ - AgentEventContext, CompactTrigger, LlmMessage, LlmRequest, PromptBuildOutput, - PromptBuildRequest, PromptDeclaration, PromptFacts, PromptFactsProvider, PromptFactsRequest, - PromptGovernanceContext, Result, StorageEvent, UserMessageOrigin, -}; -use astrcode_kernel::KernelGateway; - -use crate::{ - context_window::{ - ContextWindowSettings, - compaction::{CompactConfig, auto_compact}, - file_access::{FileAccessTracker, FileRecoveryConfig}, - micro_compact::MicroCompactState, - token_usage::{TokenUsageTracker, build_prompt_snapshot, should_compact}, - }, - state::compact_history_event_log_path, - turn::{ - compact_events::{build_post_compact_events, build_post_compact_recovery_messages}, - events::prompt_metrics_event, - tool_result_budget::{ - ApplyToolResultBudgetRequest, ToolResultBudgetOutcome, ToolResultBudgetStats, - ToolResultReplacementState, apply_tool_result_budget, - }, - }, -}; -// TODO: 需要重构 -pub struct AssemblePromptRequest<'a> { - pub gateway: &'a KernelGateway, - pub prompt_facts_provider: &'a dyn PromptFactsProvider, - pub session_id: &'a str, - pub turn_id: &'a str, - pub working_dir: &'a Path, - pub messages: Vec, - pub cancel: astrcode_core::CancelToken, - pub agent: &'a AgentEventContext, - pub step_index: usize, - pub token_tracker: &'a TokenUsageTracker, - pub tools: Arc<[astrcode_core::ToolDefinition]>, - pub settings: &'a ContextWindowSettings, - pub clearable_tools: &'a HashSet, - pub micro_compact_state: &'a mut MicroCompactState, - pub file_access_tracker: &'a FileAccessTracker, - pub session_state: &'a crate::SessionState, - pub tool_result_replacement_state: &'a mut ToolResultReplacementState, - pub prompt_declarations: &'a [PromptDeclaration], - pub prompt_governance: Option<&'a PromptGovernanceContext>, -} - -pub struct AssemblePromptResult { - pub llm_request: LlmRequest, - pub messages: Vec, - pub events: Vec, - pub auto_compacted: bool, - pub tool_result_budget_stats: ToolResultBudgetStats, -} - -pub(crate) struct PromptOutputRequest<'a> { - pub gateway: &'a KernelGateway, - pub prompt_facts_provider: &'a dyn PromptFactsProvider, - pub session_id: &'a str, - pub turn_id: &'a str, - pub working_dir: &'a Path, - pub step_index: usize, - pub messages: &'a [LlmMessage], - pub session_state: Option<&'a crate::SessionState>, - pub current_agent_id: Option<&'a str>, - pub submission_prompt_declarations: &'a [PromptDeclaration], - pub prompt_governance: Option<&'a PromptGovernanceContext>, -} - -/// Why: request assembly 要回答“最终如何形成一次 LLM 请求”， -/// 因此它属于 `turn/request`，而不属于 `context_window`。 -pub async fn assemble_prompt_request( - request: AssemblePromptRequest<'_>, -) -> Result { - let now = Instant::now(); - let mut events = Vec::new(); - let mut auto_compacted = false; - - let ToolResultBudgetOutcome { - messages: budgeted_messages, - events: budget_events, - stats: tool_result_budget_stats, - } = apply_tool_result_budget(ApplyToolResultBudgetRequest { - messages: &request.messages, - session_id: request.session_id, - working_dir: request.working_dir, - session_state: request.session_state, - replacement_state: request.tool_result_replacement_state, - aggregate_budget_bytes: request.settings.aggregate_result_bytes_budget, - turn_id: request.turn_id, - agent: request.agent, - })?; - events.extend(budget_events); - - let micro_outcome = request.micro_compact_state.apply_if_idle( - &budgeted_messages, - request.clearable_tools, - request.settings.micro_compact_config(), - now, - ); - let mut messages = micro_outcome.messages; - - let prune_outcome = crate::context_window::prune_pass::apply_prune_pass( - &messages, - request.clearable_tools, - request.settings.tool_result_max_bytes, - request.settings.compact_keep_recent_turns, - ); - messages = prune_outcome.messages; - - let mut prompt_output = build_prompt_output(PromptOutputRequest { - gateway: request.gateway, - prompt_facts_provider: request.prompt_facts_provider, - session_id: request.session_id, - turn_id: request.turn_id, - working_dir: request.working_dir, - step_index: request.step_index, - messages: &messages, - session_state: Some(request.session_state), - current_agent_id: request.agent.agent_id.as_ref().map(|id| id.as_str()), - submission_prompt_declarations: request.prompt_declarations, - prompt_governance: request.prompt_governance, - }) - .await?; - let mut snapshot = build_prompt_snapshot( - request.token_tracker, - &messages, - Some(&prompt_output.system_prompt), - request.gateway.model_limits(), - request.settings.compact_threshold_percent, - request.settings.summary_reserve_tokens, - request.settings.reserved_context_size, - ); - - if should_compact(snapshot) { - if request.settings.auto_compact_enabled { - if let Some(compaction) = auto_compact( - request.gateway, - &messages, - Some(&prompt_output.system_prompt), - CompactConfig { - keep_recent_turns: request.settings.compact_keep_recent_turns, - keep_recent_user_messages: request.settings.compact_keep_recent_user_messages, - trigger: CompactTrigger::Auto, - summary_reserve_tokens: request.settings.summary_reserve_tokens, - max_output_tokens: request.settings.compact_max_output_tokens, - max_retry_attempts: request.settings.compact_max_retry_attempts, - history_path: Some(compact_history_event_log_path( - request.session_id, - request.working_dir, - )?), - custom_instructions: None, - }, - request.cancel.clone(), - ) - .await? - { - let compact_events = build_post_compact_events( - Some(request.turn_id), - request.agent, - CompactTrigger::Auto, - &compaction, - ); - messages = compaction.messages; - auto_compacted = true; - messages.extend(build_post_compact_recovery_messages( - request.file_access_tracker, - FileRecoveryConfig { - max_tracked_files: request.settings.max_tracked_files, - max_recovered_files: request.settings.max_recovered_files, - recovery_token_budget: request.settings.recovery_token_budget, - }, - )); - events.extend(compact_events); - - prompt_output = build_prompt_output(PromptOutputRequest { - gateway: request.gateway, - prompt_facts_provider: request.prompt_facts_provider, - session_id: request.session_id, - turn_id: request.turn_id, - working_dir: request.working_dir, - step_index: request.step_index, - messages: &messages, - session_state: Some(request.session_state), - current_agent_id: request.agent.agent_id.as_ref().map(|id| id.as_str()), - submission_prompt_declarations: request.prompt_declarations, - prompt_governance: request.prompt_governance, - }) - .await?; - snapshot = build_prompt_snapshot( - request.token_tracker, - &messages, - Some(&prompt_output.system_prompt), - request.gateway.model_limits(), - request.settings.compact_threshold_percent, - request.settings.summary_reserve_tokens, - request.settings.reserved_context_size, - ); - } - } else { - log::warn!( - "turn {} step {}: context tokens ({}) exceed threshold ({}) but auto compact is \ - disabled", - request.turn_id, - request.step_index, - snapshot.context_tokens, - snapshot.threshold_tokens, - ); - } - } - - events.push(prompt_metrics_event( - request.turn_id, - request.agent, - request.step_index, - snapshot, - prune_outcome.stats.truncated_tool_results, - prompt_output.cache_metrics, - request.gateway.supports_cache_metrics(), - )); - - let mut prompt_cache_hints = prompt_output.prompt_cache_hints.clone(); - prompt_cache_hints.compacted = auto_compacted; - prompt_cache_hints.tool_result_rebudgeted = tool_result_budgeted(&tool_result_budget_stats); - - let mut llm_request = LlmRequest::new(messages.clone(), request.tools, request.cancel.clone()) - .with_system(prompt_output.system_prompt); - llm_request.system_prompt_blocks = prompt_output.system_prompt_blocks; - llm_request.prompt_cache_hints = Some(prompt_cache_hints); - - Ok(AssemblePromptResult { - llm_request, - messages, - events, - auto_compacted, - tool_result_budget_stats, - }) -} - -fn tool_result_budgeted(stats: &ToolResultBudgetStats) -> bool { - stats.replacement_count > 0 || stats.reapply_count > 0 || stats.over_budget_message_count > 0 -} - -pub(crate) async fn build_prompt_output( - request: PromptOutputRequest<'_>, -) -> Result { - let PromptOutputRequest { - gateway, - prompt_facts_provider, - session_id, - turn_id, - working_dir, - step_index, - messages, - session_state, - current_agent_id, - submission_prompt_declarations, - prompt_governance, - } = request; - let facts = prompt_facts_provider - .resolve_prompt_facts(&PromptFactsRequest { - session_id: Some(session_id.to_string().into()), - turn_id: Some(turn_id.to_string().into()), - working_dir: working_dir.to_path_buf(), - allowed_capability_names: gateway - .capabilities() - .capability_specs() - .into_iter() - .map(|spec| spec.name.to_string()) - .collect(), - governance: prompt_governance.cloned(), - }) - .await?; - let turn_index = count_user_turns(messages); - let metadata = build_prompt_metadata( - session_id, turn_id, step_index, turn_index, messages, &facts, - ); - let PromptFacts { - profile, - profile_context, - metadata: _, - skills, - agent_profiles, - mut prompt_declarations, - } = facts; - if let Some(direct_child_snapshot) = - live_direct_child_snapshot_declaration(session_state, current_agent_id)? - { - prompt_declarations.push(direct_child_snapshot); - } - if let Some(task_snapshot) = - live_task_snapshot_declaration(session_state, session_id, current_agent_id)? - { - prompt_declarations.push(task_snapshot); - } - prompt_declarations.extend_from_slice(submission_prompt_declarations); - gateway - .build_prompt(PromptBuildRequest { - session_id: Some(session_id.to_string().into()), - turn_id: Some(turn_id.to_string().into()), - working_dir: working_dir.to_path_buf(), - profile, - step_index, - turn_index, - profile_context, - capabilities: gateway.capabilities().capability_specs(), - skills, - agent_profiles, - prompt_declarations, - metadata, - }) - .await - .map_err(|error| astrcode_core::AstrError::Internal(error.to_string())) -} - -fn live_direct_child_snapshot_declaration( - session_state: Option<&crate::SessionState>, - current_agent_id: Option<&str>, -) -> Result> { - let Some(session_state) = session_state else { - return Ok(None); - }; - let Some(current_agent_id) = current_agent_id.filter(|value| !value.trim().is_empty()) else { - return Ok(None); - }; - - let direct_children = session_state.child_nodes_for_parent(current_agent_id)?; - let children_block = if direct_children.is_empty() { - "- (none)\n- If work needs a new branch, use `spawn` instead of guessing an older \ - `agentId`." - .to_string() - } else { - direct_children - .iter() - .map(|node| { - format!( - "- agentId=`{}` status=`{:?}` subRunId=`{}` childSessionId=`{}` lineage=`{:?}`", - node.agent_id(), - node.status, - node.sub_run_id(), - node.child_session_id, - node.lineage_kind - ) - }) - .collect::>() - .join("\n") - }; - - Ok(Some(PromptDeclaration { - block_id: "agent.live.direct_children".to_string(), - title: "Live Direct Child Snapshot".to_string(), - content: format!( - "Authoritative direct-child snapshot for the current agent.\n\nRouting rules:\n- Only \ - use `agentId` values from this snapshot or from a newer live tool result / child \ - notification in the current prompt tail.\n- Never reuse `agentId`, `subRunId`, or \ - `sessionId` from compact summaries, stale errors, or historical notes.\n- If a child \ - is absent from this snapshot, treat it as unavailable for `send`, `observe`, or \ - `close` at prompt-build time.\n\nDirect children:\n{children_block}" - ), - render_target: astrcode_core::PromptDeclarationRenderTarget::System, - layer: astrcode_core::SystemPromptLayer::Dynamic, - kind: astrcode_core::PromptDeclarationKind::ExtensionInstruction, - priority_hint: Some(592), - always_include: true, - source: astrcode_core::PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some(format!("live-direct-children:{current_agent_id}")), - })) -} - -fn live_task_snapshot_declaration( - session_state: Option<&crate::SessionState>, - session_id: &str, - current_agent_id: Option<&str>, -) -> Result> { - let Some(session_state) = session_state else { - return Ok(None); - }; - let owner = current_agent_id - .filter(|value| !value.trim().is_empty()) - .unwrap_or(session_id); - let Some(snapshot) = session_state.active_tasks_for(owner)? else { - return Ok(None); - }; - let active_items = snapshot.active_items(); - if active_items.is_empty() { - return Ok(None); - } - - let items_block = active_items - .iter() - .map(|item| match item.status { - astrcode_core::ExecutionTaskStatus::InProgress => format!( - "- in_progress: {}{}", - item.content, - item.active_form - .as_deref() - .map(|value| format!(" ({value})")) - .unwrap_or_default() - ), - astrcode_core::ExecutionTaskStatus::Pending => format!("- pending: {}", item.content), - astrcode_core::ExecutionTaskStatus::Completed => String::new(), - }) - .filter(|line| !line.is_empty()) - .collect::>() - .join("\n"); - - Ok(Some(PromptDeclaration { - block_id: "task.active_snapshot".to_string(), - title: "Live Task Snapshot".to_string(), - content: format!( - "Authoritative execution-task snapshot for the current owner.\n\nRules:\n- Treat this \ - snapshot as the current execution checklist for this branch of work.\n- Only \ - `in_progress` and `pending` tasks appear here; completed items are intentionally \ - omitted.\n- Update this snapshot with `taskWrite` before changing focus or after \ - completing a task.\n\nActive tasks:\n{items_block}" - ), - render_target: astrcode_core::PromptDeclarationRenderTarget::System, - layer: astrcode_core::SystemPromptLayer::Dynamic, - kind: astrcode_core::PromptDeclarationKind::ExtensionInstruction, - priority_hint: Some(593), - always_include: true, - source: astrcode_core::PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some(format!("live-task-snapshot:{owner}")), - })) -} - -pub(crate) fn build_prompt_metadata( - session_id: &str, - turn_id: &str, - step_index: usize, - turn_index: usize, - messages: &[LlmMessage], - facts: &PromptFacts, -) -> serde_json::Value { - let latest_user_message = messages.iter().rev().find_map(|message| match message { - LlmMessage::User { - content, - origin: UserMessageOrigin::User, - .. - } => Some(content.clone()), - _ => None, - }); - let mut metadata = match &facts.metadata { - serde_json::Value::Object(map) => map.clone(), - _ => serde_json::Map::new(), - }; - metadata.insert( - "sessionId".to_string(), - serde_json::Value::String(session_id.to_string()), - ); - metadata.insert( - "turnId".to_string(), - serde_json::Value::String(turn_id.to_string()), - ); - metadata.insert( - "stepIndex".to_string(), - serde_json::Value::Number((step_index as u64).into()), - ); - metadata.insert( - "turnIndex".to_string(), - serde_json::Value::Number((turn_index as u64).into()), - ); - metadata.insert( - "latestUserMessage".to_string(), - latest_user_message - .map(serde_json::Value::String) - .unwrap_or(serde_json::Value::Null), - ); - serde_json::Value::Object(metadata) -} - -pub(crate) fn count_user_turns(messages: &[LlmMessage]) -> usize { - messages - .iter() - .filter(|message| { - matches!( - message, - LlmMessage::User { - origin: UserMessageOrigin::User, - .. - } - ) - }) - .count() -} - -#[cfg(test)] -mod tests { - use std::sync::{Arc, Mutex}; - - use astrcode_core::{ - AgentLifecycleStatus, AstrError, ChildExecutionIdentity, ChildSessionLineageKind, - ChildSessionNode, ChildSessionStatusSource, ExecutionTaskItem, ExecutionTaskStatus, - LlmOutput, LlmProvider, LlmRequest, ModelLimits, ParentExecutionRef, PromptBuildOutput, - PromptBuildRequest, PromptDeclaration, PromptDeclarationKind, - PromptDeclarationRenderTarget, PromptDeclarationSource, PromptFacts, PromptFactsProvider, - PromptFactsRequest, PromptProvider, ResolvedRuntimeConfig, ResourceProvider, - ResourceReadResult, ResourceRequestContext, StorageEventPayload, SystemPromptLayer, - ToolDefinition, - }; - use astrcode_kernel::{CapabilityRouter, KernelGateway}; - use async_trait::async_trait; - use serde_json::json; - - use super::*; - use crate::{ - context_window::token_usage::TokenUsageTracker, - turn::{ - test_support::{NoopPromptFactsProvider, test_gateway, test_session_state}, - tool_result_budget::ToolResultReplacementState, - }, - }; - - #[tokio::test] - async fn assemble_prompt_request_emits_prompt_metrics_for_final_prompt() { - let gateway = test_gateway(64_000); - let mut micro_state = crate::context_window::micro_compact::MicroCompactState::default(); - let tracker = crate::context_window::file_access::FileAccessTracker::new(4); - let session_state = test_session_state(); - let mut replacement_state = ToolResultReplacementState::default(); - let settings = ContextWindowSettings::from(&ResolvedRuntimeConfig::default()); - - let result = assemble_prompt_request(AssemblePromptRequest { - gateway: &gateway, - prompt_facts_provider: &NoopPromptFactsProvider, - session_id: "session-1", - turn_id: "turn-1", - working_dir: Path::new("."), - messages: vec![LlmMessage::User { - content: "hello".to_string(), - origin: astrcode_core::UserMessageOrigin::User, - }], - cancel: astrcode_core::CancelToken::new(), - agent: &AgentEventContext::default(), - step_index: 0, - token_tracker: &TokenUsageTracker::default(), - tools: vec![ToolDefinition { - name: "readFile".to_string(), - description: "read".to_string(), - parameters: json!({"type":"object"}), - }] - .into(), - settings: &settings, - clearable_tools: &std::collections::HashSet::new(), - micro_compact_state: &mut micro_state, - file_access_tracker: &tracker, - session_state: &session_state, - tool_result_replacement_state: &mut replacement_state, - prompt_declarations: &[], - prompt_governance: None, - }) - .await - .expect("assembly should succeed"); - - assert_eq!(result.events.len(), 1); - assert!(matches!( - &result.events[0].payload, - StorageEventPayload::PromptMetrics { .. } - )); - assert_eq!(result.llm_request.messages.len(), 1); - } - - #[tokio::test] - async fn assemble_prompt_request_carries_prompt_cache_reuse_counts() { - let base_gateway = test_gateway(64_000); - let gateway = KernelGateway::new( - base_gateway.capabilities().clone(), - Arc::new(LocalNoopLlmProvider), - Arc::new(RecordingPromptProvider { - captured: Arc::new(Mutex::new(Vec::new())), - }), - Arc::new(LocalNoopResourceProvider), - ); - let mut micro_state = crate::context_window::micro_compact::MicroCompactState::default(); - let tracker = crate::context_window::file_access::FileAccessTracker::new(4); - let session_state = test_session_state(); - let mut replacement_state = ToolResultReplacementState::default(); - let settings = ContextWindowSettings::from(&ResolvedRuntimeConfig::default()); - - let result = assemble_prompt_request(AssemblePromptRequest { - gateway: &gateway, - prompt_facts_provider: &NoopPromptFactsProvider, - session_id: "session-1", - turn_id: "turn-1", - working_dir: Path::new("."), - messages: vec![LlmMessage::User { - content: "hello".to_string(), - origin: astrcode_core::UserMessageOrigin::User, - }], - cancel: astrcode_core::CancelToken::new(), - agent: &AgentEventContext::default(), - step_index: 0, - token_tracker: &TokenUsageTracker::default(), - tools: vec![ToolDefinition { - name: "readFile".to_string(), - description: "read".to_string(), - parameters: json!({"type":"object"}), - }] - .into(), - settings: &settings, - clearable_tools: &std::collections::HashSet::new(), - micro_compact_state: &mut micro_state, - file_access_tracker: &tracker, - session_state: &session_state, - tool_result_replacement_state: &mut replacement_state, - prompt_declarations: &[], - prompt_governance: None, - }) - .await - .expect("assembly should succeed"); - - assert!(matches!( - &result.events[0].payload, - StorageEventPayload::PromptMetrics { metrics } - if metrics.prompt_cache_reuse_hits == 2 - && metrics.prompt_cache_reuse_misses == 1 - && !metrics.provider_cache_metrics_supported - )); - } - - #[derive(Debug)] - struct RecordingPromptProvider { - captured: Arc>>, - } - - #[async_trait] - impl PromptProvider for RecordingPromptProvider { - async fn build_prompt( - &self, - request: PromptBuildRequest, - ) -> astrcode_core::Result { - *self.captured.lock().expect("capture lock should work") = - request.prompt_declarations.clone(); - Ok(PromptBuildOutput { - system_prompt: "recorded".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: astrcode_core::PromptBuildCacheMetrics { - reuse_hits: 2, - reuse_misses: 1, - unchanged_layers: Vec::new(), - }, - metadata: serde_json::Value::Null, - }) - } - } - - #[derive(Debug)] - struct RecordingPromptFactsProvider; - - #[async_trait] - impl PromptFactsProvider for RecordingPromptFactsProvider { - async fn resolve_prompt_facts( - &self, - _request: &PromptFactsRequest, - ) -> astrcode_core::Result { - Ok(PromptFacts { - prompt_declarations: vec![PromptDeclaration { - block_id: "facts.contract".to_string(), - title: "Facts Contract".to_string(), - content: "facts".to_string(), - render_target: PromptDeclarationRenderTarget::System, - layer: SystemPromptLayer::Inherited, - kind: PromptDeclarationKind::ExtensionInstruction, - priority_hint: None, - always_include: true, - source: PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some("facts-origin".to_string()), - }], - ..PromptFacts::default() - }) - } - } - - #[derive(Debug)] - struct LocalNoopLlmProvider; - - #[async_trait] - impl LlmProvider for LocalNoopLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> astrcode_core::Result { - Err(AstrError::Validation( - "request test noop llm provider should not execute".to_string(), - )) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 32_000, - max_output_tokens: 4096, - } - } - } - - #[derive(Debug)] - struct LocalNoopResourceProvider; - - #[async_trait] - impl ResourceProvider for LocalNoopResourceProvider { - async fn read_resource( - &self, - uri: &str, - _context: &ResourceRequestContext, - ) -> astrcode_core::Result { - Ok(ResourceReadResult { - uri: uri.to_string(), - content: serde_json::Value::Null, - metadata: serde_json::Value::Null, - }) - } - } - - #[tokio::test] - async fn build_prompt_output_merges_submission_prompt_declarations() { - let captured = Arc::new(Mutex::new(Vec::new())); - let gateway = KernelGateway::new( - CapabilityRouter::empty(), - Arc::new(LocalNoopLlmProvider), - Arc::new(RecordingPromptProvider { - captured: captured.clone(), - }), - Arc::new(LocalNoopResourceProvider), - ); - let submission_declarations = vec![PromptDeclaration { - block_id: "child.execution.contract".to_string(), - title: "Child Execution Contract".to_string(), - content: "submission".to_string(), - render_target: PromptDeclarationRenderTarget::System, - layer: SystemPromptLayer::Inherited, - kind: PromptDeclarationKind::ExtensionInstruction, - priority_hint: None, - always_include: true, - source: PromptDeclarationSource::Builtin, - capability_name: None, - origin: Some("submission-origin".to_string()), - }]; - - let output = build_prompt_output(PromptOutputRequest { - gateway: &gateway, - prompt_facts_provider: &RecordingPromptFactsProvider, - session_id: "session-1", - turn_id: "turn-1", - working_dir: Path::new("."), - step_index: 0, - messages: &[], - session_state: None, - current_agent_id: None, - submission_prompt_declarations: &submission_declarations, - prompt_governance: None, - }) - .await - .expect("prompt output should build"); - - assert_eq!(output.system_prompt, "recorded"); - let captured = captured.lock().expect("capture lock should work"); - assert_eq!(captured.len(), 2); - assert_eq!(captured[0].origin.as_deref(), Some("facts-origin")); - assert_eq!(captured[1].origin.as_deref(), Some("submission-origin")); - } - - #[tokio::test] - async fn build_prompt_output_includes_live_task_snapshot_for_current_owner() { - let captured = Arc::new(Mutex::new(Vec::new())); - let gateway = KernelGateway::new( - CapabilityRouter::empty(), - Arc::new(LocalNoopLlmProvider), - Arc::new(RecordingPromptProvider { - captured: captured.clone(), - }), - Arc::new(LocalNoopResourceProvider), - ); - let session_state = test_session_state(); - session_state - .replace_active_task_snapshot(astrcode_core::TaskSnapshot { - owner: "agent-root".to_string(), - items: vec![ - ExecutionTaskItem { - content: "实现 task prompt 注入".to_string(), - status: ExecutionTaskStatus::InProgress, - active_form: Some("正在实现 task prompt 注入".to_string()), - }, - ExecutionTaskItem { - content: "补充 request 测试".to_string(), - status: ExecutionTaskStatus::Pending, - active_form: None, - }, - ExecutionTaskItem { - content: "完成旧任务".to_string(), - status: ExecutionTaskStatus::Completed, - active_form: Some("已完成旧任务".to_string()), - }, - ], - }) - .expect("task snapshot should store"); - - build_prompt_output(PromptOutputRequest { - gateway: &gateway, - prompt_facts_provider: &RecordingPromptFactsProvider, - session_id: "session-1", - turn_id: "turn-1", - working_dir: Path::new("."), - step_index: 0, - messages: &[], - session_state: Some(session_state.as_ref()), - current_agent_id: Some("agent-root"), - submission_prompt_declarations: &[], - prompt_governance: None, - }) - .await - .expect("prompt output should build"); - - let captured = captured.lock().expect("capture lock should work"); - let declaration = captured - .iter() - .find(|declaration| declaration.block_id == "task.active_snapshot") - .expect("task snapshot declaration should exist"); - assert!( - declaration - .content - .contains("in_progress: 实现 task prompt 注入") - ); - assert!(declaration.content.contains("pending: 补充 request 测试")); - assert!(!declaration.content.contains("完成旧任务")); - } - - #[tokio::test] - async fn build_prompt_output_omits_live_task_snapshot_when_no_active_items_exist() { - let captured = Arc::new(Mutex::new(Vec::new())); - let gateway = KernelGateway::new( - CapabilityRouter::empty(), - Arc::new(LocalNoopLlmProvider), - Arc::new(RecordingPromptProvider { - captured: captured.clone(), - }), - Arc::new(LocalNoopResourceProvider), - ); - let session_state = test_session_state(); - session_state - .replace_active_task_snapshot(astrcode_core::TaskSnapshot { - owner: "session-1".to_string(), - items: vec![ExecutionTaskItem { - content: "已完成任务".to_string(), - status: ExecutionTaskStatus::Completed, - active_form: Some("已完成任务".to_string()), - }], - }) - .expect("task snapshot should store"); - - build_prompt_output(PromptOutputRequest { - gateway: &gateway, - prompt_facts_provider: &RecordingPromptFactsProvider, - session_id: "session-1", - turn_id: "turn-1", - working_dir: Path::new("."), - step_index: 0, - messages: &[], - session_state: Some(session_state.as_ref()), - current_agent_id: None, - submission_prompt_declarations: &[], - prompt_governance: None, - }) - .await - .expect("prompt output should build"); - - let captured = captured.lock().expect("capture lock should work"); - assert!( - captured - .iter() - .all(|declaration| declaration.block_id != "task.active_snapshot") - ); - } - - #[test] - fn live_direct_child_snapshot_declaration_only_uses_current_agents_children() { - let session_state = test_session_state(); - session_state - .upsert_child_session_node(ChildSessionNode { - identity: ChildExecutionIdentity { - agent_id: "agent-child-1".into(), - session_id: "session-parent".into(), - sub_run_id: "subrun-child-1".into(), - }, - child_session_id: "session-child-1".into(), - parent_session_id: "session-parent".into(), - parent: ParentExecutionRef { - parent_agent_id: Some("agent-root".into()), - parent_sub_run_id: Some("subrun-root".into()), - }, - parent_turn_id: "turn-1".into(), - lineage_kind: ChildSessionLineageKind::Spawn, - status: AgentLifecycleStatus::Idle, - status_source: ChildSessionStatusSource::Durable, - created_by_tool_call_id: None, - lineage_snapshot: None, - }) - .expect("direct child should insert"); - session_state - .upsert_child_session_node(ChildSessionNode { - identity: ChildExecutionIdentity { - agent_id: "agent-grandchild-1".into(), - session_id: "session-child-1".into(), - sub_run_id: "subrun-grandchild-1".into(), - }, - child_session_id: "session-grandchild-1".into(), - parent_session_id: "session-child-1".into(), - parent: ParentExecutionRef { - parent_agent_id: Some("agent-child-1".into()), - parent_sub_run_id: Some("subrun-child-1".into()), - }, - parent_turn_id: "turn-2".into(), - lineage_kind: ChildSessionLineageKind::Spawn, - status: AgentLifecycleStatus::Running, - status_source: ChildSessionStatusSource::Durable, - created_by_tool_call_id: None, - lineage_snapshot: None, - }) - .expect("grandchild should insert"); - - let declaration = - live_direct_child_snapshot_declaration(Some(&session_state), Some("agent-root")) - .expect("declaration build should succeed") - .expect("root declaration should exist"); - - assert_eq!(declaration.block_id, "agent.live.direct_children"); - assert!(declaration.content.contains("agentId=`agent-child-1`")); - assert!(declaration.content.contains("subRunId=`subrun-child-1`")); - assert!(!declaration.content.contains("agent-grandchild-1")); - assert!( - declaration - .content - .contains("Never reuse `agentId`, `subRunId`, or `sessionId`") - ); - } -} diff --git a/crates/session-runtime/src/turn/runner.rs b/crates/session-runtime/src/turn/runner.rs deleted file mode 100644 index 26e11a61..00000000 --- a/crates/session-runtime/src/turn/runner.rs +++ /dev/null @@ -1,581 +0,0 @@ -//! Turn 执行器。 -//! -//! 实现一个完整的 Agent Turn：LLM 调用 → 工具执行 → 循环直到完成。 -//! 所有 provider 调用通过 `kernel` gateway 进行，不直接持有 provider。 -//! -//! ## 架构：纯编排器 -//! -//! `run_turn` 只负责 step 循环的编排，所有细节委托给子模块： -//! - `request` — 最终请求拼装（微压缩 → 裁剪 → 自动压缩 → prompt request） -//! - `llm_cycle` — LLM 流式调用 -//! - `compaction_cycle` — reactive compact 错误恢复 -//! - `tool_cycle` — 工具并发执行 -//! -//! ## Turn 内部的 Step 循环 -//! -//! 一个 Turn 可能包含多个 Step（LLM → 工具 → LLM → ...），直到 LLM 不再请求工具调用。 -//! -//! ## 终止条件 -//! -//! - LLM 返回纯文本（无工具调用） -//! - 取消信号触发 -//! - 不可恢复错误 - -mod step; - -use std::{collections::HashSet, path::Path, sync::Arc, time::Instant}; - -use astrcode_core::{ - AgentEventContext, BoundModeToolContractSnapshot, CancelToken, EventStore, EventTranslator, - LlmMessage, ModeId, Phase, PromptDeclaration, PromptFactsProvider, PromptGovernanceContext, - ResolvedRuntimeConfig, Result, SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER, StorageEvent, - StorageEventPayload, ToolDefinition, UserMessageOrigin, -}; -use astrcode_kernel::{CapabilityRouter, Kernel, KernelGateway}; -use chrono::{DateTime, Utc}; -use step::{StepOutcome, run_single_step}; - -use super::{ - TurnOutcome, - journal::TurnJournal, - loop_control::{TurnLoopTransition, TurnStopCause}, - summary::{TurnCollaborationSummary, TurnFinishReason, TurnSummary}, -}; -use crate::{ - SessionState, - context_window::{ - ContextWindowSettings, file_access::FileAccessTracker, micro_compact::MicroCompactState, - token_usage::TokenUsageTracker, - }, - turn::{ - events::turn_terminal_event, finalize::persist_storage_events, - tool_result_budget::ToolResultReplacementState, - }, -}; - -/// 可清除的工具名称（这些工具的旧结果可以被 prune pass 替换为占位文本）。 -/// 工具结果可被 prune pass 替换为占位文本的工具名称。 -/// 这些工具的输出是文件内容，prune 时可以安全替换（需要时重新读取即可）。 -const CLEARABLE_TOOLS: &[&str] = &["readFile", "listDir", "grep", "findFiles"]; - -/// Turn 执行请求。 -pub(crate) struct TurnRunRequest { - pub event_store: Arc, - pub session_id: String, - pub working_dir: String, - pub turn_id: String, - pub messages: Vec, - pub last_assistant_at: Option>, - pub session_state: Arc, - pub runtime: ResolvedRuntimeConfig, - pub cancel: CancelToken, - pub agent: AgentEventContext, - pub current_mode_id: ModeId, - pub prompt_facts_provider: Arc, - pub capability_router: Option, - pub prompt_declarations: Vec, - pub bound_mode_tool_contract: Option, - pub prompt_governance: Option, -} - -/// Turn 执行结果。 -pub(crate) struct TurnRunResult { - pub outcome: TurnOutcome, - /// Turn 结束时的完整消息历史（含本次 turn 新增的）。 - pub messages: Vec, - /// run_turn 返回后仍需由 finalize 兜底持久化的尾部事件。 - pub events: Vec, - /// Turn 级稳定汇总（包含耗时、token、续写等指标）。 - pub summary: TurnSummary, -} - -struct TurnExecutionResources<'a> { - gateway: &'a astrcode_kernel::KernelGateway, - prompt_facts_provider: &'a dyn PromptFactsProvider, - session_id: &'a str, - working_dir: &'a str, - turn_id: &'a str, - session_state: &'a Arc, - runtime: &'a ResolvedRuntimeConfig, - cancel: &'a CancelToken, - agent: &'a AgentEventContext, - current_mode_id: &'a ModeId, - prompt_declarations: &'a [PromptDeclaration], - bound_mode_tool_contract: Option<&'a BoundModeToolContractSnapshot>, - prompt_governance: Option<&'a PromptGovernanceContext>, - tools: Arc<[ToolDefinition]>, - settings: ContextWindowSettings, - clearable_tools: HashSet, -} - -struct TurnExecutionRequestView<'a> { - prompt_facts_provider: &'a dyn PromptFactsProvider, - session_id: &'a str, - working_dir: &'a str, - turn_id: &'a str, - session_state: &'a Arc, - runtime: &'a ResolvedRuntimeConfig, - cancel: &'a CancelToken, - agent: &'a AgentEventContext, - current_mode_id: &'a ModeId, - prompt_declarations: &'a [PromptDeclaration], - bound_mode_tool_contract: Option<&'a BoundModeToolContractSnapshot>, - prompt_governance: Option<&'a PromptGovernanceContext>, -} - -struct TurnExecutionContext { - messages: Vec, - draft_plan_approval_guard_active: bool, - journal: TurnJournal, - lifecycle: TurnLifecycle, - budget: TurnBudgetState, - tool_result_budget: ToolResultBudgetState, - streaming_tools: StreamingToolState, -} - -struct TurnLifecycle { - turn_started_at: Instant, - step_index: usize, - reactive_compact_attempts: usize, - max_output_continuation_count: usize, - last_transition: Option, - stop_cause: Option, -} - -struct TurnBudgetState { - token_tracker: TokenUsageTracker, - total_cache_read_tokens: u64, - total_cache_creation_tokens: u64, - auto_compaction_count: usize, - micro_compact_state: MicroCompactState, - file_access_tracker: FileAccessTracker, -} - -struct ToolResultBudgetState { - replacement_state: ToolResultReplacementState, - replacement_count: usize, - reapply_count: usize, - bytes_saved: usize, - over_budget_message_count: usize, -} - -struct StreamingToolState { - launch_count: usize, - match_count: usize, - fallback_count: usize, - discard_count: usize, - overlap_ms: u64, -} - -struct TurnLifecycleSummary { - finish_reason: TurnFinishReason, - stop_cause: TurnStopCause, - last_transition: Option, - wall_duration: std::time::Duration, - step_count: usize, - reactive_compact_count: usize, - max_output_continuation_count: usize, -} - -struct TurnBudgetSummary { - total_tokens_used: u64, - cache_read_input_tokens: u64, - cache_creation_input_tokens: u64, - auto_compaction_count: usize, -} - -struct ToolResultBudgetSummary { - replacement_count: usize, - reapply_count: usize, - bytes_saved: u64, - over_budget_message_count: usize, -} - -struct StreamingToolSummary { - launch_count: usize, - match_count: usize, - fallback_count: usize, - discard_count: usize, - overlap_ms: u64, -} - -impl<'a> TurnExecutionResources<'a> { - fn new( - gateway: &'a astrcode_kernel::KernelGateway, - request: TurnExecutionRequestView<'a>, - ) -> Self { - let settings = ContextWindowSettings::from(request.runtime); - Self { - gateway, - prompt_facts_provider: request.prompt_facts_provider, - session_id: request.session_id, - working_dir: request.working_dir, - turn_id: request.turn_id, - session_state: request.session_state, - runtime: request.runtime, - cancel: request.cancel, - agent: request.agent, - current_mode_id: request.current_mode_id, - prompt_declarations: request.prompt_declarations, - bound_mode_tool_contract: request.bound_mode_tool_contract, - prompt_governance: request.prompt_governance, - tools: Arc::from(gateway.capabilities().tool_definitions()), - settings, - clearable_tools: CLEARABLE_TOOLS - .iter() - .map(|tool| (*tool).to_string()) - .collect(), - } - } -} - -impl TurnLifecycle { - fn new(turn_started_at: Instant) -> Self { - Self { - turn_started_at, - step_index: 0, - reactive_compact_attempts: 0, - max_output_continuation_count: 0, - last_transition: None, - stop_cause: None, - } - } - - fn record_transition(&mut self, transition: TurnLoopTransition) { - self.last_transition = Some(transition); - } - - fn summarize( - &mut self, - outcome: &TurnOutcome, - stop_cause: TurnStopCause, - ) -> TurnLifecycleSummary { - self.stop_cause = Some(stop_cause); - let terminal_kind = outcome.terminal_kind(stop_cause); - TurnLifecycleSummary { - finish_reason: TurnFinishReason::from(&terminal_kind), - stop_cause, - last_transition: self.last_transition, - wall_duration: self.turn_started_at.elapsed(), - step_count: self.step_index + 1, - reactive_compact_count: self.reactive_compact_attempts, - max_output_continuation_count: self.max_output_continuation_count, - } - } -} - -impl TurnBudgetState { - fn new( - resources: &TurnExecutionResources<'_>, - messages: &[LlmMessage], - turn_started_at: Instant, - last_assistant_at: Option>, - ) -> Self { - Self { - token_tracker: TokenUsageTracker::default(), - total_cache_read_tokens: 0, - total_cache_creation_tokens: 0, - auto_compaction_count: 0, - micro_compact_state: MicroCompactState::seed_from_messages( - messages, - resources.settings.micro_compact_config(), - turn_started_at, - last_assistant_at, - ), - file_access_tracker: FileAccessTracker::seed_from_messages( - messages, - resources.settings.max_tracked_files, - Path::new(resources.working_dir), - ), - } - } - - fn summarize(&self) -> TurnBudgetSummary { - TurnBudgetSummary { - total_tokens_used: self.token_tracker.budget_tokens(0) as u64, - cache_read_input_tokens: self.total_cache_read_tokens, - cache_creation_input_tokens: self.total_cache_creation_tokens, - auto_compaction_count: self.auto_compaction_count, - } - } -} - -impl ToolResultBudgetState { - fn new(resources: &TurnExecutionResources<'_>) -> Self { - Self { - replacement_state: ToolResultReplacementState::seed(resources.session_state) - .unwrap_or_default(), - replacement_count: 0, - reapply_count: 0, - bytes_saved: 0, - over_budget_message_count: 0, - } - } - - fn summarize(&self) -> ToolResultBudgetSummary { - ToolResultBudgetSummary { - replacement_count: self.replacement_count, - reapply_count: self.reapply_count, - bytes_saved: self.bytes_saved as u64, - over_budget_message_count: self.over_budget_message_count, - } - } -} - -impl StreamingToolState { - fn new() -> Self { - Self { - launch_count: 0, - match_count: 0, - fallback_count: 0, - discard_count: 0, - overlap_ms: 0, - } - } - - fn summarize(&self) -> StreamingToolSummary { - StreamingToolSummary { - launch_count: self.launch_count, - match_count: self.match_count, - fallback_count: self.fallback_count, - discard_count: self.discard_count, - overlap_ms: self.overlap_ms, - } - } -} - -impl TurnExecutionContext { - fn new( - resources: &TurnExecutionResources<'_>, - messages: Vec, - last_assistant_at: Option>, - ) -> Self { - let now = Instant::now(); - let budget = TurnBudgetState::new(resources, &messages, now, last_assistant_at); - Self { - draft_plan_approval_guard_active: messages.iter().any(|message| { - matches!( - message, - LlmMessage::User { content, origin } - if *origin == UserMessageOrigin::ReactivationPrompt - && content.contains(SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER) - ) - }), - messages, - journal: TurnJournal::default(), - lifecycle: TurnLifecycle::new(now), - budget, - tool_result_budget: ToolResultBudgetState::new(resources), - streaming_tools: StreamingToolState::new(), - } - } - - fn finish( - mut self, - resources: &TurnExecutionResources<'_>, - outcome: TurnOutcome, - stop_cause: TurnStopCause, - ) -> TurnRunResult { - let lifecycle = self.lifecycle.summarize(&outcome, stop_cause); - let budget = self.budget.summarize(); - let tool_result_budget = self.tool_result_budget.summarize(); - let streaming_tools = self.streaming_tools.summarize(); - TurnRunResult { - outcome, - messages: self.messages, - events: Vec::new(), - summary: TurnSummary { - finish_reason: lifecycle.finish_reason, - stop_cause: lifecycle.stop_cause, - last_transition: lifecycle.last_transition, - wall_duration: lifecycle.wall_duration, - step_count: lifecycle.step_count, - total_tokens_used: budget.total_tokens_used, - cache_read_input_tokens: budget.cache_read_input_tokens, - cache_creation_input_tokens: budget.cache_creation_input_tokens, - auto_compaction_count: budget.auto_compaction_count, - reactive_compact_count: lifecycle.reactive_compact_count, - max_output_continuation_count: lifecycle.max_output_continuation_count, - tool_result_replacement_count: tool_result_budget.replacement_count, - tool_result_reapply_count: tool_result_budget.reapply_count, - tool_result_bytes_saved: tool_result_budget.bytes_saved, - tool_result_over_budget_message_count: tool_result_budget.over_budget_message_count, - streaming_tool_launch_count: streaming_tools.launch_count, - streaming_tool_match_count: streaming_tools.match_count, - streaming_tool_fallback_count: streaming_tools.fallback_count, - streaming_tool_discard_count: streaming_tools.discard_count, - streaming_tool_overlap_ms: streaming_tools.overlap_ms, - collaboration: turn_collaboration_summary( - resources.session_state, - resources.turn_id, - ), - }, - } - } -} - -/// 执行一个完整的 Agent Turn。 -/// -/// 通过 `kernel` gateway 调用 LLM 和工具，不直接持有 provider。 -/// 每个重要步骤通过事件回调发出。 -pub async fn run_turn(kernel: Arc, request: TurnRunRequest) -> Result { - let TurnRunRequest { - event_store, - session_id, - working_dir, - turn_id, - messages, - last_assistant_at, - session_state, - runtime, - cancel, - agent, - current_mode_id, - prompt_facts_provider, - capability_router, - prompt_declarations, - bound_mode_tool_contract, - prompt_governance, - } = request; - let gateway = scoped_gateway(kernel.gateway(), capability_router)?; - let resources = TurnExecutionResources::new( - &gateway, - TurnExecutionRequestView { - prompt_facts_provider: prompt_facts_provider.as_ref(), - session_id: &session_id, - working_dir: &working_dir, - turn_id: &turn_id, - session_state: &session_state, - runtime: &runtime, - cancel: &cancel, - agent: &agent, - current_mode_id: ¤t_mode_id, - prompt_declarations: &prompt_declarations, - bound_mode_tool_contract: bound_mode_tool_contract.as_ref(), - prompt_governance: prompt_governance.as_ref(), - }, - ); - let mut execution = TurnExecutionContext::new(&resources, messages, last_assistant_at); - let mut translator = EventTranslator::new(session_state.current_phase().unwrap_or(Phase::Idle)); - - loop { - if resources.cancel.is_cancelled() { - execution.journal.clear(); - execution.journal.push(turn_terminal_event( - resources.turn_id, - resources.agent, - TurnStopCause::Cancelled, - Utc::now(), - )); - flush_pending_events( - &event_store, - resources.session_state, - resources.session_id, - &mut translator, - &mut execution.journal, - ) - .await?; - return Ok(execution.finish( - &resources, - TurnOutcome::Cancelled, - TurnStopCause::Cancelled, - )); - } - - match run_single_step(&mut execution, &resources).await? { - StepOutcome::Continue(transition) => { - flush_pending_events( - &event_store, - resources.session_state, - resources.session_id, - &mut translator, - &mut execution.journal, - ) - .await?; - execution.lifecycle.record_transition(transition); - }, - StepOutcome::Completed(stop_cause) => { - execution.journal.push(turn_terminal_event( - resources.turn_id, - resources.agent, - stop_cause, - Utc::now(), - )); - flush_pending_events( - &event_store, - resources.session_state, - resources.session_id, - &mut translator, - &mut execution.journal, - ) - .await?; - return Ok(execution.finish(&resources, TurnOutcome::Completed, stop_cause)); - }, - StepOutcome::Cancelled(stop_cause) => { - execution.journal.clear(); - execution.journal.push(turn_terminal_event( - resources.turn_id, - resources.agent, - stop_cause, - Utc::now(), - )); - flush_pending_events( - &event_store, - resources.session_state, - resources.session_id, - &mut translator, - &mut execution.journal, - ) - .await?; - return Ok(execution.finish(&resources, TurnOutcome::Cancelled, stop_cause)); - }, - } - } -} - -async fn flush_pending_events( - event_store: &Arc, - session_state: &Arc, - session_id: &str, - translator: &mut EventTranslator, - journal: &mut TurnJournal, -) -> Result<()> { - if journal.is_empty() { - return Ok(()); - } - let events = journal.take_events(); - persist_storage_events(event_store, session_state, session_id, translator, &events) - .await - .map(|_| ()) -} - -fn scoped_gateway( - gateway: &KernelGateway, - capability_router: Option, -) -> Result { - Ok(match capability_router { - Some(router) => gateway.with_capabilities(router), - None => gateway.clone(), - }) -} - -/// 从 session 事件流中聚合当前 turn 的 collaboration facts，生成 turn 级摘要。 -fn turn_collaboration_summary( - session_state: &SessionState, - turn_id: &str, -) -> TurnCollaborationSummary { - let facts = session_state - .snapshot_recent_stored_events() - .unwrap_or_default() - .into_iter() - .filter_map(|stored| match stored.event.payload { - StorageEventPayload::AgentCollaborationFact { fact, .. } - if stored.event.turn_id() == Some(turn_id) => - { - Some(fact) - }, - _ => None, - }) - .collect::>(); - TurnCollaborationSummary::from_facts(&facts) -} diff --git a/crates/session-runtime/src/turn/runner/step/driver.rs b/crates/session-runtime/src/turn/runner/step/driver.rs deleted file mode 100644 index f8d91715..00000000 --- a/crates/session-runtime/src/turn/runner/step/driver.rs +++ /dev/null @@ -1,166 +0,0 @@ -use std::{path::Path, sync::Arc}; - -use astrcode_core::{LlmOutput, LlmRequest, Result, ToolCallRequest}; -use async_trait::async_trait; - -use super::{TurnExecutionContext, TurnExecutionResources}; -use crate::turn::{ - compaction_cycle::{self, ReactiveCompactContext}, - llm_cycle::ToolCallDeltaSink, - request::{AssemblePromptRequest, AssemblePromptResult, assemble_prompt_request}, - tool_cycle::{self, ToolCycleContext, ToolCycleResult, ToolEventEmissionMode}, -}; - -pub(super) struct RuntimeStepDriver; - -#[async_trait] -pub(super) trait StepDriver { - async fn assemble_prompt( - &self, - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - ) -> Result; - - async fn call_llm( - &self, - resources: &TurnExecutionResources<'_>, - llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> Result; - - async fn try_reactive_compact( - &self, - execution: &TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - ) -> Result>; - - async fn execute_tool_cycle( - &self, - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - tool_calls: Vec, - event_emission_mode: ToolEventEmissionMode, - ) -> Result; -} - -#[async_trait] -impl StepDriver for RuntimeStepDriver { - async fn assemble_prompt( - &self, - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - ) -> Result { - let mut assembled = assemble_prompt_request(AssemblePromptRequest { - gateway: resources.gateway, - prompt_facts_provider: resources.prompt_facts_provider, - session_id: resources.session_id, - turn_id: resources.turn_id, - working_dir: Path::new(resources.working_dir), - messages: std::mem::take(&mut execution.messages), - cancel: resources.cancel.clone(), - agent: resources.agent, - step_index: execution.lifecycle.step_index, - token_tracker: &execution.budget.token_tracker, - tools: Arc::clone(&resources.tools), - settings: &resources.settings, - clearable_tools: &resources.clearable_tools, - micro_compact_state: &mut execution.budget.micro_compact_state, - file_access_tracker: &execution.budget.file_access_tracker, - session_state: resources.session_state, - tool_result_replacement_state: &mut execution.tool_result_budget.replacement_state, - prompt_declarations: resources.prompt_declarations, - prompt_governance: resources.prompt_governance, - }) - .await?; - execution.messages = std::mem::take(&mut assembled.messages); - if assembled.auto_compacted { - execution.budget.auto_compaction_count = - execution.budget.auto_compaction_count.saturating_add(1); - } - execution.tool_result_budget.replacement_count = execution - .tool_result_budget - .replacement_count - .saturating_add(assembled.tool_result_budget_stats.replacement_count); - execution.tool_result_budget.reapply_count = execution - .tool_result_budget - .reapply_count - .saturating_add(assembled.tool_result_budget_stats.reapply_count); - execution.tool_result_budget.bytes_saved = execution - .tool_result_budget - .bytes_saved - .saturating_add(assembled.tool_result_budget_stats.bytes_saved); - execution.tool_result_budget.over_budget_message_count = execution - .tool_result_budget - .over_budget_message_count - .saturating_add(assembled.tool_result_budget_stats.over_budget_message_count); - execution.journal.extend(assembled.events.iter().cloned()); - Ok(assembled) - } - - async fn call_llm( - &self, - resources: &TurnExecutionResources<'_>, - llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> Result { - crate::turn::llm_cycle::call_llm_streaming( - resources.gateway, - llm_request, - resources.turn_id, - resources.agent, - resources.session_state, - resources.cancel, - tool_delta_sink, - ) - .await - } - - async fn try_reactive_compact( - &self, - execution: &TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - ) -> Result> { - compaction_cycle::try_reactive_compact(&ReactiveCompactContext { - gateway: resources.gateway, - prompt_facts_provider: resources.prompt_facts_provider, - messages: &execution.messages, - session_id: resources.session_id, - working_dir: resources.working_dir, - turn_id: resources.turn_id, - step_index: execution.lifecycle.step_index, - agent: resources.agent, - cancel: resources.cancel.clone(), - settings: &resources.settings, - file_access_tracker: &execution.budget.file_access_tracker, - }) - .await - } - - async fn execute_tool_cycle( - &self, - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - tool_calls: Vec, - event_emission_mode: ToolEventEmissionMode, - ) -> Result { - tool_cycle::execute_tool_calls( - &mut ToolCycleContext { - gateway: resources.gateway, - session_state: resources.session_state, - session_id: resources.session_id, - working_dir: resources.working_dir, - turn_id: resources.turn_id, - agent: resources.agent, - cancel: resources.cancel, - events: execution.journal.events_mut(), - max_concurrency: resources.runtime.max_tool_concurrency, - tool_result_inline_limit: resources.runtime.tool_result_inline_limit, - event_emission_mode, - current_mode_id: resources.current_mode_id, - bound_mode_tool_contract: resources.bound_mode_tool_contract, - }, - tool_calls, - ) - .await - } -} diff --git a/crates/session-runtime/src/turn/runner/step/llm_step.rs b/crates/session-runtime/src/turn/runner/step/llm_step.rs deleted file mode 100644 index ba06da06..00000000 --- a/crates/session-runtime/src/turn/runner/step/llm_step.rs +++ /dev/null @@ -1,82 +0,0 @@ -use astrcode_core::{LlmFinishReason, LlmOutput, LlmRequest, Result}; - -use super::{TurnExecutionContext, TurnExecutionResources, driver::StepDriver}; -use crate::turn::llm_cycle::ToolCallDeltaSink; - -pub(super) enum StepLlmResult { - Output(Box), - RecoveredByReactiveCompact, -} - -pub(super) async fn call_llm_for_step( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - driver: &impl StepDriver, - llm_request: LlmRequest, - tool_delta_sink: Option, -) -> Result { - match driver - .call_llm(resources, llm_request, tool_delta_sink) - .await - { - Ok(output) => Ok(StepLlmResult::Output(Box::new(output))), - Err(error) => { - if error.is_cancelled() { - return Err(error); - } - if error.is_prompt_too_long() - && execution.lifecycle.reactive_compact_attempts - < resources.settings.compact_max_retry_attempts - { - execution.lifecycle.reactive_compact_attempts = execution - .lifecycle - .reactive_compact_attempts - .saturating_add(1); - log::warn!( - "turn {} step {}: prompt too long, reactive compact ({}/{})", - resources.turn_id, - execution.lifecycle.step_index, - execution.lifecycle.reactive_compact_attempts, - resources.settings.compact_max_retry_attempts, - ); - - let recovery = driver.try_reactive_compact(execution, resources).await?; - - if let Some(result) = recovery { - execution.journal.extend(result.events); - execution.messages = result.messages; - return Ok(StepLlmResult::RecoveredByReactiveCompact); - } - } - Err(error) - }, - } -} - -pub(super) fn record_llm_usage(execution: &mut TurnExecutionContext, output: &LlmOutput) { - execution.budget.token_tracker.record_usage(output.usage); - if let Some(usage) = &output.usage { - execution.budget.total_cache_read_tokens = execution - .budget - .total_cache_read_tokens - .saturating_add(usage.cache_read_input_tokens as u64); - execution.budget.total_cache_creation_tokens = execution - .budget - .total_cache_creation_tokens - .saturating_add(usage.cache_creation_input_tokens as u64); - } -} - -pub(super) fn warn_if_output_truncated( - resources: &TurnExecutionResources<'_>, - execution: &TurnExecutionContext, - output: &LlmOutput, -) { - if matches!(output.finish_reason, LlmFinishReason::MaxTokens) { - log::warn!( - "turn {} step {}: LLM output truncated by max_tokens", - resources.turn_id, - execution.lifecycle.step_index - ); - } -} diff --git a/crates/session-runtime/src/turn/runner/step/mod.rs b/crates/session-runtime/src/turn/runner/step/mod.rs deleted file mode 100644 index 117d4743..00000000 --- a/crates/session-runtime/src/turn/runner/step/mod.rs +++ /dev/null @@ -1,217 +0,0 @@ -mod driver; -mod llm_step; -mod streaming_tools; -mod tool_execution; - -#[cfg(test)] -mod tests; - -use std::time::Instant; - -use astrcode_core::{LlmMessage, LlmOutput, Result, StorageEventPayload, UserMessageOrigin}; -use chrono::Utc; -use driver::{RuntimeStepDriver, StepDriver}; -use llm_step::{StepLlmResult, call_llm_for_step, record_llm_usage, warn_if_output_truncated}; -use streaming_tools::StreamingToolPlannerHandle; -use tool_execution::{ToolExecutionDisposition, finalize_and_execute_tool_calls}; - -use super::{TurnExecutionContext, TurnExecutionResources}; -use crate::turn::{ - events::{apply_prompt_metrics_usage, assistant_final_event, user_message_event}, - loop_control::{TurnLoopTransition, TurnStopCause}, - post_llm_policy::{PostLlmDecision, PostLlmDecisionInput, PostLlmDecisionPolicy}, -}; - -pub(super) enum StepOutcome { - Continue(TurnLoopTransition), - Completed(TurnStopCause), - Cancelled(TurnStopCause), -} - -pub(super) async fn run_single_step( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, -) -> Result { - run_single_step_with(execution, resources, &RuntimeStepDriver).await -} - -async fn run_single_step_with( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - driver: &impl StepDriver, -) -> Result { - let assembled = driver.assemble_prompt(execution, resources).await?; - let streaming_planner = StreamingToolPlannerHandle::new(resources); - let llm_result = call_llm_for_step( - execution, - resources, - driver, - assembled.llm_request, - Some(streaming_planner.tool_delta_sink()), - ) - .await; - - let output = match llm_result { - Ok(StepLlmResult::Output(output)) => *output, - Ok(StepLlmResult::RecoveredByReactiveCompact) => { - streaming_planner.abort_all(); - return Ok(StepOutcome::Continue( - TurnLoopTransition::ReactiveCompactRecovered, - )); - }, - Err(error) => { - streaming_planner.abort_all(); - return Err(error); - }, - }; - - let llm_finished_at = Instant::now(); - record_llm_usage(execution, &output); - apply_prompt_metrics_usage( - execution.journal.events_mut(), - execution.lifecycle.step_index, - output.usage, - output.prompt_cache_diagnostics.clone(), - ); - append_assistant_output(execution, resources, &output); - warn_if_output_truncated(resources, execution, &output); - - match decide_post_llm_action(execution, resources, &output) { - PostLlmDecision::ExecuteTools => match finalize_and_execute_tool_calls( - execution, - resources, - driver, - &streaming_planner, - &output, - llm_finished_at, - ) - .await? - { - ToolExecutionDisposition::Completed => { - execution.lifecycle.step_index += 1; - Ok(StepOutcome::Continue( - TurnLoopTransition::ToolCycleCompleted, - )) - }, - ToolExecutionDisposition::Interrupted => { - Ok(StepOutcome::Cancelled(TurnStopCause::Cancelled)) - }, - }, - PostLlmDecision::ContinueWithPrompt { - nudge, - origin, - transition, - } => { - streaming_planner.abort_all(); - if matches!(origin, UserMessageOrigin::ContinuationPrompt) { - execution.lifecycle.max_output_continuation_count = execution - .lifecycle - .max_output_continuation_count - .saturating_add(1); - } - append_internal_user_message(execution, resources, nudge, origin); - execution.lifecycle.step_index += 1; - Ok(StepOutcome::Continue(transition)) - }, - PostLlmDecision::Stop(stop_cause) => { - streaming_planner.abort_all(); - Ok(StepOutcome::Completed(stop_cause)) - }, - } -} - -fn decide_post_llm_action( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - output: &LlmOutput, -) -> PostLlmDecision { - let policy = PostLlmDecisionPolicy::new(resources.runtime, resources.gateway.model_limits()); - - policy.decide(PostLlmDecisionInput { - output, - max_output_continuation_count: execution.lifecycle.max_output_continuation_count, - }) -} - -fn append_assistant_output( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - output: &LlmOutput, -) { - let content = output.content.trim().to_string(); - let reasoning_content = output - .reasoning - .as_ref() - .map(|reasoning| reasoning.content.clone()); - let reasoning_signature = output - .reasoning - .as_ref() - .and_then(|reasoning| reasoning.signature.clone()); - let has_persistable_assistant_output = !content.is_empty() - || reasoning_content - .as_deref() - .is_some_and(|value| !value.trim().is_empty()); - let suppress_assistant_follow_up = execution.draft_plan_approval_guard_active - || should_suppress_exit_plan_follow_up(execution); - execution.messages.push(LlmMessage::Assistant { - content: content.clone(), - tool_calls: output.tool_calls.clone(), - reasoning: output.reasoning.clone(), - }); - if suppress_assistant_follow_up { - execution.messages.pop(); - } - execution - .budget - .micro_compact_state - .record_assistant_activity(Instant::now()); - if has_persistable_assistant_output && !suppress_assistant_follow_up { - execution.journal.push(assistant_final_event( - resources.turn_id, - resources.agent, - content, - reasoning_content, - reasoning_signature, - execution.lifecycle.step_index, - Some(Utc::now()), - )); - } -} - -fn should_suppress_exit_plan_follow_up(execution: &TurnExecutionContext) -> bool { - execution - .journal - .iter() - .rev() - .find_map(|event| match &event.payload { - StorageEventPayload::ToolResult { - tool_name, - metadata, - .. - } if tool_name == "exitPlanMode" => metadata - .as_ref() - .and_then(|metadata| metadata.get("schema")) - .and_then(|value| value.as_str()), - _ => None, - }) - .is_some_and(|schema| matches!(schema, "sessionPlanExitReviewPending" | "sessionPlanExit")) -} - -fn append_internal_user_message( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - content: &str, - origin: UserMessageOrigin, -) { - execution.messages.push(LlmMessage::User { - content: content.to_string(), - origin, - }); - execution.journal.push(user_message_event( - resources.turn_id, - resources.agent, - content.to_string(), - origin, - Utc::now(), - )); -} diff --git a/crates/session-runtime/src/turn/runner/step/streaming_tools.rs b/crates/session-runtime/src/turn/runner/step/streaming_tools.rs deleted file mode 100644 index 2bdb0404..00000000 --- a/crates/session-runtime/src/turn/runner/step/streaming_tools.rs +++ /dev/null @@ -1,508 +0,0 @@ -use std::{ - collections::{BTreeMap, HashMap}, - fmt, - sync::{Arc, Mutex}, - time::Instant, -}; - -use astrcode_core::ToolCallRequest; -use serde_json::Value; -use tokio::task::JoinHandle; - -use super::TurnExecutionResources; -use crate::turn::{ - llm_cycle::{StreamedToolCallDelta, ToolCallDeltaSink}, - tool_cycle::{self, BufferedToolExecution, BufferedToolExecutionRequest}, -}; - -#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] -pub(super) struct StreamingToolStats { - pub launched_count: usize, - pub matched_count: usize, - pub fallback_count: usize, - pub discard_count: usize, - pub overlap_ms: u64, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(super) enum StreamingToolFallbackReason { - ToolNotConcurrencySafe, - IdentityNeverStabilized, - ArgumentsNeverFormedStableJson, - FinalPlanChanged, - BufferedExecutionJoinFailed, -} - -impl StreamingToolFallbackReason { - pub(super) const fn as_str(self) -> &'static str { - match self { - Self::ToolNotConcurrencySafe => "tool is not concurrency_safe", - Self::IdentityNeverStabilized => "streamed identity never stabilized", - Self::ArgumentsNeverFormedStableJson => { - "streamed arguments never formed a stable JSON payload" - }, - Self::FinalPlanChanged => "final tool plan changed after provisional execution", - Self::BufferedExecutionJoinFailed => "buffered execution join failed", - } - } -} - -impl fmt::Display for StreamingToolFallbackReason { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.as_str()) - } -} - -#[derive(Debug, Default)] -pub(super) struct StreamingToolAssembly { - pub id: Option, - pub name: Option, - pub arguments: String, - pub launched: bool, - json_tracker: StreamingJsonTracker, -} - -#[cfg(test)] -impl StreamingToolAssembly { - pub(super) fn for_test( - id: Option, - name: Option, - arguments: impl Into, - ) -> Self { - let arguments = arguments.into(); - let mut assembly = Self { - id, - name, - arguments, - launched: false, - json_tracker: StreamingJsonTracker::default(), - }; - assembly.json_tracker.observe_chunk(&assembly.arguments); - assembly - } -} - -struct StreamingToolCandidate { - index: usize, - request: ToolCallRequest, -} - -#[derive(Default)] -struct StreamingToolAssembler { - assemblies: BTreeMap, -} - -#[derive(Debug, Default)] -struct StreamingJsonTracker { - started: bool, - in_string: bool, - escape: bool, - object_depth: usize, - complete: bool, - fallback_to_full_parse: bool, -} - -impl StreamingJsonTracker { - fn observe_chunk(&mut self, chunk: &str) { - if self.fallback_to_full_parse { - return; - } - - for ch in chunk.chars() { - if self.complete { - if !ch.is_whitespace() { - self.complete = false; - self.fallback_to_full_parse = true; - } - continue; - } - - if self.in_string { - if self.escape { - self.escape = false; - continue; - } - match ch { - '\\' => self.escape = true, - '"' => self.in_string = false, - _ => {}, - } - continue; - } - - if !self.started { - if ch.is_whitespace() { - continue; - } - self.started = true; - if ch == '{' { - self.object_depth = 1; - } else { - self.fallback_to_full_parse = true; - } - continue; - } - - match ch { - '"' => self.in_string = true, - '{' => { - self.object_depth = self.object_depth.saturating_add(1); - }, - '}' => { - if self.object_depth == 0 { - self.fallback_to_full_parse = true; - return; - } - self.object_depth -= 1; - if self.object_depth == 0 { - self.complete = true; - } - }, - _ => {}, - } - } - } - - fn should_attempt_parse(&self) -> bool { - self.complete || self.fallback_to_full_parse - } -} - -impl StreamingToolAssembler { - fn observe_delta(&mut self, delta: StreamedToolCallDelta) -> Option { - let assembly = self.assemblies.entry(delta.index).or_default(); - if let Some(id) = delta.id { - assembly.id = Some(id); - } - if let Some(name) = delta.name { - assembly.name = Some(name); - } - assembly.arguments.push_str(&delta.arguments_delta); - assembly.json_tracker.observe_chunk(&delta.arguments_delta); - - if assembly.launched { - return None; - } - - let id = assembly.id.clone()?; - let name = assembly.name.clone()?; - if !assembly.json_tracker.should_attempt_parse() { - return None; - } - let Ok(args) = serde_json::from_str::(&assembly.arguments) else { - return None; - }; - - Some(StreamingToolCandidate { - index: delta.index, - request: ToolCallRequest { id, name, args }, - }) - } - - fn mark_launched(&mut self, index: usize) { - if let Some(assembly) = self.assemblies.get_mut(&index) { - assembly.launched = true; - } - } -} - -struct SpawnedStreamingTool { - request: ToolCallRequest, - handle: JoinHandle, -} - -#[derive(Default)] -struct StreamingToolLaunchContext { - gateway: Option, - session_state: Option>, - session_id: String, - working_dir: String, - turn_id: String, - agent: Option, - cancel: Option, - current_mode_id: Option, - bound_mode_tool_contract: Option, - tool_result_inline_limit: usize, -} - -#[derive(Default)] -struct StreamingToolLauncher { - context: StreamingToolLaunchContext, - spawned: HashMap, - stats: StreamingToolStats, -} - -impl StreamingToolLauncher { - fn from_resources(resources: &TurnExecutionResources<'_>) -> Self { - Self { - context: StreamingToolLaunchContext { - gateway: Some(resources.gateway.clone()), - session_state: Some(Arc::clone(resources.session_state)), - session_id: resources.session_id.to_string(), - working_dir: resources.working_dir.to_string(), - turn_id: resources.turn_id.to_string(), - agent: Some(resources.agent.clone()), - cancel: Some(resources.cancel.clone()), - current_mode_id: Some(resources.current_mode_id.clone()), - bound_mode_tool_contract: resources.bound_mode_tool_contract.cloned(), - tool_result_inline_limit: resources.runtime.tool_result_inline_limit, - }, - ..Self::default() - } - } - - fn launch_if_ready(&mut self, candidate: &StreamingToolCandidate) -> bool { - let Some(gateway) = self.context.gateway.as_ref() else { - return false; - }; - let Some(capability) = gateway - .capabilities() - .capability_spec(&candidate.request.name) - else { - return false; - }; - if !capability.concurrency_safe { - return false; - } - - let Some(session_state) = self.context.session_state.as_ref() else { - return false; - }; - let Some(agent) = self.context.agent.as_ref() else { - return false; - }; - let Some(cancel) = self.context.cancel.as_ref() else { - return false; - }; - let Some(current_mode_id) = self.context.current_mode_id.as_ref() else { - return false; - }; - - let request = candidate.request.clone(); - let handle = tokio::spawn(tool_cycle::execute_buffered_tool_call( - BufferedToolExecutionRequest { - gateway: gateway.clone(), - session_state: Arc::clone(session_state), - tool_call: request.clone(), - session_id: self.context.session_id.clone(), - working_dir: self.context.working_dir.clone(), - turn_id: self.context.turn_id.clone(), - agent: agent.clone(), - cancel: cancel.clone(), - current_mode_id: current_mode_id.clone(), - bound_mode_tool_contract: self.context.bound_mode_tool_contract.clone(), - tool_result_inline_limit: self.context.tool_result_inline_limit, - }, - )); - - self.stats.launched_count = self.stats.launched_count.saturating_add(1); - self.spawned - .insert(request.id.clone(), SpawnedStreamingTool { request, handle }); - true - } - - fn abort_all(&mut self) { - let discarded = self.spawned.len(); - self.stats.discard_count = self.stats.discard_count.saturating_add(discarded); - for (_, spawned_tool) in self.spawned.drain() { - spawned_tool.handle.abort(); - } - } -} - -#[derive(Default)] -struct StreamingToolPlanner { - assembler: StreamingToolAssembler, - launcher: StreamingToolLauncher, -} - -pub(super) struct StreamingToolFinalizeResult { - pub matched_results: HashMap, - pub remaining_tool_calls: Vec, - pub stats: StreamingToolStats, - pub used_streaming_path: bool, -} - -struct StreamingToolReconciler { - gateway: Option, - assemblies: BTreeMap, - spawned: HashMap, - stats: StreamingToolStats, -} - -impl StreamingToolReconciler { - async fn reconcile( - mut self, - final_tool_calls: &[ToolCallRequest], - llm_finished_at: Instant, - ) -> StreamingToolFinalizeResult { - let mut matched_results = HashMap::new(); - let mut remaining_tool_calls = Vec::new(); - - for (index, call) in final_tool_calls.iter().cloned().enumerate() { - if let Some(spawned_tool) = self.spawned.remove(&call.id) { - if spawned_tool.request == call { - match spawned_tool.handle.await { - Ok(buffered) => { - self.stats.matched_count = self.stats.matched_count.saturating_add(1); - self.stats.overlap_ms = self - .stats - .overlap_ms - .saturating_add(overlap_ms(&buffered, llm_finished_at)); - matched_results.insert(call.id.clone(), buffered); - }, - Err(error) => { - log::warn!( - "turn streaming tool execution join failed for {}: {error}", - call.id - ); - self.log_fallback_reason( - &call, - StreamingToolFallbackReason::BufferedExecutionJoinFailed, - ); - remaining_tool_calls.push(call); - }, - } - } else { - spawned_tool.handle.abort(); - self.stats.discard_count = self.stats.discard_count.saturating_add(1); - self.log_fallback_reason(&call, StreamingToolFallbackReason::FinalPlanChanged); - remaining_tool_calls.push(call); - } - continue; - } - - if let Some(reason) = fallback_reason_for_final_call( - self.gateway.as_ref(), - self.assemblies.get(&index), - &call, - ) { - self.log_fallback_reason(&call, reason); - } - remaining_tool_calls.push(call); - } - - self.stats.discard_count = self.stats.discard_count.saturating_add(self.spawned.len()); - for (_, spawned_tool) in self.spawned.drain() { - spawned_tool.handle.abort(); - } - - StreamingToolFinalizeResult { - matched_results, - remaining_tool_calls, - stats: self.stats, - used_streaming_path: self.stats.launched_count > 0, - } - } - - fn log_fallback_reason(&mut self, call: &ToolCallRequest, reason: StreamingToolFallbackReason) { - log::debug!( - "turn streaming tool planner fallback for {} ({}): {}", - call.id, - call.name, - reason - ); - self.stats.fallback_count = self.stats.fallback_count.saturating_add(1); - } -} - -// TODO: streaming_tools.rs 里 Arc> -> channel/collector 的并发模型替换 -#[derive(Clone)] -pub(super) struct StreamingToolPlannerHandle { - inner: Arc>, -} - -impl StreamingToolPlannerHandle { - pub(super) fn new(resources: &TurnExecutionResources<'_>) -> Self { - Self { - inner: Arc::new(Mutex::new(StreamingToolPlanner { - assembler: StreamingToolAssembler::default(), - launcher: StreamingToolLauncher::from_resources(resources), - })), - } - } - - pub(super) fn tool_delta_sink(&self) -> ToolCallDeltaSink { - let inner = Arc::clone(&self.inner); - Arc::new(move |delta| { - inner - .lock() - .expect("streaming tool planner lock should work") - .observe_delta(delta); - }) - } - - pub(super) fn abort_all(&self) { - self.inner - .lock() - .expect("streaming tool planner lock should work") - .launcher - .abort_all(); - } - - pub(super) async fn finalize( - &self, - final_tool_calls: &[ToolCallRequest], - llm_finished_at: Instant, - ) -> StreamingToolFinalizeResult { - let reconciler = { - let mut planner = self - .inner - .lock() - .expect("streaming tool planner lock should work"); - let assemblies = std::mem::take(&mut planner.assembler.assemblies); - let launcher = std::mem::take(&mut planner.launcher); - StreamingToolReconciler { - gateway: launcher.context.gateway, - assemblies, - spawned: launcher.spawned, - stats: launcher.stats, - } - }; - - reconciler - .reconcile(final_tool_calls, llm_finished_at) - .await - } -} - -impl StreamingToolPlanner { - fn observe_delta(&mut self, delta: StreamedToolCallDelta) { - let Some(candidate) = self.assembler.observe_delta(delta) else { - return; - }; - if self.launcher.launch_if_ready(&candidate) { - self.assembler.mark_launched(candidate.index); - } - } -} - -pub(super) fn fallback_reason_for_final_call( - gateway: Option<&astrcode_kernel::KernelGateway>, - assembly: Option<&StreamingToolAssembly>, - call: &ToolCallRequest, -) -> Option { - let capability = gateway?.capabilities().capability_spec(&call.name)?; - if !capability.concurrency_safe { - return Some(StreamingToolFallbackReason::ToolNotConcurrencySafe); - } - let assembly = assembly?; - if assembly.id.as_deref() != Some(call.id.as_str()) - || assembly.name.as_deref() != Some(call.name.as_str()) - { - return Some(StreamingToolFallbackReason::IdentityNeverStabilized); - } - Some(StreamingToolFallbackReason::ArgumentsNeverFormedStableJson) -} - -fn overlap_ms(buffered: &BufferedToolExecution, llm_finished_at: Instant) -> u64 { - let overlap_end = if buffered.finished_at < llm_finished_at { - buffered.finished_at - } else { - llm_finished_at - }; - if buffered.started_at >= overlap_end { - return 0; - } - overlap_end.duration_since(buffered.started_at).as_millis() as u64 -} diff --git a/crates/session-runtime/src/turn/runner/step/tests.rs b/crates/session-runtime/src/turn/runner/step/tests.rs deleted file mode 100644 index 8b44348e..00000000 --- a/crates/session-runtime/src/turn/runner/step/tests.rs +++ /dev/null @@ -1,1573 +0,0 @@ -use std::sync::{ - Arc, Mutex, - atomic::{AtomicUsize, Ordering}, -}; - -use astrcode_core::{ - AgentEventContext, AstrError, CancelToken, CapabilityKind, LlmFinishReason, LlmMessage, - LlmOutput, LlmRequest, LlmUsage, PromptFactsProvider, ResolvedRuntimeConfig, - SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER, StorageEventPayload, Tool, ToolCallRequest, - ToolContext, ToolDefinition, ToolExecutionResult, UserMessageOrigin, -}; -use astrcode_kernel::KernelGateway; -use async_trait::async_trait; -use serde_json::json; - -use super::{ - StepOutcome, TurnExecutionContext, TurnExecutionResources, - driver::StepDriver, - run_single_step_with, - streaming_tools::{ - StreamingToolAssembly, StreamingToolFallbackReason, fallback_reason_for_final_call, - }, -}; -use crate::{ - SessionState, - context_window::token_usage::PromptTokenSnapshot, - turn::{ - compaction_cycle, - events::{prompt_metrics_event, tool_call_event, tool_result_event}, - llm_cycle::{StreamedToolCallDelta, ToolCallDeltaSink}, - loop_control::{TurnLoopTransition, TurnStopCause}, - request::AssemblePromptResult, - runner::TurnExecutionRequestView, - test_support::{ - NoopPromptFactsProvider, assert_contains_compact_summary, root_compact_applied_event, - test_gateway, test_session_state, - }, - tool_cycle::{ToolCycleOutcome, ToolCycleResult, ToolEventEmissionMode}, - }, -}; - -#[derive(Default)] -struct DriverCallCounts { - assemble: AtomicUsize, - llm: AtomicUsize, - reactive_compact: AtomicUsize, - tool_cycle: AtomicUsize, -} - -struct ScriptedStepDriver { - counts: DriverCallCounts, - assemble_result: Mutex>>, - llm_result: Mutex>>, - reactive_compact_result: - Mutex>>>, - tool_cycle_result: Mutex>>, -} - -#[async_trait] -impl StepDriver for ScriptedStepDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - self.counts.assemble.fetch_add(1, Ordering::SeqCst); - self.assemble_result - .lock() - .expect("assemble result lock should work") - .take() - .expect("assemble result should be scripted") - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - _tool_delta_sink: Option, - ) -> astrcode_core::Result { - self.counts.llm.fetch_add(1, Ordering::SeqCst); - self.llm_result - .lock() - .expect("llm result lock should work") - .take() - .expect("llm result should be scripted") - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - self.counts.reactive_compact.fetch_add(1, Ordering::SeqCst); - self.reactive_compact_result - .lock() - .expect("reactive compact result lock should work") - .take() - .expect("reactive compact result should be scripted") - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - _tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - self.counts.tool_cycle.fetch_add(1, Ordering::SeqCst); - self.tool_cycle_result - .lock() - .expect("tool cycle result lock should work") - .take() - .expect("tool cycle result should be scripted") - } -} - -fn user_message(content: &str) -> LlmMessage { - LlmMessage::User { - content: content.to_string(), - origin: UserMessageOrigin::User, - } -} - -fn assembled_prompt(messages: Vec) -> AssemblePromptResult { - AssemblePromptResult { - llm_request: LlmRequest::new( - messages.clone(), - vec![ToolDefinition { - name: "dummy_tool".to_string(), - description: "dummy".to_string(), - parameters: json!({"type": "object"}), - }], - CancelToken::new(), - ) - .with_system("system"), - messages, - events: vec![prompt_metrics_event( - "turn-1", - &AgentEventContext::default(), - 0, - PromptTokenSnapshot { - context_tokens: 10, - budget_tokens: 10, - context_window: 100, - effective_window: 90, - threshold_tokens: 80, - remaining_context_tokens: 80, - reserved_context_size: 20, - }, - 0, - Default::default(), - false, - )], - auto_compacted: false, - tool_result_budget_stats: crate::turn::tool_result_budget::ToolResultBudgetStats::default(), - } -} - -fn test_resources<'a>( - gateway: &'a KernelGateway, - session_state: &'a Arc, - runtime: &'a ResolvedRuntimeConfig, - cancel: &'a CancelToken, - agent: &'a AgentEventContext, - prompt_facts_provider: &'a dyn PromptFactsProvider, -) -> TurnExecutionResources<'a> { - let current_mode_id = Box::leak(Box::new(astrcode_core::ModeId::default())); - TurnExecutionResources::new( - gateway, - TurnExecutionRequestView { - prompt_facts_provider, - session_id: "session-1", - working_dir: ".", - turn_id: "turn-1", - session_state, - runtime, - cancel, - agent, - current_mode_id, - prompt_declarations: &[], - bound_mode_tool_contract: None, - prompt_governance: None, - }, - ) -} - -#[derive(Debug)] -struct StreamingSafeProbeTool { - calls: Arc, -} - -#[async_trait] -impl Tool for StreamingSafeProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "streaming_safe_probe".to_string(), - description: "safe probe for streamed tool execution".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result - { - astrcode_core::CapabilitySpec::builder("streaming_safe_probe", CapabilityKind::Tool) - .description("safe probe for streamed tool execution") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .concurrency_safe(true) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: serde_json::Value, - _ctx: &ToolContext, - ) -> astrcode_core::Result { - self.calls.fetch_add(1, Ordering::SeqCst); - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "streaming_safe_probe".to_string(), - ok: true, - output: "streamed safe result".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } -} - -#[derive(Debug)] -struct StreamingUnsafeProbeTool; - -#[async_trait] -impl Tool for StreamingUnsafeProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "streaming_unsafe_probe".to_string(), - description: "unsafe probe for streamed tool execution".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result - { - astrcode_core::CapabilitySpec::builder("streaming_unsafe_probe", CapabilityKind::Tool) - .description("unsafe probe for streamed tool execution") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .concurrency_safe(false) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: serde_json::Value, - _ctx: &ToolContext, - ) -> astrcode_core::Result { - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "streaming_unsafe_probe".to_string(), - ok: true, - output: "unsafe result".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } -} - -fn tool_result(tool_call_id: &str, tool_name: &str, output: &str) -> ToolExecutionResult { - ToolExecutionResult { - tool_call_id: tool_call_id.to_string(), - tool_name: tool_name.to_string(), - ok: true, - output: output.to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - } -} - -#[tokio::test] -async fn run_single_step_returns_completed_when_llm_has_no_tool_calls() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: "assistant reply".to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: Some(LlmUsage { - input_tokens: 11, - output_tokens: 7, - cache_creation_input_tokens: 3, - cache_read_input_tokens: 2, - }), - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(None), - tool_cycle_result: Mutex::new(None), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Completed(TurnStopCause::Completed) - )); - assert_eq!(execution.lifecycle.step_index, 0); - assert_eq!(execution.budget.total_cache_read_tokens, 2); - assert_eq!(execution.budget.total_cache_creation_tokens, 3); - assert_eq!(driver.counts.assemble.load(Ordering::SeqCst), 1); - assert_eq!(driver.counts.llm.load(Ordering::SeqCst), 1); - assert_eq!(driver.counts.tool_cycle.load(Ordering::SeqCst), 0); - assert!(matches!( - execution.messages.last(), - Some(LlmMessage::Assistant { content, .. }) if content == "assistant reply" - )); - assert!( - execution.journal.iter().any(|event| matches!( - &event.payload, - StorageEventPayload::AssistantFinal { content, .. } if content == "assistant reply" - )), - "completed step should leave durable assistant output in the pending step journal" - ); -} - -#[tokio::test] -async fn run_single_step_returns_cancelled_when_tool_cycle_interrupts() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-1".to_string(), - name: "dummy_tool".to_string(), - args: json!({}), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(None), - tool_cycle_result: Mutex::new(Some(Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Interrupted, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }))), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Cancelled(TurnStopCause::Cancelled) - )); - assert_eq!(execution.lifecycle.step_index, 0); - assert_eq!(driver.counts.tool_cycle.load(Ordering::SeqCst), 1); - assert!( - execution - .journal - .iter() - .all(|event| !matches!(&event.payload, StorageEventPayload::AssistantFinal { .. })), - "tool-only interrupted step should not persist an empty assistant final" - ); -} - -#[tokio::test] -async fn run_single_step_reuses_streamed_safe_tool_execution_when_final_call_matches() { - struct StreamingDriver { - tool_cycle_calls: AtomicUsize, - } - - #[async_trait] - impl StepDriver for StreamingDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message("find the answer")])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 0, - id: Some("call-stream-1".to_string()), - name: Some("streaming_safe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-stream-1".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - _tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - self.tool_cycle_calls.fetch_add(1, Ordering::SeqCst); - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }) - } - } - - let probe_calls = Arc::new(AtomicUsize::new(0)); - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::clone(&probe_calls), - }), - 8192, - ); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = StreamingDriver { - tool_cycle_calls: AtomicUsize::new(0), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - assert_eq!(execution.lifecycle.step_index, 1); - assert_eq!(driver.tool_cycle_calls.load(Ordering::SeqCst), 0); - assert_eq!(execution.streaming_tools.launch_count, 1); - assert_eq!(execution.streaming_tools.match_count, 1); - assert_eq!(execution.streaming_tools.fallback_count, 0); - assert_eq!(execution.streaming_tools.discard_count, 0); - assert!( - execution.messages.iter().any(|message| matches!( - message, - LlmMessage::Tool { tool_call_id, content } - if tool_call_id == "call-stream-1" && content == "streamed safe result" - )), - "matched streamed tool result should be appended without fallback tool cycle" - ); -} - -#[tokio::test] -async fn run_single_step_returns_continue_after_reactive_compact_recovery() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let original_messages = vec![user_message("message before compact")]; - let mut execution = TurnExecutionContext::new(&resources, original_messages, None); - let recovered_messages = vec![ - user_message("compacted summary"), - LlmMessage::Assistant { - content: "recovered context".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ]; - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message( - "message before compact", - )])))), - llm_result: Mutex::new(Some(Err(AstrError::LlmRequestFailed { - status: 400, - body: "prompt too long for provider".to_string(), - }))), - reactive_compact_result: Mutex::new(Some(Ok(Some(compaction_cycle::RecoveryResult { - messages: recovered_messages.clone(), - events: vec![root_compact_applied_event( - "turn-1", - "compacted", - 1, - 100, - 60, - 2, - 40, - )], - })))), - tool_cycle_result: Mutex::new(None), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should recover via reactive compact"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ReactiveCompactRecovered) - )); - assert_eq!(execution.lifecycle.step_index, 0); - assert_eq!(execution.lifecycle.reactive_compact_attempts, 1); - assert_eq!(driver.counts.llm.load(Ordering::SeqCst), 1); - assert_eq!(driver.counts.reactive_compact.load(Ordering::SeqCst), 1); - assert_eq!(driver.counts.tool_cycle.load(Ordering::SeqCst), 0); - assert_eq!(execution.messages, recovered_messages); - let stored_like = execution - .journal - .iter() - .cloned() - .enumerate() - .map(|(index, event)| astrcode_core::StoredEvent { - storage_seq: index as u64 + 1, - event, - }) - .collect::>(); - assert_contains_compact_summary(&stored_like, "compacted"); - assert!( - execution - .journal - .iter() - .all(|event| !matches!(&event.payload, StorageEventPayload::AssistantFinal { .. })), - "recovery path should continue without persisting a failed assistant reply" - ); -} - -#[tokio::test] -async fn run_single_step_continues_after_max_tokens_without_tool_calls() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: "partial answer".to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: Some(LlmUsage { - input_tokens: 40, - output_tokens: 32, - cache_creation_input_tokens: 0, - cache_read_input_tokens: 0, - }), - finish_reason: LlmFinishReason::MaxTokens, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(None), - tool_cycle_result: Mutex::new(None), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should continue after truncated output"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::OutputContinuationRequested) - )); - assert_eq!(execution.lifecycle.max_output_continuation_count, 1); - assert!(matches!( - execution.messages.last(), - Some(LlmMessage::User { - origin: UserMessageOrigin::ContinuationPrompt, - content, - }) if content == crate::turn::continuation_cycle::OUTPUT_CONTINUATION_PROMPT - )); -} - -#[tokio::test] -async fn run_single_step_suppresses_assistant_output_after_exit_plan_review_pending() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - execution.journal.push(tool_result_event( - "turn-1", - &agent, - &ToolExecutionResult { - tool_call_id: "call-exit-review".to_string(), - tool_name: "exitPlanMode".to_string(), - ok: true, - output: "review pending".to_string(), - error: None, - metadata: Some(json!({ "schema": "sessionPlanExitReviewPending" })), - continuation: None, - duration_ms: 0, - truncated: false, - }, - )); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-exit-retry".to_string(), - name: "exitPlanMode".to_string(), - args: json!({}), - }], - reasoning: Some(astrcode_core::ReasoningContent { - content: "internal review".to_string(), - signature: None, - }), - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(Some(Ok(None))), - tool_cycle_result: Mutex::new(Some(Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }))), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should continue"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - assert!( - execution - .journal - .iter() - .all(|event| !matches!(&event.payload, StorageEventPayload::AssistantFinal { .. })), - "review-pending follow-up assistant output should stay internal" - ); - assert!( - execution - .messages - .iter() - .all(|message| !matches!(message, LlmMessage::Assistant { .. })), - "review-pending follow-up should not be appended to durable message history" - ); -} - -#[tokio::test] -async fn run_single_step_suppresses_assistant_output_for_draft_approval_guarded_turn() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = TurnExecutionContext::new( - &resources, - vec![ - user_message("按这个做，开始吧"), - LlmMessage::User { - content: format!( - "{SESSION_PLAN_DRAFT_APPROVAL_GUARD_MARKER}\\ - n内部执行约束（不要在对用户可见输出中复述）" - ), - origin: UserMessageOrigin::ReactivationPrompt, - }, - ], - None, - ); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: "收到，我先把草稿补全为可呈递版本，再交给你确认。".to_string(), - tool_calls: vec![ToolCallRequest { - id: "call-read-plan".to_string(), - name: "readFile".to_string(), - args: json!({ "path": "docs/issues.md" }), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(Some(Ok(None))), - tool_cycle_result: Mutex::new(Some(Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }))), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should continue"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - assert!( - execution - .journal - .iter() - .all(|event| !matches!(&event.payload, StorageEventPayload::AssistantFinal { .. })), - "draft-approval guarded turn should keep assistant follow-up internal" - ); - assert!( - execution - .messages - .iter() - .all(|message| { !matches!(message, LlmMessage::Assistant { .. }) }), - "draft-approval guarded turn should not append assistant follow-up to durable history" - ); -} - -#[tokio::test] -async fn run_single_step_suppresses_assistant_output_after_exit_plan_presented() { - let gateway = test_gateway(8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - &gateway, - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - execution.journal.push(tool_result_event( - "turn-1", - &agent, - &ToolExecutionResult { - tool_call_id: "call-exit-presented".to_string(), - tool_name: "exitPlanMode".to_string(), - ok: true, - output: "presented".to_string(), - error: None, - metadata: Some(json!({ "schema": "sessionPlanExit" })), - continuation: None, - duration_ms: 0, - truncated: false, - }, - )); - let driver = ScriptedStepDriver { - counts: DriverCallCounts::default(), - assemble_result: Mutex::new(Some(Ok(assembled_prompt(vec![user_message("hello")])))), - llm_result: Mutex::new(Some(Ok(LlmOutput { - content: "计划已呈递，请审阅。".to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }))), - reactive_compact_result: Mutex::new(Some(Ok(None))), - tool_cycle_result: Mutex::new(None), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should complete"); - - assert!(matches!( - outcome, - StepOutcome::Completed(TurnStopCause::Completed) - )); - assert!( - execution - .journal - .iter() - .all(|event| !matches!(&event.payload, StorageEventPayload::AssistantFinal { .. })), - "presented-plan follow-up assistant output should not be persisted" - ); - assert!( - execution - .messages - .iter() - .all(|message| !matches!(message, LlmMessage::Assistant { .. })), - "presented-plan follow-up should not be appended to durable message history" - ); -} - -#[tokio::test] -async fn run_single_step_does_not_launch_non_concurrency_safe_streaming_tool() { - struct UnsafeStreamingDriver { - tool_cycle_calls: AtomicUsize, - event_modes: Mutex>, - } - - #[async_trait] - impl StepDriver for UnsafeStreamingDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message( - "find the unsafe answer", - )])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 0, - id: Some("call-unsafe-1".to_string()), - name: Some("streaming_unsafe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-unsafe-1".to_string(), - name: "streaming_unsafe_probe".to_string(), - args: json!({"path": "README.md"}), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - _tool_calls: Vec, - event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - self.tool_cycle_calls.fetch_add(1, Ordering::SeqCst); - self.event_modes - .lock() - .expect("event mode lock should work") - .push(event_emission_mode); - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }) - } - } - - let kernel = - crate::turn::test_support::test_kernel_with_tool(Arc::new(StreamingUnsafeProbeTool), 8192); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = UnsafeStreamingDriver { - tool_cycle_calls: AtomicUsize::new(0), - event_modes: Mutex::new(Vec::new()), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - assert_eq!(execution.streaming_tools.launch_count, 0); - assert_eq!(driver.tool_cycle_calls.load(Ordering::SeqCst), 1); - assert_eq!( - driver - .event_modes - .lock() - .expect("event mode lock should work") - .as_slice(), - &[ToolEventEmissionMode::Buffered] - ); -} - -#[tokio::test] -async fn run_single_step_discards_provisional_tool_when_final_plan_changes() { - struct FinalPlanChangedDriver { - tool_cycle_calls: AtomicUsize, - captured_calls: Mutex>>, - } - - #[async_trait] - impl StepDriver for FinalPlanChangedDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message("find the answer")])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 0, - id: Some("call-stream-1".to_string()), - name: Some("streaming_safe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ToolCallRequest { - id: "call-stream-1".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "src/main.rs"}), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - self.tool_cycle_calls.fetch_add(1, Ordering::SeqCst); - self.captured_calls - .lock() - .expect("captured calls lock should work") - .push(tool_calls.clone()); - let result = tool_result( - tool_calls[0].id.as_str(), - tool_calls[0].name.as_str(), - "fallback final result", - ); - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: vec![(tool_calls[0].clone(), result)], - events: Vec::new(), - }) - } - } - - let probe_calls = Arc::new(AtomicUsize::new(0)); - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::clone(&probe_calls), - }), - 8192, - ); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - let driver = FinalPlanChangedDriver { - tool_cycle_calls: AtomicUsize::new(0), - captured_calls: Mutex::new(Vec::new()), - }; - - let outcome = run_single_step_with(&mut execution, &resources, &driver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - assert_eq!(execution.streaming_tools.launch_count, 1); - assert_eq!(driver.tool_cycle_calls.load(Ordering::SeqCst), 1); - let captured_calls = driver - .captured_calls - .lock() - .expect("captured calls lock should work"); - assert_eq!(captured_calls.len(), 1); - assert_eq!(captured_calls[0].len(), 1); - assert_eq!(captured_calls[0][0].args, json!({"path": "src/main.rs"})); - assert_eq!(execution.streaming_tools.discard_count, 1); - assert_eq!(execution.streaming_tools.fallback_count, 1); - assert!( - execution.messages.iter().any(|message| matches!( - message, - LlmMessage::Tool { tool_call_id, content } - if tool_call_id == "call-stream-1" && content == "fallback final result" - )), - "final fallback path should append exactly one final tool result" - ); -} - -#[tokio::test] -async fn run_single_step_merges_buffered_events_and_results_in_final_tool_order() { - struct MergeOrderingDriver; - - #[async_trait] - impl StepDriver for MergeOrderingDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message("find the answer")])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 1, - id: Some("call-stream-2".to_string()), - name: Some("streaming_safe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-remain-1".to_string(), - name: "dummy_tool".to_string(), - args: json!({"query": "alpha"}), - }, - ToolCallRequest { - id: "call-stream-2".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }, - ], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - let result = tool_result( - tool_calls[0].id.as_str(), - tool_calls[0].name.as_str(), - "remaining result", - ); - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: vec![(tool_calls[0].clone(), result.clone())], - events: vec![ - tool_call_event(resources.turn_id, resources.agent, &tool_calls[0]), - tool_result_event(resources.turn_id, resources.agent, &result), - ], - }) - } - } - - let probe_calls = Arc::new(AtomicUsize::new(0)); - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::clone(&probe_calls), - }), - 8192, - ); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - - let outcome = run_single_step_with(&mut execution, &resources, &MergeOrderingDriver) - .await - .expect("step should succeed"); - - assert!(matches!( - outcome, - StepOutcome::Continue(TurnLoopTransition::ToolCycleCompleted) - )); - - let tool_messages = execution - .messages - .iter() - .filter_map(|message| match message { - LlmMessage::Tool { - tool_call_id, - content, - } => Some((tool_call_id.clone(), content.clone())), - _ => None, - }) - .collect::>(); - assert_eq!( - tool_messages, - vec![ - ("call-remain-1".to_string(), "remaining result".to_string()), - ( - "call-stream-2".to_string(), - "streamed safe result".to_string() - ), - ] - ); - - let tool_event_ids = execution - .journal - .iter() - .filter_map(|event| match &event.payload { - StorageEventPayload::ToolCall { tool_call_id, .. } - | StorageEventPayload::ToolResult { tool_call_id, .. } => Some(tool_call_id.clone()), - _ => None, - }) - .collect::>(); - assert_eq!( - tool_event_ids, - vec![ - "call-remain-1".to_string(), - "call-remain-1".to_string(), - "call-stream-2".to_string(), - "call-stream-2".to_string(), - ] - ); -} - -#[cfg(not(debug_assertions))] -#[tokio::test] -async fn run_single_step_returns_internal_error_when_buffered_merge_loses_tool_result() { - struct MissingResultDriver; - - #[async_trait] - impl StepDriver for MissingResultDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message("find the answer")])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 1, - id: Some("call-stream-2".to_string()), - name: Some("streaming_safe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-remain-1".to_string(), - name: "dummy_tool".to_string(), - args: json!({"query": "alpha"}), - }, - ToolCallRequest { - id: "call-stream-2".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }, - ], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - _tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }) - } - } - - let probe_calls = Arc::new(AtomicUsize::new(0)); - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::clone(&probe_calls), - }), - 8192, - ); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - - let error = match run_single_step_with(&mut execution, &resources, &MissingResultDriver).await { - Ok(_) => panic!("missing remaining tool result should fail fast"), - Err(error) => error, - }; - - assert!(matches!(error, AstrError::Internal(message) if message.contains("call-remain-1"))); -} - -#[cfg(debug_assertions)] -#[tokio::test] -#[should_panic(expected = "merge dropped tool calls")] -async fn run_single_step_panics_when_buffered_merge_loses_tool_result_in_debug() { - struct MissingResultDriver; - - #[async_trait] - impl StepDriver for MissingResultDriver { - async fn assemble_prompt( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result { - Ok(assembled_prompt(vec![user_message("find the answer")])) - } - - async fn call_llm( - &self, - _resources: &TurnExecutionResources<'_>, - _llm_request: LlmRequest, - tool_delta_sink: Option, - ) -> astrcode_core::Result { - if let Some(sink) = tool_delta_sink { - sink(StreamedToolCallDelta { - index: 1, - id: Some("call-stream-2".to_string()), - name: Some("streaming_safe_probe".to_string()), - arguments_delta: r#"{"path":"README.md"}"#.to_string(), - }); - } - Ok(LlmOutput { - content: String::new(), - tool_calls: vec![ - ToolCallRequest { - id: "call-remain-1".to_string(), - name: "dummy_tool".to_string(), - args: json!({"query": "alpha"}), - }, - ToolCallRequest { - id: "call-stream-2".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }, - ], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }) - } - - async fn try_reactive_compact( - &self, - _execution: &TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - ) -> astrcode_core::Result> { - Ok(None) - } - - async fn execute_tool_cycle( - &self, - _execution: &mut TurnExecutionContext, - _resources: &TurnExecutionResources<'_>, - _tool_calls: Vec, - _event_emission_mode: ToolEventEmissionMode, - ) -> astrcode_core::Result { - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - }) - } - } - - let probe_calls = Arc::new(AtomicUsize::new(0)); - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::clone(&probe_calls), - }), - 8192, - ); - let session_state = test_session_state(); - let runtime = ResolvedRuntimeConfig::default(); - let cancel = CancelToken::new(); - let agent = AgentEventContext::default(); - let prompt_facts_provider = NoopPromptFactsProvider; - let resources = test_resources( - kernel.gateway(), - &session_state, - &runtime, - &cancel, - &agent, - &prompt_facts_provider, - ); - let mut execution = - TurnExecutionContext::new(&resources, vec![user_message("hello from user")], None); - - let _ = run_single_step_with(&mut execution, &resources, &MissingResultDriver).await; -} - -#[test] -fn fallback_reason_reports_identity_never_stabilized() { - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::new(AtomicUsize::new(0)), - }), - 8192, - ); - let call = ToolCallRequest { - id: "call-1".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }; - let assembly = StreamingToolAssembly::for_test( - Some("other-call".to_string()), - Some("streaming_safe_probe".to_string()), - r#"{"path":"README.md"}"#, - ); - - assert_eq!( - fallback_reason_for_final_call(Some(kernel.gateway()), Some(&assembly), &call), - Some(StreamingToolFallbackReason::IdentityNeverStabilized) - ); -} - -#[test] -fn fallback_reason_reports_unstable_json_payload() { - let kernel = crate::turn::test_support::test_kernel_with_tool( - Arc::new(StreamingSafeProbeTool { - calls: Arc::new(AtomicUsize::new(0)), - }), - 8192, - ); - let call = ToolCallRequest { - id: "call-1".to_string(), - name: "streaming_safe_probe".to_string(), - args: json!({"path": "README.md"}), - }; - let assembly = StreamingToolAssembly::for_test( - Some("call-1".to_string()), - Some("streaming_safe_probe".to_string()), - r#"{"path":"README.md""#, - ); - - assert_eq!( - fallback_reason_for_final_call(Some(kernel.gateway()), Some(&assembly), &call), - Some(StreamingToolFallbackReason::ArgumentsNeverFormedStableJson) - ); -} diff --git a/crates/session-runtime/src/turn/runner/step/tool_execution.rs b/crates/session-runtime/src/turn/runner/step/tool_execution.rs deleted file mode 100644 index a718dea8..00000000 --- a/crates/session-runtime/src/turn/runner/step/tool_execution.rs +++ /dev/null @@ -1,236 +0,0 @@ -use std::{collections::HashMap, path::Path, time::Instant}; - -use astrcode_core::{AstrError, LlmMessage, LlmOutput, Result, StorageEvent, StorageEventPayload}; - -use super::{ - TurnExecutionContext, TurnExecutionResources, - driver::StepDriver, - streaming_tools::{ - StreamingToolFinalizeResult, StreamingToolPlannerHandle, StreamingToolStats, - }, -}; -use crate::turn::tool_cycle::{ToolCycleOutcome, ToolCycleResult, ToolEventEmissionMode}; - -pub(super) enum ToolExecutionDisposition { - Completed, - Interrupted, -} - -pub(super) async fn finalize_and_execute_tool_calls( - execution: &mut TurnExecutionContext, - resources: &TurnExecutionResources<'_>, - driver: &impl StepDriver, - streaming_planner: &StreamingToolPlannerHandle, - output: &LlmOutput, - llm_finished_at: Instant, -) -> Result { - let finalized_streaming = streaming_planner - .finalize(&output.tool_calls, llm_finished_at) - .await; - let StreamingToolFinalizeResult { - matched_results, - remaining_tool_calls, - stats, - used_streaming_path, - } = finalized_streaming; - apply_streaming_stats(execution, stats); - - // Why: durable truth 现在以 step 为提交边界，工具结构事件也必须与 - // PromptMetrics / AssistantFinal 同批落盘，避免 turn 中断时留下半个 step。 - let event_emission_mode = ToolEventEmissionMode::Buffered; - let mut executed_remaining = if remaining_tool_calls.is_empty() { - empty_tool_cycle_result() - } else { - driver - .execute_tool_cycle( - execution, - resources, - remaining_tool_calls, - event_emission_mode, - ) - .await? - }; - - if used_streaming_path { - merge_buffered_and_remaining_tool_results( - execution, - output, - &matched_results, - &mut executed_remaining, - )?; - } else { - execution - .journal - .extend(std::mem::take(&mut executed_remaining.events)); - } - - track_tool_results(execution, resources.working_dir, &executed_remaining); - execution - .messages - .extend(std::mem::take(&mut executed_remaining.tool_messages)); - - if matches!(executed_remaining.outcome, ToolCycleOutcome::Interrupted) { - return Ok(ToolExecutionDisposition::Interrupted); - } - - Ok(ToolExecutionDisposition::Completed) -} - -fn apply_streaming_stats(execution: &mut TurnExecutionContext, stats: StreamingToolStats) { - execution.streaming_tools.launch_count = execution - .streaming_tools - .launch_count - .saturating_add(stats.launched_count); - execution.streaming_tools.match_count = execution - .streaming_tools - .match_count - .saturating_add(stats.matched_count); - execution.streaming_tools.fallback_count = execution - .streaming_tools - .fallback_count - .saturating_add(stats.fallback_count); - execution.streaming_tools.discard_count = execution - .streaming_tools - .discard_count - .saturating_add(stats.discard_count); - execution.streaming_tools.overlap_ms = execution - .streaming_tools - .overlap_ms - .saturating_add(stats.overlap_ms); -} - -fn empty_tool_cycle_result() -> ToolCycleResult { - ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - } -} - -fn merge_buffered_and_remaining_tool_results( - execution: &mut TurnExecutionContext, - output: &LlmOutput, - matched_results: &HashMap, - executed_remaining: &mut ToolCycleResult, -) -> Result<()> { - let mut combined_events = Vec::new(); - let mut remaining_results = executed_remaining - .raw_results - .iter() - .cloned() - .map(|(call, result)| (call.id.clone(), (call, result))) - .collect::>(); - let (mut remaining_event_groups, remaining_event_order, mut ungrouped_events) = - group_events_by_tool_call_id(std::mem::take(&mut executed_remaining.events)); - let mut merged_raw_results = Vec::with_capacity(output.tool_calls.len()); - let mut merged_tool_messages = Vec::with_capacity(output.tool_calls.len()); - let mut dropped_tool_call_ids = Vec::new(); - - for call in &output.tool_calls { - if let Some(buffered) = matched_results.get(&call.id) { - combined_events.extend(buffered.events.iter().cloned()); - merged_tool_messages.push(LlmMessage::Tool { - tool_call_id: buffered.result.tool_call_id.clone(), - content: buffered.result.model_content(), - }); - merged_raw_results.push((call.clone(), buffered.result.clone())); - continue; - } - if let Some((remaining_call, result)) = remaining_results.remove(&call.id) { - if let Some(events) = remaining_event_groups.remove(&call.id) { - combined_events.extend(events); - } - merged_tool_messages.push(LlmMessage::Tool { - tool_call_id: result.tool_call_id.clone(), - content: result.model_content(), - }); - merged_raw_results.push((remaining_call, result)); - continue; - } - - dropped_tool_call_ids.push(call.id.clone()); - } - - debug_assert_eq!( - merged_tool_messages.len(), - output.tool_calls.len(), - "merge dropped tool calls: expected {} results, got {}", - output.tool_calls.len(), - merged_tool_messages.len() - ); - if !dropped_tool_call_ids.is_empty() { - return Err(AstrError::Internal(format!( - "buffered tool merge dropped results for tool calls: {}", - dropped_tool_call_ids.join(", ") - ))); - } - - for call_id in remaining_event_order { - if let Some(events) = remaining_event_groups.remove(&call_id) { - combined_events.extend(events); - } - } - combined_events.append(&mut ungrouped_events); - execution.journal.extend(combined_events); - executed_remaining.tool_messages = merged_tool_messages; - executed_remaining.raw_results = merged_raw_results; - Ok(()) -} - -fn group_events_by_tool_call_id( - events: Vec, -) -> ( - HashMap>, - Vec, - Vec, -) { - let mut grouped = HashMap::>::new(); - let mut order = Vec::new(); - let mut ungrouped = Vec::new(); - - for event in events { - let Some(tool_call_id) = event_tool_call_id(&event) else { - ungrouped.push(event); - continue; - }; - if !grouped.contains_key(tool_call_id) { - order.push(tool_call_id.to_string()); - } - grouped - .entry(tool_call_id.to_string()) - .or_default() - .push(event); - } - - (grouped, order, ungrouped) -} - -fn event_tool_call_id(event: &StorageEvent) -> Option<&str> { - match &event.payload { - StorageEventPayload::ToolCall { tool_call_id, .. } - | StorageEventPayload::ToolResult { tool_call_id, .. } - | StorageEventPayload::ToolResultReferenceApplied { tool_call_id, .. } => { - Some(tool_call_id.as_str()) - }, - _ => None, - } -} - -fn track_tool_results( - execution: &mut TurnExecutionContext, - working_dir: &str, - tool_result: &ToolCycleResult, -) { - for (call, result) in &tool_result.raw_results { - execution.budget.file_access_tracker.record_tool_result( - call, - result, - Path::new(working_dir), - ); - execution - .budget - .micro_compact_state - .record_tool_result(result.tool_call_id.clone(), Instant::now()); - } -} diff --git a/crates/session-runtime/src/turn/runtime.rs b/crates/session-runtime/src/turn/runtime.rs deleted file mode 100644 index c8accaa2..00000000 --- a/crates/session-runtime/src/turn/runtime.rs +++ /dev/null @@ -1,524 +0,0 @@ -use std::sync::{ - Mutex as StdMutex, - atomic::{AtomicBool, AtomicU64, Ordering}, -}; - -use astrcode_core::{ - CancelToken, ResolvedRuntimeConfig, Result, SessionTurnLease, - support::{self}, -}; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) struct PendingManualCompactRequest { - pub(crate) runtime: ResolvedRuntimeConfig, - pub(crate) instructions: Option, -} - -pub(crate) struct ActiveTurnState { - pub(crate) turn_id: String, - pub(crate) generation: u64, - pub(crate) cancel: CancelToken, - #[allow(dead_code)] - pub(crate) turn_lease: Box, -} - -pub(crate) struct TurnRuntimeState { - generation: AtomicU64, - running: AtomicBool, - active_turn: StdMutex>, - compact: CompactRuntimeState, -} - -pub(crate) struct CompactingGuard<'a> { - runtime: &'a TurnRuntimeState, -} - -pub(crate) struct CompactRuntimeState { - in_progress: AtomicBool, - pending_request: StdMutex>, - failure_count: StdMutex, -} - -impl CompactRuntimeState { - fn new() -> Self { - Self { - in_progress: AtomicBool::new(false), - pending_request: StdMutex::new(None), - failure_count: StdMutex::new(0), - } - } - - fn is_in_progress(&self) -> bool { - self.in_progress.load(Ordering::SeqCst) - } - - fn set_in_progress(&self, in_progress: bool) { - self.in_progress.store(in_progress, Ordering::SeqCst); - } - - fn has_pending_request(&self) -> Result { - Ok(support::lock_anyhow( - &self.pending_request, - "session pending manual compact request", - )? - .is_some()) - } - - fn request_manual_compact(&self, request: PendingManualCompactRequest) -> Result { - let mut pending_request = support::lock_anyhow( - &self.pending_request, - "session pending manual compact request", - )?; - let already_pending = pending_request.is_some(); - *pending_request = Some(request); - Ok(!already_pending) - } - - fn take_pending_request(&self) -> Result> { - Ok(support::lock_anyhow( - &self.pending_request, - "session pending manual compact request", - )? - .take()) - } - - #[allow(dead_code)] - fn failure_count(&self) -> Result { - Ok(*support::lock_anyhow( - &self.failure_count, - "session compact failure count", - )?) - } -} - -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) struct ForcedTurnCompletion { - pub(crate) turn_id: Option, - pub(crate) pending_request: Option, -} - -impl std::fmt::Debug for TurnRuntimeState { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("TurnRuntimeState") - .field("running", &self.is_running()) - .finish_non_exhaustive() - } -} - -impl Drop for CompactingGuard<'_> { - fn drop(&mut self) { - self.runtime.set_compacting(false); - } -} - -impl TurnRuntimeState { - pub(crate) fn new() -> Self { - Self { - generation: AtomicU64::new(0), - running: AtomicBool::new(false), - active_turn: StdMutex::new(None), - compact: CompactRuntimeState::new(), - } - } - - pub(crate) fn is_running(&self) -> bool { - self.running.load(Ordering::SeqCst) - } - - pub(crate) fn active_turn_id_snapshot(&self) -> Result> { - Ok( - support::lock_anyhow(&self.active_turn, "session active turn")? - .as_ref() - .map(|active| active.turn_id.clone()), - ) - } - - pub(crate) fn prepare( - &self, - session_id: &str, - turn_id: &str, - cancel: CancelToken, - turn_lease: Box, - ) -> Result { - let mut active_turn = support::lock_anyhow(&self.active_turn, "session active turn")?; - if active_turn.is_some() || self.is_running() { - return Err(astrcode_core::AstrError::Validation(format!( - "session '{}' entered an inconsistent running state", - session_id - ))); - } - let generation = self.generation.fetch_add(1, Ordering::SeqCst) + 1; - *active_turn = Some(ActiveTurnState { - turn_id: turn_id.to_string(), - generation, - cancel, - turn_lease, - }); - self.running.store(true, Ordering::SeqCst); - Ok(generation) - } - - pub(crate) fn complete( - &self, - generation: u64, - ) -> Result<(bool, Option)> { - if self.generation.load(Ordering::SeqCst) != generation { - return Ok((false, None)); - } - let mut active_turn = support::lock_anyhow(&self.active_turn, "session active turn")?; - if active_turn.as_ref().map(|active| active.generation) != Some(generation) { - return Ok((false, None)); - } - *active_turn = None; - self.running.store(false, Ordering::SeqCst); - Ok((true, self.compact.take_pending_request()?)) - } - - pub(crate) fn force_complete(&self) -> Result { - self.generation.fetch_add(1, Ordering::SeqCst); - let mut active_turn = support::lock_anyhow(&self.active_turn, "session active turn")?; - let turn_id = active_turn.take().map(|active| { - active.cancel.cancel(); - active.turn_id - }); - self.running.store(false, Ordering::SeqCst); - Ok(ForcedTurnCompletion { - turn_id, - pending_request: self.compact.take_pending_request()?, - }) - } - - pub(crate) fn interrupt_if_running(&self) -> Result> { - let mut active_turn = support::lock_anyhow(&self.active_turn, "session active turn")?; - let Some(active_turn_state) = active_turn.take() else { - self.running.store(false, Ordering::SeqCst); - return Ok(None); - }; - self.generation.fetch_add(1, Ordering::SeqCst); - active_turn_state.cancel.cancel(); - self.running.store(false, Ordering::SeqCst); - Ok(Some(ForcedTurnCompletion { - turn_id: Some(active_turn_state.turn_id), - pending_request: self.compact.take_pending_request()?, - })) - } - - pub(crate) fn compacting(&self) -> bool { - self.compact.is_in_progress() - } - - pub(crate) fn set_compacting(&self, compacting: bool) { - self.compact.set_in_progress(compacting); - } - - pub(crate) fn enter_compacting(&self) -> CompactingGuard<'_> { - self.set_compacting(true); - CompactingGuard { runtime: self } - } - - pub(crate) fn has_pending_manual_compact(&self) -> Result { - self.compact.has_pending_request() - } - - pub(crate) fn request_manual_compact( - &self, - request: PendingManualCompactRequest, - ) -> Result { - self.compact.request_manual_compact(request) - } -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - - use astrcode_core::{ - AgentId, CancelToken, EventStore, Phase, RecoveredSessionState, SessionTurnAcquireResult, - SessionTurnLease, - }; - use async_trait::async_trait; - - use super::TurnRuntimeState; - use crate::{ROOT_AGENT_ID, actor::SessionActor, state::SessionWriter}; - - struct StubTurnLease; - - impl SessionTurnLease for StubTurnLease {} - - #[test] - fn turn_runtime_state_keeps_running_cache_and_active_turn_in_sync() { - let runtime = TurnRuntimeState::new(); - let cancel = CancelToken::new(); - runtime - .prepare( - "session-1", - "turn-1", - cancel.clone(), - Box::new(StubTurnLease), - ) - .expect("turn runtime should enter running state"); - - assert!(runtime.is_running()); - assert_eq!( - runtime - .active_turn_id_snapshot() - .expect("active turn should be readable") - .as_deref(), - Some("turn-1") - ); - - let interrupted = runtime - .interrupt_if_running() - .expect("interrupt should succeed"); - assert_eq!( - interrupted - .as_ref() - .and_then(|completion| completion.turn_id.as_deref()), - Some("turn-1") - ); - assert!(cancel.is_cancelled(), "cancel token should be triggered"); - assert!(!runtime.is_running()); - assert_eq!( - runtime - .active_turn_id_snapshot() - .expect("active turn should be readable"), - None - ); - } - - #[test] - fn stale_complete_generation_does_not_clear_resubmitted_turn() { - let runtime = TurnRuntimeState::new(); - let generation_a = runtime - .prepare( - "session-1", - "turn-a", - CancelToken::new(), - Box::new(StubTurnLease), - ) - .expect("first turn should prepare"); - let interrupted = runtime - .force_complete() - .expect("interrupt should clear active turn"); - assert_eq!(interrupted.turn_id.as_deref(), Some("turn-a")); - - let generation_b = runtime - .prepare( - "session-1", - "turn-b", - CancelToken::new(), - Box::new(StubTurnLease), - ) - .expect("second turn should prepare"); - - assert_eq!( - runtime - .complete(generation_a) - .expect("stale finalize should not error"), - (false, None) - ); - assert!( - runtime.is_running(), - "stale finalize must not clear running cache" - ); - assert_eq!( - runtime - .active_turn_id_snapshot() - .expect("active turn should stay readable") - .as_deref(), - Some("turn-b") - ); - - assert_eq!( - runtime - .complete(generation_b) - .expect("current generation should complete"), - (true, None) - ); - assert!(!runtime.is_running()); - assert_eq!( - runtime - .active_turn_id_snapshot() - .expect("active turn should be cleared"), - None - ); - } - - #[test] - fn interrupt_execution_if_running_is_noop_after_turn_already_completed() { - let runtime = TurnRuntimeState::new(); - let generation = runtime - .prepare( - "session-1", - "turn-1", - CancelToken::new(), - Box::new(StubTurnLease), - ) - .expect("turn should prepare"); - - assert_eq!( - runtime.complete(generation).expect("turn should complete"), - (true, None) - ); - - let interrupted = runtime - .interrupt_if_running() - .expect("interrupt should not fail"); - - assert_eq!(interrupted, None); - assert!(!runtime.is_running()); - } - - #[test] - fn recovery_resets_turn_runtime_to_idle_without_active_turn() { - let writer = Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter))); - let state = crate::state::SessionState::new( - Phase::Idle, - writer, - astrcode_core::AgentStateProjector::default(), - Vec::new(), - Vec::new(), - ); - let checkpoint = state - .recovery_checkpoint(7) - .expect("checkpoint should build"); - - let actor = SessionActor::from_recovery( - astrcode_core::SessionId::from("session-1".to_string()), - ".", - AgentId::from(ROOT_AGENT_ID.to_string()), - Arc::new(NoopEventStore), - RecoveredSessionState { - checkpoint: Some(checkpoint), - tail_events: Vec::new(), - }, - ) - .expect("session should recover"); - - assert!(!actor.turn_runtime().is_running()); - assert_eq!( - actor - .turn_runtime() - .active_turn_id_snapshot() - .expect("active turn should be readable"), - None - ); - assert!( - !actor - .turn_runtime() - .has_pending_manual_compact() - .expect("manual compact state should be readable") - ); - assert!(!actor.turn_runtime().compacting()); - } - - #[test] - fn compacting_guard_resets_flag_on_drop() { - let runtime = TurnRuntimeState::new(); - assert!(!runtime.compacting()); - { - let _guard = runtime.enter_compacting(); - assert!(runtime.compacting()); - } - assert!(!runtime.compacting()); - } - - #[test] - fn compacting_guard_resets_flag_when_unwinding() { - let runtime = TurnRuntimeState::new(); - - let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - let _guard = runtime.enter_compacting(); - assert!(runtime.compacting()); - panic!("boom"); - })); - - assert!(result.is_err(), "guard panic should propagate"); - assert!( - !runtime.compacting(), - "compacting flag must be cleared even if the guarded future panics" - ); - } - - #[derive(Debug)] - struct NoopEventStore; - - #[async_trait] - impl EventStore for NoopEventStore { - async fn ensure_session( - &self, - _session_id: &astrcode_core::SessionId, - _working_dir: &std::path::Path, - ) -> astrcode_core::Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &astrcode_core::SessionId, - event: &astrcode_core::StorageEvent, - ) -> astrcode_core::Result { - Ok(astrcode_core::StoredEvent { - storage_seq: 1, - event: event.clone(), - }) - } - - async fn replay( - &self, - _session_id: &astrcode_core::SessionId, - ) -> astrcode_core::Result> { - Ok(Vec::new()) - } - - async fn try_acquire_turn( - &self, - _session_id: &astrcode_core::SessionId, - _turn_id: &str, - ) -> astrcode_core::Result { - Ok(SessionTurnAcquireResult::Acquired(Box::new(StubTurnLease))) - } - - async fn list_sessions(&self) -> astrcode_core::Result> { - Ok(Vec::new()) - } - - async fn list_session_metas( - &self, - ) -> astrcode_core::Result> { - Ok(Vec::new()) - } - - async fn delete_session( - &self, - _session_id: &astrcode_core::SessionId, - ) -> astrcode_core::Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> astrcode_core::Result { - Ok(astrcode_core::DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } - } - - #[derive(Default)] - struct NoopEventLogWriter; - - impl astrcode_core::EventLogWriter for NoopEventLogWriter { - fn append( - &mut self, - event: &astrcode_core::StorageEvent, - ) -> astrcode_core::StoreResult { - Ok(astrcode_core::StoredEvent { - storage_seq: 0, - event: event.clone(), - }) - } - } -} diff --git a/crates/session-runtime/src/turn/submit.rs b/crates/session-runtime/src/turn/submit.rs deleted file mode 100644 index 8a8b8201..00000000 --- a/crates/session-runtime/src/turn/submit.rs +++ /dev/null @@ -1,1431 +0,0 @@ -use std::{sync::Arc, time::Instant}; - -use astrcode_core::{ - AgentEventContext, ApprovalPending, BoundModeToolContractSnapshot, CancelToken, CapabilityCall, - EventStore, EventTranslator, ExecutionAccepted, LlmMessage, ModeId, Phase, PolicyContext, - PromptDeclaration, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, - ResolvedSubagentContextOverrides, Result, RuntimeMetricsRecorder, SessionId, TurnId, - UserMessageOrigin, -}; -use astrcode_kernel::CapabilityRouter; -use chrono::Utc; - -use crate::{ - SessionRuntime, - actor::SessionActor, - run_turn, - turn::{ - branch::SubmitTarget, - events::{turn_terminal_event, user_message_event}, - finalize::{ - persist_pending_manual_compact_if_any, persist_storage_events, - persist_subrun_finished_event, persist_turn_failure, - }, - subrun_events::subrun_started_event, - }, -}; - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum SubmitBusyPolicy { - BranchOnBusy, - RejectOnBusy, -} - -struct SubmitPromptRequest { - session_id: String, - turn_id: Option, - live_user_input: Option, - queued_inputs: Vec, - runtime: ResolvedRuntimeConfig, - busy_policy: SubmitBusyPolicy, - submission: AgentPromptSubmission, -} - -struct TurnExecutionTask { - kernel: Arc, - request: crate::turn::RunnerRequest, - finalize: TurnFinalizeContext, -} - -struct TurnCoordinator { - kernel: Arc, - prompt_facts_provider: Arc, - event_store: Arc, - metrics: Arc, - submit_target: SubmitTarget, - turn_id: TurnId, - runtime: ResolvedRuntimeConfig, - live_user_input: Option, - queued_inputs: Vec, - submission: AgentPromptSubmission, -} - -#[derive(Clone, Default)] -pub struct AgentPromptSubmission { - pub agent: AgentEventContext, - pub capability_router: Option, - pub current_mode_id: ModeId, - pub prompt_declarations: Vec, - pub bound_mode_tool_contract: Option, - pub resolved_limits: Option, - pub resolved_overrides: Option, - pub injected_messages: Vec, - pub source_tool_call_id: Option, - pub policy_context: Option, - pub governance_revision: Option, - pub approval: Option>>, - pub prompt_governance: Option, -} - -#[derive(Debug, Clone)] -struct PersistedTurnContext { - turn_id: String, - agent: AgentEventContext, - source_tool_call_id: Option, -} - -struct TurnFinalizeContext { - kernel: Arc, - prompt_facts_provider: Arc, - event_store: Arc, - metrics: Arc, - actor: Arc, - session_id: String, - turn_started_at: Instant, - generation: u64, - persisted: PersistedTurnContext, -} - -impl TurnCoordinator { - async fn start(self) -> Result { - let accepted = self.accepted(); - let task = self.prepare().await?; - tokio::spawn(execute_turn_and_finalize(task)); - Ok(accepted) - } - - fn accepted(&self) -> ExecutionAccepted { - ExecutionAccepted { - session_id: self.submit_target.session_id.clone(), - turn_id: self.turn_id.clone(), - agent_id: None, - branched_from_session_id: self.submit_target.branched_from_session_id.clone(), - } - } - - async fn prepare(self) -> Result { - let Self { - kernel, - prompt_facts_provider, - event_store, - metrics, - submit_target, - turn_id, - runtime, - live_user_input, - queued_inputs, - submission, - } = self; - let cancel = CancelToken::new(); - let generation = submit_target.actor.turn_runtime().prepare( - submit_target.session_id.as_str(), - turn_id.as_str(), - cancel.clone(), - submit_target.turn_lease, - )?; - - let prepared = prepare_turn_submission( - submit_target.actor.state(), - turn_id.as_str(), - live_user_input, - queued_inputs, - submission, - ) - .await; - let prepared = match prepared { - Ok(prepared) => prepared, - Err(error) => { - let _ = submit_target.actor.turn_runtime().force_complete(); - return Err(error); - }, - }; - - Ok(TurnExecutionTask { - kernel: Arc::clone(&kernel), - request: crate::turn::RunnerRequest { - event_store: Arc::clone(&event_store), - session_id: submit_target.session_id.to_string(), - working_dir: submit_target.actor.working_dir().to_string(), - turn_id: turn_id.to_string(), - messages: prepared.messages, - last_assistant_at: submit_target - .actor - .state() - .snapshot_projected_state()? - .last_assistant_at, - session_state: Arc::clone(submit_target.actor.state()), - runtime, - cancel, - agent: prepared.persisted.agent.clone(), - current_mode_id: prepared.current_mode_id, - prompt_facts_provider: Arc::clone(&prompt_facts_provider), - capability_router: prepared.capability_router, - prompt_declarations: prepared.prompt_declarations, - bound_mode_tool_contract: prepared.bound_mode_tool_contract, - prompt_governance: prepared.prompt_governance, - }, - finalize: TurnFinalizeContext { - kernel, - prompt_facts_provider, - event_store, - metrics, - actor: Arc::clone(&submit_target.actor), - session_id: submit_target.session_id.to_string(), - turn_started_at: Instant::now(), - generation, - persisted: prepared.persisted, - }, - }) - } -} - -struct PreparedTurnSubmission { - capability_router: Option, - current_mode_id: ModeId, - prompt_declarations: Vec, - bound_mode_tool_contract: Option, - prompt_governance: Option, - messages: Vec, - persisted: PersistedTurnContext, -} - -async fn execute_turn_and_finalize(task: TurnExecutionTask) { - let TurnExecutionTask { - kernel, - request, - finalize, - } = task; - let result = run_turn(kernel, request).await; - finalize.metrics.record_turn_execution( - finalize.turn_started_at.elapsed().as_millis() as u64, - result.is_ok(), - ); - finalize_turn_execution(finalize, result).await; -} - -async fn finalize_turn_execution( - finalize: TurnFinalizeContext, - result: Result, -) { - let mut translator = EventTranslator::new( - finalize - .actor - .state() - .current_phase() - .unwrap_or(Phase::Idle), - ); - - match result { - Ok(turn_result) => { - if !turn_result.events.is_empty() { - if let Err(error) = persist_storage_events( - &finalize.event_store, - finalize.actor.state(), - &finalize.session_id, - &mut translator, - &turn_result.events, - ) - .await - { - log::error!( - "failed to persist trailing turn events for session '{}': {}", - finalize.session_id, - error - ); - } - } - if let Err(error) = persist_subrun_finished_event( - finalize.actor.state(), - &mut translator, - &finalize.persisted.turn_id, - &finalize.persisted.agent, - &turn_result, - finalize.persisted.source_tool_call_id.clone(), - ) - .await - { - log::error!( - "failed to persist subrun finished event for session '{}': {}", - finalize.session_id, - error - ); - } - }, - Err(error) if error.is_cancelled() => { - log::warn!( - "turn execution cancelled for session '{}': {}", - finalize.session_id, - error - ); - if let Err(append_error) = persist_storage_events( - &finalize.event_store, - finalize.actor.state(), - &finalize.session_id, - &mut translator, - &[turn_terminal_event( - &finalize.persisted.turn_id, - &finalize.persisted.agent, - crate::turn::TurnStopCause::Cancelled, - Utc::now(), - )], - ) - .await - { - log::error!( - "failed to persist cancelled turn terminal event for session '{}': {}", - finalize.session_id, - append_error - ); - } - }, - Err(error) => { - log::error!( - "turn execution failed for session '{}': {}", - finalize.session_id, - error - ); - persist_turn_failure( - finalize.actor.state(), - &finalize.session_id, - &finalize.persisted.turn_id, - finalize.persisted.agent.clone(), - &mut translator, - finalize.persisted.source_tool_call_id.clone(), - error.to_string(), - ) - .await; - }, - } - - let pending_manual_compact = match finalize.actor.turn_runtime().complete(finalize.generation) { - Ok((completed, pending)) => completed.then_some(pending).flatten(), - Err(error) => { - log::warn!( - "failed to complete turn runtime state for session '{}': {}", - finalize.session_id, - error - ); - None - }, - }; - persist_pending_manual_compact_if_any( - crate::turn::finalize::DeferredManualCompactContext { - gateway: finalize.kernel.gateway(), - prompt_facts_provider: finalize.prompt_facts_provider.as_ref(), - event_store: &finalize.event_store, - working_dir: finalize.actor.working_dir(), - turn_runtime: finalize.actor.turn_runtime(), - session_state: finalize.actor.state(), - session_id: &finalize.session_id, - }, - pending_manual_compact, - ) - .await; -} - -async fn prepare_turn_submission( - session_state: &Arc, - turn_id: &str, - live_user_input: Option, - queued_inputs: Vec, - submission: AgentPromptSubmission, -) -> Result { - let AgentPromptSubmission { - agent, - capability_router, - current_mode_id, - prompt_declarations, - bound_mode_tool_contract, - resolved_limits, - resolved_overrides, - injected_messages, - source_tool_call_id, - policy_context: _, - governance_revision: _, - approval: _, - prompt_governance, - } = submission; - - let mut translator = EventTranslator::new(session_state.current_phase()?); - for content in &queued_inputs { - let queued_event = user_message_event( - turn_id, - &agent, - content.clone(), - UserMessageOrigin::QueuedInput, - Utc::now(), - ); - session_state - .append_and_broadcast(&queued_event, &mut translator) - .await?; - } - if let Some(text) = &live_user_input { - let user_message = user_message_event( - turn_id, - &agent, - text.clone(), - UserMessageOrigin::User, - Utc::now(), - ); - session_state - .append_and_broadcast(&user_message, &mut translator) - .await?; - } - if let Some(event) = subrun_started_event( - turn_id, - &agent, - resolved_limits.clone(), - resolved_overrides.clone(), - source_tool_call_id.clone(), - ) { - session_state - .append_and_broadcast(&event, &mut translator) - .await?; - } - let mut messages = session_state.current_turn_messages()?; - if !injected_messages.is_empty() { - let insert_at = if live_user_input.is_some() { - messages.len().saturating_sub(1) - } else { - messages.len() - }; - messages.splice(insert_at..insert_at, injected_messages); - } - - Ok(PreparedTurnSubmission { - capability_router, - current_mode_id, - prompt_declarations, - bound_mode_tool_contract, - prompt_governance, - messages, - persisted: PersistedTurnContext { - turn_id: turn_id.to_string(), - agent, - source_tool_call_id, - }, - }) -} - -impl SessionRuntime { - pub async fn submit_prompt( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - ) -> Result { - self.submit_prompt_for_agent(session_id, text, runtime, AgentPromptSubmission::default()) - .await - } - - pub async fn submit_prompt_for_agent( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AgentPromptSubmission, - ) -> Result { - self.submit_prompt_inner(SubmitPromptRequest { - session_id: session_id.to_string(), - turn_id: None, - live_user_input: Some(text), - queued_inputs: Vec::new(), - runtime, - busy_policy: SubmitBusyPolicy::BranchOnBusy, - submission, - }) - .await - .and_then(|accepted| { - accepted.ok_or_else(|| { - astrcode_core::AstrError::Validation( - "submit prompt unexpectedly rejected while branch-on-busy is enabled" - .to_string(), - ) - }) - }) - } - - pub async fn try_submit_prompt_for_agent( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AgentPromptSubmission, - ) -> Result> { - self.submit_prompt_inner(SubmitPromptRequest { - session_id: session_id.to_string(), - turn_id: None, - live_user_input: Some(text), - queued_inputs: Vec::new(), - runtime, - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission, - }) - .await - } - - pub async fn try_submit_prompt_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AgentPromptSubmission, - ) -> Result> { - self.submit_prompt_inner(SubmitPromptRequest { - session_id: session_id.to_string(), - turn_id: Some(turn_id), - live_user_input: Some(text), - queued_inputs: Vec::new(), - runtime, - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission, - }) - .await - } - - pub async fn submit_prompt_for_agent_with_submission( - &self, - session_id: &str, - text: String, - runtime: ResolvedRuntimeConfig, - submission: AgentPromptSubmission, - ) -> Result { - self.submit_prompt_inner(SubmitPromptRequest { - session_id: session_id.to_string(), - turn_id: None, - live_user_input: Some(text), - queued_inputs: Vec::new(), - runtime, - busy_policy: SubmitBusyPolicy::BranchOnBusy, - submission, - }) - .await? - .ok_or_else(|| { - astrcode_core::AstrError::Validation( - "submit prompt unexpectedly rejected while branch-on-busy is enabled".to_string(), - ) - }) - } - - pub async fn submit_queued_inputs_for_agent_with_turn_id( - &self, - session_id: &str, - turn_id: TurnId, - queued_inputs: Vec, - runtime: ResolvedRuntimeConfig, - submission: AgentPromptSubmission, - ) -> Result> { - self.submit_prompt_inner(SubmitPromptRequest { - session_id: session_id.to_string(), - turn_id: Some(turn_id), - live_user_input: None, - queued_inputs, - runtime, - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission, - }) - .await - } - - async fn submit_prompt_inner( - &self, - request: SubmitPromptRequest, - ) -> Result> { - let SubmitPromptRequest { - session_id, - turn_id, - live_user_input, - queued_inputs, - runtime, - busy_policy, - submission, - } = request; - let live_user_input = live_user_input - .map(|text| text.trim().to_string()) - .filter(|text| !text.is_empty()); - let queued_inputs = queued_inputs - .into_iter() - .map(|content| content.trim().to_string()) - .filter(|content| !content.is_empty()) - .collect::>(); - if live_user_input.is_none() && queued_inputs.is_empty() { - return Err(astrcode_core::AstrError::Validation( - "turn submission must include live user input or queued inputs".to_string(), - )); - } - - let requested_session_id = SessionId::from(crate::state::normalize_session_id(&session_id)); - let turn_id = turn_id.unwrap_or_else(|| TurnId::from(astrcode_core::generate_turn_id())); - let submit_target = match busy_policy { - SubmitBusyPolicy::BranchOnBusy => Some( - self.resolve_submit_target( - &requested_session_id, - turn_id.as_str(), - runtime.max_concurrent_branch_depth, - ) - .await?, - ), - SubmitBusyPolicy::RejectOnBusy => { - self.try_resolve_submit_target_without_branch( - &requested_session_id, - turn_id.as_str(), - ) - .await? - }, - }; - let Some(submit_target) = submit_target else { - return Ok(None); - }; - - Ok(Some( - TurnCoordinator { - kernel: Arc::clone(&self.kernel), - prompt_facts_provider: Arc::clone(&self.prompt_facts_provider), - event_store: Arc::clone(&self.event_store), - metrics: Arc::clone(&self.metrics), - submit_target, - turn_id, - runtime, - live_user_input, - queued_inputs, - submission, - } - .start() - .await?, - )) - } -} - -#[cfg(test)] -mod tests { - use std::{ - sync::{ - Arc, Mutex, - atomic::{AtomicUsize, Ordering}, - }, - time::Duration, - }; - - use astrcode_core::{ - CancelToken, LlmFinishReason, LlmMessage, LlmOutput, LlmProvider, LlmRequest, ModelLimits, - PromptBuildOutput, PromptBuildRequest, PromptProvider, ResourceProvider, - ResourceReadResult, ResourceRequestContext, SessionTurnLease, StorageEventPayload, Tool, - ToolContext, ToolDefinition, ToolExecutionResult, UserMessageOrigin, - }; - use astrcode_kernel::{Kernel, ToolCapabilityInvoker}; - use async_trait::async_trait; - use serde_json::json; - use tokio::time::timeout; - - use super::*; - use crate::{ - TurnCollaborationSummary, TurnFinishReason, TurnOutcome, TurnRunResult, TurnSummary, - turn::{ - TurnLoopTransition, TurnStopCause, - events::turn_done_event, - subrun_events::subrun_finished_event, - test_support::{ - BranchingTestEventStore, NoopMetrics, append_root_turn_event_to_actor, - assert_contains_compact_summary, assert_contains_error_message, test_actor, - test_runtime, - }, - }, - }; - - #[derive(Debug)] - struct SummaryLlmProvider; - - struct StubTurnLease; - - impl SessionTurnLease for StubTurnLease {} - - #[async_trait] - impl LlmProvider for SummaryLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Ok(LlmOutput { - content: "okmanual compact summary" - .to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 64_000, - max_output_tokens: 8_000, - } - } - } - - #[derive(Debug)] - struct TestPromptProvider; - - #[async_trait] - impl PromptProvider for TestPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: serde_json::Value::Null, - }) - } - } - - #[derive(Debug)] - struct TestResourceProvider; - - #[async_trait] - impl ResourceProvider for TestResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: serde_json::Value::Null, - metadata: serde_json::Value::Null, - }) - } - } - - fn summary_kernel() -> Arc { - Arc::new( - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(SummaryLlmProvider)) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ) - } - - fn step_flush_kernel(provider: Arc) -> Arc { - let router = astrcode_kernel::CapabilityRouter::builder() - .register_invoker(Arc::new( - ToolCapabilityInvoker::new(Arc::new(StepFlushProbeTool)) - .expect("tool invoker should build"), - )) - .build() - .expect("router should build"); - Arc::new( - Kernel::builder() - .with_capabilities(router) - .with_llm_provider(provider) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ) - } - - fn finalize_context(actor: Arc) -> TurnFinalizeContext { - let generation = actor - .turn_runtime() - .prepare( - "session-1", - "turn-1", - CancelToken::new(), - Box::new(StubTurnLease), - ) - .expect("turn runtime should prepare for finalize"); - TurnFinalizeContext { - kernel: summary_kernel(), - prompt_facts_provider: Arc::new(crate::turn::test_support::NoopPromptFactsProvider), - event_store: Arc::new(BranchingTestEventStore::default()), - metrics: Arc::new(NoopMetrics), - actor, - session_id: "session-1".to_string(), - turn_started_at: Instant::now(), - generation, - persisted: PersistedTurnContext { - turn_id: "turn-1".to_string(), - agent: AgentEventContext::default(), - source_tool_call_id: None, - }, - } - } - - #[derive(Debug)] - struct RecordingLlmProvider { - requests: Arc>>>, - } - - #[async_trait] - impl LlmProvider for RecordingLlmProvider { - async fn generate( - &self, - request: LlmRequest, - _sink: Option, - ) -> Result { - self.requests - .lock() - .expect("recorded requests lock should work") - .push(request.messages.clone()); - Ok(LlmOutput { - content: "answer".to_string(), - tool_calls: Vec::new(), - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }) - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 64_000, - max_output_tokens: 8_000, - } - } - } - - #[derive(Debug)] - struct StepFlushProbeTool; - - #[async_trait] - impl Tool for StepFlushProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "step_flush_probe".to_string(), - description: "records whether completed steps survive later cancellation" - .to_string(), - parameters: json!({ "type": "object" }), - } - } - - async fn execute( - &self, - tool_call_id: String, - _input: serde_json::Value, - _ctx: &ToolContext, - ) -> Result { - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "step_flush_probe".to_string(), - ok: true, - output: "step flushed result".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } - } - - #[derive(Debug, Default)] - struct StepFlushLlmProvider { - calls: AtomicUsize, - } - - #[async_trait] - impl LlmProvider for StepFlushLlmProvider { - async fn generate( - &self, - request: LlmRequest, - _sink: Option, - ) -> Result { - match self.calls.fetch_add(1, Ordering::SeqCst) { - 0 => Ok(LlmOutput { - content: String::new(), - tool_calls: vec![astrcode_core::ToolCallRequest { - id: "call-step-1".to_string(), - name: "step_flush_probe".to_string(), - args: json!({}), - }], - reasoning: None, - usage: None, - finish_reason: LlmFinishReason::ToolCalls, - prompt_cache_diagnostics: None, - }), - 1 => loop { - if request.cancel.is_cancelled() { - return Err(astrcode_core::AstrError::Cancelled); - } - tokio::time::sleep(Duration::from_millis(10)).await; - }, - call_index => panic!("unexpected llm call index {call_index}"), - } - } - - fn model_limits(&self) -> ModelLimits { - ModelLimits { - context_window: 64_000, - max_output_tokens: 8_000, - } - } - } - - fn completed_turn_result() -> TurnRunResult { - TurnRunResult { - outcome: TurnOutcome::Completed, - messages: Vec::new(), - events: vec![turn_done_event( - "turn-1", - &AgentEventContext::default(), - Some(astrcode_core::TurnTerminalKind::Completed), - None, - chrono::Utc::now(), - )], - summary: TurnSummary { - finish_reason: TurnFinishReason::NaturalEnd, - stop_cause: TurnStopCause::Completed, - last_transition: Some(TurnLoopTransition::ToolCycleCompleted), - wall_duration: Duration::default(), - step_count: 1, - total_tokens_used: 0, - cache_read_input_tokens: 0, - cache_creation_input_tokens: 0, - auto_compaction_count: 0, - reactive_compact_count: 0, - max_output_continuation_count: 0, - tool_result_replacement_count: 0, - tool_result_reapply_count: 0, - tool_result_bytes_saved: 0, - tool_result_over_budget_message_count: 0, - streaming_tool_launch_count: 0, - streaming_tool_match_count: 0, - streaming_tool_fallback_count: 0, - streaming_tool_discard_count: 0, - streaming_tool_overlap_ms: 0, - collaboration: TurnCollaborationSummary::default(), - }, - } - } - - #[tokio::test] - async fn finalize_turn_execution_records_failure_event_and_interrupts_session() { - let actor = test_actor().await; - - finalize_turn_execution( - finalize_context(Arc::clone(&actor)), - Err(astrcode_core::AstrError::Internal("boom".to_string())), - ) - .await; - - assert_eq!( - actor - .state() - .current_phase() - .expect("phase should be readable"), - Phase::Idle - ); - let stored = actor - .state() - .snapshot_recent_stored_events() - .expect("stored events should be available"); - assert_contains_error_message(&stored, "internal error: boom"); - } - - #[tokio::test] - async fn finalize_turn_execution_persists_deferred_manual_compact_after_success() { - let actor = test_actor().await; - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_user_message_event("turn-1", "hello"), - ) - .await; - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_assistant_final_event("turn-1", "latest answer"), - ) - .await; - actor - .turn_runtime() - .request_manual_compact(crate::turn::PendingManualCompactRequest { - runtime: ResolvedRuntimeConfig::default(), - instructions: None, - }) - .expect("manual compact flag should set"); - - finalize_turn_execution( - finalize_context(Arc::clone(&actor)), - Ok(completed_turn_result()), - ) - .await; - - assert_eq!( - actor - .state() - .current_phase() - .expect("phase should be readable"), - Phase::Idle - ); - let stored = actor - .state() - .snapshot_recent_stored_events() - .expect("stored events should be available"); - assert_contains_compact_summary(&stored, "manual compact summary"); - } - - #[tokio::test] - async fn finalize_turn_execution_persists_deferred_manual_compact_after_interrupt() { - let actor = test_actor().await; - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_user_message_event("turn-1", "hello"), - ) - .await; - append_root_turn_event_to_actor( - &actor, - crate::turn::test_support::root_assistant_final_event("turn-1", "latest answer"), - ) - .await; - actor - .turn_runtime() - .request_manual_compact(crate::turn::PendingManualCompactRequest { - runtime: ResolvedRuntimeConfig::default(), - instructions: None, - }) - .expect("manual compact flag should set"); - - finalize_turn_execution( - finalize_context(Arc::clone(&actor)), - Err(astrcode_core::AstrError::Internal("boom".to_string())), - ) - .await; - - assert_eq!( - actor - .state() - .current_phase() - .expect("phase should be readable"), - Phase::Idle - ); - let stored = actor - .state() - .snapshot_recent_stored_events() - .expect("stored events should be available"); - assert_contains_error_message(&stored, "internal error: boom"); - assert_contains_compact_summary(&stored, "manual compact summary"); - } - - #[test] - fn subrun_lifecycle_events_ignore_non_subrun_context() { - assert!( - subrun_started_event("turn-1", &AgentEventContext::default(), None, None, None) - .is_none() - ); - assert!( - subrun_finished_event( - "turn-1", - &AgentEventContext::default(), - &completed_turn_result(), - None, - ) - .is_none() - ); - } - - #[tokio::test] - async fn submit_prompt_inner_returns_none_when_reject_on_busy() { - let event_store = Arc::new(BranchingTestEventStore::default()); - let runtime = test_runtime(event_store.clone()); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - event_store.push_busy("turn-busy"); - - let result = runtime - .submit_prompt_inner(SubmitPromptRequest { - session_id: session.session_id.clone(), - turn_id: None, - live_user_input: Some("hello".to_string()), - queued_inputs: Vec::new(), - runtime: ResolvedRuntimeConfig::default(), - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission: AgentPromptSubmission::default(), - }) - .await - .expect("submit should not error"); - - assert!(result.is_none(), "reject-on-busy should not branch"); - assert_eq!( - runtime.list_sessions(), - vec![SessionId::from(session.session_id)] - ); - } - - #[tokio::test] - async fn submit_prompt_inner_branches_when_branch_on_busy() { - let event_store = Arc::new(BranchingTestEventStore::default()); - let runtime = test_runtime(event_store.clone()); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - event_store.push_busy("turn-busy"); - - let accepted = runtime - .submit_prompt_inner(SubmitPromptRequest { - session_id: session.session_id.clone(), - turn_id: None, - live_user_input: Some("hello".to_string()), - queued_inputs: Vec::new(), - runtime: ResolvedRuntimeConfig { - max_concurrent_branch_depth: 2, - ..ResolvedRuntimeConfig::default() - }, - busy_policy: SubmitBusyPolicy::BranchOnBusy, - submission: AgentPromptSubmission::default(), - }) - .await - .expect("submit should not error") - .expect("branch-on-busy should always accept"); - - assert_eq!( - accepted.branched_from_session_id.as_deref(), - Some(session.session_id.as_str()) - ); - assert_ne!(accepted.session_id.as_str(), session.session_id.as_str()); - let loaded_sessions = runtime.list_sessions(); - assert_eq!( - loaded_sessions.len(), - 2, - "branch submit should load a second session" - ); - assert!( - loaded_sessions.contains(&SessionId::from(session.session_id.clone())), - "source session should stay loaded" - ); - assert!( - loaded_sessions.contains(&accepted.session_id), - "branched session should be loaded" - ); - - let stored = event_store.stored_events_for(accepted.session_id.as_str()); - assert!(stored.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::SessionStart { - parent_session_id, - .. - } if parent_session_id.as_deref() == Some(session.session_id.as_str()) - ))); - - let _ = runtime - .wait_for_turn_terminal_snapshot( - accepted.session_id.as_str(), - accepted.turn_id.as_str(), - ) - .await - .expect("background turn should settle before test exits"); - } - - #[tokio::test] - async fn submit_prompt_inner_appends_queued_inputs_before_live_user_prompt() { - let requests = Arc::new(Mutex::new(Vec::>::new())); - let kernel = Arc::new( - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(RecordingLlmProvider { - requests: Arc::clone(&requests), - })) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ); - let event_store = Arc::new(BranchingTestEventStore::default()); - let runtime = SessionRuntime::new( - kernel, - Arc::new(crate::turn::test_support::NoopPromptFactsProvider), - event_store, - Arc::new(NoopMetrics), - ); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - - let accepted = runtime - .submit_prompt_inner(SubmitPromptRequest { - session_id: session.session_id.clone(), - turn_id: None, - live_user_input: Some("live user input".to_string()), - queued_inputs: vec![ - "queued child result".to_string(), - "queued reactivation context".to_string(), - ], - runtime: ResolvedRuntimeConfig::default(), - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission: AgentPromptSubmission::default(), - }) - .await - .expect("submit should not error") - .expect("submit should be accepted"); - runtime - .wait_for_turn_terminal_snapshot( - accepted.session_id.as_str(), - accepted.turn_id.as_str(), - ) - .await - .expect("turn should finish"); - - let requests = requests.lock().expect("recorded requests lock should work"); - assert_eq!(requests.len(), 1, "expected one model request"); - - assert!(matches!( - requests[0].as_slice(), - [ - LlmMessage::User { - content: first_queued, - origin: UserMessageOrigin::QueuedInput, - }, - LlmMessage::User { - content: second_queued, - origin: UserMessageOrigin::QueuedInput, - }, - LlmMessage::User { - content: user_content, - origin: UserMessageOrigin::User, - } - ] if first_queued == "queued child result" - && second_queued == "queued reactivation context" - && user_content == "live user input" - )); - } - - #[tokio::test] - async fn submit_prompt_inner_inserts_injected_messages_before_live_user_prompt() { - let requests = Arc::new(Mutex::new(Vec::>::new())); - let kernel = Arc::new( - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(RecordingLlmProvider { - requests: Arc::clone(&requests), - })) - .with_prompt_provider(Arc::new(TestPromptProvider)) - .with_resource_provider(Arc::new(TestResourceProvider)) - .build() - .expect("kernel should build"), - ); - let event_store = Arc::new(BranchingTestEventStore::default()); - let runtime = SessionRuntime::new( - kernel, - Arc::new(crate::turn::test_support::NoopPromptFactsProvider), - event_store, - Arc::new(NoopMetrics), - ); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - - let accepted = runtime - .submit_prompt_inner(SubmitPromptRequest { - session_id: session.session_id.clone(), - turn_id: None, - live_user_input: Some("child task".to_string()), - queued_inputs: Vec::new(), - runtime: ResolvedRuntimeConfig::default(), - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission: AgentPromptSubmission { - injected_messages: vec![ - LlmMessage::User { - content: "parent turn".to_string(), - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { - content: "parent answer".to_string(), - tool_calls: Vec::new(), - reasoning: None, - }, - ], - ..AgentPromptSubmission::default() - }, - }) - .await - .expect("submit should not error") - .expect("submit should be accepted"); - runtime - .wait_for_turn_terminal_snapshot( - accepted.session_id.as_str(), - accepted.turn_id.as_str(), - ) - .await - .expect("turn should finish"); - - let requests = requests.lock().expect("recorded requests lock should work"); - assert!(matches!( - requests[0].as_slice(), - [ - LlmMessage::User { - content: inherited_user, - origin: UserMessageOrigin::User, - }, - LlmMessage::Assistant { content: inherited_answer, .. }, - LlmMessage::User { - content: child_task, - origin: UserMessageOrigin::User, - }, - ] if inherited_user == "parent turn" - && inherited_answer == "parent answer" - && child_task == "child task" - )); - } - - #[tokio::test] - async fn submit_prompt_inner_persists_completed_step_before_later_cancellation() { - let event_store = Arc::new(BranchingTestEventStore::default()); - let provider = Arc::new(StepFlushLlmProvider::default()); - let runtime = SessionRuntime::new( - step_flush_kernel(Arc::clone(&provider)), - Arc::new(crate::turn::test_support::NoopPromptFactsProvider), - event_store.clone() as Arc, - Arc::new(NoopMetrics), - ); - let session = runtime - .create_session(".") - .await - .expect("test session should be created"); - - let accepted = runtime - .submit_prompt_inner(SubmitPromptRequest { - session_id: session.session_id.clone(), - turn_id: None, - live_user_input: Some("hello".to_string()), - queued_inputs: Vec::new(), - runtime: ResolvedRuntimeConfig::default(), - busy_policy: SubmitBusyPolicy::RejectOnBusy, - submission: AgentPromptSubmission::default(), - }) - .await - .expect("submit should not error") - .expect("submit should be accepted"); - - timeout(Duration::from_secs(1), async { - loop { - if provider.calls.load(Ordering::SeqCst) >= 2 { - break; - } - tokio::time::sleep(Duration::from_millis(10)).await; - } - }) - .await - .expect("turn should advance into the second llm step before cancellation"); - - let actor = runtime - .ensure_loaded_session(&accepted.session_id) - .await - .expect("session actor should load"); - assert!( - actor - .turn_runtime() - .interrupt_if_running() - .expect("interrupt should succeed") - .is_some(), - "turn should still be running while the second llm step is blocked" - ); - - let snapshot = runtime - .wait_for_turn_terminal_snapshot( - accepted.session_id.as_str(), - accepted.turn_id.as_str(), - ) - .await - .expect("cancelled turn should still reach a terminal snapshot"); - - assert!(snapshot.events.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::ToolCall { tool_call_id, tool_name, .. } - if tool_call_id == "call-step-1" && tool_name == "step_flush_probe" - ))); - assert!(snapshot.events.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::ToolResult { tool_call_id, output, .. } - if tool_call_id == "call-step-1" && output == "step flushed result" - ))); - assert!(snapshot.events.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::TurnDone { terminal_kind, .. } - if *terminal_kind == Some(astrcode_core::TurnTerminalKind::Cancelled) - ))); - } - - #[tokio::test] - async fn prepare_turn_submission_preserves_bound_mode_tool_contract_snapshot() { - let actor = test_actor().await; - let prepared = prepare_turn_submission( - actor.state(), - "turn-1", - Some("hello".to_string()), - Vec::new(), - AgentPromptSubmission { - current_mode_id: "plan".into(), - bound_mode_tool_contract: Some(BoundModeToolContractSnapshot { - mode_id: "plan".into(), - artifact: None, - exit_gate: None, - }), - ..AgentPromptSubmission::default() - }, - ) - .await - .expect("submission should prepare"); - - assert_eq!(prepared.current_mode_id.as_str(), "plan"); - assert_eq!( - prepared - .bound_mode_tool_contract - .as_ref() - .map(|snapshot| snapshot.mode_id.as_str()), - Some("plan") - ); - } - - #[test] - fn subrun_started_event_persists_resolved_overrides_snapshot() { - let event = subrun_started_event( - "turn-1", - &AgentEventContext::sub_run( - "agent-child", - "turn-parent", - "explore", - "subrun-1", - None, - astrcode_core::SubRunStorageMode::IndependentSession, - Some("session-child".into()), - ), - None, - Some(ResolvedSubagentContextOverrides { - include_compact_summary: true, - fork_mode: Some(astrcode_core::ForkMode::LastNTurns(3)), - ..ResolvedSubagentContextOverrides::default() - }), - None, - ) - .expect("subrun event should be built"); - - assert!(matches!( - event.payload, - StorageEventPayload::SubRunStarted { resolved_overrides, .. } - if resolved_overrides.include_compact_summary - && resolved_overrides.fork_mode - == Some(astrcode_core::ForkMode::LastNTurns(3)) - )); - } -} diff --git a/crates/session-runtime/src/turn/subrun_events.rs b/crates/session-runtime/src/turn/subrun_events.rs deleted file mode 100644 index f747a070..00000000 --- a/crates/session-runtime/src/turn/subrun_events.rs +++ /dev/null @@ -1,218 +0,0 @@ -use astrcode_core::{ - AgentEventContext, CompletedParentDeliveryPayload, ParentDelivery, ParentDeliveryOrigin, - ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides, StorageEvent, StorageEventPayload, -}; -use chrono::Utc; - -use crate::turn::projector::last_non_empty_assistant_message; - -pub(crate) fn subrun_started_event( - turn_id: &str, - agent: &AgentEventContext, - resolved_limits: Option, - resolved_overrides: Option, - source_tool_call_id: Option, -) -> Option { - if agent.invocation_kind != Some(astrcode_core::InvocationKind::SubRun) { - return None; - } - - Some(StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::SubRunStarted { - tool_call_id: source_tool_call_id, - resolved_overrides: resolved_overrides.unwrap_or_default(), - resolved_limits: resolved_limits.unwrap_or_default(), - timestamp: Some(Utc::now()), - }, - }) -} - -pub(crate) fn subrun_finished_event( - turn_id: &str, - agent: &AgentEventContext, - turn_result: &crate::TurnRunResult, - source_tool_call_id: Option, -) -> Option { - if agent.invocation_kind != Some(astrcode_core::InvocationKind::SubRun) { - return None; - } - - let summary = - last_non_empty_assistant_message(&turn_result.messages).unwrap_or_else( - || match &turn_result.outcome { - crate::TurnOutcome::Completed => { - "sub-agent completed without readable summary".to_string() - }, - crate::TurnOutcome::Cancelled => "sub-agent cancelled".to_string(), - crate::TurnOutcome::Error { message } => message.trim().to_string(), - }, - ); - - let result = match &turn_result.outcome { - crate::TurnOutcome::Completed => astrcode_core::SubRunResult::Completed { - outcome: astrcode_core::CompletedSubRunOutcome::Completed, - handoff: astrcode_core::SubRunHandoff { - findings: Vec::new(), - artifacts: Vec::new(), - delivery: Some(ParentDelivery { - idempotency_key: format!( - "subrun-finished:{}:{}", - agent.sub_run_id.as_deref().unwrap_or("unknown-subrun"), - turn_id - ), - origin: ParentDeliveryOrigin::Fallback, - terminal_semantics: ParentDeliveryTerminalSemantics::Terminal, - source_turn_id: Some(turn_id.to_string()), - payload: ParentDeliveryPayload::Completed(CompletedParentDeliveryPayload { - message: summary, - findings: Vec::new(), - artifacts: Vec::new(), - }), - }), - }, - }, - crate::TurnOutcome::Cancelled => astrcode_core::SubRunResult::Failed { - outcome: astrcode_core::FailedSubRunOutcome::Cancelled, - failure: astrcode_core::SubRunFailure { - code: astrcode_core::SubRunFailureCode::Interrupted, - display_message: summary, - technical_message: "interrupted".to_string(), - retryable: false, - }, - }, - crate::TurnOutcome::Error { message } => astrcode_core::SubRunResult::Failed { - outcome: astrcode_core::FailedSubRunOutcome::Failed, - failure: astrcode_core::SubRunFailure { - code: astrcode_core::SubRunFailureCode::Internal, - display_message: summary, - technical_message: message.clone(), - retryable: true, - }, - }, - }; - - Some(StorageEvent { - turn_id: Some(turn_id.to_string()), - agent: agent.clone(), - payload: StorageEventPayload::SubRunFinished { - tool_call_id: source_tool_call_id, - result, - step_count: turn_result.summary.step_count as u32, - estimated_tokens: turn_result.summary.total_tokens_used, - timestamp: Some(Utc::now()), - }, - }) -} - -#[cfg(test)] -mod tests { - use std::time::Duration; - - use astrcode_core::{ - AgentEventContext, CompletedParentDeliveryPayload, ParentDeliveryPayload, - StorageEventPayload, SubRunStorageMode, - }; - - use super::subrun_finished_event; - - fn subrun_agent() -> AgentEventContext { - AgentEventContext::sub_run( - "agent-child", - "turn-parent", - "reviewer", - "subrun-1", - None, - SubRunStorageMode::IndependentSession, - Some("session-child".into()), - ) - } - - fn summary() -> crate::TurnSummary { - crate::TurnSummary { - finish_reason: crate::TurnFinishReason::NaturalEnd, - stop_cause: crate::turn::loop_control::TurnStopCause::Completed, - last_transition: None, - wall_duration: Duration::from_secs(1), - step_count: 0, - total_tokens_used: 0, - cache_read_input_tokens: 0, - cache_creation_input_tokens: 0, - auto_compaction_count: 0, - reactive_compact_count: 0, - max_output_continuation_count: 0, - tool_result_replacement_count: 0, - tool_result_reapply_count: 0, - tool_result_bytes_saved: 0, - tool_result_over_budget_message_count: 0, - streaming_tool_launch_count: 0, - streaming_tool_match_count: 0, - streaming_tool_fallback_count: 0, - streaming_tool_discard_count: 0, - streaming_tool_overlap_ms: 0, - collaboration: crate::TurnCollaborationSummary::default(), - } - } - - #[test] - fn completed_subrun_fallback_summary_is_language_neutral_in_durable_event() { - let event = subrun_finished_event( - "turn-1", - &subrun_agent(), - &crate::TurnRunResult { - messages: Vec::new(), - events: Vec::new(), - outcome: crate::TurnOutcome::Completed, - summary: summary(), - }, - None, - ) - .expect("subrun completion should emit a durable event"); - - let StorageEventPayload::SubRunFinished { result, .. } = event.payload else { - panic!("expected SubRunFinished payload"); - }; - let message = match result { - astrcode_core::SubRunResult::Completed { handoff, .. } => match handoff - .delivery - .expect("fallback delivery should exist") - .payload - { - ParentDeliveryPayload::Completed(CompletedParentDeliveryPayload { - message, - .. - }) => message, - other => panic!("expected completed delivery payload, got {other:?}"), - }, - other => panic!("expected completed subrun result, got {other:?}"), - }; - assert_eq!(message, "sub-agent completed without readable summary"); - } - - #[test] - fn cancelled_subrun_fallback_summary_is_language_neutral_in_durable_event() { - let event = subrun_finished_event( - "turn-1", - &subrun_agent(), - &crate::TurnRunResult { - messages: Vec::new(), - events: Vec::new(), - outcome: crate::TurnOutcome::Cancelled, - summary: summary(), - }, - None, - ) - .expect("subrun cancellation should emit a durable event"); - - let StorageEventPayload::SubRunFinished { result, .. } = event.payload else { - panic!("expected SubRunFinished payload"); - }; - let display_message = match result { - astrcode_core::SubRunResult::Failed { failure, .. } => failure.display_message, - other => panic!("expected failed subrun result, got {other:?}"), - }; - assert_eq!(display_message, "sub-agent cancelled"); - } -} diff --git a/crates/session-runtime/src/turn/summary.rs b/crates/session-runtime/src/turn/summary.rs deleted file mode 100644 index 73af8b6f..00000000 --- a/crates/session-runtime/src/turn/summary.rs +++ /dev/null @@ -1,246 +0,0 @@ -//! Turn 级稳定汇总结构。 -//! -//! 每次完整 Turn 执行结束后，由 runner 生成一份不可变汇总， -//! 供治理/诊断读取路径消费，避免上层重新扫描整条事件流。 -//! -//! ## 为什么不直接用事件流 -//! -//! 事件流是原始事实源，适合持久化和回放，但聚合查询代价高。 -//! TurnSummary 是单次 Turn 执行的聚合视图，提供 O(1) 的指标访问。 - -use std::time::Duration; - -use astrcode_core::{ - AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, - TurnTerminalKind, -}; - -use super::{TurnLoopTransition, TurnStopCause}; - -/// Turn 完成原因。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TurnFinishReason { - /// LLM 自然结束（无工具调用，无截断） - NaturalEnd, - /// 用户取消 - Cancelled, - /// 不可恢复错误 - Error, -} - -impl From<&TurnTerminalKind> for TurnFinishReason { - fn from(value: &TurnTerminalKind) -> Self { - match value { - TurnTerminalKind::Completed => Self::NaturalEnd, - TurnTerminalKind::Cancelled => Self::Cancelled, - TurnTerminalKind::Error { .. } => Self::Error, - } - } -} - -/// 单轮 turn 内的协作汇总。 -#[derive(Debug, Clone, Default)] -pub struct TurnCollaborationSummary { - pub fact_count: usize, - pub spawn_count: usize, - pub send_count: usize, - pub observe_count: usize, - pub close_count: usize, - pub delivery_count: usize, - pub rejected_count: usize, - pub failed_count: usize, - pub child_reuse_count: usize, - pub delivery_latency_samples: usize, - pub avg_delivery_latency_ms: Option, - pub max_delivery_latency_ms: Option, -} - -impl TurnCollaborationSummary { - pub fn from_facts(facts: &[AgentCollaborationFact]) -> Self { - let mut summary = Self { - fact_count: facts.len(), - ..Self::default() - }; - let mut latency_total = 0u64; - let mut max_latency = 0u64; - for fact in facts { - match fact.action { - AgentCollaborationActionKind::Spawn => summary.spawn_count += 1, - AgentCollaborationActionKind::Send => summary.send_count += 1, - AgentCollaborationActionKind::Observe => summary.observe_count += 1, - AgentCollaborationActionKind::Close => summary.close_count += 1, - AgentCollaborationActionKind::Delivery => summary.delivery_count += 1, - } - match fact.outcome { - AgentCollaborationOutcomeKind::Rejected => summary.rejected_count += 1, - AgentCollaborationOutcomeKind::Failed => summary.failed_count += 1, - AgentCollaborationOutcomeKind::Reused => summary.child_reuse_count += 1, - AgentCollaborationOutcomeKind::Consumed => { - if let Some(latency_ms) = fact.latency_ms { - summary.delivery_latency_samples += 1; - latency_total = latency_total.saturating_add(latency_ms); - max_latency = max_latency.max(latency_ms); - } - }, - _ => {}, - } - } - if summary.delivery_latency_samples > 0 { - summary.avg_delivery_latency_ms = - Some(latency_total / summary.delivery_latency_samples as u64); - summary.max_delivery_latency_ms = Some(max_latency); - } - summary - } -} - -/// 单次 Turn 执行的稳定汇总结果。 -/// -/// 由 `run_turn` 在 Turn 结束时生成，包含执行期间的关键指标。 -/// 结构一旦生成即为不可变快照。 -#[derive(Debug, Clone)] -pub struct TurnSummary { - /// Turn 完成原因 - pub finish_reason: TurnFinishReason, - /// 更细粒度的停止原因，供 loop/诊断层使用。 - pub stop_cause: TurnStopCause, - /// 最后一次进入下一轮的 transition。 - pub last_transition: Option, - /// Turn 执行总耗时 - pub wall_duration: Duration, - /// Turn 内 step 数量 - pub step_count: usize, - /// Provider 报告的总 token 使用量（含 input + output） - pub total_tokens_used: u64, - /// Provider 报告的 cache read input tokens - pub cache_read_input_tokens: u64, - /// Provider 报告的 cache creation input tokens - pub cache_creation_input_tokens: u64, - /// Turn 期间发生的自动压缩次数 - pub auto_compaction_count: usize, - /// Turn 期间发生的 reactive compact 次数 - pub reactive_compact_count: usize, - /// Turn 期间发生的 max_tokens continuation 次数 - pub max_output_continuation_count: usize, - /// aggregate tool-result budget 新增 replacement 的命中数 - pub tool_result_replacement_count: usize, - /// 已有 replacement 被 durable 重放到当前 prompt 的次数 - pub tool_result_reapply_count: usize, - /// aggregate replacement 节省的字节数 - pub tool_result_bytes_saved: u64, - /// 进入 aggregate over-budget 处理的 tool-result message 数 - pub tool_result_over_budget_message_count: usize, - /// 流式阶段提前启动的安全工具调用数 - pub streaming_tool_launch_count: usize, - /// 最终与 assistant 定稿精确匹配并复用的提前执行数 - pub streaming_tool_match_count: usize, - /// 因参数未闭合、身份未稳定或工具不安全而保守回退的次数 - pub streaming_tool_fallback_count: usize, - /// 已启动但最终被 discard 的提前执行数 - pub streaming_tool_discard_count: usize, - /// LLM streaming 与工具执行真实重叠的累计毫秒数 - pub streaming_tool_overlap_ms: u64, - /// Turn 内 agent-tool 协作汇总 - pub collaboration: TurnCollaborationSummary, -} - -impl TurnSummary { - /// 计算 cache reuse 比率（0.0 ~ 1.0）。 - /// - /// 返回 cache_read_input_tokens 占总 input tokens 的比例。 - /// 若无 token 使用记录，返回 0.0。 - pub fn cache_reuse_ratio(&self) -> f64 { - let total_input = self - .total_tokens_used - .saturating_add(self.cache_read_input_tokens) - .saturating_add(self.cache_creation_input_tokens); - if total_input == 0 { - return 0.0; - } - self.cache_read_input_tokens as f64 / total_input as f64 - } -} - -#[cfg(test)] -mod tests { - use astrcode_core::{ - AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, - AgentCollaborationPolicyContext, ChildExecutionIdentity, - }; - - use super::TurnCollaborationSummary; - - fn fact( - id: &str, - action: AgentCollaborationActionKind, - outcome: AgentCollaborationOutcomeKind, - latency_ms: Option, - ) -> AgentCollaborationFact { - AgentCollaborationFact { - fact_id: id.to_string().into(), - action, - outcome, - parent_session_id: "session-parent".to_string().into(), - turn_id: "turn-1".to_string().into(), - parent_agent_id: Some("agent-root".to_string().into()), - child_identity: Some(ChildExecutionIdentity { - agent_id: "agent-child".to_string().into(), - session_id: "session-child".to_string().into(), - sub_run_id: "subrun-child".to_string().into(), - }), - delivery_id: None, - reason_code: None, - summary: None, - latency_ms, - source_tool_call_id: None, - governance_revision: Some("governance-surface-v1".to_string()), - mode_id: Some(astrcode_core::ModeId::code()), - policy: AgentCollaborationPolicyContext { - policy_revision: "governance-surface-v1".to_string(), - max_subrun_depth: 3, - max_spawn_per_turn: 3, - }, - } - } - - #[test] - fn collaboration_summary_counts_actions_and_latency() { - let summary = TurnCollaborationSummary::from_facts(&[ - fact( - "spawn", - AgentCollaborationActionKind::Spawn, - AgentCollaborationOutcomeKind::Accepted, - None, - ), - fact( - "observe", - AgentCollaborationActionKind::Observe, - AgentCollaborationOutcomeKind::Rejected, - None, - ), - fact( - "send", - AgentCollaborationActionKind::Send, - AgentCollaborationOutcomeKind::Reused, - None, - ), - fact( - "delivery", - AgentCollaborationActionKind::Delivery, - AgentCollaborationOutcomeKind::Consumed, - Some(180), - ), - ]); - - assert_eq!(summary.fact_count, 4); - assert_eq!(summary.spawn_count, 1); - assert_eq!(summary.observe_count, 1); - assert_eq!(summary.send_count, 1); - assert_eq!(summary.delivery_count, 1); - assert_eq!(summary.rejected_count, 1); - assert_eq!(summary.child_reuse_count, 1); - assert_eq!(summary.delivery_latency_samples, 1); - assert_eq!(summary.avg_delivery_latency_ms, Some(180)); - assert_eq!(summary.max_delivery_latency_ms, Some(180)); - } -} diff --git a/crates/session-runtime/src/turn/test_support.rs b/crates/session-runtime/src/turn/test_support.rs deleted file mode 100644 index 951d082e..00000000 --- a/crates/session-runtime/src/turn/test_support.rs +++ /dev/null @@ -1,628 +0,0 @@ -#![cfg(test)] - -use std::{ - collections::{HashMap, VecDeque}, - path::Path, - sync::{ - Arc, Mutex, - atomic::{AtomicU64, Ordering}, - }, -}; - -use astrcode_core::{ - AgentCollaborationFact, AgentId, AgentStateProjector, AstrError, CompactAppliedMeta, - CompactMode, EventLogWriter, EventStore, EventTranslator, LlmOutput, LlmProvider, LlmRequest, - ModelLimits, Phase, PromptBuildOutput, PromptBuildRequest, PromptFacts, PromptFactsProvider, - PromptFactsRequest, PromptProvider, ResourceProvider, ResourceReadResult, - ResourceRequestContext, Result, RuntimeMetricsRecorder, SessionMeta, SessionTurnAcquireResult, - StorageEvent, StorageEventPayload, StoreResult, StoredEvent, Tool, -}; -use astrcode_kernel::{Kernel, KernelGateway, ToolCapabilityInvoker}; -use async_trait::async_trait; -use serde_json::Value; - -use crate::{ - SessionRuntime, SessionState, - actor::SessionActor, - state::{SessionWriter, append_and_broadcast}, - turn::events::{ - CompactAppliedStats, assistant_final_event, compact_applied_event, turn_done_event, - user_message_event, - }, -}; - -#[derive(Debug)] -struct NoopLlmProvider { - limits: ModelLimits, -} - -#[async_trait] -impl LlmProvider for NoopLlmProvider { - async fn generate( - &self, - _request: LlmRequest, - _sink: Option, - ) -> Result { - Err(AstrError::Validation( - "turn test noop llm provider should not execute".to_string(), - )) - } - - fn model_limits(&self) -> ModelLimits { - self.limits - } -} - -#[derive(Debug)] -struct NoopPromptProvider; - -#[async_trait] -impl PromptProvider for NoopPromptProvider { - async fn build_prompt(&self, _request: PromptBuildRequest) -> Result { - Ok(PromptBuildOutput { - system_prompt: "noop".to_string(), - system_prompt_blocks: Vec::new(), - prompt_cache_hints: Default::default(), - cache_metrics: Default::default(), - metadata: Value::Null, - }) - } -} - -#[derive(Debug)] -pub(crate) struct NoopPromptFactsProvider; - -#[async_trait] -impl PromptFactsProvider for NoopPromptFactsProvider { - async fn resolve_prompt_facts(&self, _request: &PromptFactsRequest) -> Result { - Ok(PromptFacts::default()) - } -} - -#[derive(Debug)] -struct NoopResourceProvider; - -#[async_trait] -impl ResourceProvider for NoopResourceProvider { - async fn read_resource( - &self, - _uri: &str, - _context: &ResourceRequestContext, - ) -> Result { - Ok(ResourceReadResult { - uri: "noop://resource".to_string(), - content: Value::Null, - metadata: Value::Null, - }) - } -} - -#[derive(Debug, Default)] -struct NoopEventLogWriter { - next_seq: u64, -} - -impl EventLogWriter for NoopEventLogWriter { - fn append(&mut self, event: &StorageEvent) -> StoreResult { - self.next_seq += 1; - Ok(astrcode_core::StoredEvent { - storage_seq: self.next_seq, - event: event.clone(), - }) - } -} - -pub(crate) fn test_gateway(context_window: usize) -> KernelGateway { - KernelGateway::new( - astrcode_kernel::CapabilityRouter::empty(), - Arc::new(NoopLlmProvider { - limits: ModelLimits { - context_window, - max_output_tokens: 4096, - }, - }), - Arc::new(NoopPromptProvider), - Arc::new(NoopResourceProvider), - ) -} - -pub(crate) fn test_kernel_with_tool(tool: Arc, context_window: usize) -> Kernel { - let router = astrcode_kernel::CapabilityRouter::builder() - .register_invoker(Arc::new( - ToolCapabilityInvoker::new(tool).expect("tool invoker should build"), - )) - .build() - .expect("router should build"); - Kernel::builder() - .with_capabilities(router) - .with_llm_provider(Arc::new(NoopLlmProvider { - limits: ModelLimits { - context_window, - max_output_tokens: 4096, - }, - })) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build") -} - -pub(crate) fn test_kernel(context_window: usize) -> Kernel { - Kernel::builder() - .with_capabilities(astrcode_kernel::CapabilityRouter::empty()) - .with_llm_provider(Arc::new(NoopLlmProvider { - limits: ModelLimits { - context_window, - max_output_tokens: 4096, - }, - })) - .with_prompt_provider(Arc::new(NoopPromptProvider)) - .with_resource_provider(Arc::new(NoopResourceProvider)) - .build() - .expect("kernel should build") -} - -pub(crate) fn test_runtime(event_store: Arc) -> SessionRuntime { - SessionRuntime::new( - Arc::new(test_kernel(8192)), - Arc::new(NoopPromptFactsProvider), - event_store, - Arc::new(NoopMetrics), - ) -} - -pub(crate) fn test_session_state() -> Arc { - Arc::new(SessionState::new( - Phase::Idle, - Arc::new(SessionWriter::new(Box::new(NoopEventLogWriter::default()))), - AgentStateProjector::default(), - Vec::new(), - Vec::new(), - )) -} - -#[derive(Debug, Default)] -pub(crate) struct StubEventStore { - next_seq: AtomicU64, -} - -pub(crate) struct StubTurnLease; - -impl astrcode_core::SessionTurnLease for StubTurnLease {} - -#[async_trait] -impl EventStore for StubEventStore { - async fn ensure_session( - &self, - _session_id: &astrcode_core::SessionId, - _working_dir: &Path, - ) -> Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &astrcode_core::SessionId, - event: &StorageEvent, - ) -> Result { - Ok(StoredEvent { - storage_seq: self.next_seq.fetch_add(1, Ordering::SeqCst) + 1, - event: event.clone(), - }) - } - - async fn replay(&self, _session_id: &astrcode_core::SessionId) -> Result> { - Ok(Vec::new()) - } - - async fn try_acquire_turn( - &self, - _session_id: &astrcode_core::SessionId, - _turn_id: &str, - ) -> Result { - Ok(SessionTurnAcquireResult::Acquired(Box::new(StubTurnLease))) - } - - async fn list_sessions(&self) -> Result> { - Ok(Vec::new()) - } - - async fn list_session_metas(&self) -> Result> { - Ok(Vec::new()) - } - - async fn delete_session(&self, _session_id: &astrcode_core::SessionId) -> Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> Result { - Ok(astrcode_core::DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } -} - -pub(crate) struct NoopMetrics; - -impl RuntimeMetricsRecorder for NoopMetrics { - fn record_session_rehydrate(&self, _duration_ms: u64, _success: bool) {} - - fn record_sse_catch_up( - &self, - _duration_ms: u64, - _success: bool, - _used_disk_fallback: bool, - _recovered_events: u64, - ) { - } - - fn record_turn_execution(&self, _duration_ms: u64, _success: bool) {} - - fn record_subrun_execution( - &self, - _duration_ms: u64, - _outcome: astrcode_core::AgentTurnOutcome, - _step_count: Option, - _estimated_tokens: Option, - _storage_mode: Option, - ) { - } - - fn record_child_spawned(&self) {} - fn record_parent_reactivation_requested(&self) {} - fn record_parent_reactivation_succeeded(&self) {} - fn record_parent_reactivation_failed(&self) {} - fn record_delivery_buffer_queued(&self) {} - fn record_delivery_buffer_dequeued(&self) {} - fn record_delivery_buffer_wake_requested(&self) {} - fn record_delivery_buffer_wake_succeeded(&self) {} - fn record_delivery_buffer_wake_failed(&self) {} - fn record_cache_reuse_hit(&self) {} - fn record_cache_reuse_miss(&self) {} - fn record_agent_collaboration_fact(&self, _fact: &AgentCollaborationFact) {} -} - -pub(crate) async fn test_actor() -> Arc { - Arc::new( - SessionActor::new_persistent( - astrcode_core::SessionId::from("session-1".to_string()), - ".", - AgentId::from("root-agent".to_string()), - Arc::new(StubEventStore::default()), - ) - .await - .expect("test actor should initialize"), - ) -} - -pub(crate) fn root_turn_event(turn_id: Option<&str>, payload: StorageEventPayload) -> StorageEvent { - StorageEvent { - turn_id: turn_id.map(str::to_string), - agent: astrcode_core::AgentEventContext::default(), - payload, - } -} - -pub(crate) fn root_user_message_event(turn_id: &str, content: impl Into) -> StorageEvent { - user_message_event( - turn_id, - &astrcode_core::AgentEventContext::default(), - content.into(), - astrcode_core::UserMessageOrigin::User, - chrono::Utc::now(), - ) -} - -pub(crate) fn root_assistant_final_event( - turn_id: &str, - content: impl Into, -) -> StorageEvent { - assistant_final_event( - turn_id, - &astrcode_core::AgentEventContext::default(), - content.into(), - None, - None, - 0, - Some(chrono::Utc::now()), - ) -} - -pub(crate) fn root_turn_done_event(turn_id: &str, reason: Option) -> StorageEvent { - turn_done_event( - turn_id, - &astrcode_core::AgentEventContext::default(), - None, - reason, - chrono::Utc::now(), - ) -} - -pub(crate) fn root_compact_applied_event( - turn_id: &str, - summary: impl Into, - preserved_recent_turns: usize, - pre_tokens: usize, - post_tokens_estimate: usize, - messages_removed: usize, - tokens_freed: usize, -) -> StorageEvent { - compact_applied_event( - Some(turn_id), - &astrcode_core::AgentEventContext::default(), - astrcode_core::CompactTrigger::Auto, - summary.into(), - CompactAppliedStats { - meta: CompactAppliedMeta { - mode: CompactMode::Full, - instructions_present: false, - fallback_used: false, - retry_count: 0, - input_units: 0, - output_summary_chars: 0, - }, - preserved_recent_turns, - pre_tokens, - post_tokens_estimate, - messages_removed, - tokens_freed, - }, - chrono::Utc::now(), - ) -} - -pub(crate) fn assert_contains_error_message(events: &[StoredEvent], expected_message: &str) { - assert!( - events.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::Error { message, .. } if message == expected_message - )), - "expected stored events to contain Error('{expected_message}')" - ); -} - -pub(crate) fn assert_contains_compact_summary(events: &[StoredEvent], expected_summary: &str) { - assert!( - events.iter().any(|stored| matches!( - &stored.event.payload, - StorageEventPayload::CompactApplied { summary, .. } if summary.contains(expected_summary) - )), - "expected stored events to contain CompactApplied('{expected_summary}')" - ); -} - -pub(crate) async fn append_root_turn_event_to_actor( - actor: &Arc, - event: StorageEvent, -) { - let mut translator = EventTranslator::new(actor.state().current_phase().expect("phase")); - append_and_broadcast(actor.state(), &event, &mut translator) - .await - .expect("test event should append"); -} - -enum AcquireScript { - Busy { turn_id: String }, - Acquired, -} - -#[derive(Default)] -pub(crate) struct BranchingTestEventStore { - next_seq: AtomicU64, - events: Mutex>>, - metas: Mutex>, - acquire_scripts: Mutex>, -} - -impl BranchingTestEventStore { - pub(crate) fn push_busy(&self, turn_id: impl Into) { - self.acquire_scripts - .lock() - .expect("acquire_scripts lock should work") - .push_back(AcquireScript::Busy { - turn_id: turn_id.into(), - }); - } - - pub(crate) fn stored_events_for(&self, session_id: &str) -> Vec { - self.events - .lock() - .expect("events lock should work") - .get(session_id) - .cloned() - .unwrap_or_default() - } - - pub(crate) fn seed_session( - &self, - session_id: &str, - working_dir: &str, - events: Vec, - ) { - let max_seq = events - .iter() - .map(|stored| stored.storage_seq) - .max() - .unwrap_or(0); - self.next_seq - .fetch_max(max_seq, std::sync::atomic::Ordering::SeqCst); - self.events - .lock() - .expect("events lock should work") - .insert(session_id.to_string(), events.clone()); - - let now = chrono::Utc::now(); - let mut meta = SessionMeta { - session_id: session_id.to_string(), - working_dir: working_dir.to_string(), - display_name: crate::display_name_from_working_dir(Path::new(working_dir)), - title: "New Session".to_string(), - created_at: now, - updated_at: now, - parent_session_id: None, - parent_storage_seq: None, - phase: Phase::Idle, - }; - if let Some(stored) = events.iter().find(|stored| { - matches!( - stored.event.payload, - StorageEventPayload::SessionStart { .. } - ) - }) { - if let StorageEventPayload::SessionStart { - parent_session_id, - parent_storage_seq, - .. - } = &stored.event.payload - { - meta.parent_session_id = parent_session_id.clone(); - meta.parent_storage_seq = *parent_storage_seq; - } - } - self.metas - .lock() - .expect("metas lock should work") - .insert(session_id.to_string(), meta); - } -} - -#[async_trait] -impl EventStore for BranchingTestEventStore { - async fn ensure_session( - &self, - session_id: &astrcode_core::SessionId, - working_dir: &Path, - ) -> Result<()> { - let now = chrono::Utc::now(); - self.metas - .lock() - .expect("metas lock should work") - .entry(session_id.to_string()) - .or_insert_with(|| SessionMeta { - session_id: session_id.to_string(), - working_dir: working_dir.display().to_string(), - display_name: crate::display_name_from_working_dir(working_dir), - title: "New Session".to_string(), - created_at: now, - updated_at: now, - parent_session_id: None, - parent_storage_seq: None, - phase: Phase::Idle, - }); - Ok(()) - } - - async fn append( - &self, - session_id: &astrcode_core::SessionId, - event: &StorageEvent, - ) -> Result { - let storage_seq = self.next_seq.fetch_add(1, Ordering::SeqCst) + 1; - let stored = StoredEvent { - storage_seq, - event: event.clone(), - }; - self.events - .lock() - .expect("events lock should work") - .entry(session_id.to_string()) - .or_default() - .push(stored.clone()); - - let mut metas = self.metas.lock().expect("metas lock should work"); - let meta = metas - .entry(session_id.to_string()) - .or_insert_with(|| SessionMeta { - session_id: session_id.to_string(), - working_dir: ".".to_string(), - display_name: ".".to_string(), - title: "New Session".to_string(), - created_at: chrono::Utc::now(), - updated_at: chrono::Utc::now(), - parent_session_id: None, - parent_storage_seq: None, - phase: Phase::Idle, - }); - meta.updated_at = chrono::Utc::now(); - if let StorageEventPayload::SessionStart { - working_dir, - parent_session_id, - parent_storage_seq, - .. - } = &event.payload - { - meta.working_dir = working_dir.clone(); - meta.display_name = crate::display_name_from_working_dir(Path::new(working_dir)); - meta.parent_session_id = parent_session_id.clone(); - meta.parent_storage_seq = *parent_storage_seq; - } - Ok(stored) - } - - async fn replay(&self, session_id: &astrcode_core::SessionId) -> Result> { - Ok(self.stored_events_for(session_id.as_str())) - } - - async fn try_acquire_turn( - &self, - _session_id: &astrcode_core::SessionId, - _turn_id: &str, - ) -> Result { - let scripted = self - .acquire_scripts - .lock() - .expect("acquire_scripts lock should work") - .pop_front(); - match scripted.unwrap_or(AcquireScript::Acquired) { - AcquireScript::Busy { turn_id } => Ok(SessionTurnAcquireResult::Busy( - astrcode_core::SessionTurnBusy { - turn_id, - owner_pid: std::process::id(), - acquired_at: chrono::Utc::now(), - }, - )), - AcquireScript::Acquired => { - Ok(SessionTurnAcquireResult::Acquired(Box::new(StubTurnLease))) - }, - } - } - - async fn list_sessions(&self) -> Result> { - Ok(self - .metas - .lock() - .expect("metas lock should work") - .keys() - .cloned() - .map(astrcode_core::SessionId::from) - .collect()) - } - - async fn list_session_metas(&self) -> Result> { - Ok(self - .metas - .lock() - .expect("metas lock should work") - .values() - .cloned() - .collect()) - } - - async fn delete_session(&self, _session_id: &astrcode_core::SessionId) -> Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> Result { - Ok(astrcode_core::DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } -} diff --git a/crates/session-runtime/src/turn/tool_cycle.rs b/crates/session-runtime/src/turn/tool_cycle.rs deleted file mode 100644 index 368e2946..00000000 --- a/crates/session-runtime/src/turn/tool_cycle.rs +++ /dev/null @@ -1,1304 +0,0 @@ -//! # 工具执行周期 -//! -//! 负责执行 LLM 请求中的工具调用，包括： -//! - 并发执行（只读工具可并行，写操作串行） -//! - 结果收集和事件广播 -//! - 取消信号传播 -//! -//! ## 并发模型 -//! -//! 只读工具（`concurrency_safe`）使用 `buffer_unordered` 并发执行。 -//! 有副作用的工具按顺序执行，避免并发写冲突。 -//! 并发上限通过 `max_concurrency` 参数控制。 -//! -//! ## 架构约束 -//! -//! 所有工具调用通过 `KernelGateway` 进行，session-runtime 不直接持有 provider。 -//! 策略检查（policy/approval）由 kernel gateway 在 `invoke_tool` 内部处理。 - -use std::{ - sync::{Arc, Mutex}, - time::Instant, -}; - -use astrcode_core::{ - AgentEventContext, CancelToken, LlmMessage, Result, StorageEvent, ToolCallRequest, ToolContext, - ToolEventSink, ToolExecutionResult, ToolOutputDelta, tool_result_persist::resolve_inline_limit, -}; -use astrcode_kernel::KernelGateway; -use async_trait::async_trait; -use futures_util::stream::{self, StreamExt}; -use tokio::{ - sync::{mpsc, oneshot}, - task::JoinHandle, -}; - -#[cfg(test)] -use crate::SessionStateEventSink; -use crate::{ - SessionState, - turn::events::{tool_call_event, tool_result_event}, -}; - -/// 工具执行周期的最终结果。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub(crate) enum ToolCycleOutcome { - /// 所有工具调用均已完成。 - Completed, - /// 工具执行被取消。 - Interrupted, -} - -/// 工具执行周期的完整结果。 -pub(crate) struct ToolCycleResult { - pub outcome: ToolCycleOutcome, - /// 工具结果消息，需要追加到对话历史。 - pub tool_messages: Vec, - /// 原始调用和结果，供外部追踪（文件访问、微压缩等）。 - pub raw_results: Vec<(ToolCallRequest, ToolExecutionResult)>, - /// 仅在 buffered 模式下返回，由 step 在 assistant 定稿后统一刷入 durable 事件流。 - pub events: Vec, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(crate) enum ToolEventEmissionMode { - #[cfg(test)] - Immediate, - Buffered, -} - -/// 工具执行周期的上下文参数，避免函数参数过多。 -pub(crate) struct ToolCycleContext<'a> { - pub gateway: &'a KernelGateway, - pub session_state: &'a Arc, - pub session_id: &'a str, - pub working_dir: &'a str, - pub turn_id: &'a str, - pub agent: &'a AgentEventContext, - pub cancel: &'a CancelToken, - pub events: &'a mut Vec, - pub max_concurrency: usize, - pub tool_result_inline_limit: usize, - pub event_emission_mode: ToolEventEmissionMode, - pub current_mode_id: &'a astrcode_core::ModeId, - pub bound_mode_tool_contract: Option<&'a astrcode_core::BoundModeToolContractSnapshot>, -} - -struct SingleToolInvocation<'a> { - gateway: &'a KernelGateway, - session_state: Arc, - tool_call: &'a ToolCallRequest, - session_id: &'a str, - working_dir: &'a str, - turn_id: &'a str, - agent: &'a AgentEventContext, - cancel: &'a CancelToken, - tool_result_inline_limit: usize, - event_emission_mode: ToolEventEmissionMode, - current_mode_id: &'a astrcode_core::ModeId, - bound_mode_tool_contract: Option<&'a astrcode_core::BoundModeToolContractSnapshot>, -} - -pub(crate) struct BufferedToolExecutionRequest { - pub gateway: KernelGateway, - pub session_state: Arc, - pub tool_call: ToolCallRequest, - pub session_id: String, - pub working_dir: String, - pub turn_id: String, - pub agent: AgentEventContext, - pub cancel: CancelToken, - pub current_mode_id: astrcode_core::ModeId, - pub bound_mode_tool_contract: Option, - pub tool_result_inline_limit: usize, -} - -pub(crate) struct BufferedToolExecution { - pub result: ToolExecutionResult, - pub events: Vec, - pub started_at: Instant, - pub finished_at: Instant, -} - -struct BufferedToolEventSink { - events: Arc>>, -} - -#[async_trait] -impl ToolEventSink for BufferedToolEventSink { - async fn emit(&self, event: StorageEvent) -> Result<()> { - self.events - .lock() - .expect("buffered tool event sink lock should work") - .push(event); - Ok(()) - } -} - -struct ToolOutputForwarder { - shutdown_tx: oneshot::Sender<()>, - join_handle: JoinHandle<()>, -} - -impl ToolOutputForwarder { - fn spawn( - session_state: Arc, - turn_id: &str, - agent: &AgentEventContext, - mut tool_output_rx: mpsc::UnboundedReceiver, - ) -> Self { - let (shutdown_tx, mut shutdown_rx) = oneshot::channel::<()>(); - let turn_id = turn_id.to_string(); - let agent = agent.clone(); - let join_handle = tokio::spawn(async move { - loop { - tokio::select! { - biased; - _ = &mut shutdown_rx => { - while let Ok(delta) = tool_output_rx.try_recv() { - broadcast_tool_output_delta(&session_state, &turn_id, &agent, delta); - } - break; - } - maybe_delta = tool_output_rx.recv() => { - let Some(delta) = maybe_delta else { - break; - }; - broadcast_tool_output_delta(&session_state, &turn_id, &agent, delta); - } - } - } - }); - Self { - shutdown_tx, - join_handle, - } - } - - async fn shutdown(self) { - let _ = self.shutdown_tx.send(()); - if let Err(error) = self.join_handle.await { - log::warn!("tool output forwarder join failed: {error}"); - } - } -} - -/// 执行一组工具调用，支持并发安全工具并行。 -/// -/// 工具分为两类： -/// - **安全调用**（`concurrency_safe = true`）：并发执行，受 `max_concurrency` 限制 -/// - **不安全调用**（有副作用）：按顺序执行 -pub async fn execute_tool_calls( - ctx: &mut ToolCycleContext<'_>, - tool_calls: Vec, -) -> Result { - let capabilities = ctx.gateway.capabilities(); - - let mut safe_calls = Vec::new(); - let mut unsafe_calls = Vec::new(); - - for call in tool_calls { - if ctx.cancel.is_cancelled() { - return Ok(interrupted_result()); - } - - let is_safe = capabilities - .capability_spec(&call.name) - .is_some_and(|spec| spec.concurrency_safe); - - if is_safe { - safe_calls.push(call); - } else { - unsafe_calls.push(call); - } - } - - // 收集所有 fallback 事件到局部缓冲，最后合并到 ctx.events。 - // 为什么仍保留这层缓冲： - // 1. 并发工具执行期间不能直接借用共享的 ctx.events。 - // 2. 若即时 durable 发射失败，turn 结束阶段还能兜底落盘，避免结构事件丢失。 - let mut collected_events: Vec = Vec::new(); - let mut raw_results: Vec<(ToolCallRequest, ToolExecutionResult)> = Vec::new(); - - // 并发执行安全工具 - if !safe_calls.is_empty() { - if ctx.cancel.is_cancelled() { - return Ok(interrupted_result()); - } - let results = execute_concurrent_safe(ctx, safe_calls).await?; - for (call, result, local_events) in results { - collected_events.extend(local_events); - raw_results.push((call, result)); - } - } - - // 串行执行不安全工具 - for call in unsafe_calls { - if ctx.cancel.is_cancelled() { - // 已执行的工具事件仍需保留 - ctx.events.extend(collected_events); - return Ok(interrupted_result()); - } - let (result, local_events) = invoke_single_tool(SingleToolInvocation { - gateway: ctx.gateway, - session_state: Arc::clone(ctx.session_state), - tool_call: &call, - session_id: ctx.session_id, - working_dir: ctx.working_dir, - turn_id: ctx.turn_id, - agent: ctx.agent, - cancel: ctx.cancel, - tool_result_inline_limit: ctx.tool_result_inline_limit, - event_emission_mode: ctx.event_emission_mode, - current_mode_id: ctx.current_mode_id, - bound_mode_tool_contract: ctx.bound_mode_tool_contract, - }) - .await; - collected_events.extend(local_events); - raw_results.push((call, result)); - } - - let events = match ctx.event_emission_mode { - #[cfg(test)] - ToolEventEmissionMode::Immediate => { - ctx.events.extend(collected_events); - Vec::new() - }, - ToolEventEmissionMode::Buffered => collected_events, - }; - - // 构建工具结果消息 - let tool_messages: Vec = raw_results - .iter() - .map(|(_, result)| LlmMessage::Tool { - tool_call_id: result.tool_call_id.clone(), - content: result.model_content(), - }) - .collect(); - - Ok(ToolCycleResult { - outcome: ToolCycleOutcome::Completed, - tool_messages, - raw_results, - events, - }) -} - -/// 并发执行多个只读工具调用。 -/// -/// 每个并发 future 有自己的局部事件 Vec，完成后统一合并。 -async fn execute_concurrent_safe( - ctx: &ToolCycleContext<'_>, - safe_calls: Vec, -) -> Result)>> { - let concurrency_limit = ctx.max_concurrency.min(safe_calls.len().max(1)); - - let results = stream::iter(safe_calls) - .map(|call| { - let gateway = ctx.gateway.clone(); - let session_id = ctx.session_id.to_string(); - let working_dir = ctx.working_dir.to_string(); - let turn_id = ctx.turn_id.to_string(); - let agent = ctx.agent.clone(); - let cancel = ctx.cancel.clone(); - let tool_result_inline_limit = ctx.tool_result_inline_limit; - let session_state = Arc::clone(ctx.session_state); - - async move { - let (result, events) = invoke_single_tool(SingleToolInvocation { - gateway: &gateway, - session_state, - tool_call: &call, - session_id: &session_id, - working_dir: &working_dir, - turn_id: &turn_id, - agent: &agent, - cancel: &cancel, - tool_result_inline_limit, - event_emission_mode: ctx.event_emission_mode, - current_mode_id: ctx.current_mode_id, - bound_mode_tool_contract: ctx.bound_mode_tool_contract, - }) - .await; - (call, result, events) - } - }) - .buffer_unordered(concurrency_limit) - .collect() - .await; - - Ok(results) -} - -pub async fn execute_buffered_tool_call( - request: BufferedToolExecutionRequest, -) -> BufferedToolExecution { - let BufferedToolExecutionRequest { - gateway, - session_state, - tool_call, - session_id, - working_dir, - turn_id, - agent, - cancel, - current_mode_id, - bound_mode_tool_contract, - tool_result_inline_limit, - } = request; - let started_at = Instant::now(); - let (result, events) = invoke_single_tool(SingleToolInvocation { - gateway: &gateway, - session_state, - tool_call: &tool_call, - session_id: &session_id, - working_dir: &working_dir, - turn_id: &turn_id, - agent: &agent, - cancel: &cancel, - tool_result_inline_limit, - event_emission_mode: ToolEventEmissionMode::Buffered, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: bound_mode_tool_contract.as_ref(), - }) - .await; - let finished_at = Instant::now(); - BufferedToolExecution { - result, - events, - started_at, - finished_at, - } -} - -/// 底层工具调用：通过 kernel gateway 执行，记录开始/结束事件。 -/// -/// 返回 `(ToolExecutionResult, Vec)`， -/// 返回值中的事件仅用于“即时 durable 发射失败”时的兜底补写。 -async fn invoke_single_tool( - invocation: SingleToolInvocation<'_>, -) -> (ToolExecutionResult, Vec) { - let SingleToolInvocation { - gateway, - session_state, - tool_call, - session_id, - working_dir, - turn_id, - agent, - cancel, - tool_result_inline_limit, - event_emission_mode, - current_mode_id, - bound_mode_tool_contract, - } = invocation; - let buffered_events = Arc::new(Mutex::new(Vec::new())); - let mut fallback_events = Vec::new(); - let start = Instant::now(); - let event_sink = match event_emission_mode { - #[cfg(test)] - ToolEventEmissionMode::Immediate => SessionStateEventSink::new(Arc::clone(&session_state)) - .map(|sink| Arc::new(sink) as Arc) - .ok(), - ToolEventEmissionMode::Buffered => Some(Arc::new(BufferedToolEventSink { - events: Arc::clone(&buffered_events), - }) as Arc), - }; - let (tool_output_tx, tool_output_rx) = mpsc::unbounded_channel::(); - let tool_output_forwarder = - ToolOutputForwarder::spawn(Arc::clone(&session_state), turn_id, agent, tool_output_rx); - - // 发出 ToolCall 开始事件 - let tool_call_event = tool_call_event(turn_id, agent, tool_call); - emit_or_buffer_tool_event( - &event_sink, - &mut fallback_events, - tool_call_event, - "tool start", - ) - .await; - broadcast_tool_start(&session_state, turn_id, agent, tool_call); - - // 构建工具上下文 - let tool_ctx = ToolContext::new( - session_id.to_string().into(), - working_dir.to_string().into(), - cancel.clone(), - ) - .with_turn_id(turn_id.to_string()) - .with_tool_call_id(tool_call.id.clone()) - .with_agent_context(agent.clone()) - .with_resolved_inline_limit(resolve_inline_limit( - &tool_call.name, - gateway - .capabilities() - .capability_spec(&tool_call.name) - .and_then(|spec| spec.max_result_inline_size), - tool_result_inline_limit, - )) - .with_tool_output_sender(tool_output_tx.clone()); - let tool_ctx = tool_ctx.with_current_mode_id(current_mode_id.clone()); - let tool_ctx = if let Some(snapshot) = bound_mode_tool_contract.cloned() { - tool_ctx.with_bound_mode_tool_contract(snapshot) - } else { - tool_ctx - }; - let tool_ctx = if let Some(sink) = &event_sink { - tool_ctx.with_event_sink(Arc::clone(sink)) - } else { - tool_ctx - }; - - // 通过 kernel gateway 执行工具 - let result = gateway.invoke_tool(tool_call, &tool_ctx).await; - let duration_ms = start.elapsed().as_millis() as u64; - // 先释放当前调用持有的上下文，再显式通知 forwarder 排空并退出。 - // 不能把“所有 sender 都 drop”当成工具结束条件，因为 sender 会被多层上下文 clone。 - drop(tool_ctx); - drop(tool_output_tx); - tool_output_forwarder.shutdown().await; - - // 发出 ToolResult 结束事件 - let tool_result_event = tool_result_event( - turn_id, - agent, - &ToolExecutionResult { - duration_ms, - ..result.clone() - }, - ); - emit_or_buffer_tool_event( - &event_sink, - &mut fallback_events, - tool_result_event, - "tool result", - ) - .await; - broadcast_tool_result( - &session_state, - turn_id, - agent, - &ToolExecutionResult { - duration_ms, - ..result.clone() - }, - ); - - let mut events = buffered_events - .lock() - .expect("buffered tool events lock should work") - .clone(); - events.extend(fallback_events); - (result, events) -} - -fn broadcast_tool_output_delta( - session_state: &SessionState, - turn_id: &str, - agent: &AgentEventContext, - delta: ToolOutputDelta, -) { - session_state.broadcast_live_event(astrcode_core::AgentEvent::ToolCallDelta { - turn_id: turn_id.to_string(), - agent: agent.clone(), - tool_call_id: delta.tool_call_id, - tool_name: delta.tool_name, - stream: delta.stream, - delta: delta.delta, - }); -} - -fn broadcast_tool_start( - session_state: &SessionState, - turn_id: &str, - agent: &AgentEventContext, - tool_call: &ToolCallRequest, -) { - session_state.broadcast_live_event(astrcode_core::AgentEvent::ToolCallStart { - turn_id: turn_id.to_string(), - agent: agent.clone(), - tool_call_id: tool_call.id.clone(), - tool_name: tool_call.name.clone(), - input: tool_call.args.clone(), - }); -} - -fn broadcast_tool_result( - session_state: &SessionState, - turn_id: &str, - agent: &AgentEventContext, - result: &ToolExecutionResult, -) { - session_state.broadcast_live_event(astrcode_core::AgentEvent::ToolCallResult { - turn_id: turn_id.to_string(), - agent: agent.clone(), - result: result.clone(), - }); -} - -async fn emit_or_buffer_tool_event( - event_sink: &Option>, - events: &mut Vec, - event: StorageEvent, - label: &str, -) { - if let Some(sink) = event_sink { - if let Err(error) = sink.emit(event.clone()).await { - log::warn!("failed to emit {label} immediately, buffering fallback event: {error}"); - events.push(event); - } - } else { - events.push(event); - } -} - -fn interrupted_result() -> ToolCycleResult { - ToolCycleResult { - outcome: ToolCycleOutcome::Interrupted, - tool_messages: Vec::new(), - raw_results: Vec::new(), - events: Vec::new(), - } -} - -#[cfg(test)] -mod tests { - use std::sync::{Arc, Mutex}; - - use astrcode_core::{ - AgentLifecycleStatus, CapabilityKind, StorageEventPayload, Tool, ToolDefinition, - ToolOutputStream, - }; - use async_trait::async_trait; - use serde_json::{Value, json}; - use tokio::time::{Duration, timeout}; - - use super::*; - use crate::{ - state::sample_spawn_child_ref, - turn::test_support::{test_kernel_with_tool, test_session_state}, - }; - - #[test] - fn tool_cycle_outcome_equality() { - assert_eq!(ToolCycleOutcome::Completed, ToolCycleOutcome::Completed); - assert_eq!(ToolCycleOutcome::Interrupted, ToolCycleOutcome::Interrupted); - assert_ne!(ToolCycleOutcome::Completed, ToolCycleOutcome::Interrupted); - } - - #[derive(Debug, Clone, PartialEq, Eq)] - struct ObservedToolContext { - turn_id: Option, - agent_id: Option, - agent_profile: Option, - } - - #[derive(Debug)] - struct ContextProbeTool { - observed: Arc>>, - } - - #[async_trait] - impl Tool for ContextProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "context_probe".to_string(), - description: "records tool context".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result< - astrcode_core::CapabilitySpec, - astrcode_core::CapabilitySpecBuildError, - > { - astrcode_core::CapabilitySpec::builder("context_probe", CapabilityKind::Tool) - .description("records tool context") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - ctx: &ToolContext, - ) -> Result { - self.observed - .lock() - .expect("observed lock should work") - .push(ObservedToolContext { - turn_id: ctx.turn_id().map(ToString::to_string), - agent_id: ctx - .agent_context() - .agent_id - .clone() - .map(|id| id.to_string()), - agent_profile: ctx.agent_context().agent_profile.clone(), - }); - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "context_probe".to_string(), - ok: true, - output: "ok".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } - } - - #[derive(Debug)] - struct StreamingProbeTool; - - #[async_trait] - impl Tool for StreamingProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "streaming_probe".to_string(), - description: "emits durable and live probe events".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result< - astrcode_core::CapabilitySpec, - astrcode_core::CapabilitySpecBuildError, - > { - astrcode_core::CapabilitySpec::builder("streaming_probe", CapabilityKind::Tool) - .description("emits durable and live probe events") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - ctx: &ToolContext, - ) -> Result { - let turn_id = ctx - .turn_id() - .expect("streaming probe should receive turn id") - .to_string(); - let sink = ctx - .event_sink() - .expect("streaming probe should receive tool event sink"); - sink.emit(crate::turn::events::tool_call_delta_event( - &turn_id, - ctx.agent_context(), - tool_call_id.clone(), - "streaming_probe".to_string(), - ToolOutputStream::Stdout, - "durable-delta".to_string(), - )) - .await?; - assert!( - ctx.emit_stdout(tool_call_id.clone(), "streaming_probe", "live-stdout"), - "streaming probe should be able to emit live stdout" - ); - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "streaming_probe".to_string(), - ok: true, - output: "done".to_string(), - error: None, - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } - } - - #[derive(Debug)] - struct StreamingStderrProbeTool; - - #[async_trait] - impl Tool for StreamingStderrProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "streaming_stderr_probe".to_string(), - description: "emits stderr probe events".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result< - astrcode_core::CapabilitySpec, - astrcode_core::CapabilitySpecBuildError, - > { - astrcode_core::CapabilitySpec::builder("streaming_stderr_probe", CapabilityKind::Tool) - .description("emits stderr probe events") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - ctx: &ToolContext, - ) -> Result { - let turn_id = ctx - .turn_id() - .expect("stderr probe should receive turn id") - .to_string(); - let sink = ctx - .event_sink() - .expect("stderr probe should receive tool event sink"); - sink.emit(crate::turn::events::tool_call_delta_event( - &turn_id, - ctx.agent_context(), - tool_call_id.clone(), - "streaming_stderr_probe".to_string(), - ToolOutputStream::Stderr, - "durable-stderr".to_string(), - )) - .await?; - assert!( - ctx.emit_stderr( - tool_call_id.clone(), - "streaming_stderr_probe", - "live-stderr" - ), - "stderr probe should be able to emit live stderr" - ); - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "streaming_stderr_probe".to_string(), - ok: false, - output: String::new(), - error: Some("stderr failure".to_string()), - metadata: None, - continuation: None, - duration_ms: 0, - truncated: false, - }) - } - } - - #[derive(Debug)] - struct ChildRefProbeTool; - - #[async_trait] - impl Tool for ChildRefProbeTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "child_ref_probe".to_string(), - description: "returns a typed child ref".to_string(), - parameters: json!({"type": "object"}), - } - } - - fn capability_spec( - &self, - ) -> std::result::Result< - astrcode_core::CapabilitySpec, - astrcode_core::CapabilitySpecBuildError, - > { - astrcode_core::CapabilitySpec::builder("child_ref_probe", CapabilityKind::Tool) - .description("returns a typed child ref") - .schema(json!({"type": "object"}), json!({"type": "string"})) - .build() - } - - async fn execute( - &self, - tool_call_id: String, - _input: Value, - _ctx: &ToolContext, - ) -> Result { - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "child_ref_probe".to_string(), - ok: true, - output: "spawn accepted".to_string(), - error: None, - metadata: Some(json!({ "schema": "subRunResult" })), - continuation: Some(astrcode_core::ExecutionContinuation::child_agent( - sample_child_ref(), - )), - duration_ms: 0, - truncated: false, - }) - } - } - - fn sample_child_ref() -> astrcode_core::ChildAgentRef { - sample_spawn_child_ref(AgentLifecycleStatus::Running) - } - - #[tokio::test] - async fn invoke_single_tool_preserves_turn_and_agent_context() { - let observed = Arc::new(Mutex::new(Vec::new())); - let kernel = test_kernel_with_tool( - Arc::new(ContextProbeTool { - observed: Arc::clone(&observed), - }), - 8192, - ); - let tool_call = ToolCallRequest { - id: "call-1".to_string(), - name: "context_probe".to_string(), - args: json!({}), - }; - let agent = AgentEventContext::root_execution("root-agent:session-1", "default"); - let session_state = test_session_state(); - - let cancel = CancelToken::new(); - let current_mode_id = astrcode_core::ModeId::default(); - let (result, _) = invoke_single_tool(SingleToolInvocation { - gateway: kernel.gateway(), - session_state, - tool_call: &tool_call, - session_id: "session-1", - working_dir: ".", - turn_id: "turn-1", - agent: &agent, - cancel: &cancel, - tool_result_inline_limit: 32 * 1024, - event_emission_mode: ToolEventEmissionMode::Immediate, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: None, - }) - .await; - - assert!(result.ok, "tool invocation should succeed: {result:?}"); - let observed = observed.lock().expect("observed lock should work"); - assert_eq!( - observed.as_slice(), - &[ObservedToolContext { - turn_id: Some("turn-1".to_string()), - agent_id: Some("root-agent:session-1".to_string()), - agent_profile: Some("default".to_string()), - }] - ); - } - - #[tokio::test] - async fn invoke_single_tool_emits_structured_and_live_events_immediately() { - let kernel = test_kernel_with_tool(Arc::new(StreamingProbeTool), 8192); - let tool_call = ToolCallRequest { - id: "call-live".to_string(), - name: "streaming_probe".to_string(), - args: json!({}), - }; - let agent = AgentEventContext::root_execution("root-agent:session-1", "default"); - let session_state = test_session_state(); - let mut live_receiver = session_state.subscribe_live(); - - let cancel = CancelToken::new(); - let current_mode_id = astrcode_core::ModeId::default(); - let (result, fallback_events) = invoke_single_tool(SingleToolInvocation { - gateway: kernel.gateway(), - session_state: Arc::clone(&session_state), - tool_call: &tool_call, - session_id: "session-1", - working_dir: ".", - turn_id: "turn-live", - agent: &agent, - cancel: &cancel, - tool_result_inline_limit: 32 * 1024, - event_emission_mode: ToolEventEmissionMode::Immediate, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: None, - }) - .await; - - assert!(result.ok, "tool invocation should succeed: {result:?}"); - assert!( - fallback_events.is_empty(), - "immediate event emission should avoid fallback buffering: {fallback_events:?}" - ); - - let stored = session_state - .snapshot_recent_stored_events() - .expect("snapshot recent stored events should work"); - assert!( - stored.iter().any(|event| matches!( - &event.event.payload, - StorageEventPayload::ToolCall { - tool_call_id, - tool_name, - .. - } if tool_call_id == "call-live" && tool_name == "streaming_probe" - )), - "tool start should be durably recorded immediately" - ); - assert!( - stored.iter().any(|event| matches!( - &event.event.payload, - StorageEventPayload::ToolCallDelta { - tool_call_id, - tool_name, - delta, - .. - } if tool_call_id == "call-live" - && tool_name == "streaming_probe" - && delta == "durable-delta" - )), - "tool internal durable delta should flow through event sink" - ); - assert!( - stored.iter().any(|event| matches!( - &event.event.payload, - StorageEventPayload::ToolResult { - tool_call_id, - tool_name, - output, - .. - } if tool_call_id == "call-live" - && tool_name == "streaming_probe" - && output == "done" - )), - "tool result should be durably recorded immediately" - ); - - let live_start = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool start in time") - .expect("live receiver should stay open"); - let live_delta = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get stdout delta in time") - .expect("live receiver should stay open"); - let live_result = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool result in time") - .expect("live receiver should stay open"); - assert!( - matches!( - live_start, - astrcode_core::AgentEvent::ToolCallStart { - turn_id, - tool_call_id, - tool_name, - .. - } if turn_id == "turn-live" - && tool_call_id == "call-live" - && tool_name == "streaming_probe" - ), - "tool start should go through the live channel immediately" - ); - assert!( - matches!( - live_delta, - astrcode_core::AgentEvent::ToolCallDelta { - turn_id, - tool_call_id, - tool_name, - stream: ToolOutputStream::Stdout, - delta, - .. - } if turn_id == "turn-live" - && tool_call_id == "call-live" - && tool_name == "streaming_probe" - && delta == "live-stdout" - ), - "stdout delta should go through the live channel immediately" - ); - assert!( - matches!( - live_result, - astrcode_core::AgentEvent::ToolCallResult { turn_id, result, .. } - if turn_id == "turn-live" - && result.tool_call_id == "call-live" - && result.tool_name == "streaming_probe" - && result.output == "done" - ), - "tool result should go through the live channel immediately" - ); - } - - #[tokio::test] - async fn invoke_single_tool_buffers_structured_events_when_requested() { - let kernel = test_kernel_with_tool(Arc::new(StreamingProbeTool), 8192); - let tool_call = ToolCallRequest { - id: "call-buffered".to_string(), - name: "streaming_probe".to_string(), - args: json!({}), - }; - let agent = AgentEventContext::root_execution("root-agent:session-1", "default"); - let session_state = test_session_state(); - let mut live_receiver = session_state.subscribe_live(); - - let cancel = CancelToken::new(); - let current_mode_id = astrcode_core::ModeId::default(); - let (result, buffered_events) = invoke_single_tool(SingleToolInvocation { - gateway: kernel.gateway(), - session_state: Arc::clone(&session_state), - tool_call: &tool_call, - session_id: "session-1", - working_dir: ".", - turn_id: "turn-buffered", - agent: &agent, - cancel: &cancel, - tool_result_inline_limit: 32 * 1024, - event_emission_mode: ToolEventEmissionMode::Buffered, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: None, - }) - .await; - - assert!(result.ok, "tool invocation should succeed: {result:?}"); - assert!( - buffered_events.iter().any(|event| matches!( - &event.payload, - StorageEventPayload::ToolCall { - tool_call_id, - tool_name, - .. - } if tool_call_id == "call-buffered" && tool_name == "streaming_probe" - )), - "buffered mode should keep tool start in local event buffer" - ); - assert!( - buffered_events.iter().any(|event| matches!( - &event.payload, - StorageEventPayload::ToolCallDelta { - tool_call_id, - tool_name, - delta, - .. - } if tool_call_id == "call-buffered" - && tool_name == "streaming_probe" - && delta == "durable-delta" - )), - "buffered mode should preserve tool-emitted durable deltas" - ); - assert!( - session_state - .snapshot_recent_stored_events() - .expect("snapshot recent stored events should work") - .is_empty(), - "buffered mode should not immediately append durable events" - ); - - let live_start = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool start in time") - .expect("live receiver should stay open"); - let live_delta = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get stdout delta in time") - .expect("live receiver should stay open"); - let live_result = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool result in time") - .expect("live receiver should stay open"); - assert!( - matches!( - live_start, - astrcode_core::AgentEvent::ToolCallStart { - turn_id, - tool_call_id, - tool_name, - .. - } if turn_id == "turn-buffered" - && tool_call_id == "call-buffered" - && tool_name == "streaming_probe" - ), - "buffered mode should still broadcast tool start live" - ); - assert!( - matches!( - live_delta, - astrcode_core::AgentEvent::ToolCallDelta { - turn_id, - tool_call_id, - tool_name, - stream: ToolOutputStream::Stdout, - delta, - .. - } if turn_id == "turn-buffered" - && tool_call_id == "call-buffered" - && tool_name == "streaming_probe" - && delta == "live-stdout" - ), - "buffered mode should keep live stdout forwarding" - ); - assert!( - matches!( - live_result, - astrcode_core::AgentEvent::ToolCallResult { turn_id, result, .. } - if turn_id == "turn-buffered" - && result.tool_call_id == "call-buffered" - && result.tool_name == "streaming_probe" - && result.output == "done" - ), - "buffered mode should still broadcast tool result live" - ); - } - - #[tokio::test] - async fn invoke_single_tool_persists_child_continuation_in_tool_result() { - let kernel = test_kernel_with_tool(Arc::new(ChildRefProbeTool), 8192); - let tool_call = ToolCallRequest { - id: "call-child-ref".to_string(), - name: "child_ref_probe".to_string(), - args: json!({}), - }; - let agent = AgentEventContext::root_execution("root-agent:session-1", "default"); - let session_state = test_session_state(); - - let cancel = CancelToken::new(); - let current_mode_id = astrcode_core::ModeId::default(); - let (result, fallback_events) = invoke_single_tool(SingleToolInvocation { - gateway: kernel.gateway(), - session_state: Arc::clone(&session_state), - tool_call: &tool_call, - session_id: "session-parent-1", - working_dir: ".", - turn_id: "turn-child-ref", - agent: &agent, - cancel: &cancel, - tool_result_inline_limit: 32 * 1024, - event_emission_mode: ToolEventEmissionMode::Immediate, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: None, - }) - .await; - - assert!(result.ok, "tool invocation should succeed: {result:?}"); - assert!( - fallback_events.is_empty(), - "immediate mode should not fall back to buffered events" - ); - assert_eq!( - result - .continuation() - .and_then(astrcode_core::ExecutionContinuation::child_agent_ref), - Some(&sample_child_ref()) - ); - - let stored = session_state - .snapshot_recent_stored_events() - .expect("snapshot recent stored events should work"); - assert!(stored.iter().any(|event| matches!( - &event.event.payload, - StorageEventPayload::ToolResult { - tool_call_id, - tool_name, - continuation: Some(astrcode_core::ExecutionContinuation::ChildAgent { child_ref }), - .. - } if tool_call_id == "call-child-ref" - && tool_name == "child_ref_probe" - && child_ref == &sample_child_ref() - ))); - } - - #[tokio::test] - async fn invoke_single_tool_forwards_stderr_to_durable_and_live_channels() { - let kernel = test_kernel_with_tool(Arc::new(StreamingStderrProbeTool), 8192); - let tool_call = ToolCallRequest { - id: "call-stderr".to_string(), - name: "streaming_stderr_probe".to_string(), - args: json!({}), - }; - let agent = AgentEventContext::root_execution("root-agent:session-1", "default"); - let session_state = test_session_state(); - let mut live_receiver = session_state.subscribe_live(); - - let cancel = CancelToken::new(); - let current_mode_id = astrcode_core::ModeId::default(); - let (result, fallback_events) = invoke_single_tool(SingleToolInvocation { - gateway: kernel.gateway(), - session_state: Arc::clone(&session_state), - tool_call: &tool_call, - session_id: "session-1", - working_dir: ".", - turn_id: "turn-stderr", - agent: &agent, - cancel: &cancel, - tool_result_inline_limit: 32 * 1024, - event_emission_mode: ToolEventEmissionMode::Immediate, - current_mode_id: ¤t_mode_id, - bound_mode_tool_contract: None, - }) - .await; - - assert!( - !result.ok && result.error.as_deref() == Some("stderr failure"), - "stderr probe should surface failure result: {result:?}" - ); - assert!( - fallback_events.is_empty(), - "immediate stderr event emission should avoid fallback buffering: {fallback_events:?}" - ); - - let stored = session_state - .snapshot_recent_stored_events() - .expect("snapshot recent stored events should work"); - assert!( - stored.iter().any(|event| matches!( - &event.event.payload, - StorageEventPayload::ToolCallDelta { - tool_call_id, - tool_name, - stream: ToolOutputStream::Stderr, - delta, - .. - } if tool_call_id == "call-stderr" - && tool_name == "streaming_stderr_probe" - && delta == "durable-stderr" - )), - "stderr durable delta should be recorded immediately" - ); - - let live_start = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool start in time") - .expect("live receiver should stay open"); - let live_delta = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get stderr delta in time") - .expect("live receiver should stay open"); - let live_result = timeout(Duration::from_secs(1), live_receiver.recv()) - .await - .expect("live receiver should get tool result in time") - .expect("live receiver should stay open"); - - assert!(matches!( - live_start, - astrcode_core::AgentEvent::ToolCallStart { - turn_id, - tool_call_id, - tool_name, - .. - } if turn_id == "turn-stderr" - && tool_call_id == "call-stderr" - && tool_name == "streaming_stderr_probe" - )); - assert!(matches!( - live_delta, - astrcode_core::AgentEvent::ToolCallDelta { - turn_id, - tool_call_id, - tool_name, - stream: ToolOutputStream::Stderr, - delta, - .. - } if turn_id == "turn-stderr" - && tool_call_id == "call-stderr" - && tool_name == "streaming_stderr_probe" - && delta == "live-stderr" - )); - assert!(matches!( - live_result, - astrcode_core::AgentEvent::ToolCallResult { turn_id, result, .. } - if turn_id == "turn-stderr" - && result.tool_call_id == "call-stderr" - && result.tool_name == "streaming_stderr_probe" - && result.error.as_deref() == Some("stderr failure") - )); - } -} diff --git a/crates/session-runtime/src/turn/watcher.rs b/crates/session-runtime/src/turn/watcher.rs deleted file mode 100644 index 814b5bdd..00000000 --- a/crates/session-runtime/src/turn/watcher.rs +++ /dev/null @@ -1,482 +0,0 @@ -use astrcode_core::{ - AgentEvent, Phase, Result, SessionEventRecord, SessionId, StoredEvent, TurnProjectionSnapshot, -}; -use tokio::sync::broadcast::error::RecvError; - -use crate::{ - ProjectedTurnOutcome, SessionRuntime, SessionState, TurnTerminalSnapshot, - query::turn::project_turn_outcome, - turn::projector::{has_terminal_projection, project_turn_projection}, -}; - -pub(crate) async fn wait_for_turn_terminal_snapshot( - runtime: &SessionRuntime, - session_id: &str, - turn_id: &str, -) -> Result { - let session_id = SessionId::from(crate::state::normalize_session_id(session_id)); - let actor = runtime.ensure_loaded_session(&session_id).await?; - let state = actor.state(); - let mut receiver = state.broadcaster.subscribe(); - if let Some(snapshot) = - try_turn_terminal_snapshot(runtime, &session_id, state.as_ref(), turn_id, true).await? - { - return Ok(snapshot); - } - loop { - match receiver.recv().await { - Ok(record) => { - if !record_targets_turn(&record, turn_id) { - continue; - } - if let Some(snapshot) = - try_turn_terminal_snapshot_from_recent(state.as_ref(), turn_id)? - { - return Ok(snapshot); - } - }, - Err(RecvError::Lagged(_)) => { - if let Some(snapshot) = - try_turn_terminal_snapshot(runtime, &session_id, state.as_ref(), turn_id, true) - .await? - { - return Ok(snapshot); - } - }, - Err(RecvError::Closed) => { - if let Some(snapshot) = - try_turn_terminal_snapshot(runtime, &session_id, state.as_ref(), turn_id, true) - .await? - { - return Ok(snapshot); - } - return Err(astrcode_core::AstrError::Internal(format!( - "session '{}' broadcaster closed before turn '{}' reached a terminal snapshot", - session_id, turn_id - ))); - }, - } - } -} - -pub(crate) async fn wait_and_project_turn_outcome( - runtime: &SessionRuntime, - session_id: &str, - turn_id: &str, -) -> Result { - let terminal = wait_for_turn_terminal_snapshot(runtime, session_id, turn_id).await?; - Ok(project_turn_outcome( - terminal.phase, - terminal.projection.as_ref(), - &terminal.events, - )) -} - -pub(crate) async fn try_turn_terminal_snapshot( - runtime: &SessionRuntime, - session_id: &SessionId, - state: &SessionState, - turn_id: &str, - allow_durable_fallback: bool, -) -> Result> { - if let Some(snapshot) = try_turn_terminal_snapshot_from_recent(state, turn_id)? { - return Ok(Some(snapshot)); - } - - if !allow_durable_fallback { - return Ok(None); - } - - runtime.ensure_session_exists(session_id).await?; - let events = turn_events(runtime.event_store.replay(session_id).await?, turn_id); - let phase = state.current_phase()?; - let projection = state - .turn_projection(turn_id)? - .or_else(|| project_turn_projection(&events)); - if turn_snapshot_is_terminal(phase, projection.as_ref(), &events) { - return Ok(Some(TurnTerminalSnapshot { - phase, - projection, - events, - })); - } - - Ok(None) -} - -pub(crate) fn try_turn_terminal_snapshot_from_recent( - state: &SessionState, - turn_id: &str, -) -> Result> { - let events = turn_events(state.snapshot_recent_stored_events()?, turn_id); - let phase = state.current_phase()?; - let projection = state - .turn_projection(turn_id)? - .or_else(|| project_turn_projection(&events)); - if turn_snapshot_is_terminal(phase, projection.as_ref(), &events) { - return Ok(Some(TurnTerminalSnapshot { - phase, - projection, - events, - })); - } - - Ok(None) -} - -pub(crate) fn turn_events(stored_events: Vec, turn_id: &str) -> Vec { - stored_events - .into_iter() - .filter(|stored| stored.event.turn_id() == Some(turn_id)) - .collect() -} - -pub(crate) fn turn_snapshot_is_terminal( - phase: Phase, - projection: Option<&TurnProjectionSnapshot>, - events: &[StoredEvent], -) -> bool { - has_terminal_projection(projection) - || (!events.is_empty() && matches!(phase, Phase::Interrupted)) -} - -pub(crate) fn record_targets_turn(record: &SessionEventRecord, turn_id: &str) -> bool { - match &record.event { - AgentEvent::UserMessage { turn_id: id, .. } - | AgentEvent::ModelDelta { turn_id: id, .. } - | AgentEvent::ThinkingDelta { turn_id: id, .. } - | AgentEvent::AssistantMessage { turn_id: id, .. } - | AgentEvent::ToolCallStart { turn_id: id, .. } - | AgentEvent::ToolCallDelta { turn_id: id, .. } - | AgentEvent::ToolCallResult { turn_id: id, .. } - | AgentEvent::TurnDone { turn_id: id, .. } => id == turn_id, - AgentEvent::PhaseChanged { - turn_id: Some(id), .. - } - | AgentEvent::PromptMetrics { - turn_id: Some(id), .. - } - | AgentEvent::CompactApplied { - turn_id: Some(id), .. - } - | AgentEvent::SubRunStarted { - turn_id: Some(id), .. - } - | AgentEvent::SubRunFinished { - turn_id: Some(id), .. - } - | AgentEvent::ChildSessionNotification { - turn_id: Some(id), .. - } - | AgentEvent::AgentInputQueued { - turn_id: Some(id), .. - } - | AgentEvent::AgentInputBatchStarted { - turn_id: Some(id), .. - } - | AgentEvent::AgentInputBatchAcked { - turn_id: Some(id), .. - } - | AgentEvent::AgentInputDiscarded { - turn_id: Some(id), .. - } - | AgentEvent::Error { - turn_id: Some(id), .. - } => id == turn_id, - _ => false, - } -} - -#[cfg(test)] -mod tests { - use std::{ - path::Path, - sync::{ - Arc, Mutex, - atomic::{AtomicU64, AtomicUsize, Ordering}, - }, - }; - - use astrcode_core::{ - AgentEventContext, DeleteProjectResult, EventStore, EventTranslator, Phase, Result, - SessionId, SessionMeta, SessionTurnAcquireResult, StorageEvent, StorageEventPayload, - StoredEvent, TurnProjectionSnapshot, - }; - use async_trait::async_trait; - use tokio::time::{Duration, timeout}; - - use super::{turn_snapshot_is_terminal, wait_for_turn_terminal_snapshot}; - use crate::{ - state::append_and_broadcast, - turn::test_support::{StubEventStore, test_runtime}, - }; - - #[test] - fn turn_snapshot_is_terminal_accepts_replayed_terminal_projection() { - let projection = TurnProjectionSnapshot { - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - last_error: None, - }; - - assert!(turn_snapshot_is_terminal( - Phase::Idle, - Some(&projection), - &[] - )); - } - - #[test] - fn turn_snapshot_is_terminal_accepts_interrupted_phase_with_turn_history() { - let events = vec![StoredEvent { - storage_seq: 1, - event: StorageEvent { - turn_id: Some("turn-1".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::Error { - message: "interrupted".to_string(), - timestamp: Some(chrono::Utc::now()), - }, - }, - }]; - - assert!(turn_snapshot_is_terminal(Phase::Interrupted, None, &events)); - } - - #[tokio::test] - async fn wait_for_turn_terminal_snapshot_wakes_on_broadcast_event() { - let runtime = test_runtime(Arc::new(StubEventStore::default())); - let session = runtime - .create_session(".") - .await - .expect("session should be created"); - let session_id = session.session_id.clone(); - let turn_id = "turn-1".to_string(); - - let waiter = { - let runtime = &runtime; - let session_id = session_id.clone(); - let turn_id = turn_id.clone(); - async move { wait_for_turn_terminal_snapshot(runtime, &session_id, &turn_id).await } - }; - - let state = runtime - .get_session_state(&session_id.clone().into()) - .await - .expect("state should load"); - tokio::spawn(async move { - tokio::time::sleep(Duration::from_millis(10)).await; - let mut translator = EventTranslator::new(Phase::Idle); - append_and_broadcast( - state.as_ref(), - &StorageEvent { - turn_id: Some(turn_id), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: Some("completed".to_string()), - }, - }, - &mut translator, - ) - .await - .expect("turn done should append"); - }); - - let snapshot = timeout(Duration::from_secs(1), waiter) - .await - .expect("wait should complete") - .expect("snapshot should load"); - - assert!(turn_snapshot_is_terminal( - snapshot.phase, - snapshot.projection.as_ref(), - &snapshot.events, - )); - assert_eq!(snapshot.events.len(), 1); - assert_eq!(snapshot.events[0].event.turn_id(), Some("turn-1")); - } - - #[tokio::test] - async fn wait_for_turn_terminal_snapshot_replays_only_once_while_waiting() { - let event_store = Arc::new(CountingEventStore::default()); - let runtime = test_runtime(event_store.clone()); - let session = runtime - .create_session(".") - .await - .expect("session should be created"); - let session_id = session.session_id.clone(); - let turn_id = "turn-1".to_string(); - - let waiter = { - let runtime = &runtime; - let session_id = session_id.clone(); - let turn_id = turn_id.clone(); - async move { wait_for_turn_terminal_snapshot(runtime, &session_id, &turn_id).await } - }; - - let state = runtime - .get_session_state(&session_id.clone().into()) - .await - .expect("state should load"); - tokio::spawn(async move { - tokio::time::sleep(Duration::from_millis(75)).await; - let mut translator = EventTranslator::new(Phase::Idle); - append_and_broadcast( - state.as_ref(), - &StorageEvent { - turn_id: Some(turn_id), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: Some("completed".to_string()), - }, - }, - &mut translator, - ) - .await - .expect("turn done should append"); - }); - - timeout(Duration::from_secs(1), waiter) - .await - .expect("wait should complete") - .expect("snapshot should load"); - - assert_eq!( - event_store.replay_count(), - 1, - "live wait should not repeatedly rescan durable history" - ); - } - - #[tokio::test] - async fn wait_for_turn_terminal_snapshot_projects_typed_terminal_kind_history() { - let runtime = test_runtime(Arc::new(StubEventStore::default())); - let session = runtime - .create_session(".") - .await - .expect("session should be created"); - let session_id = session.session_id.clone(); - let state = runtime - .get_session_state(&session_id.clone().into()) - .await - .expect("state should load"); - - let mut translator = EventTranslator::new(Phase::Idle); - append_and_broadcast( - state.as_ref(), - &StorageEvent { - turn_id: Some("turn-terminal".to_string()), - agent: AgentEventContext::default(), - payload: StorageEventPayload::TurnDone { - timestamp: chrono::Utc::now(), - terminal_kind: Some(astrcode_core::TurnTerminalKind::Completed), - reason: None, - }, - }, - &mut translator, - ) - .await - .expect("turn done should append"); - - let snapshot = wait_for_turn_terminal_snapshot(&runtime, &session_id, "turn-terminal") - .await - .expect("terminal snapshot should load"); - let outcome = runtime - .project_turn_outcome(&session_id, "turn-terminal") - .await - .expect("turn outcome should project"); - - assert_eq!( - snapshot - .projection - .as_ref() - .and_then(|projection| projection.terminal_kind.clone()), - Some(astrcode_core::TurnTerminalKind::Completed) - ); - assert_eq!(outcome.outcome, astrcode_core::AgentTurnOutcome::Completed); - } - - #[derive(Debug, Default)] - struct CountingEventStore { - events: Mutex>, - next_seq: AtomicU64, - replay_count: AtomicUsize, - } - - impl CountingEventStore { - fn replay_count(&self) -> usize { - self.replay_count.load(Ordering::SeqCst) - } - } - - struct CountingTurnLease; - - impl astrcode_core::SessionTurnLease for CountingTurnLease {} - - #[async_trait] - impl EventStore for CountingEventStore { - async fn ensure_session(&self, _session_id: &SessionId, _working_dir: &Path) -> Result<()> { - Ok(()) - } - - async fn append( - &self, - _session_id: &SessionId, - event: &StorageEvent, - ) -> Result { - let stored = StoredEvent { - storage_seq: self.next_seq.fetch_add(1, Ordering::SeqCst) + 1, - event: event.clone(), - }; - self.events - .lock() - .expect("counting event store should lock") - .push(stored.clone()); - Ok(stored) - } - - async fn replay(&self, _session_id: &SessionId) -> Result> { - self.replay_count.fetch_add(1, Ordering::SeqCst); - Ok(self - .events - .lock() - .expect("counting event store should lock") - .clone()) - } - - async fn try_acquire_turn( - &self, - _session_id: &SessionId, - _turn_id: &str, - ) -> Result { - Ok(SessionTurnAcquireResult::Acquired(Box::new( - CountingTurnLease, - ))) - } - - async fn list_sessions(&self) -> Result> { - Ok(vec![]) - } - - async fn list_session_metas(&self) -> Result> { - Ok(vec![]) - } - - async fn delete_session(&self, _session_id: &SessionId) -> Result<()> { - Ok(()) - } - - async fn delete_sessions_by_working_dir( - &self, - _working_dir: &str, - ) -> Result { - Ok(DeleteProjectResult { - success_count: 0, - failed_session_ids: Vec::new(), - }) - } - } -} diff --git "a/docs/ideas/\346\212\275\347\246\273.md" "b/docs/ideas/\346\212\275\347\246\273.md" new file mode 100644 index 00000000..8bf23beb --- /dev/null +++ "b/docs/ideas/\346\212\275\347\246\273.md" @@ -0,0 +1,2 @@ +1. hooks生命周期加入 +2. \ No newline at end of file diff --git a/examples/example-plugin/Cargo.toml b/examples/example-plugin/Cargo.toml deleted file mode 100644 index 2034de1f..00000000 --- a/examples/example-plugin/Cargo.toml +++ /dev/null @@ -1,15 +0,0 @@ -[package] -name = "astrcode-example-plugin" -version = "0.1.0" -edition.workspace = true -license-file.workspace = true -authors.workspace = true - -[dependencies] -astrcode-core = { path = "../../crates/core" } -astrcode-plugin = { path = "../../crates/plugin" } -astrcode-protocol = { path = "../../crates/protocol" } -astrcode-sdk = { path = "../../crates/sdk" } -async-trait.workspace = true -serde_json.workspace = true -tokio.workspace = true diff --git a/examples/example-plugin/src/main.rs b/examples/example-plugin/src/main.rs deleted file mode 100644 index 8b7af1eb..00000000 --- a/examples/example-plugin/src/main.rs +++ /dev/null @@ -1,291 +0,0 @@ -use std::{ - fs, - path::{Path, PathBuf}, - pin::Pin, - sync::Arc, -}; - -use astrcode_core::{ - AstrError, CancelToken, CapabilityKind, CapabilitySpec, InvocationMode, Result, SideEffect, - Stability, -}; -use astrcode_plugin::{CapabilityHandler, CapabilityRouter, EventEmitter, Worker}; -use astrcode_protocol::plugin::{InvocationContext, PeerDescriptor, PeerRole}; -use astrcode_sdk::{ - DeserializeOwned, PluginContext, Serialize, StreamWriter, ToolHandler, ToolRegistration, - ToolResult, -}; -use async_trait::async_trait; -use serde_json::{Value, json}; - -struct RegisteredToolAdapter { - registration: ToolRegistration, -} - -impl RegisteredToolAdapter { - fn new(handler: H) -> Self - where - H: ToolHandler + 'static, - I: DeserializeOwned + Send + 'static, - O: Serialize + Send + 'static, - { - Self { - registration: ToolRegistration::new(handler), - } - } -} - -#[async_trait] -impl CapabilityHandler for RegisteredToolAdapter { - fn capability_spec(&self) -> CapabilitySpec { - self.registration.descriptor().clone() - } - - async fn invoke( - &self, - input: Value, - context: InvocationContext, - events: EventEmitter, - cancel: CancelToken, - ) -> Result { - let plugin_context = PluginContext::from(context); - let stream = StreamWriter::default(); - let tool_name = self.registration.descriptor().name.to_string(); - if cancel.is_cancelled() { - return Err(AstrError::Cancelled); - } - let output = self - .registration - .handler() - .execute_value(input, plugin_context, stream.clone()) - .await - .map_err(|error| AstrError::ToolError { - name: tool_name.clone(), - reason: error.to_string(), - })?; - for chunk in stream.records().map_err(|error| AstrError::ToolError { - name: tool_name.clone(), - reason: error.to_string(), - })? { - events.delta(chunk.event, chunk.payload).await?; - } - if cancel.is_cancelled() { - return Err(AstrError::Cancelled); - } - Ok(output) - } -} - -#[derive(Default)] -struct WorkspaceSummaryTool; - -impl ToolHandler for WorkspaceSummaryTool { - fn descriptor(&self) -> CapabilitySpec { - CapabilitySpec::builder("workspace.summary", CapabilityKind::tool()) - .description("Summarize the active coding workspace") - .schema( - json!({ - "type": "object", - "properties": {} - }), - json!({ - "type": "object", - "properties": { - "workspaceRoot": { "type": "string" }, - "entries": { "type": "array" }, - "markerFiles": { "type": "array" } - } - }), - ) - .invocation_mode(InvocationMode::Unary) - .concurrency_safe(true) - .profiles(["coding"]) - .tags(["example", "workspace"]) - .side_effect(SideEffect::None) - .stability(Stability::Stable) - .build() - .expect("workspace summary capability spec should build") - } - - fn execute( - &self, - _input: Value, - context: PluginContext, - stream: StreamWriter, - ) -> Pin> + Send>> { - Box::pin(async move { - let root = workspace_root(&context)?; - stream.diagnostic("info", format!("Scanning workspace {}", root.display()))?; - - let mut entries = fs::read_dir(&root)? - .filter_map(|entry| entry.ok()) - .map(|entry| { - let kind = entry - .file_type() - .ok() - .map(|kind| if kind.is_dir() { "dir" } else { "file" }) - .unwrap_or("unknown"); - json!({ - "name": entry.file_name().to_string_lossy().into_owned(), - "kind": kind - }) - }) - .collect::>(); - entries.sort_by(|left, right| { - left["name"] - .as_str() - .unwrap_or_default() - .cmp(right["name"].as_str().unwrap_or_default()) - }); - - let marker_files = [ - "Cargo.toml", - "package.json", - "pnpm-workspace.yaml", - "pyproject.toml", - ".git", - ] - .into_iter() - .filter(|candidate| root.join(candidate).exists()) - .collect::>(); - - Ok(json!({ - "workspaceRoot": root.to_string_lossy().into_owned(), - "entryCount": entries.len(), - "entries": entries, - "markerFiles": marker_files - })) - }) - } -} - -#[derive(Default)] -struct FilePreviewTool; - -impl ToolHandler for FilePreviewTool { - fn descriptor(&self) -> CapabilitySpec { - CapabilitySpec::builder("file.preview", CapabilityKind::tool()) - .description("Read a short preview from a file inside the active workspace") - .schema( - json!({ - "type": "object", - "required": ["path"], - "properties": { - "path": { "type": "string" }, - "maxLines": { "type": "integer", "minimum": 1, "maximum": 200 } - } - }), - json!({ - "type": "object", - "properties": { - "path": { "type": "string" }, - "preview": { "type": "string" }, - "truncated": { "type": "boolean" } - } - }), - ) - .invocation_mode(InvocationMode::Unary) - .concurrency_safe(true) - .profiles(["coding"]) - .tags(["example", "file"]) - .side_effect(SideEffect::None) - .stability(Stability::Stable) - .build() - .expect("file preview capability spec should build") - } - - fn execute( - self: &FilePreviewTool, - input: Value, - context: PluginContext, - stream: StreamWriter, - ) -> Pin> + Send>> { - Box::pin(async move { - let root = workspace_root(&context)?; - let path = input - .get("path") - .and_then(Value::as_str) - .ok_or_else(|| "missing required field 'path'".to_string())?; - let max_lines = input - .get("maxLines") - .and_then(Value::as_u64) - .unwrap_or(40) - .min(200) as usize; - - let resolved = resolve_workspace_path(&root, path)?; - stream.message_delta(format!("Previewing {}", resolved.display()))?; - - let content = fs::read_to_string(&resolved)?; - let lines = content.lines().collect::>(); - let truncated = lines.len() > max_lines; - let preview = lines - .into_iter() - .take(max_lines) - .collect::>() - .join("\n"); - - Ok(json!({ - "path": resolved.strip_prefix(&root).unwrap_or(&resolved).to_string_lossy().into_owned(), - "preview": preview, - "truncated": truncated - })) - }) - } -} - -fn workspace_root(context: &PluginContext) -> ToolResult { - if let Some(coding) = context.coding_profile() { - if let Some(path) = coding.working_dir.or(coding.repo_root).map(PathBuf::from) { - return Ok(path); - } - } - - if let Some(workspace) = &context.workspace { - if let Some(path) = workspace - .working_dir - .as_ref() - .or(workspace.repo_root.as_ref()) - .map(PathBuf::from) - { - return Ok(path); - } - } - - Err("workspace path is missing from coding context".into()) -} - -fn resolve_workspace_path(root: &Path, candidate: &str) -> ToolResult { - let joined = if Path::new(candidate).is_absolute() { - PathBuf::from(candidate) - } else { - root.join(candidate) - }; - - let canonical_root = root.canonicalize()?; - let canonical_path = joined.canonicalize()?; - if !canonical_path.starts_with(&canonical_root) { - return Err("requested file is outside the active workspace".into()); - } - Ok(canonical_path) -} - -#[tokio::main] -async fn main() -> Result<()> { - let mut router = CapabilityRouter::default(); - router.register_arc(Arc::new(RegisteredToolAdapter::new(WorkspaceSummaryTool)))?; - router.register_arc(Arc::new(RegisteredToolAdapter::new(FilePreviewTool)))?; - - let worker = Worker::from_stdio( - PeerDescriptor { - id: "astrcode-example-plugin".to_string(), - name: "astrcode-example-plugin".to_string(), - role: PeerRole::Worker, - version: env!("CARGO_PKG_VERSION").to_string(), - supported_profiles: vec!["coding".to_string()], - metadata: json!({ "example": true }), - }, - router, - None, - )?; - worker.run().await -} diff --git a/examples/plugins/repo-inspector/README.md b/examples/plugins/repo-inspector/README.md deleted file mode 100644 index 0078811e..00000000 --- a/examples/plugins/repo-inspector/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# Repo Inspector Example Plugin - -`repo-inspector` 是一个真实的 AstrCode V4 示例插件，不是测试专用 fixture。 - -它通过 `cargo run -p astrcode-example-plugin --quiet` 启动，并暴露两个 `coding` profile 下的 capability： - -- `workspace.summary` -- `file.preview` - -## 目录说明 - -- `plugin.toml`: 平台发现与启动该插件时使用的 manifest -- `examples/example-plugin`: 插件实际实现 - -## 本地接入 - -把插件目录加入 `ASTRCODE_PLUGIN_DIRS` 后启动 server。 -这个环境变量已收口到 `crates/runtime-config/src/constants.rs` 的 plugin 分类： - -```powershell -$env:ASTRCODE_PLUGIN_DIRS = (Resolve-Path "examples/plugins/repo-inspector") -cargo run -p astrcode-server -``` - -平台启动后会： - -1. 发现 `plugin.toml` -2. 启动 `astrcode-example-plugin` -3. 通过 V4 `initialize` 握手获取 capability -4. 把插件 capability 和内置 tool 一起接入统一 `CapabilityRouter` - -## 设计目的 - -这个示例用于演示： - -- `stdio` transport -- `Peer / Supervisor / Worker` -- `coding profile` 上下文读取 -- 插件 capability 进入平台统一 capability 路由 diff --git a/examples/plugins/repo-inspector/plugin.toml b/examples/plugins/repo-inspector/plugin.toml deleted file mode 100644 index d2c05c22..00000000 --- a/examples/plugins/repo-inspector/plugin.toml +++ /dev/null @@ -1,34 +0,0 @@ -name = "repo-inspector" -version = "0.1.0" -description = "Example coding plugin that summarizes the active workspace and previews files." -plugin_type = ["Tool"] -executable = "cargo" -args = ["run", "-p", "astrcode-example-plugin", "--quiet"] -working_dir = "../../.." -repository = "https://github.com/whatevertogo/astrcode" - -[[capabilities]] -name = "workspace.summary" -kind = "tool" -description = "Summarize the active coding workspace." -input_schema = { type = "object", properties = {} } -output_schema = { type = "object" } -streaming = false -profiles = ["coding"] -tags = ["example", "workspace"] -permissions = [] -side_effect = "none" -stability = "stable" - -[[capabilities]] -name = "file.preview" -kind = "tool" -description = "Preview a file that lives inside the active workspace." -input_schema = { type = "object", properties = { path = { type = "string" }, maxLines = { type = "integer" } } } -output_schema = { type = "object" } -streaming = false -profiles = ["coding"] -tags = ["example", "file"] -permissions = [] -side_effect = "none" -stability = "stable" diff --git a/openspec/changes/hooks-platform/.openspec.yaml b/openspec/changes/hooks-platform/.openspec.yaml deleted file mode 100644 index 4b8c565f..00000000 --- a/openspec/changes/hooks-platform/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-04-21 diff --git a/openspec/changes/hooks-platform/proposal.md b/openspec/changes/hooks-platform/proposal.md deleted file mode 100644 index 3298808e..00000000 --- a/openspec/changes/hooks-platform/proposal.md +++ /dev/null @@ -1,93 +0,0 @@ -## Why - -项目需要为外部扩展点（plugin、内置工具、第三方集成）提供生命周期回调能力。当前 hook 系统存在三层缺失： - -**运行时层面**：`core/hook.rs` 定义了 `HookEvent`、`HookInput`、`HookOutcome`、`HookHandler` trait 等基础类型，`core/policy/engine.rs` 提供了 `PolicyEngine` trait。但这些类型没有形成可用的运行时——没有注册表、没有生命周期管理、没有统一调度路径。观察型 hook（异步通知）和决策型 hook（同步阻塞）没有区分。hook 无法影响工具调用、compact 等关键行为。 - -**治理层面**：builtin `plan` mode 的 prompt 注入逻辑（`facts`、`reentry`、`exit`、`execute bridge`）分散在 `session_plan.rs` 与 `session_use_cases.rs` 的条件分支里，没有统一抽象，无法被其他 mode 或 workflow 复用。继续在这个结构上推进 mode contract 重构，会把新 mode 语义绑死在 plan 专属 helper 上。系统内部的行为（plan prompt、workflow overlay、permission request）和外部扩展（plugin hook）走的是两条完全不同的路径，无法共享同一个平台。 - -**架构层面**：完整 hooks 运行时机制不应该停留在 `core` 中。`core` 应该只保留最小共享语义面（事件类型、payload trait），hooks 平台的 registry、runner、reload、schema 与执行语义应升格为独立 crate。 - -前序 change 确立了必要前提： -- `linearize-session-runtime-application-boundaries`（Change 1）确立了"外部扩展点收纯数据、吐纯数据"的原则。 -- `session-runtime-state-turn-boundary`（Change 2）把 turn 运行时状态完整归入 turn 子域。 - -这两个前提到位后，hook 系统可以安全地插入 turn 执行路径，而不需要暴露运行时内脏。 - -本 change 吸收并替代两个更窄的前序方向： -- `extract-governance-prompt-hooks`：plan prompt 不再作为单独平行系统推进，而是成为 hooks 平台中的标准 turn-level effect。 -- `introduce-hooks-platform-crate`：独立 crate 的方向被本 change 直接采纳。 - -## What Changes - -### 1. 独立 `astrcode-hooks` crate - -- 新增 `crates/hooks` crate，承载 hooks 平台的事件模型、typed payload、effect、matcher、registry、runner、report 与 schema。 -- 将 `crates/core/src/hook.rs` 收缩为极小的共享语义面或兼容壳层；完整的 hooks 平台运行时不再写入 `core`。 - -### 2. 统一 hook 生命周期模型 - -- 引入统一的 builtin / external hook 注册模型：内置系统自己的 plan / workflow / permission / compact 等行为也通过同一 hooks 平台实现，而不是继续走硬编码特例。 -- 明确区分两种 hook 类型： - - **决策型 hook**（同步阻塞）：`beforeToolCall`、`beforeModelRequest` 等。接收纯数据 context，返回纯数据 verdict（允许/拒绝/修改）。在 turn 执行路径中同步调用，结果影响后续行为。 - - **观察型 hook**（异步通知）：`afterToolCall`、`afterCompact`、`afterTurnComplete` 等。接收纯数据 context，无返回值。在 turn 执行路径后异步触发，不影响执行结果。 -- 定义 hook 执行顺序、失败语义与 observability。 - -### 3. Turn 执行路径中的 hook 调度点 - -- 在 turn 执行的关键节点（tool 调用前/后、compact 前/后、turn 开始/结束）插入 hook 调度点。 -- hook 的输入输出严格遵循纯数据原则——context 和 verdict 都是可序列化的 DTO，不包含 CancelToken、锁、原子变量等运行时原语。 - -### 4. 治理 prompt hooks（吸收 extract-governance-prompt-hooks） - -- 定义 governance 级 prompt hook 能力，turn 提交前如何基于 session、artifact、workflow 与 mode 上下文解析额外 `PromptDeclaration`。 -- 将 builtin `plan` mode 当前的 `facts` / `reentry` / `template` / `exit` / `execute bridge` prompt 逻辑迁移到 hook 解析路径，不再由 `session_use_cases` 直接拼接专用 helper。 -- 让 workflow phase 的 bridge prompt overlay 通过 workflow-scoped hook/provider 产出，而不是在提交路径里按 phase 写死条件分支。 -- turn 级 prompt/context 注入收敛为标准 hook effect，通过现有 `PromptDeclaration` / governance surface 链路进入 prompt 组装，不新增平行 prompt 渲染系统。 - -### 5. Plugin hook 接入 - -- 通过 plugin SDK 暴露 hook 注册 API，plugin 可声明自己处理哪些 hook。 -- plugin hooks 与 builtin hooks 进入统一 registry，具备一致的 candidate snapshot / commit / rollback 行为。 -- 扩展 plugin reload 语义：plugin hooks 参与统一 reload，与 mode catalog、capability surface、skill catalog 的切换一起满足原子替换或完整回滚。 - -## Non-Goals - -- 本次不实现 hook 的持久化或跨 session 共享。 -- 本次不实现 hook 的权限隔离（哪些 plugin 可以注册哪些 hook）。 -- 本次不实现 hook 的超时、重试或熔断机制。 -- 本次不直接移除 `enterPlanMode` / `exitPlanMode` / `upsertSessionPlan` 等现有工具——plan prompt 先迁入 hook 路径，工具通用化留给 `unify-declarative-dsl-compiler-architecture`。 -- 本次不接管 workflow signal 解释或 phase 迁移真相。 -- 本次不新增平行 prompt 渲染系统。 - -## Capabilities - -### New Capabilities -- `lifecycle-hooks-platform`: 定义独立 hooks crate、生命周期事件模型、effect 约束、builtin/external handler 类型、执行顺序、失败语义与 hook observability。 -- `governance-prompt-hooks`: 定义 governance/application 层如何注册、解析和组合 turn-scoped prompt hooks，以生成额外的 `PromptDeclaration`。 - -### Modified Capabilities -- `turn-execution`: turn 执行路径中增加 hook 调度点（tool 调用、compact、turn 生命周期）。 -- `plugin-sdk`: SDK 新增 hook 注册 API。 -- `plugin-integration`: plugin hook 的声明、注册、调用与热重载从 `core::HookHandler` 适配升级为 hooks 平台协议。 -- `plugin-capability-surface`: plugin hooks 与 builtin hooks、skills、capabilities 一起参与统一候选快照与重载一致性。 -- `governance-surface-assembly`: 所有 turn 入口在治理装配阶段执行 turn-level hooks，合法 hook effect 合并进治理包络。 -- `mode-prompt-program`: mode / builtin prompt 行为通过 hooks 平台的 turn-level prompt effects 进入既有 `PromptDeclaration` 注入路径。 -- `workflow-phase-orchestration`: workflow phase 相关 overlay 与 lifecycle 事件通过 hooks 平台暴露，但 hooks 不接管 signal 解释或 phase 迁移真相。 - -## Impact - -- 受影响代码： - - 新增 `crates/hooks` - - `crates/core/src/hook.rs`（收缩为兼容壳层） - - `crates/application/src/session_plan.rs`（plan prompt 迁移到 hook） - - `crates/application/src/session_use_cases.rs`（移除 plan-specific 条件分支） - - `crates/application/src/governance_surface/*`（hook 调度集成） - - `crates/application/src/workflow/*`（workflow prompt hook） - - `crates/session-runtime/src/turn/*`（hook 调度点插入） - - `crates/server/src/bootstrap/governance.rs`（reload 路径） - - `crates/protocol/src/plugin/*`（plugin hook 协议） - - plugin / supervisor / reload 相关模块 -- 新增功能，不影响现有行为：hook 注册表初始为空，所有 hook 调度点走 no-op 默认路径。plan prompt 先迁入 hook 路径并验证等价性。 -- 依赖 `linearize-session-runtime-application-boundaries`（纯数据接口原则）和 `session-runtime-state-turn-boundary`（turn 运行时状态归位）的成果。 -- `extract-governance-prompt-hooks` 和 `introduce-hooks-platform-crate` 被本 change 吸收，不再独立演进。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/.openspec.yaml b/openspec/changes/plugin-first-runtime-rearchitecture/.openspec.yaml new file mode 100644 index 00000000..28a64b86 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/.openspec.yaml @@ -0,0 +1,2 @@ +schema: my-workflow +created: 2026-04-23 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/design.md b/openspec/changes/plugin-first-runtime-rearchitecture/design.md new file mode 100644 index 00000000..3cdad8be --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/design.md @@ -0,0 +1,602 @@ +## 背景与现状 + +当前架构与本次目标存在直接冲突，且冲突点不适合继续通过“补一层抽象”解决。 + +- `session-runtime` 同时承担了 turn 执行、事件日志、投影、会话目录、branch/fork、恢复、查询等多类职责，已经不是“runtime core”，而是“runtime + host + read model”的混合体。 +- `application` 仍然暴露并消费 `session-runtime` / `kernel` 的内部事实，说明它没有形成稳定的上层边界，只是中间编排层。 +- `kernel` 作为 provider/tool/resource 聚合门面，在当前结构里承担了过多“为了分层而分层”的职责，既没有形成独立产品边界，也让依赖方向更绕。 +- `server` 仍手工拼接 builtin tools、plugin、MCP、governance、workflow、mode catalog 等多条装配路径，导致“核心行为”和“扩展行为”存在并行事实源。 +- 当前 hooks 仍偏窄，旧 `core::HookInput` / `HookOutcome` 只能表达 tool/compact 一类场景，无法成为统一扩展总线。 + +`PROJECT_ARCHITECTURE.md` 目前仍把 `session-runtime`、`application`、`kernel` 定义为长期正式边界，这与本 change 的目标不一致。因此本次实现前，必须先更新 `PROJECT_ARCHITECTURE.md`，把新的 crate 边界和依赖方向提升为仓库级权威约束。 + +这次设计明确采用“无向后兼容、直接面向最终形态”的策略： + +- 不保留 `application` 兼容 façade。 +- 不保留 `kernel` 过渡壳层。 +- 不把旧 `session-runtime` 继续瘦身为长期边界。 +- 不维持“核心特判 + plugin 补充”的双轨实现。 + +## 设计目标 + +- 建立最小 `agent-runtime`，只负责单 turn 执行、provider 调用、tool dispatch、hook dispatch、流式输出与取消。 +- 建立 `host-session`，统一承接会话 durable truth、事件日志、恢复、branch/fork、read model、模型选择、输入入口与执行面组装。 +- 延续“一个 session 即一个 agent”的协作原则，把多 agent 协作中的父子 session、sub-run lineage、input queue、结果投递与跨 turn 取消统一收敛到 `host-session`。 +- 建立 `plugin-host`，统一承接 builtin / external plugin 的发现、校验、加载、active snapshot、reload 与资源发现。 +- 将 hooks 平台升级为唯一扩展总线，覆盖 runtime、host、resource discovery 的正式事件目录。 +- 删除 `application` 与 `kernel`，让边界回到真正稳定且可解释的 owner 上。 +- 让 `server` 只保留组合根职责，不再手工维护多套产品事实源。 +- 让实现直接面向最终目标形态，不为旧 API、旧 crate、旧装配路径保留长期兼容层。 + +## 非目标 + +- 不逐字复刻 `pi-mono` 的产品矩阵；本次借鉴的是“最小核心 + 扩展优先 + 统一注册表”的架构方法。 +- 不在本次 change 内重做前端 UI 模型，只做后端边界变化所需的最小适配。 +- 不保留旧 `application` / `kernel` / `session-runtime` 的双写、双读或双装配长期过渡层。 +- 不把所有 builtin 能力都强行做成外部进程；热路径 builtin plugin 允许进程内执行。 + +## 方案概览 + +目标形态采用五层结构： + +1. `core` + - 只保留真正跨 owner 共享的值对象、消息模型、稳定枚举和极少数公共合同。 + - 典型内容包括：`ids`、`LlmMessage` / tool call 相关消息模型、`CapabilitySpec`、最小 prompt 声明模型、hooks 事件键与 effect kind。 + - 不保留 owner 专属 DTO，如 plugin descriptor 家族、执行面 DTO、会话快照、恢复模型、projection、workflow/mode、plugin registry、配置持久化 ports。 + - `core` 的规则不是“纯数据都能放进来”，而是“只有多个 owner 共同消费且语义稳定的数据才允许进入 core”。 + +2. `agent-runtime` + - 只负责单 turn / 单 agent 的 live 执行。 + - 输入是 `agent-runtime` 自己公开的 `AgentRuntimeExecutionSurface`。 + - 负责 `context -> before_agent_start -> before_provider_request -> provider stream -> tool_call/tool_result -> turn_end` 这条执行链。 + - 不负责 session 目录、事件日志、resource discovery、settings、workflow、catalog、branch/fork。 + +3. `host-session` + - 负责会话 durable truth 与 host use-case。 + - 维护事件日志、恢复、投影、查询、branch/fork、compact、模型选择、输入入口、turn 创建与 `AgentRuntimeExecutionSurface` 组装。 + - 维护多 agent 协作的 durable truth：父子 session 关系、`SubRunHandle`、`InputQueueProjection`、结果投递、子运行取消和 lineage。 + - 它是“runtime 的宿主”，不是“又一个 runtime”。 + +4. `plugin-host` + - 负责 builtin / external plugin 的统一发现、描述、校验、候选快照、active snapshot、reload、资源发现。 + - 输出统一 `PluginActiveSnapshot`，供 `host-session` 和 `agent-runtime` 消费。 + - builtin plugin 与 external plugin 共用同一套 descriptor 和 hook/tool/provider/resource 注册面，只在执行后端上区分。 + +5. `server` + - 只做组合根。 + - 组装 `host-session`、`agent-runtime`、`plugin-host`、各 adapter 与协议层。 + - 不再承载治理、workflow、plugin 贡献合并、mode catalog 计算等业务真相。 + +DTO 的归属原则也同步调整： + +- `core` 只保留共享语义值对象，不再收纳“只因为是 struct 就进 core”的模型。 +- `agent-runtime` 自己拥有执行面、provider/tool 流程输入输出、runtime hook payload/report。 +- `host-session` 自己拥有 durable snapshot、recovery checkpoint、projection/read model、session/query 结果。 +- `plugin-host` 自己拥有 plugin descriptor、active snapshot、resource descriptor、hook registration descriptor。 +- `protocol` 只保留真正跨进程或跨网络传输的线协议模型，不承载宿主内部 DTO。 + +最终 crate 方向如下： + +```text +adapter-* ───────────────┐ + ├──> plugin-host ──┐ +storage / protocol ──────┘ │ + │ +core <──────────── agent-runtime <──────────┤ + ^ ^ │ + | | │ + └──────────── host-session <──────────────┘ + ^ + | + server +``` + +其中： + +- `application` 删除。 +- `kernel` 删除。 +- 旧 `session-runtime` 拆分后删除。 +- 当前 `plugin` crate 的进程管理、stdio JSON-RPC、supervisor、worker 协议实现迁入新的 `plugin-host` 边界。 + +建议的第一版模块布局如下。 + +### `agent-runtime` 建议结构 + +```text +crates/agent-runtime/ +├── src/ +│ ├── lib.rs +│ ├── runtime.rs +│ ├── loop.rs +│ ├── types.rs +│ ├── tool_dispatch.rs +│ ├── hook_dispatch.rs +│ ├── stream.rs +│ └── cancel.rs +``` + +- `runtime.rs`：对外唯一执行入口，如 `execute_turn` +- `loop.rs`：单次 turn 的主循环 +- `types.rs`：`TurnInput`、`TurnOutput`、`AgentRuntimeExecutionSurface` +- `tool_dispatch.rs`：工具调度与 tool batch 语义 +- `hook_dispatch.rs`：runtime owner 的 hook 触发与 effect 解释 +- `stream.rs`：provider 流式增量处理 +- `cancel.rs`：取消、中断和超时传播 + +### `host-session` 建议结构 + +```text +crates/host-session/ +├── src/ +│ ├── lib.rs +│ ├── host.rs +│ ├── catalog.rs +│ ├── event_log.rs +│ ├── recovery.rs +│ ├── collaboration.rs +│ ├── input_queue.rs +│ ├── projection/ +│ ├── query/ +│ ├── branch.rs +│ ├── fork.rs +│ ├── compaction.rs +│ ├── execution_surface.rs +│ └── model_selection.rs +``` + +- `host.rs`：对外 host use-case surface +- `catalog.rs`：session 目录与元信息 +- `event_log.rs` / `recovery.rs`：durable truth、恢复、回放 +- `collaboration.rs`：父子 session / sub-run 协作编排、结果投递、取消传播 +- `input_queue.rs`：session 级输入队列和子 agent 投递队列 +- `projection/` / `query/`：read model 与查询结果 +- `branch.rs` / `fork.rs`：lineage 和会话分叉 +- `compaction.rs`：压缩与 `session_before_compact` +- `execution_surface.rs`：组装 runtime 输入 +- `model_selection.rs`：模型选择和 `model_select` + +### 新旧模块迁移映射 + +| 当前位置 | 迁移目标 | 原因 | +| --- | --- | --- | +| `session-runtime/turn/*` 中与 loop、llm/tool cycle、streaming 直接相关的模块 | `agent-runtime` | 属于最小执行内核 | +| `session-runtime` 中的 catalog、query、replay、observe、branch/fork、projection | `host-session` | 属于宿主 durable truth 与 read model | +| `core/src/agent/*` 中的 `SubRunHandle`、`InputQueueProjection`、协作执行合同 | `host-session` owner bridge | 属于跨 turn durable collaboration truth | +| `core/src/agent/*` 中嵌入 `ChildSessionNotification` / `StorageEventPayload` 的 `ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` | 暂留 `core` | 这些类型当前是 durable event DTO 的序列化组成部分，迁出会造成 `core -> host-session` 反向依赖或重复 wire schema | +| `application/src/agent/*` 与 `application/src/execution/subagent.rs` | `host-session` | 属于父子 session 编排和 child session 启动 | +| `session-runtime/src/turn/subrun_*`、`state/input_queue.rs`、`query/subrun.rs` | `host-session` + `agent-runtime` 最小执行合同 | 持久化/read model 在 host，实际 turn 执行仍在 runtime | +| `plugin` 中的 loader / process / peer / supervisor / worker 协议 | `plugin-host` | 属于统一插件宿主 | +| `kernel` 的 gateway / router / surface 聚合 | `plugin-host` + `host-session` + `agent-runtime` | 不再保留独立 service-locator 边界 | +| `application` 的 use-case façade | `host-session` / `plugin-host` / `server` | 删除穿透层 | +| `core::ports` | 按 owner 拆散 | 不再保留 mega ports | +| `core::projection` / `workflow` / `session_catalog` | `host-session` 或删除 | 不属于共享语义层 | +| `core::mode` | `plugin-host` + `core` 共享合同 | 治理 DSL / builtin mode owner 逻辑迁往 plugin-host；`ModeId`、durable mode-change event DTO、tool-contract snapshot 在协议/事件 DTO 拆分前暂留 core | + +## 必须删除的旧实现清单 + +迁移完成后的目标不是“新边界可用”，而是“旧边界消失”。以下内容应视为本次 change 的正式删除范围。 + +### 1. 整 crate 删除 + +- `crates/application/**` + - 删除整个 crate，而不是只保留一个空 façade。 + - 其中包括 `agent`、`execution`、`governance_surface`、`mode`、`workflow`、`mcp`、`ports`、`terminal_queries` 等子域。 +- `crates/kernel/**` + - 删除整个 crate，不保留 `KernelGateway`、`CapabilityRouter`、`KernelBuilder`、`SurfaceManager` 之类的长期壳层。 +- `crates/session-runtime/**` + - 删除 monolith `session-runtime` crate，迁移后不保留同名长期边界。 +- 旧 `crates/plugin/**` + - 在 `plugin-host` 建立完成后，删除旧 `plugin` crate 作为正式边界；其中可复用的进程管理和 transport 实现迁入新 crate，而不是继续并存。 + +### 2. `core` 中必须清零的旧共享面 + +- `crates/core/src/projection/**` +- `crates/core/src/mode/**` 中的治理 DSL / builtin mode owner 逻辑（`ModeId` 与 tool/event wire contract 暂留） +- `crates/core/src/config.rs` 中的 owner-only 配置持久化 / 解析逻辑（runtime config 共享合同暂留） +- `crates/core/src/observability.rs` 中的 owner-only collector / summary 逻辑（wire metrics snapshot 暂留） +- `crates/core/src/session_plan.rs` +- `crates/core/src/store.rs` +- `crates/core/src/composer.rs` +- `crates/core/src/plugin/registry.rs` +- `crates/core/src/session_catalog.rs` +- `crates/core/src/runtime/traits.rs` +- `crates/core/src/plugin/manifest.rs` 中旧 `PluginManifest` +- `crates/core/src/hook.rs` 中旧 `HookInput`、`HookOutcome` +- `crates/core/src/agent/lineage.rs` 中 `SubRunHandle` +- `crates/core/src/agent/input_queue.rs` 中 `InputQueueProjection` +- `crates/core/src/lib.rs` 中对应旧 re-export + - 包括 `PluginRegistry` / `PluginManifest` / `PluginHealth` / `PluginState` / `PluginType` + - 包括 `SessionCatalogEvent` + - 包括 `session_plan` / `observability` / `store` / `composer` 相关旧导出 + +判定标准不是“文件是否还在”，而是 `core` 不得再暴露这些 owner 专属模型和合同。 + +### 3. `application` 中必须迁出后删除的旧编排实现 + +- `crates/application/src/agent/**` + - 包括 `AgentOrchestrationService`、child/parent routing、observe、wake、terminal 等协作编排实现。 +- `crates/application/src/execution/root.rs` +- `crates/application/src/execution/subagent.rs` +- `crates/application/src/governance_surface/**` +- `crates/application/src/mode/**` +- `crates/application/src/workflow/**` +- `crates/application/src/mcp/mod.rs` +- `crates/application/src/composer/mod.rs` +- `crates/application/src/ports/**` + +这些内容要么迁入 `host-session`，要么迁入 `plugin-host`，要么回到 server 组合根；不能再由 `application` 继续承载。 + +### 4. 协作主线里必须删除的旧跨层真相 + +- `crates/kernel/src/agent_tree/**` +- `crates/kernel/src/agent_surface.rs` +- `crates/session-runtime/src/query/subrun.rs` +- `crates/session-runtime/src/state/input_queue.rs` +- `crates/session-runtime/src/turn/finalize.rs` 中 subrun 完成持久化路径 +- `crates/session-runtime/src/turn/interrupt.rs` 中 subrun 取消传播路径 +- `crates/application/src/agent/mod.rs` 中 `SubAgentExecutor` / `CollaborationExecutor` 的旧实现承载点 + +这些旧实现删除后的唯一真相位置是： + +- durable collaboration truth -> `host-session` +- child-session live execution contract -> `agent-runtime` +- collaboration surface exposure -> `plugin-host` + +### 5. server 组合根中必须消失的旧特判逻辑 + +- `crates/server/src/bootstrap/runtime.rs` 中 builtin tools / agent tools / MCP / plugin / governance / workflow / mode 的并列装配特判 +- `crates/server/src/bootstrap/providers.rs` 中 `provider_kind == openai` 的硬编码 provider 选择路径 +- `crates/server/src/bootstrap/plugins.rs` 中旧 plugin boundary 装配逻辑 +- `crates/server/src/bootstrap/mcp.rs` 中独立旁路装配逻辑 +- `crates/server/src/bootstrap/governance.rs` 中旧治理面特判逻辑 +- `crates/server/src/bootstrap/capabilities.rs` 中旧 capability sync 主线路径 +- `crates/server/src/bootstrap/composer_skills.rs` 中技能/命令旁路装配逻辑 +- `crates/server/src/bootstrap/prompt_facts.rs` 中旧 prompt facts 旁路解析与注入逻辑 +- `crates/server/src/bootstrap/watch.rs` 中旧 profile watch 旁路装配逻辑 +- `crates/server/src/bootstrap/deps.rs` 中围绕旧组合根的依赖打包壳层 +- `crates/server/src/bootstrap/runtime_coordinator.rs` 中旧运行时协调壳层 + +这里的目标不是机械删文件，而是删掉“组合根内业务特判”这类旧事实源。 + +### `adapter-llm` 的新位置 + +- `adapter-llm` 保留为 provider backend 实现层，而不是 runtime 核心的一部分。 +- `agent-runtime` 只依赖抽象的 stream surface，不知道 OpenAI、DeepSeek、Ollama 等 provider 差异。 +- `plugin-host` 负责 provider contribution 的注册与快照归集。 +- `host-session` 负责为当前 turn 选择 provider，并把最终执行面注入 `agent-runtime`。 +- 当前 `server/bootstrap/providers.rs` 中的 OpenAI-only 选择逻辑是过渡实现，最终应从组合根移出，改成 provider registry + contribution 模型。 + +### 借鉴 `pi-mono` 的 session-as-agent 模式 + +这次不是要把 Astrcode 做成“看起来像 `pi`”，而是要借它已经验证过的 owner 切分： + +- `pi` 的 `Agent` 只负责执行，最多感知 `sessionId`、上下文快照、tool hooks 和 prompt/continue。 +- `pi` 的 `AgentSession` 才持有 `SessionManager`、`ResourceLoader`、扩展动作和 session tree/navigation。 +- 扩展通过 `sendUserMessage`、`appendEntry`、`setSessionName` 之类的 session action 进入系统，而不是直接篡改 session 真相。 + +映射到 Astrcode： + +- `agent-runtime` 对应 `pi` 的 `Agent` + - 只执行某个 session/turn + - 不拥有 session tree、resource discovery、协作 durable truth +- `host-session` 对应 `pi` 的 `AgentSession` + - 持有 session durable truth + - 持有 child session / sub-run 协作真相 + - 暴露正式 host-side actions 给 plugin tools/commands 或协议层调用 +- `plugin-host` 对应 `pi` 的 extension/resource host + - 提供 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree` 这类协作 surface + - 但不拥有 collaboration durable truth + +和 `pi` 不同的是：Astrcode 的多 agent 协作不是临时 UI 行为，而是正式 durable truth。因此我们借鉴它的“session owner”思路，但不照搬它“没有多 agent 真相层”的限制。 + +## 关键决策 + +### 决策 1 + +- 决策：新建 `agent-runtime`、`host-session`、`plugin-host` 三个 crate，再迁移旧实现；旧 `session-runtime` 最终删除。 +- 原因：当前 `session-runtime` 的问题不是实现细节，而是 owner 混合。继续原地瘦身会长期残留“runtime 像 host、host 又像 runtime”的边界污染。 +- 备选方案：保留 `session-runtime` crate，只做内部模块重构。 +- 为什么没选：crate 名义与真实职责会继续失真，且会诱导后续功能继续往单 crate 堆积。 + +### 决策 2 + +- 决策：完全删除 `application` crate，不保留 façade。 +- 原因：它没有形成真正稳定的业务层边界，反而把 `session-runtime` 和 `kernel` 的内部事实重新导出到上层。继续保留只会制造多一层穿透与映射成本。 +- 备选方案：保留 `application` 作为过渡 use-case façade。 +- 为什么没选：这是典型兼容层，会让 server 继续依赖旧心智模型，延缓真正的边界切换。 + +### 决策 3 + +- 决策：删除 `kernel` crate，把它拆回真正的 owner 边界。 +- 原因：provider/tool/resource orchestration 并不是一个独立产品边界。`agent-runtime` 直接消费 provider/tool/hook 执行面，`host-session` 负责装配，`core` 保留纯合同即可。 +- 备选方案：保留更薄的 `kernel` 作为统一门面。 +- 为什么没选：会继续引入一层没有独立业务真相的中间层，让依赖方向和调试路径更绕。 + +### 决策 4 + +- 决策：统一 plugin descriptor 覆盖 `tools`、`hooks`、`providers`、`resources`、`commands`、`themes`、`prompts`、`skills` 的完整贡献面。 +- 原因：只统一 tools/hooks/providers/resources 会继续保留 prompts、skills、themes、commands 的“旁路发现系统”，最终还是多套事实源。 +- 备选方案：先只统一运行时贡献面，资源类扩展以后再并入。 +- 为什么没选：这会把当前分裂的发现逻辑永久化，后续再并入的成本更高。 + +### 决策 5 + +- 决策：`core` 不再作为 DTO 总仓库，owner 专属 DTO 一律迁回 owner crate。 +- 原因：当前 `core` 的问题不是“DTO 多”，而是把 session 恢复、projection、workflow、mode、plugin registry、配置存储 ports 这些 owner 私有模型都升格成了跨 crate 依赖。 +- 备选方案：继续把新 DTO 放进 `core`，只做文件整理。 +- 为什么没选：这只会让 `core` 继续膨胀，延续今天 `ports.rs`、`projection`、`workflow`、`mode` 这种“半核心半实现”的混杂状态。 + +### 决策 6 + +- 决策：hooks 平台成为唯一扩展总线，governance、workflow overlay、tool policy、resource discovery、model selection 全部走正式 hooks catalog。 +- 原因：Astrcode 已经在 prompt hooks、tool hooks、policy hooks 上积累了多条平行路线，继续增加特判只会让行为来源更隐式。 +- 备选方案：保留 governance/workflow 的特判链路，只让部分能力走 hooks。 +- 为什么没选：这会让 hooks 失去“统一总线”的意义，只变成又一套附属扩展点。 + +### 决策 7 + +- 决策：builtin plugin 与 external plugin 共享统一 descriptor、registry、snapshot 和 hook surface，但采用不同执行后端。 +- 原因：统一事实面是必须的，但热路径性能和进程隔离需求不能强行合并成同一性能模型。 +- 备选方案：全部外部进程化，或 builtin / external 完全两套实现。 +- 为什么没选：前者会把热路径延迟和失败面放大，后者会重新回到双轨事实源。 + +### 决策 8 + +- 决策：新 turn 固定绑定启动时的 `PluginActiveSnapshot`，reload 只影响后续 turn。 +- 原因：这样才能保证执行一致性，避免中途切换 snapshot 导致同一 turn 的工具、hook、provider、prompt 语义漂移。 +- 备选方案：reload 后立即让所有在途 turn 读取新 snapshot。 +- 为什么没选：会造成执行不确定性和调试困难，尤其在流式 provider / tool execution 期间。 + +### 决策 9 + +- 决策：多 agent 协作继续遵循“一个 session 即一个 agent”的原则，所有父子 session 关系、`SubRunHandle`、input queue、结果投递、跨 turn 取消与 lineage durable truth 一律归 `host-session`；`agent-runtime` 只保留最小 child-session 执行合同。 +- 原因：Astrcode 现有 sub-run 协作已经明确依赖事件日志、query/read model、parent/child lineage 与 turn 终态，这些都属于宿主 durable truth，而不是 live runtime loop。 +- 备选方案：单独新建 collaboration crate，或继续把协作模型分散留在 `core + application + session-runtime`。 +- 为什么没选：前者会把本质上依赖 session durable truth 的能力又切出一个没有独立真相的中间层；后者会延续今天最严重的跨 owner 污染。 + +### 决策 10 + +- 决策：协作能力对外通过 plugin/tool/command surface 暴露，但这些 surface 只负责把动作提交给 `host-session`，不拥有 collaboration durable truth。 +- 原因：这样既能满足“其他一切通过 plugin 提供”的 product surface 目标，也能保持 session / sub-run / input queue / result delivery 的唯一真相仍在 `host-session`。 +- 备选方案：让 `plugin-host` 或扩展 handler 直接维护 child session 状态，或让 runtime 内部直接暴露协作特判入口。 +- 为什么没选：前者会让扩展层越权持有 durable truth，后者会重新把协作逻辑塞回 runtime 主链。 + +## 数据流 / 控制流 / 错误流 + +### 启动与装配 + +1. `server` 启动时装配 storage、provider adapters、tool adapters、prompt/resource adapters。 +2. `plugin-host` 发现 builtin plugin 定义和 external plugin 来源。 +3. `plugin-host` 将所有来源解析为 `PluginDescriptor`，校验字段、冲突、权限、执行后端可用性。 +4. 校验通过后构建 `PluginActiveSnapshot` 并提交为 active revision。 +5. `host-session` 使用 active snapshot 生成资源目录、模型目录和 host 可用能力视图。 + +这里的关键点是：`server` 只负责把“有哪些后端”交给 `plugin-host`，真正的合并、排序、冲突解析、激活都由 `plugin-host` owner 负责。 + +### 正常 turn 执行流 + +1. 外部输入先进入 `host-session`。 +2. `host-session` 触发 `input` hook，允许短路、转换或已处理。 +3. `host-session` 根据当前 `HostSessionSnapshot`、模型选择结果、`PluginActiveSnapshot` 组装 `AgentRuntimeExecutionSurface`。 +4. `agent-runtime` 开始 turn： + - 触发 `turn_start` + - 运行 `context` + - 运行 `before_agent_start` + - 运行 `before_provider_request` + - 发起 provider 流式请求 +5. 如果模型返回工具调用： + - `agent-runtime` 触发 `tool_call` + - 执行工具 + - 触发 `tool_result` + - 决定是否继续下一轮 provider 请求 +6. turn 结束时触发 `turn_end`。 +7. `agent-runtime` 只返回执行结果和运行时事件；durable 写入由 `host-session` 完成。 + +### compaction / branch / fork / model 切换流 + +- compaction 由 `host-session` 决策和执行，执行前触发 `session_before_compact`。 +- branch / fork 是 `host-session` 的 durable 操作，不经过 `agent-runtime`。 +- 模型切换由 `host-session` 发起，经过 `model_select` hook 校验、重写或拒绝，再更新后续 turn 的执行面。 + +### 多 agent 协作流 + +1. 父 session 的某个 turn 在 `host-session` 内决定发起子 agent。 +2. `host-session` 创建新的 child session，并把它视为新的 agent 实例，而不是在同一 session 内切换“子人格”。 +3. `host-session` 追加 sub-run started / lineage / input queue 相关事件，生成 `SubRunHandle` 并更新 `InputQueueProjection`。 +4. `host-session` 为 child session 组装新的 `AgentRuntimeExecutionSurface`，然后调用 `agent-runtime` 执行 child turn。 +5. child turn 完成后，`agent-runtime` 只返回最小执行结果；sub-run finished、结果投递、父 turn 唤醒、跨 turn cancel 清理由 `host-session` 落 durable truth。 +6. 如果父 turn 被取消或中断，取消传播先由 `host-session` 决定并记录，再把 cancel token 传递给对应 child runtime。 + +这个流程的关键不是“能不能启动子 agent”，而是“子 agent 是否仍然是一个完整可恢复、可查询、可分叉的 session”。因此 collaboration 真相必须留在 `host-session`。 + +### 协作能力暴露流 + +1. `plugin-host` 在 active snapshot 中暴露 collaboration 相关 tools/commands，例如 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree`。 +2. LLM、CLI、RPC 或其他宿主通过这些统一 surface 发起协作动作。 +3. surface handler 不直接改 session durable truth，而是调用 `host-session` 的正式 use-case surface。 +4. `host-session` 负责 child session 创建、sub-run 事件落库、input queue 投递、结果回传与取消传播。 +5. 如需执行 child turn，再由 `host-session` 调用 `agent-runtime`。 + +这样可以同时满足两件事： + +- 对外看，协作能力和其他 builtin/external 扩展一样，走统一 plugin surface。 +- 对内看，协作状态仍只有一个 owner，不会被扩展层复制一份真相。 + +### resource discovery 流 + +1. `plugin-host` 在 active snapshot 构建后或 reload 后触发 `resources_discover`。 +2. 各 plugin 贡献 `skills`、`prompts`、`themes`、`commands`、其他资源入口。 +3. `plugin-host` 聚合为统一资源目录，供 `host-session`、CLI、server 路由或 UI 消费。 + +### 错误流 + +#### plugin 加载 / reload + +- `plugin-host` 先构建 candidate snapshot，再做原子提交。 +- 任一 descriptor 校验失败、backend 启动失败、冲突无法消解时，candidate 作废，旧 active snapshot 保持不变。 +- reload 错误只影响新 revision，不污染当前 active turn。 + +#### hook 执行 + +- 每个 hook 按 `failure_policy` 处理： + - `fail_closed`：阻断当前流程。 + - `fail_open`：记录报告后继续。 + - `report_only`：只产出观测结果，不改变主流程。 +- hook 只能返回受约束 effect，不能直接写 durable truth。 + +#### provider / tool 执行 + +- `agent-runtime` 负责把 provider/tool 错误转成统一运行时结果。 +- 会话日志、read model、终态快照的持久化仍由 `host-session` owner 处理。 +- 在取消、中断、部分流输出场景下，`agent-runtime` 产出“不完整但一致”的执行结果，`host-session` 决定如何写入事件日志与恢复点。 + +## 与 DTO / Spec 的对应关系 + +### 对 `agent-runtime-core` 的落实 + +- `AgentRuntimeExecutionSurface` 是 `host-session -> agent-runtime` 的唯一正式输入，但它归属 `agent-runtime` crate，而不是 `core`。 +- `agent-runtime` 只消费纯数据输入，不自行做资源发现或持久化。 +- `HookEventEnvelope`、`HookEffect`、`HookExecutionReport` 覆盖 runtime 事件触发和 effect 解释，但它们属于 hooks/runtime owner，而不是默认进入 `core`。 +- 即使存在 child-session 启动场景，`agent-runtime` 也只负责执行某个 session/turn，不负责维护 `SubRunHandle`、input queue、结果投递或 parent/child lineage durable truth。 + +### 对 `host-session-runtime` 的落实 + +- `HostSessionSnapshot` 是 host 层对 durable truth / read model 的统一视图，归属 `host-session`。 +- 输入入口、compaction、branch/fork、query/read model、turn 组装全部归 `host-session` owner。 +- `session_before_compact`、`model_select`、`input` 等事件由 `host-session` 触发。 +- 多 agent 协作里的 `SubRunHandle`、`InputQueueProjection`、parent/child lineage、subrun finished/cancel 事件、结果投递与父 turn 唤醒也归 `host-session` owner。 + +### 对 `plugin-host-runtime` 的落实 + +- `PluginDescriptor` 是统一输入模型，归属 `plugin-host`。 +- `PluginActiveSnapshot` 是唯一生效快照，归属 `plugin-host`。 +- builtin / external plugin 只在 backend 执行方式不同，不在描述模型和装配流程上分叉。 + +### 对 `lifecycle-hooks-platform` 的落实 + +- hooks catalog、dispatch mode、failure policy、effect 限制都以 `HookDescriptor` + `HookEventEnvelope` + `HookEffect` 表达。 +- governance prompt augment 通过 `augment_prompt -> PromptDeclaration` 映射进入既有 prompt 管线。 + +### 对 DTO 的补充决策 + +- `ProviderDescriptor`、`ResourceDescriptor`、`CommandDescriptor`、`ThemeDescriptor`、`PromptDescriptor`、`SkillDescriptor` 都属于 `plugin-host` 的子贡献面。 +- `SessionRecoveryCheckpoint`、`RecoveredSessionState`、各类 projection/read model 不再属于 `core`，而是 `host-session` 自有模型。 +- `LlmRequest`、`LlmOutput`、provider stream event、tool/runtime execution context 不再通过 `core::ports` 这个 mega 模块承载，而是迁到各自 owner 合同模块。 +- `workflow`、`plugin::registry`、`projection`、`session_catalog` 不再被视为 core 语义，而是迁出或删除；`mode` 先拆成 plugin-host owner DSL 与 core 共享 wire/control 合同。 + +这些调整的目标不是“减少 struct 数量”，而是让 DTO 和 owner 一一对应，避免 `core` 继续成为跨边界耦合中心。 + +## 风险与取舍 + +- [大范围 crate 重构] -> 先更新 `PROJECT_ARCHITECTURE.md`，再按 owner 拆 crate；每一步都以编译边界和 bootstrap 切换为验收点。 +- [删除 `application` / `kernel` 影响面大] -> 不做长期兼容层，但允许在迁移阶段保留短生命周期的内部桥接模块，桥接模块不得对外暴露为正式 API。 +- [收缩 `core` 时类型搬迁范围大] -> 先定义“哪些模型真的是跨 owner 共享语义”，其余按 owner 逐批迁移；迁移顺序以删除 `core::ports`、`core::projection`、`core::plugin`、`core::workflow/mode` 为主线。 +- [多 agent 协作跨 crate 现状复杂] -> 先用“一个 session 即一个 agent”固定语义，再把 `SubRunHandle`、input queue、cancel/result-delivery 真相统一迁入 `host-session`，避免 runtime 和 host 各记一套状态。 +- [plugin 贡献面扩大后校验复杂度上升] -> 所有贡献先落到 `PluginDescriptor`，统一做 schema 校验、命名冲突校验、优先级排序和 backend 就绪检查。 +- [hooks 事件增多后行为更隐式] -> 强制 event catalog、owner、dispatch mode、failure policy 全部显式化，并输出 `HookExecutionReport`。 +- [builtin 与 external backend 差异] -> 保持统一 descriptor / snapshot，不强行统一性能模型；host 只承诺行为语义一致。 +- [reload 与在途 turn 一致性] -> turn 固定绑定 snapshot revision，新 revision 只作用于后续 turn。 + +## 实施与迁移 + +### 第 0 步：更新架构权威文档 + +- 先修改 `PROJECT_ARCHITECTURE.md`。 +- 删除 `application`、`kernel`、monolith `session-runtime` 的长期权威定义。 +- 写入 `agent-runtime`、`host-session`、`plugin-host` 的新边界、依赖方向和 owner 约束。 + +### 第 1 步：建立新 crate 骨架 + +- 新建： + - `crates/agent-runtime` + - `crates/host-session` + - `crates/plugin-host` +- 在 `core` 中只保留新的共享语义和值对象，不把 owner 专属 DTO 再放回去。 + +### 第 2 步：迁移最小 runtime 核心 + +- 从旧 `session-runtime` 中迁出 turn loop、provider 调用、tool dispatch、hook dispatch、流式状态机到 `agent-runtime`。 +- 明确 `agent-runtime` 不再依赖 session catalog、query、projection、branch/fork。 + +### 第 3 步：迁移 host 会话能力 + +- 从旧 `session-runtime` 中迁出事件日志、恢复、投影、query、branch/fork、compact、session catalog 到 `host-session`。 +- 从 `core/application/session-runtime` 中迁出 `SubRunHandle`、`InputQueueProjection`、协作 executor 合同、subrun finished/cancel 持久化、child session 启动与结果投递逻辑到 `host-session`。 +- 迁移期使用 owner bridge：执行/read-model 类型先通过 `host-session` 对外暴露；`ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` 暂留 `core`，因为它们嵌入 `ChildSessionNotification` 和 durable event payload。 +- 由 `host-session` 负责组装 `AgentRuntimeExecutionSurface` 并调用 `agent-runtime`。 + +### 第 3.5 步：收缩 core + +- 拆掉 `crates/core/src/ports.rs` 这一类 mega 合同文件，按 owner 迁入 `agent-runtime`、`host-session`、`plugin-host` 或 `support`。 +- 迁出或删除 `crates/core/src/projection`、`workflow.rs`、`plugin/registry.rs`、`session_catalog.rs`、owner 专属 observability / config store 模型；`mode` 采取窄桥接策略，避免 `core` 反向依赖 plugin-host。 +- 保留 `ids`、消息模型、`CapabilitySpec`、极少数共享 prompt/hook 语义和值对象。 + +### 第 4 步：迁移 plugin 宿主能力 + +- 把当前 `crates/plugin` 的 loader / process / peer / supervisor / invoker / worker 协议收敛到 `plugin-host`。 +- 新增 active snapshot、descriptor 校验、reload candidate/commit/rollback、resource discovery。 +- 将 builtin tools、governance、workflow overlay、MCP bridge 逐步改造成 builtin plugin 贡献。 + +### 第 5 步：切换组合根 + +- 先重写 `crates/server/src/bootstrap/runtime.rs` 的 plugin/provider/resource 生效事实来源，进入短生命周期 bridge： + - `server` 仍保留现有 HTTP/API 调用所需的 `application` / `kernel` / `session-runtime` 外壳。 + - builtin tools、MCP tools、collaboration tools、provider 与 external plugin descriptor 必须合并为同一组 `PluginDescriptor[]`。 + - 这组 descriptor 通过单个 reload bridge 产出 `PluginActiveSnapshot`、`ResourceCatalog`、`ProviderContributionCatalog`，server 后续 provider、prompt facts、resource catalog 只消费该产物。 +- governance / mode / workflow 也按 bridge 处理： + - builtin modes 与 plugin-declared modes 先进入 `PluginDescriptor.modes`，并随 `PluginActiveSnapshot` 一起提交。 + - server 从 snapshot 中的 mode 贡献构建 `ModeCatalog`，旧 `GovernanceSurfaceAssembler` / `AppGovernance` 只消费这个 catalog。 + - `WorkflowOrchestrator` 的最终 hooks 化和旧 owner 删除留到旧 API 调用方切换后执行，不在 bridge 阶段同时跨越。 +- 旧 `application`、`kernel`、旧 `session-runtime` 的正式依赖删除放到第 6 步执行；只有当协议/API 调用方已经切到 `host-session + agent-runtime + plugin-host` 后，才删除这些旧边界。 + +### 第 6 步：分阶段删除旧边界 + +第 6 步必须先迁移调用方，再删除 crate。当前 bridge 已经把 plugin/provider/resource/mode 的生效事实收敛到 `plugin-host`，但 server HTTP/API 面仍编译依赖旧 `application` / `kernel` / `session-runtime` / `plugin`。因此删除顺序固定为： + +1. 切换 server 运行时 API 面，按调用面分批推进： + - config / model：从 `App::config()` 迁到 server-owned config/profile service 或新 owner service。 + - session catalog CRUD / fork / catalog stream：list/create/delete/delete_project/fork/catalog stream 先迁到 server-owned `host-session::SessionCatalog`，fork 可短期保留 server-side plan artifact copy bridge。 + - turn mutation 分阶段迁移： + 1. 先在 `host-session` 建立 submit/compact/interrupt owner 合同，明确 durable turn mutation 与 governance/workflow/skill-invocation bridge 的边界。 + 2. 再把 submit acceptance、turn lease、branch-on-busy 目标解析迁到 `host-session::SessionCatalog`，让 `application` 不再决定 submit target。 + 3. 再接通 `agent-runtime::RuntimeTurnEvent` 到 `host-session` 事件持久化、投影、broadcast、checkpoint 路径。 + 4. 再迁移 compact / interrupt 的 owner 行为，包括 manual compact 延迟登记、cancel token、terminal cancelled event 与 pending compact flush。 + 5. 最后切换 server submit/compact/interrupt 路由，不再调用 `application::App` turn/session mutation use-case。 + 迁移期间 governance/workflow/skill-invocation 可保留短生命周期 bridge，但该 bridge 不得拥有 durable turn mutation truth。 + - session mode：list_modes/get_session_mode/switch_mode 迁到 `plugin-host` mode catalog 与 `host-session` mode state owner。 + - conversation / terminal read-model：terminal facts、conversation stream、authoritative summary 迁到 `host-session` query/read-model 与 server projection adapter。 + - composer / resource discovery：composer options、skills、commands、prompts、themes 迁到 `plugin-host::ResourceCatalog` / descriptor-derived catalog。 + - agent collaboration：agent status、root execute、close/observe 和 collaboration tools 迁到 `host-session` collaboration use-case 与 `plugin-host` surface。 + - 最后移除 `ServerRuntime.app` / `AppState.app`；协议映射可以留在 server thin adapter 中，但 `application::App` 不再是业务入口。 +2. 切换旧 `kernel` 能力面：`CapabilityRouter` / `KernelGateway` / `SurfaceManager` 的调用方改为消费 `plugin-host` active snapshot、tool dispatch、provider/resource catalog 或 `agent-runtime` 执行面。 +3. 切换旧 `session-runtime` 剩余调用面：catalog、query/read-model、observe、branch/fork、compaction、turn 提交和 child-session 驱动全部归 `host-session + agent-runtime`。 +4. 切换旧 `plugin` 进程宿主边界：loader / supervisor / process / peer / worker protocol 作为 `plugin-host` external backend 生效，不再暴露旧 `astrcode-plugin` crate。 +5. 删除 workspace 中的旧 crate 与依赖规则：`crates/application`、`crates/kernel`、旧 `crates/session-runtime`、旧 `crates/plugin` 不再作为正式 crate 参与编译。 +6. 执行 `0.*` 删除验收：清理旧 port、旧 re-export、旧 helper、旧 bootstrap 特判和 owner-only core 暴露，确认仓库中无残留正式依赖路径。 + +### 回滚策略 + +- 不提供长期双轨回滚。 +- 在组合根正式切换前，每个迁移阶段都可以通过 git revert 回退。 +- 一旦 `server` 切换到新边界，旧路径应直接删除，回滚只能基于版本回退，不保留运行时开关。 + +## 验证方案 + +- 架构验证： + - 更新并执行 `node scripts/check-crate-boundaries.mjs` + - 确认 `server` 只做组合根，新依赖方向满足文档约束 +- 编译验证： + - `cargo check --workspace` +- 行为验证： + - 为 `agent-runtime` 编写 turn 执行、取消、tool_call/tool_result、provider streaming 测试 + - 为 `host-session` 编写事件日志恢复、branch/fork、compaction、model_select 测试 + - 为 `plugin-host` 编写 descriptor 校验、snapshot commit/rollback、reload、一致性测试 + - 为 hooks 平台编写 event owner、dispatch mode、failure policy、effect 解释测试 +- 集成验证： + - 验证 builtin plugin 与 external plugin 在同一 active snapshot 中可共同提供 tools/hooks/providers/resources + - 验证 reload 失败不会污染旧 snapshot + - 验证 in-flight turn 固定绑定旧 snapshot，新 turn 使用新 snapshot + +## 未决问题 + +无。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/dto.md b/openspec/changes/plugin-first-runtime-rearchitecture/dto.md new file mode 100644 index 00000000..00bfbef1 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/dto.md @@ -0,0 +1,669 @@ +## 概览 + +本次 change 的数据模型分成四组，但需要先强调一个收缩原则： + +- 不是所有 DTO 都应该继续放进 `core` +- DTO 的归属优先跟 owner，而不是跟“它看起来像纯数据” +- `core` 只保留真正跨 owner 共享且长期稳定的值对象 +- `agent-runtime`、`host-session`、`plugin-host` 各自拥有自己的内部/公共合同 + +在这个原则下，本次 change 的数据模型分成四组： + +- 新增核心模型： + - `PluginDescriptor` + - `PluginActiveSnapshot` + - `HookMatcher` + - `HookDescriptor` + - `HookEventEnvelope` + - `HookEffect` + - `HookExecutionReport` + - `AgentRuntimeExecutionSurface` + - `HostSessionSnapshot` +- 迁移并继续复用的协作模型： + - `SubRunHandle` + - `InputQueueProjection` +- 修改/替代模型： + - 旧 `PluginManifest` 不再足够表达完整贡献面，需要被新的 `PluginDescriptor` 取代 + - 旧 `core::HookInput` / `HookOutcome` 只覆盖窄版 tool/compact hook，需要被更宽的 hooks 事件与 effect 模型替代 + - 旧 monolith `session-runtime` 对外 surface 会被拆成 `agent-runtime` 与 `host-session` 两类模型 + - 旧 `core + application + session-runtime` 三处分散的 subagent/subrun 协作模型，会收敛成 `host-session` durable truth + `agent-runtime` 最小执行合同 +- 直接复用的现有模型： + - `CapabilitySpec` + - `PromptDeclaration` + - `PromptGovernanceContext` + - `SessionObserveSnapshot` + - `TurnTerminalSnapshot` +- 建模目标： + - 让 `agent-runtime` 只消费纯数据的执行面 + - 让 `plugin-host` 统一管理 builtin / external plugin 的贡献 + - 让 hooks 的事件、effect、执行报告都可以独立序列化、校验和记录 + - 让 DTO 跟随 owner 收缩，不再继续把 owner 专属模型堆入 `core` + +## 归属原则 + +### `core` 保留什么 + +- `ids` +- LLM / tool / message 相关的基础消息模型 +- `CapabilitySpec` +- 极少数跨 owner 共享的 prompt 声明和值对象 +- hooks 的稳定事件键、effect kind 这类共享语义枚举 + +### `core` 不再保留什么 + +- session recovery checkpoint、projection snapshot、read model +- workflow / mode / session catalog +- plugin manifest / plugin registry / active snapshot +- provider / prompt / resource / config 的 owner 专属 ports +- observability report、runtime execution report 这类 owner 局部模型 + +### owner 模型归属 + +- `agent-runtime` + - `AgentRuntimeExecutionSurface` + - runtime hook payload / effect interpreter input + - provider/tool 执行上下文与结果 +- `host-session` + - `HostSessionSnapshot` + - `SessionRecoveryCheckpoint` + - `RecoveredSessionState` + - projection / query / observe 结果 + - `SubRunHandle` + - `InputQueueProjection` + - 协作 executor 合同、结果投递与协作终态快照 + - parent/child lineage 的 owner 仍是 host-session；迁移期 `ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` 作为 durable event DTO 组成部分暂留 `core` +- `plugin-host` + - `PluginDescriptor` + - `PluginActiveSnapshot` + - `HookDescriptor` + - `ProviderDescriptor` + - `ResourceDescriptor` + - `CommandDescriptor` + - `ThemeDescriptor` + - `PromptDescriptor` + - `SkillDescriptor` + +## 模型清单 + +### `HookMatcher` + +- 用途：描述某个 hook 在命中指定事件后，还需要如何进一步收窄匹配范围 +- 类型：值对象 +- 所属边界：hooks platform / `plugin-host` +- 来源：`HookDescriptor` +- 去向：dispatcher 的匹配阶段 + +#### 表达形式 + +- `All` + - 匹配当前事件下的全部实例，是第一阶段默认值 +- `ToolNames(Vec)` + - 仅匹配指定工具名 +- `AgentIds(Vec)` + - 仅匹配指定 agent +- `SessionIds(Vec)` + - 仅匹配指定 session + +#### 校验规则与不变量 + +- `HookMatcher` 只能收窄当前 `event` 的命中范围，不能声明新的事件类型 +- 第一阶段没有更细的上下文条件时，默认使用 `All` +- `ToolNames` 只对 `tool_call` / `tool_result` 这类工具相关事件生效 + +### `PluginDescriptor` + +- 用途：描述一个 plugin 的完整贡献面，是 `plugin-host` 的正式输入模型 +- 类型：DTO +- 所属边界：`plugin-host` 对内/对外统一装配边界 +- 来源：builtin plugin 定义、external plugin manifest/handshake、远程 plugin 元数据 +- 去向：`plugin-host` registry、reload candidate snapshot、资源发现、hooks 注册、tool/provider 注册 + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `plugin_id` | `string` | 是 | - | 全局唯一、kebab-case | 稳定插件标识 | +| `display_name` | `string` | 是 | - | 非空 | 展示名称 | +| `version` | `string` | 是 | - | 语义版本或稳定 revision | 插件版本/修订 | +| `source_kind` | `"builtin" \| "process" \| "command" \| "http"` | 是 | - | 枚举 | 执行来源 | +| `source_ref` | `string` | 是 | - | 非空 | 可执行路径、URL、内联实现名等 | +| `enabled` | `boolean` | 是 | `true` | - | 是否参与当前候选装配 | +| `priority` | `i32` | 否 | `0` | 数值越大优先级越高 | 冲突解析顺序 | +| `tools` | `CapabilitySpec[]` | 否 | `[]` | 名称唯一 | LLM 可调用工具贡献 | +| `hooks` | `HookDescriptor[]` | 否 | `[]` | `hook_id` 唯一 | 生命周期 hooks 贡献 | +| `providers` | `ProviderDescriptor[]` | 否 | `[]` | provider id 唯一 | 模型/provider 贡献 | +| `resources` | `ResourceDescriptor[]` | 否 | `[]` | 可按 kind 聚合 | 原始资源贡献 | +| `commands` | `CommandDescriptor[]` | 否 | `[]` | command id 唯一 | slash/命令贡献 | +| `themes` | `ThemeDescriptor[]` | 否 | `[]` | theme id 唯一 | 主题贡献 | +| `prompts` | `PromptDescriptor[]` | 否 | `[]` | prompt id 唯一 | prompt 模板贡献 | +| `skills` | `SkillDescriptor[]` | 否 | `[]` | skill id 唯一 | skill 贡献 | + +#### 与其他模型的关系 + +- 与 `PluginActiveSnapshot`：`PluginDescriptor` 是 snapshot 构建输入 +- 与 `HookDescriptor`：一个 plugin 可以贡献 0..N 个 hooks +- 与 `AgentRuntimeExecutionSurface`：部分字段会被降维投影到执行面 + +#### 校验规则与不变量 + +- 同一 `plugin_id` 在同一个 active snapshot 中只能出现一次 +- 同一 plugin 内部的 `tools/hooks/providers/resources/commands/themes/prompts/skills` 标识不得冲突 +- `source_kind = "builtin"` 时，`source_ref` 必须指向已注册的进程内实现 +- `source_kind != "builtin"` 时，必须提供可解析的执行入口 + +#### 生命周期 / 状态变化 + +- `discovered -> validated -> candidate -> active -> stale` + +#### 映射关系 + +- `plugin manifest / handshake -> PluginDescriptor -> PluginActiveSnapshot` + +### `PluginActiveSnapshot` + +- 用途：表示某一时刻真正生效的统一 plugin 贡献面 +- 类型：视图模型 +- 所属边界：`plugin-host -> host-session / agent-runtime` +- 来源：由多个 `PluginDescriptor` 经过校验、冲突解析和合并得到 +- 去向：`agent-runtime`、`host-session`、统一 discovery、reload rollback + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `snapshot_id` | `string` | 是 | - | 全局唯一 | 当前生效面版本 | +| `revision` | `u64` | 是 | - | 单调递增 | reload 版本号 | +| `plugin_ids` | `string[]` | 是 | - | 去重 | 参与本次快照的 plugin 列表 | +| `tools` | `CapabilitySpec[]` | 是 | `[]` | 名称唯一 | 生效工具集合 | +| `hooks` | `HookDescriptor[]` | 是 | `[]` | `hook_id` 唯一 | 生效 hooks 集合 | +| `providers` | `ProviderDescriptor[]` | 是 | `[]` | provider id 唯一 | 生效 provider 集合 | +| `resources` | `ResourceDescriptor[]` | 是 | `[]` | 可按 kind 聚合 | 生效资源集合 | +| `commands` | `CommandDescriptor[]` | 是 | `[]` | command id 唯一 | 生效命令集合 | +| `themes` | `ThemeDescriptor[]` | 是 | `[]` | theme id 唯一 | 生效主题集合 | +| `prompts` | `PromptDescriptor[]` | 是 | `[]` | prompt id 唯一 | 生效 prompt 集合 | +| `skills` | `SkillDescriptor[]` | 是 | `[]` | skill id 唯一 | 生效 skills 集合 | + +#### 与其他模型的关系 + +- 与 `PluginDescriptor`：由多个 descriptor 聚合而来 +- 与 `AgentRuntimeExecutionSurface`：执行面只消费其中相关子集 + +#### 校验规则与不变量 + +- 任何 active snapshot 必须是完整可用的整体，不能是半成功状态 +- reload 失败时不得产生新 active snapshot +- 进行中的 turn 绑定旧 snapshot，新 turn 绑定新 snapshot + +#### 生命周期 / 状态变化 + +- `candidate -> active -> superseded -> garbage_collectable` + +#### 映射关系 + +- `PluginDescriptor[] -> PluginActiveSnapshot -> AgentRuntimeExecutionSurface` + +### `HookDescriptor` + +- 用途：描述一个 hook 的注册信息、触发事件、匹配条件与执行策略 +- 类型：DTO +- 所属边界：`plugin-host -> hooks platform` +- 来源：builtin hook 定义、external plugin hook 声明 +- 去向：hooks registry、active snapshot、dispatch pipeline + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `hook_id` | `string` | 是 | - | 全局唯一 | 稳定 hook 标识 | +| `plugin_id` | `string` | 是 | - | 必须指向已存在 plugin | 所属插件 | +| `event` | `HookEventKey` | 是 | - | 枚举值 | 订阅的事件名 | +| `stage` | `"runtime" \| "host" \| "resource"` | 是 | - | 枚举 | 所属执行阶段 | +| `dispatch_mode` | `"sequential" \| "pipeline" \| "cancellable" \| "intercept" \| "modify" \| "short_circuit"` | 是 | - | 与 `event` 必须匹配 | 分发语义 | +| `priority` | `i32` | 否 | `0` | 数值越大越先执行 | 稳定顺序 | +| `matcher` | `HookMatcher` | 否 | `All` | 只能收窄命中范围 | 细粒度匹配 | +| `timeout_ms` | `u64` | 否 | `5000` | `> 0` | 单次执行超时 | +| `failure_policy` | `"fail_closed" \| "fail_open" \| "report_only"` | 是 | - | 枚举 | 失败语义 | +| `handler_ref` | `string` | 是 | - | 非空 | 指向内联实现、命令、进程或远程入口 | +| `enabled` | `boolean` | 是 | `true` | - | 是否生效 | + +#### 与其他模型的关系 + +- 与 `HookEventEnvelope`：按 `event` 匹配后执行 +- 与 `HookEffect`：执行后产出 0..N 个 effect +- 与 `HookExecutionReport`：每次执行都会记录一条报告 + +#### 校验规则与不变量 + +- `event` 与 `dispatch_mode` 必须匹配对应的正式事件语义 +- `hook_id` 在同一个 active snapshot 中必须唯一 +- `matcher` 默认值为 `All` +- `matcher` 只能收窄命中范围，不能声明新的事件类型 + +#### 生命周期 / 状态变化 + +- `declared -> validated -> registered -> active -> stale` + +#### 映射关系 + +- `plugin hook declaration -> HookDescriptor -> HookEventEnvelope -> HookEffect[]` + +### `HookEventEnvelope` + +- 用途：统一描述一次 hook 触发时的输入上下文 +- 类型：事件 +- 所属边界：`hooks platform` 运行时事件模型；实现归属具体 owner crate，而不是 `core` +- 来源：运行时、host、resource discovery +- 去向：hooks dispatcher、hooks report、诊断日志 + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `event_id` | `string` | 是 | - | 全局唯一 | 本次触发实例 id | +| `event` | `HookEventKey` | 是 | - | 枚举值 | 事件名 | +| `session_id` | `string` | 否 | `null` | 与 session 相关时必填 | 所属 session | +| `turn_id` | `string` | 否 | `null` | 与 turn 相关时必填 | 所属 turn | +| `agent_id` | `string` | 否 | `null` | 与 agent 相关时必填 | 所属 agent | +| `source_owner` | `"agent-runtime" \| "host-session" \| "plugin-host"` | 是 | - | 枚举 | 触发 owner | +| `timestamp_ms` | `u64` | 是 | - | 单调时间戳 | 触发时间 | +| `payload` | `serde_json::Value` | 是 | - | 必须符合该 `event` 的 schema | 事件载荷 | +| `snapshot_id` | `string` | 是 | - | 非空 | 绑定的 active snapshot | + +#### 与其他模型的关系 + +- 与 `HookDescriptor`：按 `event` 和 `matcher` 选出命中的 hooks +- 与 `HookExecutionReport`：是报告的主键引用之一 + +#### 校验规则与不变量 + +- `payload` 必须与 `event` 对应的 schema 一致 +- 同一 `event_id` 不得重复执行两次正式 dispatch +- `source_owner` 必须和正式 event catalog 中定义的 owner 一致 + +#### 生命周期 / 状态变化 + +- `created -> dispatched -> settled -> reported` + +#### 映射关系 + +- `runtime/host trigger -> HookEventEnvelope -> dispatcher` + +### `HookEffect` + +- 用途：表达 hook 对当前流程施加的受约束影响 +- 类型：其他 +- 所属边界：hooks platform -> owner runtime/host +- 来源：hook handler 执行结果 +- 去向：`agent-runtime`、`host-session`、`plugin-host` 的 effect interpreter + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `effect_id` | `string` | 是 | - | 全局唯一 | effect 实例 id | +| `event_id` | `string` | 是 | - | 必须指向触发事件 | 来源事件 | +| `kind` | `"block" \| "cancel_turn" \| "transform_input" \| "augment_prompt" \| "mutate_payload" \| "override_tool_result" \| "resource_path" \| "model_hint" \| "diagnostic"` | 是 | - | 枚举 | effect 类型 | +| `target` | `string` | 是 | - | 非空 | 作用对象，如 tool/model/prompt/resources | +| `payload` | `serde_json::Value` | 是 | - | 必须符合 `kind` schema | effect 数据 | +| `terminal` | `boolean` | 是 | `false` | - | 是否短路后续处理 | +| `diagnostic_message` | `string` | 否 | `null` | 可为空 | 面向日志/观测的说明 | + +#### 与其他模型的关系 + +- 与 `HookExecutionReport`：报告中会汇总 effect 列表 +- 与 `PromptDeclaration`：`augment_prompt` 会被映射成 `PromptDeclaration` + +#### 校验规则与不变量 + +- effect 只能来自正式允许的 effect 集合 +- effect 不得直接写 durable truth +- `kind = "augment_prompt"` 时，必须能映射到既有 `PromptDeclaration` 或 `PromptGovernanceContext` +- `kind = "cancel_turn"` 时，`terminal` 必须为 `true`，且 `payload` 必须包含可对用户或上层宿主解释的终止原因 + +#### 生命周期 / 状态变化 + +- `emitted -> interpreted -> applied / rejected` + +#### 映射关系 + +- `HookEventEnvelope + HookDescriptor -> HookEffect[] -> owner interpreter` + +### `HookExecutionReport` + +- 用途：记录某次 hook 执行的结果，支撑 observability 与调试 +- 类型：事件 +- 所属边界：hooks platform observability；归属 hooks/runtime owner +- 来源：dispatcher +- 去向：日志、观测面板、调试导出、reload 诊断 + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `report_id` | `string` | 是 | - | 全局唯一 | 执行报告 id | +| `event_id` | `string` | 是 | - | 必须存在 | 对应触发事件 | +| `hook_id` | `string` | 是 | - | 必须存在 | 对应 hook | +| `status` | `"matched" \| "skipped" \| "succeeded" \| "blocked" \| "failed_open" \| "failed_closed"` | 是 | - | 枚举 | 执行结果 | +| `duration_ms` | `u64` | 是 | - | `>= 0` | 执行耗时 | +| `effects` | `HookEffect[]` | 是 | `[]` | - | 产出的 effect | +| `error_code` | `string` | 否 | `null` | 可为空 | 错误码 | +| `error_message` | `string` | 否 | `null` | 可为空 | 错误信息 | + +#### 与其他模型的关系 + +- 与 `HookEventEnvelope`：多条 report 可关联同一个 event +- 与 `HookDescriptor`：一条 report 只对应一个 hook + +#### 校验规则与不变量 + +- `status = "succeeded"` 时，`error_*` 应为空 +- `status` 为失败态时，必须遵守 `failure_policy` +- 报告属于观测事实，不属于 durable session truth + +#### 生命周期 / 状态变化 + +- `pending -> finalized -> exported` + +#### 映射关系 + +- `dispatcher result -> HookExecutionReport -> observability` + +### `AgentRuntimeExecutionSurface` + +- 用途：`host-session` 传给 `agent-runtime` 的最小执行面 +- 类型：内部核心模型 +- 所属边界：`host-session -> agent-runtime` +- 来源：`host-session` 根据当前 session 状态和 `PluginActiveSnapshot` 组装 +- 去向：`agent-runtime` turn loop + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `session_id` | `string` | 是 | - | 非空 | 当前会话 | +| `turn_id` | `string` | 是 | - | 非空 | 当前 turn | +| `agent_id` | `string` | 是 | - | 非空 | 当前 agent | +| `model_ref` | `string` | 是 | - | 非空 | 当前模型引用 | +| `provider_ref` | `string` | 是 | - | 非空 | 当前 provider 引用 | +| `tool_specs` | `CapabilitySpec[]` | 是 | `[]` | 名称唯一 | 生效工具集合 | +| `hook_snapshot_id` | `string` | 是 | - | 非空 | 绑定的 hooks snapshot | +| `prompt_declarations` | `PromptDeclaration[]` | 是 | `[]` | 可为空 | 初始 prompt 声明 | +| `prompt_governance` | `PromptGovernanceContext` | 否 | `null` | 可为空 | prompt 治理上下文 | +| `limits` | `ResolvedExecutionLimitsSnapshot` | 否 | `null` | 可为空 | 执行限制 | + +#### 与其他模型的关系 + +- 与 `PluginActiveSnapshot`：消费其中 tools/hooks/providers 的当前子集 +- 与 `PromptDeclaration`：直接复用既有 prompt 注入链路 + +#### 校验规则与不变量 + +- `agent-runtime` 只消费这个 surface，不自行做资源发现 +- 同一次 turn 内 `hook_snapshot_id` 必须稳定 +- 不得包含 process-local 句柄或锁对象 + +#### 生命周期 / 状态变化 + +- `assembled -> bound_to_turn -> consumed -> discarded` + +#### 映射关系 + +- `HostSessionSnapshot + PluginActiveSnapshot -> AgentRuntimeExecutionSurface` + +### `HostSessionSnapshot` + +- 用途：表示 `host-session` 持有的 session durable/read-model 视图 +- 类型：视图模型 +- 所属边界：`host-session` +- 来源：事件日志、投影、catalog、branch/fork 状态 +- 去向：对外查询、`AgentRuntimeExecutionSurface` 组装、design/read model + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `session_id` | `string` | 是 | - | 非空 | 会话 id | +| `working_dir` | `string` | 是 | - | 非空 | 工作目录 | +| `event_log_revision` | `u64` | 是 | - | 单调递增 | durable 版本 | +| `read_model_revision` | `u64` | 是 | - | 单调递增 | 投影视图版本 | +| `lineage_parent_session_id` | `string` | 否 | `null` | 可为空 | 父 session | +| `active_turn_id` | `string` | 否 | `null` | 最多一个 | 当前活动 turn | +| `mode_id` | `string` | 否 | `null` | 可为空 | 当前 mode | +| `observe_snapshot` | `SessionObserveSnapshot` | 否 | `null` | 可为空 | 对外观察视图 | +| `terminal_snapshot` | `TurnTerminalSnapshot` | 否 | `null` | 可为空 | 最近终态视图 | + +#### 与其他模型的关系 + +- 与 `AgentRuntimeExecutionSurface`：为 turn 组装提供 session 侧事实 +- 与 `SessionObserveSnapshot` / `TurnTerminalSnapshot`：直接复用既有查询模型 + +#### 校验规则与不变量 + +- durable truth 以事件日志为准 +- `active_turn_id` 最多一个 +- 所有派生视图必须可由 durable truth 恢复 + +#### 生命周期 / 状态变化 + +- `created -> active -> compacted -> forked / archived / deleted` + +#### 映射关系 + +- `event log -> HostSessionSnapshot -> query surface / AgentRuntimeExecutionSurface` + +### `SubRunHandle` + +- 用途：描述父 turn 与 child session/agent 之间的 durable 协作关系 +- 类型：关系模型 +- 所属边界：`host-session` +- 来源：父 session 发起子 agent、事件日志恢复、sub-run 生命周期推进 +- 去向：query/read model、协作取消、结果投递、observability + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `subrun_id` | `string` | 是 | - | 全局唯一 | 子运行 id | +| `parent_session_id` | `string` | 是 | - | 非空 | 父 session | +| `parent_turn_id` | `string` | 是 | - | 非空 | 发起该子运行的父 turn | +| `child_session_id` | `string` | 是 | - | 非空 | 子 session | +| `child_agent_id` | `string` | 是 | - | 非空 | 子 agent | +| `status` | `"queued" \| "running" \| "succeeded" \| "failed" \| "cancelled"` | 是 | - | 枚举 | 当前状态 | +| `input_delivery_state` | `"pending" \| "delivered" \| "acknowledged"` | 是 | `pending` | 枚举 | 子输入投递状态 | +| `result_delivery_state` | `"pending" \| "delivered" \| "dropped"` | 是 | `pending` | 枚举 | 结果回传状态 | +| `spawn_reason` | `string` | 否 | `null` | 可为空 | 发起原因或能力说明 | +| `started_at_ms` | `u64` | 否 | `null` | 可为空 | 启动时间 | +| `finished_at_ms` | `u64` | 否 | `null` | 可为空 | 结束时间 | + +#### 与其他模型的关系 + +- 与 `HostSessionSnapshot`：父/子 session 的 durable truth 都由 host 持有 +- 与 `InputQueueProjection`：输入投递和回传依赖 queue read model + +#### 校验规则与不变量 + +- 一个 `SubRunHandle` 只能绑定一个父 turn 和一个 child session +- child session 仍然是完整 session，因此必须满足“一个 session 即一个 agent” +- durable truth 以事件日志为准，`SubRunHandle` 必须可由事件恢复 + +#### 生命周期 / 状态变化 + +- `queued -> running -> succeeded / failed / cancelled` + +#### 映射关系 + +- `spawn request -> SubRunHandle -> query/cancel/result-delivery` + +### `InputQueueProjection` + +- 用途：描述某个 session/agent 当前待处理输入的 read model，包括协作输入投递状态 +- 类型：视图模型 +- 所属边界：`host-session` +- 来源：事件日志、输入入队/出队、sub-run 投递 +- 去向：host 调度、协作恢复、观测与调试 + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `session_id` | `string` | 是 | - | 非空 | 所属 session | +| `queue_depth` | `u32` | 是 | `0` | `>= 0` | 当前队列长度 | +| `pending_input_ids` | `string[]` | 是 | `[]` | 保持顺序 | 待处理输入 id 列表 | +| `head_input_kind` | `"user" \| "parent_subrun" \| "follow_up"` | 否 | `null` | 枚举 | 队头输入类型 | +| `last_enqueued_input_id` | `string` | 否 | `null` | 可为空 | 最近入队输入 | +| `last_delivered_input_id` | `string` | 否 | `null` | 可为空 | 最近已投递输入 | +| `blocked_by_subrun_id` | `string` | 否 | `null` | 可为空 | 当前阻塞此 queue 的 subrun | +| `updated_at_ms` | `u64` | 是 | - | 单调时间戳 | 最近更新时间 | + +#### 与其他模型的关系 + +- 与 `SubRunHandle`：sub-run 输入投递与结果回传会改变队列视图 +- 与 `AgentRuntimeExecutionSurface`：只有当 host 从 queue 中取出输入后，runtime 才会消费对应 turn + +#### 校验规则与不变量 + +- 输入队列属于 session durable truth 的派生读模型，而不是 runtime 内部缓存 +- 任意一次服务重启后，都必须能通过事件日志恢复 `InputQueueProjection` +- runtime 不得直接突变 queue，所有变更都经由 `host-session` + +#### 生命周期 / 状态变化 + +- `empty -> pending -> delivering -> settled` + +#### 映射关系 + +- `input events + subrun delivery events -> InputQueueProjection -> host dispatch` + +## 兼容性与迁移 + +- 本次是明确的 breaking change： + - 旧 `application::App` 不再保留 + - 旧 `kernel` crate 不再保留 + - 旧 `core` 作为“大而全 DTO/trait 仓库”的定位不再保留 + - 旧 monolith `session-runtime` 对外 surface 不再作为长期正式边界 + - 旧窄版 `PluginManifest` / `core::HookInput` / `HookOutcome` 不足以表达新系统，需要迁移到新的 descriptor / envelope / effect 模型 +- 不保留长期兼容 DTO 壳层： + - `PluginDescriptor` 直接成为 `plugin-host` 的正式插件描述模型 + - `HookDescriptor + HookEventEnvelope + HookEffect` 直接成为新的 hooks 边界模型 + - owner 专属 DTO 直接迁回 owner crate，不保留 `core` 中转层 +- 迁移顺序建议： + - 先引入新模型并仅在新 crate 内消费 + - 再迁移旧 owner 的实现 + - 最后删除旧的 `application`、`kernel` 与 monolith `session-runtime` +- `SubRunHandle`、`InputQueueProjection` 与协作 executor 合同优先通过 `host-session` owner bridge 对外暴露；`ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` 暂不迁出 `core`，直到 durable event wire schema 可以独立表达该嵌入结构。 + +## 复用说明 + +- 继续复用的现有模型： + - `CapabilitySpec` + - `PromptDeclaration` + - `PromptGovernanceContext` + - `SessionObserveSnapshot` + - `TurnTerminalSnapshot` +- 复用理由： + - 它们已经是纯数据模型，且能直接服务新边界 + - 特别是 prompt augment 不需要新建平行 DTO，沿用 `PromptDeclaration` 更干净 +- 不继续复用的现有模型： + - 旧 `PluginManifest`：贡献面太窄 + - 旧 `HookInput` / `HookOutcome`：事件面和 effect 面都太窄，只覆盖 tool/compact + - 旧 `ports.rs`、`projection`、`session_catalog`、`workflow`、`mode` 中的大量 owner 模型：它们不适合继续保留在 `core` + +## 补充贡献描述模型 + +以下贡献描述模型作为 `PluginDescriptor` 的正式子结构存在，由 `plugin-host` 统一校验与聚合，不再拥有独立的长期发现合同，也不再进入 `core`。 + +这些模型在本 change 中先锁定关键字段、约束与 owner 归属；完整字段表在实现 PR 中结合现有代码与 wire 需求定稿。 + +### `ProviderDescriptor` + +- 用途：描述 provider 贡献与模型目录 +- 关键字段： + - `provider_id` + - `display_name` + - `api_kind` + - `base_url` + - `auth_scheme` + - `models` + - `timeout_ms` + - `retry_policy` + - `capabilities` +- 约束： + - `provider_id` 在一个 active snapshot 中唯一 + - `models` 必须是纯数据目录，不得夹带运行时句柄 + +### `ResourceDescriptor` + +- 用途：描述技能、模板、主题、命令目录之外的原始资源入口 +- 关键字段： + - `resource_id` + - `kind` + - `locator` + - `scope` + - `watch_mode` + - `visibility` + - `metadata` +- 约束： + - `locator` 必须可解析 + - `kind` 只能落在正式注册的资源种类中 + +### `CommandDescriptor` + +- 用途：描述 slash/命令能力 +- 关键字段： + - `command_id` + - `display_name` + - `description` + - `argument_schema` + - `entry_ref` + - `permission_profile` + - `interaction_mode` +- 约束： + - `entry_ref` 必须指向可执行入口 + - `argument_schema` 必须可序列化、可校验 + +### `ThemeDescriptor` + +- 用途：描述主题贡献 +- 关键字段： + - `theme_id` + - `display_name` + - `extends` + - `tokens` + - `metadata` +- 约束： + - `tokens` 必须是纯数据 token 集 + - `extends` 若存在，必须引用当前 snapshot 中可解析的主题 + +### `PromptDescriptor` + +- 用途：描述 prompt 模板贡献 +- 关键字段： + - `prompt_id` + - `display_name` + - `description` + - `argument_schema` + - `scope` + - `body` + - `metadata` +- 约束： + - `body` 必须可安全渲染 + - `scope` 必须落在正式 prompt 作用域中 + +### `SkillDescriptor` + +- 用途：描述 skill 贡献 +- 关键字段： + - `skill_id` + - `display_name` + - `description` + - `allowed_tools` + - `entry_ref` + - `lazy_load` + - `metadata` +- 约束： + - `allowed_tools` 只能引用当前 snapshot 中存在的工具 + - `entry_ref` 必须指向可加载内容 + +## 未决问题 + +无。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/proposal.md b/openspec/changes/plugin-first-runtime-rearchitecture/proposal.md new file mode 100644 index 00000000..e4776d42 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/proposal.md @@ -0,0 +1,342 @@ +## 背景 + +Astrcode 当前的 `session-runtime`、`application`、`server bootstrap` 都承担了过多职责。`session-runtime` 不只是 turn loop，还同时暴露 session catalog、conversation replay、query/read model、child lineage、mode state 等宿主能力；`application` 仍然直接知道 `CapabilityRouter` 和 runtime 提交结构；`server` 则继续手工拼接 builtin tools、agent tools、MCP、plugin、governance、mode catalog 等多套事实源。 + +这种结构不适合继续往“核心最小化，一切可扩展”演进。即使再叠加 hooks，也只会得到一个更复杂的大核心。与此同时，仓库已经有 hooks 平台与 governance prompt hooks 的历史提案，它们实际上已经证明：Astrcode 更需要的是统一扩展总线，而不是更多 plan/workflow 特判。 + +本次变更的目标，是把 Astrcode 重构为更接近 `pi-mono` 的分层：核心只保留最小 `agent-runtime`；session 持久化、branch/fork、resource discovery、settings、workflow、governance 等上移到 `host-session` 与 `plugin-host`；builtin 与 external 功能统一通过 plugin / hooks 提供，不再维持多套并行事实源。 + +同时，`crates/core` 本身也要收缩。它不再继续充当“所有 DTO 和 trait 的总仓库”，而是退回成极薄的共享语义层，只保留真正跨 owner 复用的值对象、消息模型和稳定语义。凡是只被某一个 owner 使用的 DTO、快照、恢复模型、registry、配置或 ports，都应该迁回各自的 owner crate，而不是继续堆在 `core`。 + +## 目标 + +- 将运行时核心收缩到新 `agent-runtime` crate，只保留“单 session / 单 agent loop + provider 调用 + tool dispatch + hook dispatch + 流式状态机”这一最小边界。 +- 建立新 `host-session` crate，承接事件日志、恢复、branch/fork、session catalog、query/read model 与对外 use-case surface。 +- 建立统一的 plugin-first host：builtin 与 external 统一进入同一 registry、active snapshot 与 reload 语义，不再由 server 手工拼接多条特例路径。 +- 将正在推进的 hooks 系统直接升级为统一扩展总线，而不是再做一套平行扩展机制。 +- 删除 `application` crate，把其职责按新边界重新分配，而不是保留兼容 façade。 +- 收缩 `core` crate，只保留真正跨边界共享的语义和最小合同，不再把 owner 专属 DTO 继续放进 `core`。 +- 保留并重构多 agent 协作，但继续沿用“一个 session 即一个 agent”的原理：父子 agent 关系、sub-run lineage、输入队列、结果投递与取消语义统一归 `host-session` 管理，`agent-runtime` 只负责最小执行入口。 +- 借鉴 `pi-mono` 的 session-as-agent 思路：对外暴露给 LLM、CLI 或扩展的协作能力通过 plugin/tool/command surface 进入系统，但 session durable truth 与协作状态始终由 `host-session` owner 持有。 +- 保持 `server` 作为唯一组合根、保持 DTO / 协议层纯数据、保持事件日志优先的持久化原则，但不再让这些约束继续膨胀 runtime core。 +- 同步更新 `PROJECT_ARCHITECTURE.md`，让新边界成为仓库级权威约定。 + +## 非目标 + +- 不保留旧 crate 结构、旧 API、旧 `application` façade 或旧装配路径的向后兼容壳层。 +- 不要求逐字复刻 `pi-mono` 的所有产品能力；本次借鉴的是“最小核心 + 扩展优先”的分层方法，不是照抄它的 Slack、TUI、theme 或 package 生态。 +- 不在本 change 内重做前端交互模型；前端只跟随后端新边界做必要适配。 +- 不把所有 builtin 功能都强行外置为子进程 plugin；热路径能力允许以内建 plugin 形态存在。 + +## 变更内容 + +- **BREAKING**：新建 `agent-runtime` crate，承接当前 `session-runtime` 中的最小 live runtime 核心；旧 `session-runtime` 的“大一统”职责将被拆解，不保留长期兼容壳层。 +- **BREAKING**：新建 `host-session` crate，承接事件日志、恢复、branch/fork、session catalog、query/read model 与外部 use-case surface。 +- **BREAKING**：多 agent 协作相关的 `SubRunHandle`、父子 session lineage、input queue、subrun finished/cancel 持久化与结果投递，从 `core + application + session-runtime` 的分散结构收敛到 `host-session`；不再保留跨三层拼装的历史布局。 +- **BREAKING**：删除 `application` crate。原有用例编排、治理、模式、workflow、MCP、observability 等职责按新边界重分配到 `host-session`、`plugin-host`、`server` 或对应 owner crate，不保留兼容 façade。 +- **BREAKING**：删除 `kernel` crate。原先由 `kernel` 承担的 provider/tool/resource 聚合职责拆回 `core` 纯合同、`agent-runtime` 执行面和 `host-session` 装配面，不保留独立门面。 +- 新增统一 `plugin-host` 能力层，负责 builtin / external plugin 的注册、active snapshot、reload、resource discovery 与贡献合并。 +- 统一 plugin descriptor 到完整贡献面，至少覆盖： + - `tools` + - `hooks` + - `providers` + - `resources` + - `commands` + - `themes` + - `prompts` + - `skills` +- 将 hooks 系统升格为统一扩展总线，事件面至少覆盖： + - `input` + - `context` + - `before_agent_start` + - `before_provider_request` + - `tool_call` + - `tool_result` + - `turn_start` + - `turn_end` + - `session_before_compact` + - `resources_discover` + - `model_select` +- 将 governance prompt hooks 并入统一 hooks 总线，继续通过既有 `PromptDeclaration` / `PromptGovernanceContext` 链路进入 prompt 组装，不再新增平行 prompt 渲染系统。 +- 将 builtin tools、MCP bridge、workflow overlay、governance 行为、resource discovery 等产品能力逐步迁移为 builtin plugins，由统一 registry 与 hooks 总线驱动。 +- 将 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree` 这类协作能力逐步迁移为 builtin plugin tools/commands；这些 surface 只负责发起协作动作，不持有 collaboration durable truth。 +- 更新 `PROJECT_ARCHITECTURE.md` 以及相关 OpenSpec，明确新分层、owner、依赖方向、迁移顺序与失败语义。 + +## 能力变更 + +### 新增能力 +- `agent-runtime-core`: 定义最小 `agent-runtime` 的边界、输入输出、tool/provider/hook 调度、流式与取消语义。 +- `host-session-runtime`: 定义 `host-session` 的事件日志、恢复、branch/fork、session catalog、query/read model 与 host use-case surface。 +- `plugin-host-runtime`: 定义统一 builtin / external plugin host、active snapshot、resource discovery、reload 与贡献合并规则。 +- `lifecycle-hooks-platform`: 定义统一 hooks 总线、事件分发语义、effect 约束，以及 builtin / external hooks 共享的注册与执行模型。 +- `core-boundary-slimming`: 定义 `core` 的收缩边界，移除 owner 专属 DTO、registry、projection、workflow、mode、plugin manifest 和 mega ports。 + +### 修改能力 +- `session-runtime`: 旧的“大一统 session-runtime”被拆解，不再作为单一能力 owner 继续存在。 +- `application-use-cases`: 删除 `application` crate，原有 use-case 语义迁移到 `host-session`、`plugin-host` 与 `server` 的新边界。 +- `plugin-integration`: 从能力调用桥升级为统一 plugin 贡献面，支持 hooks、providers、resources、prompts、commands 等更宽的扩展面。 +- `turn-orchestration`: turn loop 只负责 prompt -> provider -> tool/hook dispatch -> stop/continue，不再直接承载 workflow / governance / discovery 特判。 +- `session-persistence`: 事件日志、恢复、branch/fork、read model 的 owner 上移到 host-session 层，与最小 runtime core 解耦。 +- `tool-and-skill-discovery`: 资源发现改由 plugin-host / resource discovery 统一驱动，并扩展到 commands、themes、prompts、skills 等完整贡献面。 +- `core-semantics`: `core` 不再承载 session 恢复快照、projection、workflow/mode、plugin registry、配置持久化 ports 等 owner 专属内容，只保留共享值对象和稳定语义。 + +## 影响范围 + +- 受影响模块 + - `PROJECT_ARCHITECTURE.md` + - `crates/agent-runtime/*` + - `crates/host-session/*` + - `crates/session-runtime/*` + - `crates/application/*` + - `crates/kernel/*` + - `crates/server/src/bootstrap/*` + - `crates/core/src/agent/*` + - `crates/application/src/agent/*` + - `crates/plugin/*` + - `crates/sdk/*` + - `crates/core/src/hook.rs` + - `crates/core/src/plugin/*` + - `crates/protocol/src/plugin/*` + - `adapter-*` 中与 builtin tools、MCP、skills、prompt、agents 发现相关的 owner +- 使用方式影响 + - 对用户来说，最终目标是保持“同一产品能力仍可用”，但底层不再区分“核心特判”和“扩展提供”两套实现路径。 + - 对开发者来说，新增内建能力时不再默认改 `application` 或 `server bootstrap` 主链，而是优先通过 builtin plugin / hooks 扩展面接入。 +- 架构影响 + - 本次 proposal 与当前 `PROJECT_ARCHITECTURE.md` 对 `session-runtime` 的定义存在冲突，因此必须先更新架构文档，再推进实现。 + - `server` 仍然是唯一组合根，但它的职责会收缩为“装配 `agent-runtime` / `host-session` / `plugin-host` / adapters”，而不是继续作为多套事实源的手工缝合处。 + +## 旧架构保留内容 + +以下内容来自旧 `session-runtime` / `core` / `server` 的已验证实现，必须原样或等价迁入新架构，不做重新设计。 + +### 事件模型（core → host-session 保留） + +- `StorageEvent` / `StorageEventPayload` / `StoredEvent`：append-only JSONL 事件体系。 + - 20+ 种事件变体（SessionStart, UserMessage, AssistantDelta/Final, ToolCall/Delta/Result, ToolResultReferenceApplied, PromptMetrics, CompactApplied, SubRunStarted/Finished, ChildSessionNotification, AgentCollaborationFact, ModeChanged, TurnDone, AgentInputQueued/BatchStarted/BatchAcked/InputDiscarded, Error）。 + - `storage_seq` 单调递增，由 session writer 独占分配。 + - `AgentEventContext` 携带 agent 谱系（root / sub-run / fork / resume），支持跨 session lineage 追踪。 + - 校验规则：SessionStart 禁止 turn_id 和 agent 上下文；SubRun 事件要求 child_session_id。 +- 这些类型全部保留在 `core`（因为它们是跨 owner 共享的持久化语义），不迁入 host-session。 + +### 持久化合同（core → host-session 消费） + +- `EventLogWriter`：append-only 同步写入器，`append(&mut self, &StorageEvent) -> StoreResult`。 +- `EventStore`：异步追加，`append(&self, session_id: &SessionId, event: &StorageEvent) -> Result`。 +- `SessionManager`：会话生命周期管理（create_event_log, open_event_log, replay_events, try_acquire_turn, last_storage_seq, list/delete）。 +- `SessionTurnLease`：跨进程 turn 执行租约（RAII 语义，Drop 时释放锁）。 +- `SessionTurnAcquireResult`：Acquired / Busy，Busy 时返回当前 turn_id 和 owner_pid，支持自动分叉。 +- `FileSystemSessionRepository`：基于文件系统的实现（JSONL + 文件锁）。 +- 这些 trait 保留在 `core`；`host-session` 通过 `Arc` / `Arc` 消费。 + +### SessionState 投影与广播（session-runtime/state → host-session 迁入） + +- `ProjectionRegistry`：增量投影，对每条 StoredEvent 做 `apply()` 更新投影状态（AgentState、turn 投影、child nodes、active tasks、input queue、mode state）。 + - `from_recovery()`：从 checkpoint + tail events 重建完整投影。 + - `snapshot_projected_state()` → `AgentState`（messages, phase, turn_count, mode_id）。 +- `SessionState`：组合 projection + writer + 双通道广播。 + - `append_and_broadcast(event, translator)`：append → apply → translate → broadcast，这是事件写入的唯一生产路径。 + - `translate_store_and_cache(stored, translator)`：validate → apply projection → translate to AgentEvent → cache records。 + - 双通道广播：`SessionEventRecord`（durable，含 storage_seq，用于 SSE 断点续传）和 `AgentEvent`（live，token 级 delta 等瞬时事件）。 +- `EventTranslator`：StorageEvent → AgentEvent 转换器，按 phase 过滤 sub-run 事件。 +- **整块迁入 host-session**，这是 host-session 作为 session truth owner 的核心机制。 + +### 恢复模型（session-runtime → host-session 迁入） + +- `SessionRecoveryCheckpoint`：持久化的恢复快照，包含 `AgentState` + `ProjectionRegistrySnapshot` + `checkpointStorageSeq`。 + - 包含 `childNodes`（ChildSessionNode 索引）、`activeTasks`（任务跟踪）、`inputQueueProjectionIndex`（输入队列投影）。 + - 支持从旧格式 checkpoint 迁移（字段兼容性）。 +- 恢复流程：`SessionState::from_recovery(writer, checkpoint, tail_events)` → validate tail events → apply to ProjectionRegistry → cache records → 初始化广播通道。 +- **迁入 host-session/recovery.rs**。 + +### Turn 执行模型（session-runtime/turn → agent-runtime 迁入） + +- `run_turn(kernel, TurnRunRequest)` → `TurnRunResult`：turn 主循环。 + - 输入：session_id, working_dir, turn_id, messages, event_store, session_state, cancel token, agent context, prompt declarations, capability router, prompt governance。 + - 循环：`run_single_step()` → `StepOutcome::Continue(transition)` / `StepOutcome::Completed(stop_cause)` / `StepOutcome::Error`。 + - 每步结束后 `flush_pending_events()` 批量写入事件日志。 + - 取消时写入 TurnDone(Cancelled) 后退出。 +- `TurnRunRequest` 的装配目前散在 `session-runtime` 和 `application` 中。 +- **核心循环迁入 agent-runtime**；TurnRunRequest 的装配（从哪拿 provider、tools、hooks）由 host-session 提供。 + +### Server 组合根（server/bootstrap → 保留并简化） + +- `ServerBootstrapOptions`：可覆盖选项（home_dir, working_dir, plugin_search_paths, enable_profile_watch, watch_service_override），支持测试注入。 +- `ServerBootstrapPaths`：从 options 解析路径（config_path, mcp_approvals_path, plugin_skill_root, projects_root, plugin_search_paths）。 +- profile watch runtime：监听 agent profile 变更，触发 hot reload。 +- MCP warmup：后台任务预热 MCP 连接。 +- **保留组合根模式，但内部实现从”手工拼接多套事实源”改为”装配 plugin-host → host-session → agent-runtime”**。 + +### 其他保留机制 + +- `ToolSearchIndex`：工具搜索索引，由 adapter-tools 提供。 +- `PromptFactsProvider` / `PromptProvider`：prompt 事实来源。 +- `GovernanceSurfaceAssembler` / `AppGovernance`：治理面组装。 +- `CapabilitySurfaceSync`：能力同步（目前用于 external invokers 变更时同步到 router）。 +- config 覆盖层（用户级 → 项目级）、agent profile 解析、mode catalog。 + +## 新架构详细设计 + +### host-session 事件日志集成 + +host-session 作为 session truth owner，通过以下机制接入事件日志： + +``` +HostSession 持有: + Arc ← 由 server 注入 + Arc ← 由 server 注入 + sessions: DashMap> + +LoadedSession 持有: + SessionState ← 包含 ProjectionRegistry + SessionWriter + 双通道广播 + SessionActor ← 消息驱动的 turn 调度 + +事件写入流: + agent-runtime 产生 StorageEvent + → host-session 通过回调收到事件 + → SessionState.append_and_broadcast(event, translator) + → SessionWriter.append(event) ← 持久化到 JSONL + → ProjectionRegistry.apply(stored) ← 更新投影状态 + → EventTranslator.translate(stored) ← 转换为 AgentEvent + → broadcaster.send(record) ← durable 广播 + → live_broadcaster.send(agent_event) ← live 广播 +``` + +host-session 对 agent-runtime 只暴露一个事件发射回调，agent-runtime 不直接接触 EventStore 或 SessionWriter。 + +### host-session 恢复流 + +``` +恢复一个 session: + 1. SessionManager.open_event_log(session_id) → EventLogWriter + 2. SessionManager.last_storage_seq(session_id) → seq + 3. 读取 checkpoint 文件 → SessionRecoveryCheckpoint + 4. 从 checkpoint.checkpointStorage_seq 之后 replay tail events + 5. SessionState::from_recovery(writer, checkpoint, tail_events) + 6. 注册到 HostSession.sessions +``` + +如果 checkpoint 不存在或损坏，从第一条事件开始全量 replay（现有行为保留）。 + +### agent-runtime 执行流 + +``` +AgentRuntime.execute_turn(TurnInput) → TurnOutput: + 1. 从 TurnInput 取出 agent-runtime 执行面： + - session_id, turn_id, agent_id + - model_ref, provider_ref + - tool_specs: Vec ← 来自 plugin-host active snapshot + - hook_snapshot_id: String ← 来自 plugin-host active snapshot + 2. 通过 TurnLoop 循环执行： + - prompt assembly（消费 prompt_declarations + prompt_governance） + - provider request（通过 provider_ref 路由到具体 LLM 实现） + - tool dispatch（通过 tool_specs 匹配，调用 plugin-host 的 dispatch） + - hook dispatch（通过 hook_snapshot_id 查找注册的 hooks） + - 每步通过 emit_event 回调发出 StorageEvent + - stop/continue/continue_with_tool_result 判断 + 3. 返回 TurnOutput（session_id, turn_id, agent_id, terminal_kind） +``` + +agent-runtime 的关键设计：**不持有任何有状态资源**。不持有 EventStore、不持有 plugin registry、不持有 session state。所有有状态依赖通过 TurnInput 传入或通过回调发出。这使得同一个 AgentRuntime 实例可以安全地并发执行多个 session 的 turn。 + +### server 组合根新设计 + +```rust +// 新 bootstrap_server_runtime 伪代码 +pub async fn bootstrap_server_runtime_with_options(options: ServerBootstrapOptions) -> Result { + // 1. 路径和配置（保留现有） + let paths = ServerBootstrapPaths::from_options(&options)?; + let config_service = build_config_service(paths.config_path)?; + let resolved_config = config_service.load_overlayed_config(...)?; + + // 2. plugin-host：统一注册表替代手工拼接 + let plugin_host = Arc::new(PluginHost::new()); + let builtin_descriptors = build_builtin_descriptors(&config_service, &paths)?; + let loader = PluginLoader::new(paths.plugin_search_paths.clone()); + let reload = plugin_host.reload_with_builtin_loader_and_capabilities( + builtin_descriptors, + &loader, + &mcp_capabilities, + ).await?; + // reload.snapshot 包含所有 tools/hooks/providers/resources + // reload.builtin_backends 包含内置插件句柄 + // reload.external_backends 包含外部插件进程 + + // 3. host-session：session truth owner + let event_store: Arc = Arc::new(FileSystemSessionRepository::new_with_projects_root(paths.projects_root)); + let host_session = Arc::new(HostSession::new(event_store, plugin_host.active_snapshot())); + + // 4. agent-runtime：最小执行内核 + let agent_runtime = Arc::new(AgentRuntime::new()); + + // 5. 组装完成 + // host_session 持有 event_store + plugin_host 的 active snapshot + // agent_runtime 通过 TurnInput 获取执行所需的一切 + // server 只负责装配这三者，不再手工拼接多套 invoker + + ServerRuntime { host_session, plugin_host, agent_runtime, governance, handles } +} +``` + +**核心改变**：旧 `bootstrap_server_runtime` 中手工拼接 core_tool_invokers + agent_tool_invokers + mcp_invokers + plugin_invokers + capability_sync 的 200 行代码，全部被 `plugin_host.reload_with_builtin_loader_and_capabilities()` 一个调用替代。builtin tools、agent tools、MCP tools、plugin tools 全部通过 `PluginDescriptor` 进入同一个 `PluginRegistry`，产出统一的 `PluginActiveSnapshot`。 + +### 多 agent 协作在新架构中的归属 + +``` +协作行为: + spawn_child_session → host-session.HostSession.spawn_child_session() + send_to_child → host-session.HostSession.send_to_child() + send_to_parent → host-session.HostSession.send_to_parent() + observe_subtree → host-session.HostSession.observe_subtree() + terminate_subtree → host-session.HostSession.terminate_subtree() + +协作 durable truth: + SubRunHandle → host-session.collaboration.SubRunHandle + InputQueueProjection → host-session.input_queue.InputQueueProjection + SubRunStarted/Finished 事件 → 通过 host-session 的事件日志持久化 + +协作入口: + spawn_agent / send_to_child 等作为 builtin plugin tools 注册到 plugin-host + 它们只负责发起动作，不持有 collaboration durable truth + +agent-runtime 的职责: + 只执行 child session 的 turn loop + 不感知父子关系、不感知 input queue、不感知协作状态 + 所有协作上下文通过 TurnInput.agent 中的 AgentEventContext 传入 +``` + +### hooks 统一扩展总线 + +``` +事件面（来自旧 core::hook + 新增）: + input ← 用户输入到达 + context ← prompt 组装前 + before_agent_start ← turn 开始前 + before_provider_request ← LLM 请求前 + tool_call ← 工具调用前后 + tool_result ← 工具结果返回 + turn_start ← turn 开始 + turn_end ← turn 结束 + session_before_compact ← compact 前 + resources_discover ← 资源发现 + model_select ← 模型选择 + +注册: + 通过 PluginDescriptor.hooks 注册到 plugin-host + builtin plugin 和 external plugin 使用相同 HookDescriptor + +执行语义: + 顺序分发 / 可取消 / 可拦截 / 可修改 / 管道式 / 短路式 + （借鉴 pi-mono ExtensionRunner 的分发模式） + +governance prompt hooks: + 继续通过 PromptDeclaration / PromptGovernanceContext 进入 prompt 组装 + 不新增平行 prompt 渲染系统 +``` + +## 约束与风险 + +- 当前架构权威文档与目标方向冲突，如果不先更新 `PROJECT_ARCHITECTURE.md`，后续实现会持续处于”代码和架构文档互相打架”的状态。 +- 项目要求事件日志优先，因此不能简单抛弃 event-sourcing；更合理的做法是把事件日志与 read model 上移到 host-session 层，而不是继续强绑在 runtime core。 +- builtin plugin 与 external plugin 必须共享统一 descriptor 和 active snapshot，但不能共享完全相同的性能模型；热路径必须允许进程内 builtin plugin。 +- hooks 一旦成为统一扩展总线，就必须明确稳定顺序、失败语义、effect 约束与 observability；否则会把当前特判分支换成更难理解的隐式行为。 +- 这是一次大范围 breaking refactor，会同时触及 crate 边界、协议、测试与架构守卫；实现必须按阶段迁移，但阶段迁移不等于保留长期兼容层。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/research.md b/openspec/changes/plugin-first-runtime-rearchitecture/research.md new file mode 100644 index 00000000..30dce921 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/research.md @@ -0,0 +1,421 @@ +## 调研目标 + +- 评估 Astrcode 是否应该从当前的 `session-runtime + application + kernel + server bootstrap` 结构，重构为更接近 `pi-mono` 的“最小运行时核心 + plugin-first host + hooks 总线”架构。 +- 回答三个核心问题： + - 现在的 `session-runtime`、`application`、`plugin/sdk` 各自承担了什么职责，哪里已经出现边界漂移。 + - 现有 hooks 方向与 `pi-mono` 的扩展系统，哪些可以直接借鉴，哪些不能直接照搬。 + - 在“不做向后兼容”的前提下，哪种重构方向最符合仓库当前约束。 +- 本次调研范围聚焦后端运行时与扩展层，不展开前端 UI 或协议细节重做。 + +## 当前现状 + +### 相关代码与模块 + +- `PROJECT_ARCHITECTURE.md` + - 当前架构权威文档明确把 `session-runtime` 定义为“单会话执行引擎和事实边界”，并要求它内部同时承载事件溯源层、运行时状态层、外部接口层。 + - 文档还明确要求 `server` 是唯一组合根，`application` 是业务编排层，`plugin` 是宿主侧插件运行时。 +- `crates/session-runtime/src/lib.rs` + - `SessionRuntime` 当前公开了大量“上层宿主能力”而不只是 turn loop：`list_sessions`、`list_session_metas`、`create_session`、`create_child_session`、`observe`、`conversation_snapshot`、`conversation_stream_replay`、`session_child_nodes`、`session_mode_state`、`active_task_snapshot`、`replay_stored_events`、`wait_for_turn_terminal_snapshot` 等。 + - 这说明它已经不是“薄 runtime core”，而是 runtime + session service façade + query/read model 入口的组合。 +- `crates/session-runtime/src` + - 当前共有 79 个源码文件，这个数量级本身就说明它不是“最小 turn 执行内核”，而是一整个宿主系统。 +- `crates/application/src/lib.rs` + - `App` 持有 `governance_surface`、`mode_catalog`、`workflow_orchestrator`、`mcp_service`、`agent_service` 等多个高层组件。 + - `application` 还直接 re-export 了大量 `astrcode_session_runtime`、`astrcode_kernel`、`astrcode_core` 类型，说明它并没有完全退到稳定 host 边界后面。 +- `crates/application/src/ports/session_submission.rs` + - `AppAgentPromptSubmission` 中仍然直接包含 `astrcode_kernel::CapabilityRouter`。 + - 同时存在 `impl From for astrcode_session_runtime::AgentPromptSubmission`，说明 `application -> runtime` 之间仍存在具体结构泄漏。 +- `crates/server/src/bootstrap/runtime.rs` + - 当前组合根显式区分并组装多条事实源：`core builtin tools`、`agent tools`、`MCP invokers`、`plugin invokers`、`plugin modes`、`governance surface`、`capability sync`、`runtime coordinator`。 + - 这是一种“server 手工拼接多条特例路径”的模型，而不是 plugin-first 的统一注册表模型。 +- `crates/sdk/src/lib.rs`、`crates/sdk/src/hook.rs` + - 当前 SDK 暴露的核心能力主要是 `ToolHandler`、`HookRegistry` / `PolicyHookChain`、`PluginContext`、`StreamWriter`。 + - 这套能力足够支撑“工具 + 少量策略 hook”，但还不足以表达统一扩展系统里的 provider、resource、prompt、command、shortcut、resource discovery 等贡献面。 +- `crates/plugin/src/lib.rs` + - 当前插件系统的核心仍是“插件进程管理 + JSON-RPC capability bridge + stdio streaming”。 + - 它更像“能力调用基础设施”，还不是一套完整的 plugin host。 +- `crates/core/src/lib.rs` + - 当前 `core` 导出了大约 120 个公开类型与 trait，且 `crates/core/src` 下共有 58 个源码文件。 + - 其中混杂了共享值对象、ports、projection、workflow、mode、plugin registry、session catalog、observability、config 等多类 owner 专属内容。 +- `crates/kernel/src/lib.rs` + - `kernel` 当前主要只是重新导出 `KernelBuilder`、`KernelGateway`、`CapabilityRouter`、`SurfaceManager`、`EventHub` 等聚合/路由对象。 + - 结合 `kernel/src/kernel.rs` 可见它本质上更接近一个 service locator / provider aggregator，而不是拥有独立业务真相的正式架构层。 +- `crates/server/src/bootstrap/providers.rs` + - 当前 `ConfigBackedLlmProvider` 明确拒绝 `provider_kind != openai` 的配置，并在运行时只实例化 `OpenAiProvider`。 + - 这说明 Astrcode 虽然有 `LlmProvider` trait，但当前产品级 provider 抽象仍明显偏薄，尚未形成 plugin-first 的 provider registry。 +- 多 agent 协作相关实现 + - `crates/core/src/agent/` 当前已经包含 `SubRunHandle`、`CollaborationExecutor`、`SubAgentExecutor`、`InputQueueProjection` 等协作模型和合同。 + - `crates/application/src/agent/` 当前包含 `AgentOrchestrationService`、`launch_subagent`、`subrun_event_context` 等编排逻辑。 + - `crates/session-runtime/src/turn/` 与 `crates/session-runtime/src/state/` 当前包含 `subrun_events`、`persist_subrun_finished_event`、`cancel_subruns_for_turn`、`input_queue`、`query/subrun` 等持久化与查询路径。 + - 这说明 Astrcode 还有一条 `pi-mono` 本身没有的“多 agent 协作”主线，而且它现在横跨 `core`、`application`、`session-runtime` 三层。 +- 既有 hooks 相关提案 + - `openspec/changes/archive/2026-04-21-introduce-hooks-platform-crate/proposal.md` + - `openspec/changes/archive/2026-04-21-introduce-hooks-platform-crate/specs/lifecycle-hooks-platform/spec.md` + - `openspec/changes/archive/2026-04-21-extract-governance-prompt-hooks/proposal.md` + - 这些历史提案已经把方向指向“独立 hooks 平台 + 复用 `PromptDeclaration` 注入链路”，说明仓库内部其实已经出现了朝 plugin-first / hook-first 演进的前置设计。 +- `pi-mono` 参考实现 + - `D:/GitObjectsOwn/pi-mono/packages/agent/src/agent.ts` + - `D:/GitObjectsOwn/pi-mono/packages/agent/src/types.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/extensions/loader.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/extensions/runner.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/agent-session.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/resource-loader.ts` + - 这些文件对应了 `pi` 的三层结构：最小 `agent-core`、上层 `AgentSession`、再上层的 extension/resource host。 + +### 相关接口与能力 + +- Astrcode 当前对外扩展面仍以“能力调用”为中心： + - `CapabilitySpec` / `CapabilityWireDescriptor` + - plugin capability invoker + - `core::hook` 中较窄的 lifecycle hook 事件 +- `crates/core/src/hook.rs` 当前事件面只覆盖： + - `PreToolUse` + - `PostToolUse` + - `PostToolUseFailure` + - `PreCompact` + - `PostCompact` + - 这离一个完整的运行时扩展总线还有明显距离。 +- `pi-mono` 当前扩展面明显更宽： + - `ExtensionAPI` 支持 `on`、`registerTool`、`registerCommand`、`registerShortcut`、`registerProvider`、`sendMessage`、`sendUserMessage`、`appendEntry`、`setModel`、`setThinkingLevel` 等。 + - `ExtensionRunner` 已经内建多种事件分发语义：顺序分发、可取消、可拦截、可修改、管道式、短路式。 +- `pi` 的 `AgentOptions` 非常薄，只保留： + - `convertToLlm` + - `transformContext` + - `streamFn` + - `getApiKey` + - `beforeToolCall` + - `afterToolCall` + - `toolExecution` + - `transport` + - `steeringMode` + - `followUpMode` + - 这证明 `pi` 的核心 runtime 只承担 loop、provider 调用、tool dispatch、event 流等最小职责。 +- `pi` 的 `AgentSession` 与 `ResourceLoader` 则承担更上层的事情： + - session 持久化 + - compaction + - bash 执行 + - extension 绑定 + - skill / prompt / theme / context file 发现 + - 这和 Astrcode 当前“很多 host 逻辑被塞进 `session-runtime` 与 `application`”的状态形成鲜明对比。 + +### 相关数据与模型 + +- Astrcode 当前关键模型 + - `crates/core/src/capability.rs`：`CapabilitySpec` + - `crates/protocol/src/capability/descriptors.rs`：`CapabilityWireDescriptor` 直接复用 `CapabilitySpec` + - `crates/core/src/plugin/manifest.rs`：`PluginManifest` + - `crates/core/src/ports.rs`：`PromptDeclaration`、`PromptGovernanceContext` + - `crates/core/src/hook.rs`：`HookInput`、`HookOutcome`、`ToolHookContext`、`CompactionHookContext` + - `crates/session-runtime/src/lib.rs`：`SessionObserveSnapshot`、`TurnTerminalSnapshot`、`ProjectedTurnOutcome`、`AgentPromptSubmission` +- 从这些模型可以看出： + - DTO / 协议层本身并不是完全失控，问题核心在于“哪些模型被错误放进了 core，哪些模型被错误提升成跨 crate 合同”。 + - 换句话说，问题不是“DTO 数量多”，而是“owner 专属 DTO 被 core 化了”。 +- `pi-mono` 当前关键模型 + - `AgentOptions` / `AgentState` + - `BeforeToolCallContext` / `BeforeToolCallResult` + - `AfterToolCallContext` / `AfterToolCallResult` + - `AgentEvent` + - `ExtensionRuntime` 里的 pending provider registration + - `ResourceExtensionPaths` +- `pi` 的模型特点是： + - runtime 模型小而稳定 + - host / extension 模型在 runtime 之上增量扩展 + - handler 结果大多是“拦截 / 增补 / 修改 / 取消”这种 effect 风格 + +### 测试、约束与边界 + +- 当前硬约束 + - `PROJECT_ARCHITECTURE.md` 是权威架构文档。本次目标与它当前对 `session-runtime` 的定义存在明显冲突，因此不能只改代码不改文档。 + - schema 与仓库约定都强调：会话持久化优先基于事件日志，而不是隐式内存状态。 + - DTO / 协议层必须保持纯数据，不得把运行时内脏泄漏到外部边界。 + - `server` 仍应保持唯一组合根。 + - 本项目明确不要求向后兼容。 +- 当前已有验证与守卫 + - `node scripts/check-crate-boundaries.mjs` 是依赖边界守卫。 + - `crates/sdk/src/tests.rs`、`crates/protocol/src/plugin/tests.rs` 已覆盖一部分 SDK / 协议现状。 + - 但这次调研没有逐个盘点所有 runtime 相关测试，只能确认“现有测试面存在”，不能把它当作完整迁移保障。 +- 关键边界张力 + - 如果要做成 pi 风格的最小 runtime core，就必须把“事件日志 / 回放 / projection / session catalog”与“live turn runtime”解耦。 + - 但项目又要求事件日志优先，因此更合理的做法不是丢掉事件日志，而是把它上移到 host-session 层，而不是继续让它定义 runtime core 的边界。 + - 同时，plugin-first 并不等于“一切都改成外部子进程”。热路径上的 hooks、builtin tools、provider 适配仍需要进程内 builtin plugin 形态。 + +## 必须删除或归零的旧内容 + +这轮额外勘察确认：本次 change 不只是“新增 3 个 crate”，而是需要在迁移完成后让一批旧边界彻底消失。否则仓库会长期处于“双边界并存”的半重构状态。 + +### 整 crate 删除 + +- `crates/application/**` + - 当前共有 80 个源码文件。 + - 该 crate 里需要整体消失的旧子域包括： + - `src/agent/**` + - `src/execution/root.rs` + - `src/execution/subagent.rs` + - `src/governance_surface/**` + - `src/mode/**` + - `src/workflow/**` + - `src/mcp/mod.rs` + - `src/ports/**` + - `src/lib.rs` 对 `AgentOrchestrationService`、`GovernanceSurfaceAssembler`、`ModeCatalog`、`WorkflowOrchestrator` 的公开导出 +- `crates/kernel/**` + - 当前共有 16 个源码文件。 + - 需要整体消失的旧边界包括： + - `src/kernel.rs` + - `src/gateway/mod.rs` + - `src/registry/**` + - `src/agent_surface.rs` + - `src/agent_tree/**` + - `src/surface/mod.rs` +- `crates/session-runtime/**` + - 当前共有 80 个源码文件。 + - 迁移完成后旧 crate 应整体删除；核心目录包括： + - `src/turn/**` + - `src/state/**` + - `src/query/**` + - `src/catalog/**` + - `src/context_window/**` + - `src/observe/**` + - `src/command/**` + - `src/actor/**` +- 旧 `crates/plugin/**` 边界 + - 当前共有 `loader.rs`、`process.rs`、`peer.rs`、`supervisor.rs`、`worker.rs`、`capability_router.rs` 等宿主实现。 + - 这些实现不是全部废弃，而是迁入 `plugin-host` 后，旧 `crates/plugin` 作为独立正式边界应删除。 + +### `core` 中必须删掉的旧共享面 + +- `crates/core/src/projection/**` +- `crates/core/src/mode/**` +- `crates/core/src/config.rs` +- `crates/core/src/observability.rs` +- `crates/core/src/session_plan.rs` +- `crates/core/src/store.rs` +- `crates/core/src/composer.rs` +- `crates/core/src/plugin/registry.rs` +- `crates/core/src/session_catalog.rs` +- `crates/core/src/runtime/traits.rs` +- `crates/core/src/plugin/manifest.rs` 中旧 `PluginManifest` +- `crates/core/src/hook.rs` 中旧 `HookInput`、`HookOutcome` +- `crates/core/src/agent/lineage.rs` 中 `SubRunHandle` +- `crates/core/src/agent/input_queue.rs` 中 `InputQueueProjection` +- `crates/core/src/lib.rs` 中对应的旧 re-export + - 包括旧 `PluginRegistry`、`PluginManifest`、`PluginHealth`、`PluginState`、`PluginType` + - 包括旧 `SessionCatalogEvent` + - 包括 `session_plan`、`observability`、`store`、`composer` 相关 re-export + +这些内容的问题不只是“代码老”，而是它们把 owner 专属模型错误提升成了共享依赖面。 + +### 必须消失的旧特判装配路径 + +- `crates/server/src/bootstrap/runtime.rs` + - 里面当前手工拼接 builtin tools、agent tools、MCP invokers、plugin invokers、governance、mode、workflow、capability sync。 +- `crates/server/src/bootstrap/providers.rs` + - 里面当前保留 `provider_kind == openai` 的硬编码选择路径。 +- `crates/server/src/bootstrap/plugins.rs` +- `crates/server/src/bootstrap/mcp.rs` +- `crates/server/src/bootstrap/governance.rs` +- `crates/server/src/bootstrap/capabilities.rs` +- `crates/server/src/bootstrap/composer_skills.rs` +- `crates/server/src/bootstrap/prompt_facts.rs` +- `crates/server/src/bootstrap/watch.rs` +- `crates/server/src/bootstrap/deps.rs` +- `crates/server/src/bootstrap/runtime_coordinator.rs` + +这里不要求这些文件名全部删除，但要求其中承载的“组合根内业务特判逻辑”必须消失，不能原样搬到新架构里。 + +### 多 agent 协作相关的旧跨层实现 + +- `crates/application/src/agent/mod.rs` 中 `AgentOrchestrationService` +- `crates/application/src/agent/routing.rs` +- `crates/application/src/agent/routing/child_send.rs` +- `crates/application/src/agent/routing/parent_delivery.rs` +- `crates/application/src/agent/observe.rs` +- `crates/application/src/agent/terminal.rs` +- `crates/application/src/agent/wake.rs` +- `crates/application/src/execution/subagent.rs` +- `crates/session-runtime/src/turn/finalize.rs` 中 subrun finished 持久化路径 +- `crates/session-runtime/src/turn/interrupt.rs` 中 cancel subruns for turn 路径 +- `crates/session-runtime/src/query/subrun.rs` +- `crates/session-runtime/src/state/input_queue.rs` +- `crates/kernel/src/agent_tree/**` +- `crates/kernel/src/agent_surface.rs` + +这些内容最终不能再以“core + application + kernel + session-runtime 四处分摊”的形式存在，而是要么进入 `host-session`，要么只留下最小 child-turn 执行合同在 `agent-runtime`。 + +## 关键发现 + +### 发现 1 + +- 事实：`session-runtime` 当前已经同时拥有 session catalog、query/read model、conversation replay、child lineage、mode state、event replay、turn terminal wait 等大量宿主级接口。 +- 证据：`crates/session-runtime/src/lib.rs`、`crates/session-runtime/src` 共 79 个文件 +- 影响：它无法继续被视为“最小 agent runtime core”；如果保留现状，只是在外围加 plugin / hook，最终只会得到一个“大核心 + 扩展糖衣”的系统。 +- 可复用点：其中与单次 turn loop、流式执行、工具调度直接相关的部分仍可保留为新 runtime core 的素材；查询、目录、回放等能力则更适合上移。 + +### 发现 2 + +- 事实：`application` 仍直接暴露并消费大量 `session-runtime` 与 `kernel` 具体结构；`AppAgentPromptSubmission` 甚至直接包含 `CapabilityRouter`，随后再转换为 runtime 的具体提交结构。 +- 证据：`crates/application/src/lib.rs`、`crates/application/src/ports/session_submission.rs` +- 影响：这说明 `application` 没有成为稳定 host use-case boundary，而是继续充当“知道太多 runtime 内部结构的编排层”。 +- 可复用点：`governance_surface`、`profile resolution`、`McpService`、`WorkflowOrchestrator` 等能力仍可保留，但应重挂到更清晰的 host 层，而不是继续作为 runtime 边界的一部分。 + +### 发现 3 + +- 事实：`server` 当前显式区分 `core builtin tools`、`agent tools`、`MCP invokers`、`plugin invokers`、`plugin modes`、`capability sync` 等多套装配路径。 +- 证据：`crates/server/src/bootstrap/runtime.rs` +- 影响：这说明系统现在不是“统一扩展面 + 统一 active snapshot”，而是“server 组合根手工缝合多条事实源”。 +- 可复用点：现有 `bootstrap_plugins_with_skill_root`、`CapabilitySurfaceSync`、`ToolSearchIndex`、plugin registry 等基础设施，可以作为未来 `plugin-host` 的实现基础，而不必全部重写。 + +### 发现 4 + +- 事实：Astrcode 当前 SDK / plugin 更偏向“工具与 capability 调用基础设施”，扩展贡献面明显窄于 `pi`。 +- 证据：`crates/sdk/src/lib.rs`、`crates/sdk/src/hook.rs`、`crates/plugin/src/lib.rs` +- 影响：如果目标是“其他一切都通过 plugin 提供”，现有 SDK 和 plugin manifest 不足以直接承载 provider、resource、prompt、workflow overlay、command、hot reload 一致性等能力。 +- 可复用点：现有 capability router、JSON-RPC transport、plugin supervisor、manifest 解析都可以继续作为“外部 plugin 执行后端”；缺的是更高层的统一贡献协议和 host registry。 + +### 发现 5 + +- 事实：仓库内部已经有明确的 hooks 前置设计，主张把 hooks 升格为独立平台，并通过 `PromptDeclaration` 进入既有 prompt 组装链路，而不是再造一套平行 prompt 系统。 +- 证据： + - `openspec/changes/archive/2026-04-21-introduce-hooks-platform-crate/proposal.md` + - `openspec/changes/archive/2026-04-21-introduce-hooks-platform-crate/specs/lifecycle-hooks-platform/spec.md` + - `openspec/changes/archive/2026-04-21-extract-governance-prompt-hooks/proposal.md` +- 影响：如果现在要做 plugin-first runtime 重构，hooks 不应该再被当成“另一个子系统”，而应该直接成为统一扩展总线。 +- 可复用点：历史 hooks 提案里的 event/effect 思路、builtin/external shared registry、prompt hook 复用 `PromptDeclaration` 的约束，都可以直接延续。 + +### 发现 6 + +- 事实：`pi-mono` 已经验证了一种清晰分层： + - `agent-core` 只保留最小 runtime 注入点 + - `AgentSession` 承担 session host 逻辑 + - `ExtensionRunner` 与 `ResourceLoader` 承担扩展与资源发现 +- 证据： + - `D:/GitObjectsOwn/pi-mono/packages/agent/src/agent.ts` + - `D:/GitObjectsOwn/pi-mono/packages/agent/src/types.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/extensions/loader.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/extensions/runner.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/agent-session.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/resource-loader.ts` +- 影响：Astrcode 想变成“核心最小化，一切可扩展”，不是缺一个 hooks trait，而是需要重新划分 crate 边界与 owner。 +- 可复用点：可以直接借鉴 `pi` 的晚绑定扩展运行时、queued provider registration、事件分发语义、resource discovery 分层，但不必照搬 `pi` 的全部产品能力。 + +### 发现 6.1 + +- 事实：`pi-mono` 的 `Agent` 只感知 `sessionId`、tool hooks、上下文快照和 prompt/continue 执行；真正持有 `SessionManager`、`ResourceLoader`、`sendUserMessage`、`appendEntry`、`setSessionName` 等 session owner 行为的是 `AgentSession`。 +- 证据： + - `D:/GitObjectsOwn/pi-mono/packages/agent/src/agent.ts` + - `D:/GitObjectsOwn/pi-mono/packages/coding-agent/src/core/agent-session.ts` +- 影响：这说明 `pi` 的真正可借鉴点不是“它已经有多 agent”，而是“它天然把 agent 执行面和 session owner 行为拆开了”。 +- 可复用点：Astrcode 可以沿用这个 `session-as-agent-owner` 思路，把 `agent-runtime` 做成只执行某个 session/turn 的最小内核，把 `host-session` 做成持有 session 真相、资源、扩展动作和多 agent 协作 durable truth 的 owner。 + +### 发现 7 + +- 事实：`core` 当前过大，不只是“共享语义层”，而是混杂了共享值对象、mega ports、projection、workflow、mode、plugin registry、session catalog、observability、config 等多种 owner 专属模型。 +- 证据：`crates/core/src/lib.rs`、`crates/core/src/ports.rs`、`crates/core/src/projection`、`crates/core/src/workflow.rs`、`crates/core/src/mode`、`crates/core/src/plugin/registry.rs`、`crates/core/src/session_catalog.rs`、`crates/core/src` 共 58 个文件 +- 影响：任何想复用“最小 runtime”或“共享消息模型”的场景，都会被迫拉入一大批并不属于 core 的依赖。 +- 可复用点：`ids`、`LlmMessage`、`ToolCallRequest`、`CapabilitySpec`、`PromptDeclaration` 这类真正共享的值对象仍适合留在 core。 + +### 发现 8 + +- 事实：`kernel` 当前更像 service locator，而不是正式的业务 owner 边界。 +- 证据：`crates/kernel/src/lib.rs` 主要只 re-export `KernelBuilder`、`KernelGateway`、`CapabilityRouter`、`SurfaceManager`、`EventHub`；`kernel/src/kernel.rs` 主要做 provider 注入与校验 +- 影响：它不值得继续保留为长期 crate 边界，更适合拆回 `agent-runtime`、`host-session` 与 `plugin-host`。 +- 可复用点：其中的 router/gateway 思路可以转化为 `plugin-host` 的统一注册表与 active snapshot 组装逻辑。 + +### 发现 9 + +- 事实：当前产品级 LLM provider 抽象仍偏薄，运行时实际上只支持 OpenAI 家族 provider。 +- 证据：`crates/server/src/bootstrap/providers.rs` 中 `ConfigBackedLlmProvider` 对 `provider_kind != openai` 直接报错；`crates/adapter-llm` 当前只实现 OpenAI 家族 provider +- 影响：如果要做成 plugin-first 架构，provider 贡献和选择逻辑不能继续硬编码在 server/bootstrap 中，必须进入统一的 provider contribution / registry 体系。 +- 可复用点：`adapter-llm` 现有 OpenAI 兼容实现可以保留，但需要改成“后端实现之一”，而不是“唯一正式路径”。 + +### 发现 10 + +- 事实：Astrcode 的多 agent 协作不是附属功能，而是已经落进 durable truth、query/read model、父子 lineage、turn 中断与结果投递的正式主链；但这套能力当前分散在 `core`、`application`、`session-runtime` 三个 crate。 +- 证据： + - `crates/core/src/agent/lineage.rs` + - `crates/core/src/agent/executor.rs` + - `crates/core/src/agent/input_queue.rs` + - `crates/application/src/agent/mod.rs` + - `crates/application/src/execution/subagent.rs` + - `crates/session-runtime/src/turn/finalize.rs` + - `crates/session-runtime/src/turn/interrupt.rs` + - `crates/session-runtime/src/query/subrun.rs` +- 影响：如果在新架构里不先明确 collaboration owner，迁移时一定会把同一条事实链继续拆散到 runtime、host、core 三边，最后既不像 `pi-mono` 的最小 runtime，也无法维持 Astrcode 现有的子 agent 可恢复性。 +- 可复用点：可以借鉴 `pi-mono` “新的 agent 行为应该通过 session owner 和扩展动作进入系统”的思路，但 Astrcode 仍必须保留“一个 session 即一个 agent”的 durable collaboration truth，因此更适合把协作真相上移到 `host-session`，把协作入口做成 plugin/tool/command surface，把最小执行合同留在 `agent-runtime`。 + +## 建议的具体迁移映射 + +### `agent-runtime` 应接收的实现 + +- 迁入： + - `session-runtime/turn/*` 中与 loop、llm cycle、tool cycle、continuation cycle、loop control、streaming 直接相关的模块 + - 取消语义、runtime 事件分发、tool dispatch、hook dispatch +- 新结构建议： + - `runtime.rs` + - `loop.rs` + - `types.rs` + - `tool_dispatch.rs` + - `hook_dispatch.rs` + - `stream.rs` + - `cancel.rs` + +### `host-session` 应接收的实现 + +- 迁入： + - session catalog + - event log writer / recovery / replay + - query/read model + - branch/fork + - compaction orchestration + - observe / conversation snapshot + - `SubRunHandle`、父子 session lineage、sub-run finished/cancel 事件 + - `InputQueueProjection`、跨 session 输入投递、子 agent 结果回传 + - session/query 公共 surface + +### `core` 的建议去留 + +- 继续保留： + - `ids.rs` + - `action.rs` 中的基础消息模型 + - `capability.rs` + - 极少数真正跨 owner 共享的 prompt/hook 语义 +- 应迁出或删除： + - `projection/` -> `host-session` + - `workflow.rs` -> `host-session` + - `session_plan.rs` -> `host-session` + - `session_catalog.rs` -> `host-session` + - `ports.rs` -> 按 owner 拆散 + - `plugin/` -> `plugin-host` + - `mode/` -> `plugin-host` 或 builtin plugin + - `observability.rs` -> `host-session` + - `runtime/traits.rs` -> 删除或迁回 owner 专属合同 + +## 可选方案比较 + +| 方案 | 适用前提 | 优点 | 风险/代价 | 结论 | +| --- | --- | --- | --- | --- | +| A：保留当前 `session-runtime/application/kernel` 主体，只在外层继续叠加 hooks / plugins | 只想低成本追加扩展点，不追求彻底边界重建 | 改动相对小，短期内更容易落地 | 保留大核心；`application` 与 `session-runtime` 的边界泄漏不会消失；最终很难达到 `pi` 那种“核心最小化” | 不推荐 | +| B：按 plugin-first 方向重构为“最小 runtime core + host-session + plugin-host + hooks 总线” | 接受 breaking change，并愿意同步更新架构文档、spec 与 crate 边界 | 最符合用户目标；能统一 builtin / external 行为；与既有 hooks 方向一致 | 影响范围大，需要分阶段迁移 `session-runtime`、`application`、`server`、`plugin/sdk` | 推荐 | +| C：只把 tools / MCP / discovery plugin 化，保留 governance / workflow / session truth 在旧结构里 | 只想减少部分 bootstrap 特判 | 可以较快减少一部分 server 组装分支 | 仍会保留“两套事实源”：核心内置逻辑一套，plugin 扩展一套；hooks 很难成为统一总线 | 不推荐作为最终形态 | + +## 结论 + +- 推荐方向：采用方案 B，把 Astrcode 重构为“`agent-runtime` + `host-session` + `plugin-host` + hooks 总线”的 plugin-first 架构。 +- 理由： + - 这是唯一真正符合“不要向后兼容，只要完整良好的实现”和“其他一切通过 plugin 提供”的方向。 + - 当前 `session-runtime`、`application`、`server bootstrap` 的职责都明显偏大，只靠继续补 hooks 无法解决。 + - 既有 hooks 提案与 `pi-mono` 的分层思路并不冲突，反而可以自然合流。 + - Astrcode 现有的多 agent 协作必须继续存在，但它应该以“一个 session 即一个 agent”的原则收敛到 `host-session`，而不是继续散落在 `core`、`application` 和 monolith runtime 中。 +- 已决策方向： + - 新建 `agent-runtime` 与 `host-session` 等 crate，再迁移旧实现；不在原有大 crate 内继续原地抽丝剥茧。 + - 删除 `application` crate，不保留长期兼容 façade；原 use-case 语义重新分配到 `host-session`、`plugin-host` 与 `server` 的新边界上。 + - 删除 `kernel` crate，不再保留 provider/tool/resource 的中间门面。 + - 统一 plugin descriptor 扩展到完整贡献面，至少覆盖 `tools`、`hooks`、`providers`、`resources`、`commands`、`themes`、`prompts`、`skills`。 + - 收缩 `core`，不再把 owner 专属 DTO 与 mega ports 留在共享层。 +- 暂不采用的方案： + - 保留当前大核心，只在外围继续堆 plugin / hook。 + - 只 plugin 化工具与 MCP，但把 workflow / governance / session truth 继续硬编码留在旧核心里。 + +## 未决问题 + +- builtin plugin 与 external plugin 的执行模型、失败语义、reload 顺序如何统一定义。 +- provider contribution 的最终注册协议如何设计，才能既覆盖现有 OpenAI 家族实现，也允许后续引入新的 provider 后端而不再改 server bootstrap。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/agent-runtime-core/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/agent-runtime-core/spec.md new file mode 100644 index 00000000..7eef2fef --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/agent-runtime-core/spec.md @@ -0,0 +1,64 @@ +## ADDED Requirements + +### Requirement: `agent-runtime` SHALL 只拥有最小 live runtime 边界 + +系统 MUST 新建 `agent-runtime` crate，作为唯一的最小 live runtime 核心。它 SHALL 只负责单次 agent/turn 执行、流式 provider 调用、tool dispatch、hook dispatch、取消、中断与 loop control，SHALL NOT 再拥有 session catalog、event log 枚举、branch/fork 持久化、read model、resource discovery、workflow 组装或 settings 解析。 + +#### Scenario: runtime core 不再暴露宿主级 session 服务 +- **WHEN** 审查 `agent-runtime` 的公共 API +- **THEN** 其中 SHALL 不存在列举全部 session、枚举 session meta、读取 durable replay、发现 prompts/themes/skills 或管理 plugin search path 的入口 +- **AND** 这些能力 SHALL 归属 `host-session` 或 `plugin-host` + +### Requirement: `agent-runtime` SHALL 消费宿主预解析好的 active snapshot + +`agent-runtime` MUST 只消费 host 预先组装好的生效输入，包括模型、工具集合、hook snapshot、provider 选择、prompt 输入与执行约束。runtime SHALL NOT 自己判断贡献来自 builtin 还是 external plugin，也 SHALL NOT 在 turn 中重新做 discovery。 + +#### Scenario: runtime 不区分 builtin 与 external 贡献来源 +- **WHEN** 某次 turn 使用一组工具、hooks、providers 与 prompt declarations 执行 +- **THEN** `agent-runtime` 只看到当前生效 snapshot +- **AND** SHALL NOT 因贡献来自 builtin 还是 external 而走不同装配分支 + +### Requirement: `agent-runtime` SHALL 暴露稳定的 hook/provider/tool 调度点 + +`agent-runtime` MUST 提供稳定调度点，至少覆盖上下文变换、provider 请求前处理、tool call 前后处理、turn start/end 与取消传播。这些调度点 SHALL 使用纯数据上下文和可组合 effect，而不是暴露 process-local 内部状态。 + +#### Scenario: runtime 在一次 turn 内顺序执行核心调度点 +- **WHEN** 用户提交一轮 prompt +- **THEN** `agent-runtime` SHALL 按 `context -> before_agent_start -> before_provider_request -> tool_call/tool_result -> turn_end` 的顺序驱动调度 +- **AND** 每个调度点的输入输出 SHALL 为纯数据 snapshot 或 effect + +### Requirement: `agent-runtime` SHALL 只提供单一 turn 执行入口 + +`agent-runtime` MUST 以单一 turn 执行入口对外暴露其核心能力，例如 `execute_turn(input, cancel)` 这一类语义稳定的方法。系统 SHALL NOT 再把 session catalog、conversation query、event replay、branch/fork 或 config 解析混入 runtime 公共 API。 + +#### Scenario: 运行时公共面收敛为执行入口 +- **WHEN** 审查 `agent-runtime` crate 的正式 surface +- **THEN** 其核心公共能力 SHOULD 收敛到 turn 执行、取消、流式事件与 hook/tool 调度 +- **AND** SHALL NOT 再把 session service façade 暴露给上层 + +### Requirement: `agent-runtime` SHALL 依赖抽象的 provider stream surface + +`agent-runtime` MUST 依赖抽象的 provider stream 合同，而不是依赖 `KernelGateway`、`ConfigBackedLlmProvider` 或任何特定 provider kind。runtime SHALL 只知道“如何流式调用模型”，不知道“当前是 OpenAI 还是其他 provider”。 + +#### Scenario: runtime 不感知 OpenAI-only 现状 +- **WHEN** `host-session` 为某次 turn 选择了 provider 并组装执行面 +- **THEN** `agent-runtime` 只消费抽象的 stream surface +- **AND** SHALL NOT 在 runtime 内部硬编码 `openai` 或其他 provider kind 分支 + +### Requirement: `agent-runtime` SHALL 不保留向后兼容 façade + +本次重构完成后，系统 SHALL 以 `agent-runtime` 作为新的 live runtime owner，而不是保留旧 `session-runtime` 的兼容 façade 长期并存。 + +#### Scenario: 旧 monolith runtime 不继续对外提供兼容入口 +- **WHEN** `agent-runtime` 与 `host-session` 完成接管 +- **THEN** 旧的 monolith `session-runtime` SHALL 不再作为正式对外能力边界继续存在 +- **AND** 新实现 SHALL 直接以新 crate 边界为准 + +### Requirement: `agent-runtime` SHALL 不拥有 collaboration durable truth + +`agent-runtime` MAY 提供最小的 child-session 执行合同，但它 MUST 只执行某个 session/turn，而 SHALL NOT 维护 `SubRunHandle`、父子 lineage、input queue、结果投递或取消后的 durable 协作状态。 + +#### Scenario: 子 agent 执行由 host 触发、runtime 只负责执行 +- **WHEN** `host-session` 决定为某个父 turn 启动 child session +- **THEN** `host-session` SHALL 先完成 child session 与协作状态的 durable 建模，再调用 `agent-runtime` 执行该 child turn +- **AND** `agent-runtime` SHALL NOT 自己创建第二套 collaboration truth diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/application-use-cases/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/application-use-cases/spec.md new file mode 100644 index 00000000..9cac8015 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/application-use-cases/spec.md @@ -0,0 +1,19 @@ +## REMOVED Requirements + +### Requirement: `application` 提供唯一业务入口 `App` + +**Reason**: 本次重构明确删除 `application` crate，不保留 `App` 作为兼容 façade。旧 use-case 语义将按新边界分配到 `host-session`、`plugin-host` 与 `server`。 + +**Migration**: 将 session/conversation/observe/branch/fork 等入口迁入 `host-session`；将 plugin discovery/reload/resource aggregation 迁入 `plugin-host`；`server` 改为直接装配并消费新 host surfaces。 + +### Requirement: `application` 只依赖核心运行时层 + +**Reason**: `application` crate 将被删除，这条 crate 依赖边界约束不再成立。 + +**Migration**: 以新的 `agent-runtime`、`host-session`、`plugin-host` crate 边界替代旧的 `application -> kernel/session-runtime` 依赖结构。 + +### Requirement: `application` 负责用例编排、参数校验和权限前置 + +**Reason**: 这些职责会被拆分给新的 host 层 owner，而不是继续堆叠在单独的 `application` crate 中。 + +**Migration**: session/turn 相关用例下沉到 `host-session`；plugin/resource/reload 相关用例归属 `plugin-host`；协议映射与 transport concern 保持在 `server`。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/core-boundary-slimming/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/core-boundary-slimming/spec.md new file mode 100644 index 00000000..f78daefa --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/core-boundary-slimming/spec.md @@ -0,0 +1,78 @@ +## ADDED Requirements + +### Requirement: `core` SHALL 只保留跨 owner 共享的最小语义 + +系统 MUST 将 `crates/core` 收缩为极薄的共享语义层。`core` SHALL 只保留多个 owner 共同消费且长期稳定的值对象、消息模型、能力语义与少量共享枚举，SHALL NOT 继续作为所有 DTO、trait 和内部状态模型的总仓库。 + +#### Scenario: 审查 core 导出面时只看到共享语义 +- **WHEN** 审查 `crates/core/src/lib.rs` 的公开导出 +- **THEN** 导出面 SHOULD 主要由 `ids`、消息模型、`CapabilitySpec`、最小 prompt/hook 共享语义组成 +- **AND** SHALL NOT 再大量导出 owner 专属 checkpoint、projection、plugin registry、workflow/mode 或配置存储模型 + +### Requirement: owner 专属 DTO SHALL 跟随 owner crate + +只被单一 owner 或单一边界使用的 DTO、快照、恢复模型、执行面、descriptor 与 observability 报告 MUST 迁回对应 owner crate，而不是继续放在 `core`。 + +#### Scenario: session 恢复和 projection 模型迁回 host-session +- **WHEN** 系统需要表达 session recovery checkpoint、projection snapshot、query/read model +- **THEN** 这些模型 SHALL 归属 `host-session` +- **AND** SHALL NOT 继续停留在 `core` + +#### Scenario: plugin 描述模型迁回 plugin-host +- **WHEN** 系统需要表达 plugin descriptor、active snapshot、resource/theme/prompt/skill descriptor +- **THEN** 这些模型 SHALL 归属 `plugin-host` +- **AND** SHALL NOT 继续作为 `core` 的默认 DTO 集合 + +#### Scenario: runtime 执行面迁回 agent-runtime +- **WHEN** 系统需要表达 turn 执行面、runtime hook payload、provider/tool 执行上下文 +- **THEN** 这些模型 SHALL 归属 `agent-runtime` +- **AND** SHALL NOT 继续通过 `core::ports` 之类的 mega 模块承载 + +### Requirement: `core` SHALL 删除膨胀型 mega 模块 + +`core` 中承载多 owner 合同和历史兼容模型的 mega 模块 MUST 被拆分或删除，至少包括 `ports.rs` 这类混合型合同文件，以及 `projection`、`workflow`、`plugin registry`、`session catalog` 等 owner 专属模块。`mode`、config、observability 需要先按共享合同与 owner 实现拆分：`ModeId`、durable mode-change event DTO、mode tool-contract snapshot、runtime config、observability wire metrics MAY 暂留 `core`，直到协议/事件 DTO 拆出稳定 wire schema；治理 DSL、builtin mode owner 逻辑、配置持久化、metrics collector 不得继续回流到 `core`。 + +#### Scenario: mega ports 被 owner 合同替代 +- **WHEN** 需要定义 provider、prompt、resource、event-store 等合同 +- **THEN** 它们 SHALL 被迁入对应 owner crate 或更小的专属合同模块 +- **AND** SHALL NOT 继续集中堆叠在 `core::ports` + +#### Scenario: mode/config/observability 先拆 owner 实现再拆共享 wire 合同 +- **WHEN** 某个 `mode`、config 或 observability 类型仍被 durable event、`ToolContext`、session-runtime、server 和 protocol 同时消费 +- **THEN** 它 MAY 暂留 `core` 作为共享 wire/control 合同 +- **AND** 对应 owner 实现（治理 DSL 编译、builtin mode 装配、配置持久化、metrics collector）SHALL 迁入 `plugin-host`、`server`、`application` 或 `host-session` +- **AND** 后续只有在协议/事件 DTO 稳定拆分后，才能继续迁出这些共享合同 + +### Requirement: `core::ports` SHALL 按 owner 拆散 + +当前 `core::ports` 中混合的合同 MUST 按 owner 重新归属，至少满足： + +- `EventStore`、`SessionRecoveryCheckpoint`、`RecoveredSessionState` -> `host-session` +- `LlmProvider` / provider stream 合同 -> `agent-runtime` 或专属 provider 合同模块 +- `PromptProvider` / `PromptFactsProvider` -> `host-session` +- `ResourceProvider`、skill/prompt/theme/resource 发现合同 -> `plugin-host` 或 host 资源层 + +#### Scenario: 旧 mega ports 不再作为统一入口存在 +- **WHEN** 实现者查找某个合同应放在哪个 crate +- **THEN** 可以根据 owner 直接定位到 `agent-runtime`、`host-session` 或 `plugin-host` +- **AND** SHALL NOT 再以 `core::ports` 作为默认落点 + +### Requirement: `core` SHALL 不以“纯数据”为理由继续吸纳模型 + +本次重构中，系统 SHALL NOT 仅因为某个结构体可序列化或看起来像 DTO，就将其放入 `core`。进入 `core` 的必要条件是“多个 owner 共同消费且语义长期稳定”，而不是“它是纯数据”。 + +#### Scenario: 可序列化但 owner 单一的模型不进入 core +- **WHEN** 某个模型只服务于 plugin reload、session recovery 或 runtime execution +- **THEN** 即使它是纯数据结构 +- **AND** 它也 SHALL 归属对应 owner crate，而不是进入 `core` + +### Requirement: collaboration lineage 与 input queue 模型 SHALL 迁出 `core` + +当前 `core/src/agent/*` 中的 `SubRunHandle`、`InputQueueProjection`、协作 executor 合同与相关投影模型 MUST 迁出 `core` 的顶层共享面，并通过 `host-session` owner bridge 对新调用方暴露。其中 durable collaboration truth SHALL 归 `host-session`，最小执行合同若仍需要存在，也 SHALL 归对应执行 owner，而不是继续停留在共享层。 + +迁移期例外：`ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` MAY 暂留 `core`，因为它们当前嵌入 `ChildSessionNotification` / `StorageEventPayload` 等 durable event DTO。除非先拆出稳定 wire schema，否则迁出这些类型会导致 `core` 反向依赖 `host-session` 或复制事件 DTO。 + +#### Scenario: 协作模型不再作为 core 默认导出面 +- **WHEN** 审查重构后的 `crates/core/src/lib.rs` +- **THEN** 不应再把 sub-run lineage、input queue projection、协作读模型作为 `core` 默认导出 +- **AND** 实现者应从 `host-session` 或运行时 owner 获取这些模型 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/host-session-runtime/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/host-session-runtime/spec.md new file mode 100644 index 00000000..31667d64 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/host-session-runtime/spec.md @@ -0,0 +1,51 @@ +## ADDED Requirements + +### Requirement: `host-session` SHALL 成为 session durable truth owner + +系统 MUST 新建 `host-session` crate，统一负责事件日志、冷恢复、branch/fork、session catalog、query/read model 与对外 host use-case surface。`host-session` SHALL 通过事件日志维护 durable truth，并驱动 `agent-runtime` 执行，而不是让 live runtime 同时承担全部 durable/session 服务职责。 + +#### Scenario: host-session 持有事件日志与恢复语义 +- **WHEN** 某个 session 需要创建、恢复、分叉或回放 +- **THEN** `host-session` SHALL 负责事件追加、投影恢复与 read model 产出 +- **AND** `agent-runtime` SHALL 只负责被调用时的 live execution + +### Requirement: `host-session` SHALL 替代旧 `application` 的 host 用例入口 + +`host-session` MUST 暴露稳定的 host-side use-case surface，承接旧 `application` 中与 session、conversation、observe、branch/fork、workflow 驱动相关的正式入口。系统 SHALL 删除 `application` crate，而不是保留一个薄兼容层。 + +#### Scenario: server 通过 host-session 获取业务用例 +- **WHEN** `server` 需要处理 session、conversation、observe、fork、turn 提交等请求 +- **THEN** 它 SHALL 通过 `host-session` 暴露的正式 surface 完成 +- **AND** SHALL NOT 继续依赖 `application::App` + +### Requirement: `host-session` SHALL 通过事件日志驱动 read model + +`host-session` MUST 让 conversation snapshot、terminal facts、task facts、branch lineage、mode state 与 turn terminal 等读模型全部来源于事件日志与投影，而不是隐式内存影子状态。 + +#### Scenario: 服务重启后读模型仍可恢复 +- **WHEN** 服务重启后重新读取某个 session 的 conversation snapshot 或 task facts +- **THEN** `host-session` SHALL 通过事件日志恢复读模型 +- **AND** SHALL NOT 依赖旧 `application` 或 process-local shadow state + +### Requirement: `host-session` SHALL 以新 crate 边界替代旧实现 + +本次重构完成后，旧 `session-runtime` 中与 event log、query/read model、session catalog、branch/fork 相关的实现 SHALL 迁入 `host-session`，不保留长期兼容 owner。 + +#### Scenario: 旧 owner 被明确迁出 +- **WHEN** 审查最终 crate 职责边界 +- **THEN** durable session 服务与 read model SHALL 归属 `host-session` +- **AND** SHALL NOT 继续以“历史原因”留在旧 monolith runtime 中 + +### Requirement: `host-session` SHALL 维持一 session 即一 agent 的协作真相 + +系统 MUST 把多 agent 协作建模为“父 session 驱动 child session”，而不是在同一 session 内维护多个可变 agent 身位。`host-session` SHALL 持有 `SubRunHandle`、父子 lineage、`InputQueueProjection`、结果投递与取消传播的 durable truth。 + +#### Scenario: 发起子 agent 时创建 child session 与 durable linkage +- **WHEN** 父 turn 需要启动一个子 agent +- **THEN** `host-session` SHALL 创建新的 child session 并记录父 turn 到 child session 的 durable 关联 +- **AND** SHALL 使用 `SubRunHandle` 与输入队列读模型表达协作状态 + +#### Scenario: 父 turn 取消时由 host-session 传播到子运行 +- **WHEN** 某个父 turn 被取消或中断，且其下存在进行中的 sub-run +- **THEN** `host-session` SHALL 记录取消语义、更新协作状态并向对应 child runtime 传播取消 +- **AND** `agent-runtime` SHALL NOT 自己维护另一套 parent/child durable truth diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/lifecycle-hooks-platform/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/lifecycle-hooks-platform/spec.md new file mode 100644 index 00000000..7624dbf2 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/lifecycle-hooks-platform/spec.md @@ -0,0 +1,148 @@ +## ADDED Requirements + +### Requirement: hooks 平台 SHALL 成为统一扩展总线 + +系统 MUST 提供统一的 hooks 平台，作为 builtin 与 external 扩展共享的生命周期总线。该平台 SHALL 至少覆盖 `input`、`context`、`before_agent_start`、`before_provider_request`、`tool_call`、`tool_result`、`turn_start`、`turn_end`、`session_before_compact`、`resources_discover`、`model_select` 这些事件点。 + +#### Scenario: 同一 turn 触发完整 hook 生命周期 +- **WHEN** 一次 turn 从用户输入开始直到完成 +- **THEN** 系统 SHALL 在相应时点触发上述 hook 事件 +- **AND** builtin 与 external handlers SHALL 通过同一平台接收这些事件 + +### Requirement: hooks 平台 SHALL 提供明确的分发语义 + +hooks 平台 MUST 按事件类型提供确定性的分发语义，至少支持顺序执行、可取消、可拦截、可修改、管道式与短路式分发。系统 SHALL NOT 对相同事件类型同时混用未定义的 effect 合并顺序。 + +#### Scenario: tool_call hook 可拦截 +- **WHEN** 某个 `tool_call` hook 返回阻断 effect +- **THEN** 当前工具调用 SHALL 被阻止执行 +- **AND** 系统 SHALL 产生可观测的阻断结果 + +#### Scenario: context hook 以管道方式修改输入 +- **WHEN** 多个 `context` hooks 同时命中 +- **THEN** 后一个 handler SHALL 接收前一个 handler 的输出 +- **AND** 合并顺序 SHALL 保持稳定 + +### Requirement: governance prompt hooks SHALL 走统一 hooks 平台 + +所有 turn-scoped prompt augment 行为 MUST 作为 hooks 平台中的标准 effect 处理，并继续通过 `PromptDeclaration` / `PromptGovernanceContext` 进入既有 prompt 组装链路。系统 SHALL NOT 再维护平行的 governance prompt 特判系统。 + +#### Scenario: hook 产出的 prompt augment 进入既有 prompt 管线 +- **WHEN** 某个 hook 需要为当前 turn 注入额外 prompt declarations +- **THEN** 系统 SHALL 将其转换为 `PromptDeclaration` +- **AND** SHALL 沿既有 prompt 组装链路进入最终请求 + +### Requirement: hooks 平台 SHALL 只允许受约束的 effect + +hooks 平台 MUST 将 handlers 产出的 effect 限制在可验证的受约束集合内，例如阻断、取消当前 turn、上下文补充、prompt augment、结果修饰、资源发现或模型选择建议。hook SHALL NOT 直接突变 session durable truth 或绕过 host/runtime owner 写入内部状态。 + +#### Scenario: hook 不得直接写 durable truth +- **WHEN** 某个 hook 尝试直接修改 session durable state +- **THEN** 系统 SHALL 拒绝该 effect +- **AND** durable truth 仍 SHALL 只由正式 owner 写入 + +#### Scenario: `cancel_turn` 只能短路当前 turn +- **WHEN** 某个 hook 返回 `cancel_turn` effect +- **THEN** 当前 turn SHALL 被有界地终止，并返回可解释的终止结果 +- **AND** hook SHALL NOT 借此直接写入或篡改 session durable truth + +### Requirement: hooks 平台 SHALL 为每个 hook 事件定义明确的 owner、触发点与分发模式 + +hooks 平台 MUST 为每个正式事件定义唯一 owner、触发时机与分发模式，避免同一事件同时被多个层随意触发。第一阶段与 `pi-mono` 对齐的正式事件目录如下： + +| 事件 | owner | 触发点 | 分发模式 | 当前用途 | +| --- | --- | --- | --- | --- | +| `input` | `host-session` | 接收用户输入后、进入 turn 前 | 短路 / 转换 | 输入拦截、预处理、重写 | +| `context` | `agent-runtime` | 组装 provider 上下文前 | 管道 | 上下文裁剪、补充、注入 | +| `before_agent_start` | `agent-runtime` | system prompt 组装完成后、loop 启动前 | 管道 | prompt augment、治理 overlay | +| `before_provider_request` | `agent-runtime` | 发起 provider 请求前 | 管道 | 路由、鉴权、payload 修饰 | +| `tool_call` | `agent-runtime` | 工具执行前 | 拦截 | 参数修补、策略阻断 | +| `tool_result` | `agent-runtime` | 工具执行后 | 修改 | 结果修饰、错误重分类 | +| `turn_start` | `agent-runtime` | turn 开始时 | 顺序 | 观测、初始化 | +| `turn_end` | `agent-runtime` | turn 结束时 | 顺序 | 清理、汇总、通知 | +| `session_before_compact` | `host-session` | 压缩执行前 | 可取消 / 可修改 | 阻止压缩、定制压缩输入 | +| `resources_discover` | `plugin-host` | 构建资源目录前 | 聚合 | 贡献 skills/prompts/themes 等资源路径 | +| `model_select` | `host-session` | 模型切换或恢复时 | 可取消 / 可修改 | 模型准入、重定向、降级 | + +#### Scenario: 每个事件只有一个正式 owner +- **WHEN** 系统实现某个 hooks 事件 +- **THEN** 该事件 SHALL 由上表指定的 owner 触发 +- **AND** 其他层 SHALL NOT 以同名事件重复触发第二次 + +#### Scenario: event 目录可直接映射到实现位置 +- **WHEN** 实现者查找某个 hook 的触发逻辑 +- **THEN** 能从事件名直接定位到 `agent-runtime`、`host-session` 或 `plugin-host` 中的单一 owner +- **AND** SHALL NOT 需要在多个 crate 中猜测哪个才是真实触发点 + +### Requirement: 第一阶段正式 hook 事件 SHALL 具备明确使用点 + +第一阶段正式 hooks 事件 MUST 具备明确的使用点，而不是只保留事件名。每个事件至少满足以下语义： + +- `input`：允许 host 在 turn 创建前阻断、转换或完全处理输入。 +- `context`：允许 runtime 在 provider 调用前对消息上下文做链式变换。 +- `before_agent_start`：允许把 workflow / governance / mode overlay 转成 `PromptDeclaration`。 +- `before_provider_request`：允许 provider payload 被代理、路由或加签。 +- `tool_call`：允许阻断工具、修补参数或施加更严格策略。 +- `tool_result`：允许工具结果被修饰、截断、重分类。 +- `turn_start` / `turn_end`：允许做 turn 粒度观测、初始化和收尾。 +- `session_before_compact`：允许压缩被取消、定制或由外部摘要取代。 +- `resources_discover`：允许 plugin-host 聚合 skills / prompts / themes / commands 等资源入口。 +- `model_select`：允许模型选择被策略校验、重定向或拒绝。 + +#### Scenario: `input` hook 在创建 turn 前工作 +- **WHEN** 用户输入到达系统但尚未创建 turn +- **THEN** `input` hook SHALL 有机会返回“继续”“转换后继续”或“已处理” +- **AND** host SHALL 根据结果决定是否创建新 turn + +#### Scenario: `tool_call` 与 `tool_result` 分别负责前置拦截和后置修饰 +- **WHEN** 某次工具调用发生 +- **THEN** `tool_call` SHALL 在工具执行前运行 +- **AND** `tool_result` SHALL 在工具执行后运行 +- **AND** 这两个事件 SHALL NOT 互相替代 + +#### Scenario: `resources_discover` 聚合完整资源面 +- **WHEN** `plugin-host` 组装当前可用资源目录 +- **THEN** `resources_discover` SHALL 允许贡献 `skills`、`prompts`、`themes`、`commands` 等资源入口 +- **AND** SHALL NOT 只局限于 tool 或 capability 发现 + +### Requirement: 第二阶段预留 hook 事件 SHALL 先保留正式事件名与未来使用点 + +为与 `pi-mono` 对齐并避免未来再次引入私有回调，hooks 平台 MUST 为下一阶段预留正式事件名、owner 与未来使用点。以下事件在本 change 中不要求全部实现，但 SHALL 作为正式 hook catalog 的保留项存在： + +| 预留事件 | owner | 未来使用点 | +| --- | --- | --- | +| `session_start` | `host-session` | session 初始化、默认资源装载、首次治理注入 | +| `session_before_switch` | `host-session` | session 切换前阻断或清理 | +| `session_before_fork` | `host-session` | fork 前校验、摘要策略 | +| `session_compact` | `host-session` | 压缩完成后的观测与补充记录 | +| `session_shutdown` | `host-session` | reload、退出、session replacement 前清理 | +| `session_before_tree` | `host-session` | branch/tree 导航前拦截、摘要覆盖 | +| `session_tree` | `host-session` | branch/tree 导航后的观测与同步 | +| `session_before_spawn_child` | `host-session` | child session 创建前校验、路由、命名、limits 注入 | +| `subrun_start` | `host-session` | sub-run durable linkage 建立后的观测 | +| `subrun_end` | `host-session` | child turn terminal 后的收尾、通知、摘要 | +| `subrun_result_delivery` | `host-session` | 结果回传父 session 前的过滤、摘要、路由 | +| `after_provider_response` | `agent-runtime` | provider metadata、headers、retry hint 观测 | +| `agent_start` | `agent-runtime` | agent loop 生命周期观测 | +| `agent_end` | `agent-runtime` | agent loop 结束汇总 | +| `message_start` | `agent-runtime` | 消息级生命周期通知 | +| `message_update` | `agent-runtime` | 流式 token/message 更新观测 | +| `message_end` | `agent-runtime` | 消息结束汇总 | +| `tool_execution_start` | `agent-runtime` | 工具执行开始观测 | +| `tool_execution_update` | `agent-runtime` | 工具流式更新观测 | +| `tool_execution_end` | `agent-runtime` | 工具执行结束观测 | +| `user_bash` | `host-session` 或终端 host | 终端专属 shell shortcut 与执行代理 | + +#### Scenario: 未来扩展继续沿正式 catalog 增长 +- **WHEN** 系统后续需要扩展 session tree、message streaming 或 tool execution 粒度的 hooks +- **THEN** 应直接实现上述预留事件 +- **AND** SHALL NOT 再新增一套平行的私有 callback surface + +### Requirement: hooks 平台 SHALL 为 streaming 与 observability 事件保留非真相语义 + +`after_provider_response`、`message_start/update/end`、`tool_execution_start/update/end`、`agent_start/end` 这类 streaming / observability 事件 MUST 明确为“观测或 UI 协调事件”，它们 SHALL NOT 成为 session durable truth 的写入入口。 + +#### Scenario: message/tool execution hooks 只做观测与附加行为 +- **WHEN** 某个 streaming 或 tool execution 事件触发 +- **THEN** handler MAY 记录指标、发送 UI 更新或附加诊断 +- **AND** SHALL NOT 直接重写 durable transcript 真相 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-host-runtime/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-host-runtime/spec.md new file mode 100644 index 00000000..f1306ea4 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-host-runtime/spec.md @@ -0,0 +1,74 @@ +## ADDED Requirements + +### Requirement: `plugin-host` SHALL 统一 builtin 与 external plugin 的贡献模型 + +系统 MUST 新建统一的 `plugin-host` 能力层，用同一套 registry、descriptor、active snapshot 与 reload 语义承载 builtin 与 external plugin。系统 SHALL NOT 继续分别维护“server 内置特判路径”和“plugin 补充路径”两套事实源。 + +#### Scenario: builtin 与 external 进入同一 active snapshot +- **WHEN** 系统装配当前可用扩展面 +- **THEN** builtin 与 external plugin 的贡献 SHALL 一起进入同一 active snapshot +- **AND** 新 turn SHALL 只消费这一个 snapshot + +### Requirement: 统一 plugin descriptor SHALL 覆盖完整贡献面 + +统一 plugin descriptor MUST 至少支持以下贡献类型：`tools`、`hooks`、`providers`、`resources`、`commands`、`themes`、`prompts`、`skills`。系统 SHALL NOT 再把 commands、themes、prompts、skills 视为 plugin host 之外的平行体系。 + +#### Scenario: 一个 plugin 可同时贡献多类资源 +- **WHEN** 某个 plugin 同时提供 tool、prompt、skill 与 theme +- **THEN** 它 SHALL 通过同一 plugin descriptor 描述这些贡献 +- **AND** 宿主 SHALL 在同一发现/校验/装配流程中处理它们 + +### Requirement: `plugin-host` SHALL 支持进程内 builtin plugin 与外部 plugin 并存 + +为保证热路径性能和统一扩展面，`plugin-host` MUST 同时支持进程内 builtin plugin 与外部 plugin。两者共享同一 descriptor 与 snapshot 语义，但 MAY 使用不同执行后端。 + +#### Scenario: 热路径 builtin plugin 以内联方式运行 +- **WHEN** 一个需要低延迟的 hooks 或工具贡献由 builtin plugin 提供 +- **THEN** 系统 SHALL 允许其以内联方式执行 +- **AND** SHALL NOT 强制其经过外部进程 hop + +#### Scenario: 外部 plugin 继续通过隔离执行后端运行 +- **WHEN** 一个 external plugin 被装载 +- **THEN** 系统 MAY 通过进程、命令或远程协议运行它 +- **AND** 它对上层暴露的 descriptor/snapshot 语义 SHALL 与 builtin plugin 保持一致 + +### Requirement: `plugin-host` SHALL 提供 snapshot 一致性的 reload 语义 + +`plugin-host` MUST 在 reload 时构建新的候选 snapshot，并以显式 commit/rollback 方式替换当前 active snapshot。进行中的 turn SHALL 继续使用旧 snapshot，新 turn SHALL 使用新 snapshot。 + +#### Scenario: reload 不打断进行中的 turn +- **WHEN** reload 发生时已有 turn 正在执行 +- **THEN** 当前 turn SHALL 继续使用旧 snapshot 完成 +- **AND** reload 成功后新 turn SHALL 切换到新 snapshot + +#### Scenario: 候选 snapshot 构建失败时回滚 +- **WHEN** 某个 plugin descriptor 校验失败、资源冲突或装配失败 +- **THEN** 新候选 snapshot SHALL 被放弃 +- **AND** 系统 SHALL 保持旧 active snapshot 不变 + +### Requirement: `plugin-host` SHALL 统一承接 provider contributions + +`plugin-host` MUST 把 provider 视为正式 plugin contribution，而不是继续由 `server/bootstrap` 直接硬编码选择。provider 的发现、注册、校验、优先级与 active snapshot 集合 SHALL 统一进入 `plugin-host`。 + +#### Scenario: provider 与 tools/hooks 一起进入统一快照 +- **WHEN** 某个 builtin 或 external plugin 贡献 provider +- **THEN** 它 SHALL 与该 plugin 的 tools/hooks/resources 一起进入统一 descriptor 与 active snapshot +- **AND** SHALL NOT 需要额外的平行 provider 装配路径 + +### Requirement: `plugin-host` SHALL 让新增 provider 不再要求修改 server 组合根 + +新增 provider 后端时，系统 SHOULD 只需要新增 provider backend 或 plugin contribution，而不是继续修改 `server/src/bootstrap/providers.rs` 的硬编码分支。 + +#### Scenario: 新 provider 通过 contribution 接入 +- **WHEN** 系统新增一个非 OpenAI 的 provider backend +- **THEN** 它 SHOULD 通过 provider contribution / registry 接入 +- **AND** `server` SHALL 不需要因为支持这个 provider 而再新增一条长期硬编码装配分支 + +### Requirement: collaboration surfaces MAY 作为 plugin contribution 暴露，但 SHALL 委托给 `host-session` + +多 agent 协作相关的 tools/commands MAY 通过 builtin 或 external plugin contribution 进入统一 active snapshot，例如 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree`。但这些 surface SHALL 只负责把动作提交给 `host-session`，而 SHALL NOT 自己持有 child session、sub-run lineage、input queue 或结果投递的 durable truth。 + +#### Scenario: 协作工具通过 plugin-host 暴露、通过 host-session 生效 +- **WHEN** 当前 active snapshot 中存在 `spawn_agent` 之类的协作工具或命令 +- **THEN** 它 SHALL 作为普通 plugin contribution 被发现、装配和暴露 +- **AND** 实际 child session 创建与协作状态落库 SHALL 由 `host-session` 执行 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-integration/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-integration/spec.md new file mode 100644 index 00000000..61312512 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/plugin-integration/spec.md @@ -0,0 +1,37 @@ +## ADDED Requirements + +### Requirement: plugin integration SHALL 基于统一 descriptor 与 snapshot 装配 + +系统 MUST 以统一 plugin descriptor 和 active snapshot 模型装配 plugin 贡献，而不是只把 plugin 视为 capability invoker 或窄版 hook 的补充来源。 + +#### Scenario: plugin 装配覆盖完整贡献面 +- **WHEN** 宿主装载一个 plugin +- **THEN** 系统 SHALL 同时解析其 tool、hook、provider、resource、command、theme、prompt、skill 等贡献 +- **AND** SHALL 在一次统一装配流程中完成校验与注册 + +### Requirement: plugin integration SHALL 不再只依赖 HookHandler 适配 + +plugin hook 集成 MUST 基于统一 hooks 平台接入，而不是继续把 plugin hook 视为 `core::HookHandler` 的薄适配层。 + +#### Scenario: plugin hook 进入统一 hooks registry +- **WHEN** 某个 plugin 声明 lifecycle hooks +- **THEN** 其 handlers SHALL 进入统一 hooks registry +- **AND** SHALL 与 builtin hooks 共享相同的事件、effect 与执行语义 + +### Requirement: plugin reload SHALL 以候选 surface commit/rollback 方式完成 + +plugin 集成 MUST 使用候选 surface 构建、校验、commit/rollback 的方式进行 reload，而不是边发现边直接修改当前生效 surface。 + +#### Scenario: reload 失败不污染当前 surface +- **WHEN** 某次 plugin reload 在校验或装配阶段失败 +- **THEN** 当前 active surface SHALL 保持不变 +- **AND** 系统 SHALL 报告失败原因 + +### Requirement: collaboration capabilities SHALL 通过统一 plugin surface 接入 + +多 agent 协作相关能力 MUST 通过统一 plugin surface 接入，而不是继续保留 `application` 或 `server` 私有特判入口。协作 surface 可以是 tool、command 或其他 plugin contribution，但它们 SHALL 只调用 `host-session` 的正式 use-case surface。 + +#### Scenario: 协作入口从 plugin surface 调用 host-session +- **WHEN** 某个 builtin collaboration tool 或 command 需要启动 child session、向 child 发送消息或终止子树 +- **THEN** 该入口 SHALL 通过统一 plugin integration 进入 active snapshot +- **AND** SHALL 通过 `host-session` 完成 durable truth 写入与后续 runtime 驱动 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-persistence/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-persistence/spec.md new file mode 100644 index 00000000..00a0f269 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-persistence/spec.md @@ -0,0 +1,19 @@ +## ADDED Requirements + +### Requirement: session persistence SHALL 归属 `host-session` + +事件日志、session meta、冷恢复、branch/fork durable truth 与 read model 恢复 MUST 归属 `host-session` crate，而不是继续由 live runtime 或已删除的 `application` 承担。 + +#### Scenario: 持久化 owner 与 live runtime 解耦 +- **WHEN** 某个 turn 产生 durable events +- **THEN** `host-session` SHALL 负责其追加、恢复与后续投影 +- **AND** `agent-runtime` SHALL 不再拥有全部持久化服务职责 + +### Requirement: session persistence SHALL 不依赖兼容影子状态 + +重构后系统 MUST 仅以事件日志与正式投影作为 session durable truth，SHALL NOT 通过旧 `application` 缓存、旧 runtime shadow state 或过渡兼容表维护第二套真相。 + +#### Scenario: 冷恢复不读取兼容缓存 +- **WHEN** 服务重启后恢复某个 session +- **THEN** 系统 SHALL 仅从事件日志与正式投影恢复 +- **AND** SHALL NOT 读取兼容 shadow state diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-runtime/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-runtime/spec.md new file mode 100644 index 00000000..6d36cbca --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/session-runtime/spec.md @@ -0,0 +1,13 @@ +## REMOVED Requirements + +### Requirement: `session-runtime` 是唯一会话真相面 + +**Reason**: 本次重构将旧的大一统 `session-runtime` 拆解为 `agent-runtime` 与 `host-session` 两个 owner，分别负责最小 live runtime 与 durable session truth，不再保留单一 monolith crate 作为全部会话真相面。 + +**Migration**: 将 live turn/agent loop 相关实现迁入 `agent-runtime`；将事件日志、恢复、catalog、query/read model、branch/fork 迁入 `host-session`；删除旧 monolith `session-runtime` 的正式 owner 地位。 + +### Requirement: 会话执行构造逻辑归 `session-runtime` + +**Reason**: turn 构造与执行循环将迁入新 `agent-runtime` crate；旧 `session-runtime` 不再继续作为 live runtime owner。 + +**Migration**: 将 `build_agent_loop`、`LoopRuntimeDeps`、`AgentLoop`、`TurnRunner` 等 live runtime 构造迁入 `agent-runtime`，由 `host-session` 负责驱动调用。 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/tool-and-skill-discovery/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/tool-and-skill-discovery/spec.md new file mode 100644 index 00000000..0e681682 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/tool-and-skill-discovery/spec.md @@ -0,0 +1,19 @@ +## ADDED Requirements + +### Requirement: discovery SHALL 升级为统一资源发现面 + +系统的 discovery MUST 不再只覆盖 tools 与 skills，而是升级为统一资源发现面，至少覆盖 tools、commands、prompts、skills、themes 与其他 plugin 贡献的用户可见资源。 + +#### Scenario: 单次 discovery 返回多类资源候选 +- **WHEN** 某个交互式 surface 请求当前可用候选 +- **THEN** 系统 SHALL 能返回 tool、command、prompt、skill、theme 等多类候选 +- **AND** 这些候选 SHALL 来自同一当前 active snapshot + +### Requirement: discovery SHALL 由 plugin-host 驱动 + +统一资源发现 MUST 由 `plugin-host` 的当前生效 descriptor/snapshot 驱动，而不是由 server、CLI 或其他客户端各自维护平行目录。 + +#### Scenario: 新 plugin 资源在 reload 后被统一发现 +- **WHEN** 某个 plugin 新增 prompt、skill 或 command 并成功 reload +- **THEN** 新资源 SHALL 自动进入统一 discovery 结果 +- **AND** 客户端 SHALL 不需要维护独立的本地注册表 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/specs/turn-orchestration/spec.md b/openspec/changes/plugin-first-runtime-rearchitecture/specs/turn-orchestration/spec.md new file mode 100644 index 00000000..d19b8b76 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/specs/turn-orchestration/spec.md @@ -0,0 +1,19 @@ +## ADDED Requirements + +### Requirement: turn orchestration SHALL 归属 `agent-runtime` + +turn loop、provider 调用、tool dispatch、hook dispatch、stop/continue 判定与取消传播 MUST 由新 `agent-runtime` 统一拥有。workflow、discovery、plugin origin 判定等宿主逻辑 SHALL 不再直接嵌入 turn loop。 + +#### Scenario: turn loop 只围绕执行主链工作 +- **WHEN** 一次 turn 从 prompt 开始执行 +- **THEN** `agent-runtime` SHALL 只负责 `prompt -> provider -> tool/hook dispatch -> continue/stop` +- **AND** SHALL NOT 在 loop 中自行做 plugin discovery、theme/prompt/skill 搜索或 workflow 特判装配 + +### Requirement: turn orchestration SHALL 消费统一 hooks 事件点 + +turn orchestration MUST 在执行主链中显式触发统一 hooks 事件点，而不是只支持窄版 tool/compact hooks。 + +#### Scenario: turn 执行过程中触发扩展后的事件点 +- **WHEN** 一次 turn 完整执行 +- **THEN** 系统 SHALL 至少触发 `context`、`before_agent_start`、`before_provider_request`、`tool_call`、`tool_result`、`turn_start`、`turn_end` +- **AND** 这些事件 SHALL 由统一 hooks 平台接管 diff --git a/openspec/changes/plugin-first-runtime-rearchitecture/tasks.md b/openspec/changes/plugin-first-runtime-rearchitecture/tasks.md new file mode 100644 index 00000000..073cdaa1 --- /dev/null +++ b/openspec/changes/plugin-first-runtime-rearchitecture/tasks.md @@ -0,0 +1,531 @@ +## 移植参考：旧架构必须保留的机制 + +> 以下是旧 `session-runtime` / `core` / `server` 中已验证的实现，必须等价迁入新架构。 +> codex 在执行迁移任务时，应先读取源文件，理解其实现，再等价搬到目标 crate。 + +### 必须保留的事件模型（留在 core） + +- `core/src/event/types.rs`：`StorageEvent` / `StorageEventPayload` / `StoredEvent` / `CompactTrigger` / `CompactMode` / `CompactAppliedMeta` / `TurnTerminalKind` / `PromptMetricsPayload`。 + - 20+ 种事件变体原样保留。 + - `storage_seq` 单调递增由 session writer 独占分配。 + - 校验规则（SessionStart 禁止 turn_id/agent，SubRun 要求 child_session_id）原样保留。 +- `core/src/event/` 中 `EventTranslator`、`AgentEvent`、`SessionEventRecord` 等翻译层原样保留。 + +### 必须保留的持久化合同（留在 core 或迁入 host-session） + +- `core/src/store.rs`：`EventLogWriter`、`EventStore`、`SessionManager`、`SessionTurnLease`、`SessionTurnAcquireResult`、`SessionTurnBusy`、`StoreError`。 + - 这些 trait 是跨 crate 共享的稳定合同，继续留在 core。 + - `FileSystemSessionRepository`（adapter-storage）实现不变。 + +### 必须迁入 host-session 的机制 + +- **ProjectionRegistry**（`session-runtime/src/state/projection_registry.rs`）： + - 增量投影：对每条 StoredEvent 做 `apply()` 更新 AgentState、turn 投影、child nodes、active tasks、input queue、mode state。 + - `from_recovery()`：从 checkpoint + tail events 重建完整投影。 + - `snapshot_projected_state()` → `AgentState`。 +- **SessionState**（`session-runtime/src/state/mod.rs`）： + - 组合 projection + writer + 双通道广播。 + - `append_and_broadcast(event, translator)`：append → apply → translate → broadcast。这是事件写入的唯一生产路径。 + - `translate_store_and_cache(stored, translator)`：validate → apply projection → translate → cache records。 + - 双通道广播：`broadcaster: Sender`（durable）和 `live_broadcaster: Sender`（live）。 + - `from_recovery(writer, checkpoint, tail_events)` 恢复流原样保留。 +- **SessionWriter**（`session-runtime/src/state/writer.rs`）： + - 异步 `EventStore` 包装 + 同步 `EventLogWriter` 兼容层。 + - `append()` 异步写入，测试态走 `spawn_blocking` 桥接同步 writer。 +- **恢复模型**： + - `SessionRecoveryCheckpoint`（core）原样保留。 + - 恢复流：open_event_log → 读取 checkpoint → replay tail events → SessionState::from_recovery。 + - checkpoint 包含 `childNodes`、`activeTasks`、`inputQueueProjectionIndex` 等投影快照。 +- **事件广播常量**：`SESSION_BROADCAST_CAPACITY = 2048`、`SESSION_LIVE_BROADCAST_CAPACITY = 2048`。 + +### 必须迁入 agent-runtime 的机制 + +- **run_turn**（`session-runtime/src/turn/runner.rs`）： + - 主循环：`loop { run_single_step() → StepOutcome::Continue/Completed/Error }`。 + - 每步后 `flush_pending_events()` 批量写入事件。 + - 取消时写入 `TurnDone(Cancelled)` 后退出。 + - 返回 `TurnRunResult`。 +- **TurnRunRequest**（`session-runtime/src/turn/request.rs`）： + - 输入结构：session_id, working_dir, turn_id, messages, event_store, session_state, cancel, agent context, prompt_declarations, capability_router, prompt_governance。 + - 拆分为：agent-runtime 只接收最小执行面（`TurnInput`），host-session 负责装配其余部分。 +- **TurnExecutionContext / TurnExecutionResources**（`session-runtime/src/turn/runner.rs`）： + - execution 上下文和资源持有。 + - step 执行、journal 管理、lifecycle 转换。 +- **流式输出**（`session-runtime/src/turn/` 中 stream 相关）： + - provider streaming → AssistantDelta 事件 → live broadcast。 + - tool streaming → ToolCallDelta 事件。 +- **取消传播**（`session-runtime/src/turn/` 中 cancel 相关）： + - cancel token → provider abort → pending tool abort → TurnDone(Cancelled)。 + +### server 组合根保留的设计 + +- `ServerBootstrapOptions`：可覆盖选项（home_dir, working_dir, plugin_search_paths, enable_profile_watch, watch_service_override）。 +- `ServerBootstrapPaths`：从 options 解析路径。 +- profile watch runtime 和 MCP warmup 后台任务模式。 +- config 覆盖层（用户级 → 项目级）。 + +--- + +## 0. 删除验收清单 + +> 这一组不是“第一步就执行删除”，而是本次 change 的最终验收条件。 +> 实际执行顺序应先完成 `1` 到 `7.5` 的迁移、切换与清理，再回到这里做总收口。 +> 仓库允许保留旧源码目录作为迁移归档源，但它们不得继续参与活跃 workspace、正式依赖图或对外 surface。 + +- [x] 0.1 移除整个旧边界的正式 workspace 成员与正式依赖：`crates/application/**`、`crates/kernel/**`、旧 `crates/session-runtime/**`，以及被 `plugin-host` 取代后的旧 `crates/plugin/**` 只允许作为迁移归档源保留；以活跃 workspace / 正式 crate 依赖图中不再出现这些旧边界为验证。 +- [x] 0.2 收缩 `core` 的正式公开面，只保留跨 owner 共享语义；`projection/**`、`session_plan.rs`、`composer.rs`、`plugin/registry.rs`、`session_catalog.rs`、旧 `PluginManifest`、旧 `HookInput` / `HookOutcome`、`SubRunHandle`、`InputQueueProjection` 等 owner-only 能力不再作为 `core` 顶层默认导出，新调用方统一通过 owner bridge（主要是 `host-session` / `plugin-host`）消费；`ModeId`、durable event DTO、runtime config、observability wire metrics、`store.rs` 等跨 owner 稳定合同按既定例外保留。 +- [x] 0.3 移除 `application` 作为正式编排入口：`src/agent/**`、`src/execution/root.rs`、`src/execution/subagent.rs`、`src/governance_surface/**`、`src/mode/**`、`src/workflow/**`、`src/mcp/mod.rs`、`src/composer/mod.rs`、`src/ports/**` 等旧实现点只允许作为迁移归档源保留，不能再作为活跃实现入口或正式依赖。 +- [x] 0.4 移除多 agent 协作的旧跨层真相承载点：旧 `kernel` / `session-runtime` / `application` 中分散的 subrun 持久化、结果回传、取消传播和 input queue 真相不再参与正式路径；以 collaboration durable truth 只剩 `host-session` owner 为验证。 +- [x] 0.5 移除 server 组合根里的旧并列事实源与旁路装配语义：`runtime.rs`、`providers.rs`、`plugins.rs`、`mcp.rs`、`governance.rs`、`capabilities.rs`、`watch.rs`、`deps.rs`、`runtime_coordinator.rs` 等剩余文件只允许作为 server-owned bridge / facility 存在，不得再回退到 application/kernel/session-runtime 式手工并列装配；未参与编译的旧旁路文件（如 `prompt_facts.rs`）必须删除。 +- [x] 0.6 项目无向后兼容：活跃 workspace、正式依赖图和对外 surface 不再承诺旧 crate / 旧装配路径 / 旧 facade 的兼容性；必要的 compat 仅允许留在私有 bridge/helper 中，不能重新升级为正式入口。 + +## 1. 架构定版与 crate 骨架 + +- [x] 1.1 更新 `PROJECT_ARCHITECTURE.md`，把 `agent-runtime`、`host-session`、`plugin-host` 写成新的正式边界，并删除 `application`、`kernel`、monolith `session-runtime` 的长期权威定义。 +- [x] 1.2 更新 `node scripts/check-crate-boundaries.mjs` 与 workspace 依赖规则，禁止新边界回头依赖旧 `application` / `kernel` / monolith `session-runtime`。 +- [x] 1.3 在 `crates/` 下新建 `agent-runtime`、`host-session`、`plugin-host` crate，并更新根 `Cargo.toml`、workspace 文档与最小公开入口，确保空骨架能编译通过。 + +## 2. 收缩 `core` + +- [x] 2.1 重构 `crates/core` 导出面，只保留 `ids`、消息模型、`CapabilitySpec`、最小 prompt/hook 共享语义；把 `PluginDescriptor` / `PluginActiveSnapshot` / descriptor 家族迁入 `plugin-host`，把 `AgentRuntimeExecutionSurface` 迁入 `agent-runtime`，把 `HostSessionSnapshot` 与恢复/投影模型迁入 `host-session`。 +- [x] 2.2 拆散 `crates/core/src/ports.rs`： + - `EventStore`、`EventLogWriter`、`SessionManager`、`SessionTurnLease`、`SessionTurnAcquireResult`、`SessionTurnBusy` → 留在 core（跨 crate 共享合同）。 + - `PromptDeclaration`、`PromptGovernanceContext` → 留在 core（被 prompt 组装和 hooks 共用）。 + - `PromptProvider`、`PromptFactsProvider` → 迁入 host-session（owner 专属）。 + - `ResourceProvider` → 迁入 plugin-host（owner 专属）。 + - `LlmProvider` → 迁入 agent-runtime（owner 专属）或独立 provider 合同模块。 + - 验证：`core::ports` 不再作为 mega 入口。 +- [x] 2.3 从 `crates/core/src/agent/*` 迁出协作模型： + - `SubRunHandle`、`InputQueueProjection` → host-session owner bridge。 + - `CollaborationExecutor`、`SubAgentExecutor` 相关合同 → host-session owner bridge。 + - `AgentEventContext`、`ChildSessionNotification`、`SubRunResult` → 留在 core（跨 crate 共享）。 + - `ChildAgentRef`、`ChildSessionNode`、`ChildSessionLineageKind` 暂留 core，作为 `ChildSessionNotification` / `StorageEventPayload` 的嵌入式 durable event DTO；后续只有在事件 DTO 拆分出稳定 wire schema 后再迁出。 + - 验证：新调用方通过 host-session owner bridge 消费执行/read-model 类型和协作执行合同；`core` 顶层导出面不再暴露 `SubRunHandle`、`InputQueueProjection`、`CollaborationExecutor`、`SubAgentExecutor`。 +- [x] 2.4 迁出或删除 `crates/core/src/projection/`、`workflow.rs`、`plugin/registry.rs`、`session_catalog.rs` 等可安全迁移的 owner 专属模块，并记录 `mode` / config / observability 的共享合同例外： + - `projection/` → host-session（由 ProjectionRegistry 消费）。 + - `workflow.rs` → host-session。 + - `mode/` 中 `ModeId`、durable mode-change event DTO、`ToolContext` 所需的 bound tool contract snapshot 暂留 core；治理 DSL / builtin mode owner 逻辑在 6.3 迁往 plugin-host，避免当前反向依赖。 + - `plugin/registry.rs` → plugin-host（已有等价实现）。 + - `session_catalog.rs` → host-session。 + - `session_plan.rs` → host-session。 + - `config.rs` 中 runtime config / resolved config 暂留 core 作为 session-runtime、server、adapter-storage 的共享合同；配置持久化和 owner-only 解析逻辑归 application/server，后续协议拆分后再继续收缩。 + - `observability.rs` 中 wire metrics snapshot 暂留 core 供 application 与 protocol 共享；collector / governance summary 已归 application，后续协议 DTO 独立后再迁出。 + - `store.rs` → 留在 core（跨 crate 共享合同）。 + - `composer.rs` → host-session。 + - 验证：`core` 导出面显著收缩；`cargo check --workspace` 通过；`core` 不再导出 `projection`、`workflow`、`session_plan`、`session_catalog`、`composer`、`PluginRegistry`。 +- [x] 2.5 删除旧窄版 `PluginManifest`（`core/src/plugin/manifest.rs`）、旧 `HookInput` / `HookOutcome`（`core/src/hook.rs`）相关公开暴露，确保新实现只围绕 descriptor / envelope / effect 模型展开。 + +## 3. 建立最小 `agent-runtime` + +- [x] 3.1 在 `crates/agent-runtime` 中建立骨架模块和 `execute_turn` 入口。 +- [x] 3.2 从旧 `session-runtime/src/turn/runner.rs` 迁出 turn 主循环： + - 源：`run_turn(kernel, TurnRunRequest)` → 目标：`AgentRuntime::execute_turn(TurnInput) → TurnOutput`。 + - 迁出 `run_single_step()` 和 `StepOutcome::Continue/Completed/Error`。 + - 迁出 `TurnExecutionContext` 和 `TurnExecutionResources`。 + - 迁出 `flush_pending_events()` 的事件批处理逻辑（改为通过回调发出，不直接写 EventStore）。 + - 迁出 `TurnStopCause` 和 turn terminal 判断。 + - 关键约束：agent-runtime 不持有 EventStore、不持有 SessionState、不持有 PluginRegistry。 + 所有有状态依赖通过 TurnInput 传入或通过 `emit_event` 回调发出。 + - 验证：`execute_turn` 可驱动空流程和基本 turn 生命周期。 +- [x] 3.3 迁出 provider 请求和 continuation cycle： + - 源：`session-runtime/src/turn/runner.rs` 中 provider 调用路径。 + - 迁出 provider stream → `AssistantDelta` / `ThinkingDelta` / `AssistantFinal` 事件的产出。 + - 迁出 continuation 判断（stop / tool_use / continue）。 + - agent-runtime 通过 `TurnInput.provider_ref` 路由到具体 LLM 实现，不硬编码 OpenAI。 + - 验证：provider turn 集成测试通过。 +- [x] 3.4 迁出 tool dispatch 和 tool-result 回环： + - 源：`session-runtime/src/turn/` 中 tool call 执行和结果处理。 + - 迁出 tool call → `ToolCall` / `ToolCallDelta` / `ToolResult` 事件的产出。 + - 迁出 tool result → continuation 判断。 + - agent-runtime 通过 `TurnInput.tool_specs` 匹配工具，通过 plugin-host dispatch 调用。 + - 验证：tool call / tool result 测试通过。 +- [x] 3.5 接入 hooks 调度链： + - 迁出 hook dispatch 逻辑，覆盖 `turn_start` / `context` / `before_agent_start` / `before_provider_request` / `tool_call` / `tool_result` / `turn_end`。 + - hooks 通过 `TurnInput.hook_snapshot_id` 查找，不直接持有 hook registry。 + - 实现 dispatch mode：顺序 / 可取消 / 可拦截 / 可修改 / 管道式 / 短路式。 + - 验证：hooks 顺序、阻断、修改语义测试通过。 +- [x] 3.6 迁出取消和流式传播控制： + - 源：`session-runtime/src/turn/` 中 cancel token 和 streaming。 + - 迁出 cancel → provider abort → pending tool abort → `TurnDone(Cancelled)` 传播。 + - 迁出 streaming delta 通过 `emit_event` 回调发出。 + - 验证：取消与流式恢复测试通过。 +- [x] 3.7 验证 child-session 执行合同边界： + - agent-runtime 只执行 child turn，不持有 `SubRunHandle`、不感知 input queue、不感知父子关系。 + - 协作上下文通过 `TurnInput.agent` 中的 `AgentEventContext` 传入。 + - 验证：runtime 公共 API 审查无协作状态泄漏。 + +## 4. 建立 `host-session` + +- [x] 4.1 迁入事件日志基础设施： + - 从 `session-runtime/src/state/writer.rs` 迁入 `SessionWriter`（异步 EventStore 包装 + 同步 EventLogWriter 兼容层）。 + - 从 `session-runtime/src/state/projection_registry.rs` 迁入 `ProjectionRegistry`（增量投影 + from_recovery）。 + - 从 `session-runtime/src/state/mod.rs` 迁入 `SessionState`（projection + writer + 双通道广播）。 + - 保留 `append_and_broadcast(event, translator)` 作为事件写入唯一生产路径。 + - 保留双通道广播：`broadcaster: Sender`（durable）和 `live_broadcaster: Sender`（live）。 + - 保留广播容量常量 `SESSION_BROADCAST_CAPACITY = 2048`。 + - 迁入 `translate_store_and_cache(stored, translator)` 流程。 + - 从 `session-runtime/src/state/execution.rs` 迁入 `append_and_broadcast` 自由函数和 `checkpoint_if_compacted`。 + - 验证：恢复、投影和广播测试通过。 +- [x] 4.2 迁入恢复流和 session catalog： + - 从 `session-runtime/src/state/mod.rs` 迁入 `SessionState::from_recovery(writer, checkpoint, tail_events)`。 + - 保留恢复流：open_event_log → 读取 checkpoint → replay tail events → from_recovery。 + - 从 `session-runtime/src/lib.rs` 迁入 `LoadedSession` 和 session DashMap。 + - 保留 `SessionManager::try_acquire_turn` → `SessionTurnAcquireResult::Acquired/Busy` → RAII lease。 + - 从 `session-runtime/src/catalog/` 迁入 session catalog（list/create/delete）。 + - 验证：session 恢复、创建和列表测试通过。 +- [x] 4.3 迁入 branch/fork/compact： + - 从 `session-runtime/src/turn/branch.rs` 迁入 branch 逻辑。 + - 从 `session-runtime/src/turn/fork.rs` 迁入 fork 逻辑。 + - 从 `session-runtime/src/turn/compaction_cycle.rs` 和 `manual_compact.rs` 迁入 compaction。 + - 从 `session-runtime/src/turn/watcher.rs` 迁入 compaction watcher。 + - compaction 产出 `CompactApplied` 事件，通过 `append_and_broadcast` 持久化。 + - 验证：branch/fork/compact 测试通过。 +- [x] 4.4 迁入多 agent 协作 durable truth： + - `host-session` 已有 `SubRunHandle`、`InputQueueProjection`、`HostSession`（spawn_child/send_to_child/send_to_parent/observe_subtree/terminate_subtree）。 + - 从旧实现迁入持久化集成： + - `session-runtime/src/turn/finalize.rs` 中 subrun finished 持久化 → host-session 的事件写入。 + - `session-runtime/src/turn/interrupt.rs` 中 cancel subruns → host-session 的 terminate_subtree + 事件写入。 + - `session-runtime/src/state/child_sessions.rs` 中 child node 追踪 → host-session 的 lineage 管理。 + - `session-runtime/src/state/input_queue.rs` 中 input queue 投影 → host-session 的 InputQueueProjection 持久化。 + - 落地"一个 session 即一个 agent"的协作模型：父 turn 发起 child session → host 记录 durable linkage → host 调用 agent-runtime 执行 child turn。 + - 验证：child-session 恢复、取消和结果回传测试通过。 +- [x] 4.5 迁入 query/read model： + - 从 `session-runtime/src/query/` 迁入 query 服务（conversation snapshot, subrun query, conversation stream replay）。 + - 从 `session-runtime/src/observe.rs` 迁入 observe 机制（SessionObserveSnapshot, wait_for_turn_terminal_snapshot）。 + - query 直接读 ProjectionRegistry，不额外持久化。 + - 验证：query 和 observe 测试通过。 +- [x] 4.6 为 `host-session` 提供正式协作用例入口（已实现：spawn_child, send_to_child, send_to_parent, observe_subtree, terminate_subtree）。 + +## 5. 建立 `plugin-host` 与统一 surface + +- [x] 5.1 实现 descriptor 校验、registry、candidate snapshot、active snapshot、commit/rollback 和 revision 管理。 +- [x] 5.2 实现 builtin plugin backend 与 external plugin backend 共用同一 descriptor/snapshot 语义。 +- [x] 5.3 统一资源发现： + - 将 skills、prompts、themes、commands、其他资源入口统一纳入 `resources_discover` 与 `PluginDescriptor` 聚合流程。 + - 从 `server/src/bootstrap/composer_skills.rs` 迁入 skill catalog 构建。 + - 从 `server/src/bootstrap/prompt_facts.rs` 迁入 prompt facts 组装。 + - 移除平行发现路径。 + - 验证：统一资源目录测试和冲突校验测试通过。 +- [x] 5.4 统一 provider contribution： + - 将 provider 纳入 `plugin-host` 的统一 registry / active snapshot。 + - 从 `server/src/bootstrap/providers.rs` 迁入 provider 选择和实例化。 + - 去除 `provider_kind == openai` 硬编码，改为通过 `ProviderDescriptor` 注册。 + - 验证：provider registry 集成测试通过。 +- [x] 5.5 将 builtin tools 迁为 builtin plugin： + - 从 `server/src/bootstrap/capabilities.rs` 中 `build_core_tool_invokers` + `build_agent_tool_invokers` → 改为 builtin `PluginDescriptor`（tools 字段填充 builtin tools）。 + - 从 `server/src/bootstrap/mcp.rs` 中 MCP invokers → 改为 builtin 或 external `PluginDescriptor`（tools 字段填充 MCP tools）。 + - 所有 invoker 注册走 `plugin_host.reload_with_builtin_and_loader()`。 + - 验证：builtin tools 通过 plugin-host active snapshot 可查可执行。 +- [x] 5.6 将协作入口收敛为 builtin plugin tools： + - `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree` → builtin `PluginDescriptor` 的 tools 字段。 + - 这些 surface 只调用 `host-session` use-case，不持有 collaboration durable truth。 + - 验证：协作入口集成测试通过。 +- [x] 5.7 实现 hooks 统一扩展总线： + - 定义 `HookDescriptor`（已在 descriptor.rs 中）。 + - 实现事件分发语义：顺序 / 可取消 / 可拦截 / 可修改 / 管道式 / 短路式。 + - 覆盖事件面：input, context, before_agent_start, before_provider_request, tool_call, tool_result, turn_start, turn_end, session_before_compact, resources_discover, model_select。 + - governance prompt hooks 继续通过 `PromptDeclaration` / `PromptGovernanceContext` 进入 prompt 组装，不新增平行 prompt 渲染系统。 + - 验证：hooks 顺序、阻断、修改语义测试通过。 + +## 6. 切换组合根与删除旧边界 + +- [x] 6.1 重写 server 组合根装配路径： + - 旧路径：手工拼接 core_tool_invokers + agent_tool_invokers + mcp_invokers + plugin_invokers + capability_sync + kernel + application + session_runtime。 + - 当前桥接路径： + ``` + build_server_plugin_contribution_descriptors(...) + → reload_server_plugin_host_snapshot(...) + → PluginActiveSnapshot + ResourceCatalog + ProviderContributionCatalog + ``` + - 迁移期允许旧 `application` / `kernel` / `session-runtime` 继续承载现有 HTTP/API 调用面，但 server bootstrap 中 plugin/provider/resource 的生效事实必须先收敛为同一组 `PluginDescriptor[]` 产物。 + - `host_session = HostSession::new(...)`、`agent_runtime = AgentRuntime::new()` 和旧 crate 正式依赖删除保留到 6.5 / 0.* 验收清单执行，避免本任务同时跨越 API 调用方切换和旧边界删除。 + - 保留 `ServerBootstrapOptions` 和 `ServerBootstrapPaths`。 + - 保留 profile watch runtime 和 MCP warmup 后台任务模式。 + - 验证：server 编译通过和启动冒烟验证。 +- [x] 6.2 重写 provider 装配： + - 旧：`server/src/bootstrap/providers.rs` 中 `ConfigBackedLlmProvider` 对 `provider_kind != openai` 报错。 + - 新：通过 plugin-host 的 `ProviderDescriptor` 注册 provider，server 不再硬编码 provider kind。 + - 验证：新增 provider 不再要求改组合根。 +- [x] 6.3 迁移 governance / mode / workflow 到 plugin/host 层： + - 当前桥接路径：`ModeCatalog` / `builtin_mode_catalog()` 的生效输入先迁为 plugin-host descriptor 的 `modes` 贡献，server 从 `PluginActiveSnapshot` 派生 builtin/plugin mode catalog。 + - `GovernanceSurfaceAssembler` / `AppGovernance` 与 `WorkflowOrchestrator` 迁移期继续作为旧 API 调用面的消费者存在，但不得再作为 mode 生效事实源；完整 owner 删除放到 6.5 / 0.*。 + - 验证：builtin/plugin modes 通过 plugin-host active snapshot 进入 mode catalog，server bootstrap 不再直接用旁路 `plugin_modes` 替换 catalog。 +- [x] 6.4 更新 sdk / protocol / adapter-* 调用方： + - 统一改用新 DTO、hooks catalog 和 plugin descriptor。 + - 不再暴露旧 `application` / `kernel` / `session-runtime` 内部类型。 + - 验证：全 workspace 编译通过和类型错误清零。 +### 6.5 分阶段删除旧边界 + +> `6.5` 不再作为一次性删除任务执行。旧 `application` / `kernel` / `session-runtime` / `plugin` 仍被 server/API 调用面编译依赖，必须先按下面顺序切换调用方，再执行 `0.*` 删除验收。 + +- [x] 6.5.1a 切换 config / model API 面： + - 将 `routes/config.rs`、`routes/model.rs`、provider/profile resolution 和 config selection 从 `App::config()` 迁到 server-owned config/profile service 或新 owner service。 + - `ApplicationError` 映射同步替换为 server/core error 映射。 + - 验证：config/model 路由不再通过 `state.app` 访问配置。 +- [x] 6.5.1b-1 切换 session catalog CRUD / fork / catalog stream API 面： + - 将 `routes/sessions/query.rs`、`routes/sessions/mutation.rs`、`routes/sessions/stream.rs` 的 list/create/delete/delete_project/fork/catalog stream 调用迁到 server-owned `host-session::SessionCatalog`。 + - fork 迁移期允许保留 server-side plan artifact copy bridge，但 catalog durable truth 必须由 `host-session` 写入事件日志。 + - 验证：session catalog CRUD/fork/catalog stream 路由不再通过 `state.app` 访问 session catalog 用例。 +- [x] 6.5.1b-2a 建立 `host-session` turn mutation 合同： + - 在 `host-session` 定义 submit/compact/interrupt 的 owner 输入输出类型与 facade，覆盖 `PromptAcceptedSummary`、`CompactSessionSummary`、interrupt accepted 语义。 + - 合同必须显式区分 `host-session` 拥有的 durable turn mutation 与迁移期仍由 server/application bridge 提供的 governance/workflow/skill-invocation 准备。 + - 验证：新合同不依赖 `application`、旧 `session-runtime` 或 `kernel`。 +- [x] 6.5.1b-2b 迁移 submit acceptance / branch-on-busy 归属： + - 将 turn id 生成、busy lease 获取、branch-on-busy 目标解析和 `ExecutionAccepted` 等价摘要迁到 `host-session::SessionCatalog` / turn mutation facade。 + - `application` 可短期只作为 prompt/governance/workflow 准备 bridge，不再拥有 submit target 决策。 + - 验证：submit acceptance 单测覆盖空输入、busy branch、reject-on-busy 和 accepted response shape。 +- [x] 6.5.1b-2c 接通 `agent-runtime` 执行事件持久化： + - 将 `agent-runtime::RuntimeTurnEvent` 映射到 `host-session` durable event append / projection / broadcast / checkpoint 路径。 + - 保留必要 provider/tool/hook dispatcher bridge，但 turn loop 执行结果不得再由旧 `session-runtime` finalizer 作为唯一持久化入口。 + - 验证：最小 turn 执行能通过 `host-session` 持久化 user/assistant/terminal 事件，并能由 read model 恢复。 +- [x] 6.5.1b-2d 迁移 compact / interrupt owner 行为： + - 将 manual compact 的立即执行/延迟登记、interrupt cancel token、terminal cancelled event、pending compact flush 迁到 `host-session` turn mutation facade。 + - 子运行取消传播可通过临时 executor bridge 调用现有协作入口，但 durable 状态必须由 `host-session` 记录。 + - 验证：compact/interrupt contract tests 不再依赖旧 `session-runtime` 方法。 +- [x] 6.5.1b-2e 切换 server submit/compact/interrupt 路由： + - 将 `routes/sessions/mutation.rs` 的 submit_prompt/compact_session/interrupt_session 从 `state.app` 切换到 server-owned `host-session` turn mutation facade。 + - server 可保留协议 DTO mapper，但不得调用 `application::App` turn/session mutation use-case。 + - 验证：submit/compact/interrupt 路由不再通过 `state.app` 访问 turn 用例，`cargo check -p astrcode-server` 与 session contract tests 通过。 +- [x] 6.5.1b-3 切换 session mode API 面： + - 将 list_modes/get_session_mode/switch_mode 调用迁到 `plugin-host` mode catalog 与 `host-session` mode state owner。 + - 验证：mode 相关 session 路由不再通过 `state.app` 访问 mode 用例。 +- [x] 6.5.1c 切换 conversation / terminal read-model API 面： + - 将 `routes/conversation.rs`、`terminal_projection.rs`、terminal resume/snapshot/stream facts 从 `application::terminal_queries` 迁到 `host-session` query/read-model 与 server projection adapter。 + - 验证：conversation/terminal 路由不再引用 `astrcode_application::terminal*`。 +- [x] 6.5.1d 切换 composer / resource discovery API 面： + - 将 composer options、skills、commands、prompt/theme/resource discovery 从 `application::composer` 迁到 `plugin-host::ResourceCatalog` / descriptor-derived catalog。 + - 验证：composer 路由和 mapper 不再引用 `ComposerOption*` 的 application 类型。 +- [x] 6.5.1e 切换 agent collaboration API 面： + - 将 agent status、root execute、close/observe 和 builtin collaboration tools 从 `AgentOrchestrationService` 迁到 `host-session` collaboration use-case 与 `plugin-host` collaboration surface。 + - 验证：agent routes 和 builtin collaboration invokers 不再依赖 `application::agent`。 +- [x] 6.5.1f 移除 server 的 `application::App` 状态入口： + - 分阶段完成：先移除生产路由/状态对 `App` facade 的依赖，再清理 bootstrap/watch/测试辅助中的 `App` 过渡桥，最后删除 `server` 对 `astrcode-application` 的正式依赖。 + - 只有全部子任务完成后，才能视为 `6.5.1f` 完成。 +- [x] 6.5.1f-1 移除生产态 `App` facade 路由入口： + - `ServerRuntime` / `AppState` 在生产路径上显式持有 agent/config/session/profile/MCP/resource/mode/governance 等 owner service，agent/composer/MCP 路由不再通过 `App` facade。 + - 允许迁移期保留 `cfg(test)` 的 `App` shim，仅供未迁完的 server 测试辅助复用。 + - 验证：生产构建下 `server` 路由代码不再引用 `state.app` / `runtime.app`，`cargo check -p astrcode-server` 通过。 +- [x] 6.5.1f-2 清理 bootstrap/watch/测试辅助里的 `App` 过渡桥： + - profile watch 改为直接消费 `SessionCatalog + ProfileResolutionService`，server 测试辅助改为显式 owner service，不再通过 `App::list_sessions` / `App::profiles` / `App::agent` 等 helper。 + - 删除 `cfg(test)` 下仅为 server 测试保留的 `AppState.app` / `ServerRuntime.app` 过渡字段。 + - 验证：`cargo test -p astrcode-server --no-run` 与路由级测试在无 `App` shim 情况下通过。 +- [x] 6.5.1f-3 删除 server 对 `astrcode-application` 的正式依赖： + - 分阶段完成：先移除 routes/mapper 对 `application` 摘要类型和请求 DTO 的直接依赖，再抽离 bootstrap/watch/MCP/governance/profile bridge，最后删除 `Cargo.toml` 中的正式依赖并做全量验证。 + - 只有全部子任务完成后，才能视为 `6.5.1f-3` 完成。 +- [x] 6.5.1f-3a 收敛 agent route / mapper 的 `application` 摘要类型依赖： + - 为 server 引入本地 bridge DTO / summary，agent routes 和 mapper 不再直接引用 `AgentExecuteSummary`、`RootExecutionRequest`、`SubRunStatusSummary` 等 `application` 类型。 + - 迁移期允许 `server` 内部 bridge 实现继续调用 `application` 用例，但协议层输入输出必须只依赖 server/core/protocol 类型。 + - 验证：相关 routes / mapper 编译通过，agent/config 路由测试通过。 +- [x] 6.5.1f-3b 抽离 bootstrap/watch/MCP/governance/profile bridge 的 `application` 服务依赖： + - 分阶段完成：先抽离 watch contract，再抽离 profile resolver bridge，随后迁移 MCP bridge，最后处理 governance/runtime status 和通用错误桥接。 + - 只有全部子任务完成后，才能视为 `6.5.1f-3b` 完成。 +- [x] 6.5.1f-3b-1 抽离 server-owned watch contract： + - 将 `WatchSource`、`WatchEvent`、`WatchPort`、`WatchService` 从 `application` 下沉为 server-owned bridge，`bootstrap/watch.rs`、`runtime.rs`、`test_support.rs`、watch 相关路由测试不再直接依赖 `astrcode-application::watch::*` 类型。 + - 迁移期允许 watch 实现内部仍复用 `ApplicationError` 作为错误壳，但 service / source / event / port 类型必须改为 server-owned。 + - 验证：watch 相关测试通过，server bootstrap/watch 代码不再直接引用 `astrcode-application::Watch*` 类型。 +- [x] 6.5.1f-3b-2 抽离 server-owned profile resolver bridge： + - 为 server 引入本地 profile resolver surface，`main.rs`、`runtime.rs`、`agent_api.rs`、测试辅助不再直接暴露 `ProfileResolutionService` 类型。 + - 迁移期允许 bridge 内部继续调用旧 profile resolution 实现，但 server 状态面只暴露本地 contract。 + - 验证：agent/profile/watch 相关测试通过，server runtime/state 不再以 `ProfileResolutionService` 作为公开桥接类型。 +- [x] 6.5.1f-3b-3 抽离 server-owned MCP bridge： + - 将 `McpService`、`McpPort`、`RegisterMcpServerInput`、status summary/view 等 server 直接消费的 bridge 类型下沉到 server-owned contract 或新 owner service。 + - 验证：`bootstrap/mcp.rs`、`main.rs`、MCP routes 不再直接暴露 `astrcode-application::Mcp*` 服务类型。 +- [x] 6.5.1f-3b-4 抽离 governance/runtime status 与通用错误桥接： + - 分阶段完成：先引入 server-owned governance service，再下沉 runtime/config summary projection，最后收敛 `ApplicationError -> ApiError` / conversation error 的通用桥接。 + - 只有全部子任务完成后，才能视为 `6.5.1f-3b-4` 完成。 +- [x] 6.5.1f-3b-4a 引入 server-owned governance service： + - 为 server 引入本地 governance bridge，`main.rs`、`runtime.rs`、composer/config 路由只暴露 server-owned contract，不再以 `AppGovernance` 作为状态面类型。 + - 迁移期允许 bridge 内部继续委托旧治理实现，但 shutdown/reload/runtime snapshot 的公开入口必须经由 server-owned service。 + - 验证：`AppState` / `ServerRuntime` / 测试装配不再暴露 `AppGovernance`。 +- [x] 6.5.1f-3b-4b 下沉 runtime/config summary projection： + - 将 runtime status summary、plugin/capability summary 和 config summary 的协议输入投影下沉为 server-owned projection 类型与函数，`mapper.rs` / `routes/config.rs` 不再直接依赖 `application` 的 summary 类型或 helper。 + - 验证：`mapper.rs`、`routes/config.rs` 不再直接引用 `ResolvedRuntimeStatusSummary`、`RuntimeCapabilitySummary`、`PluginState`、`PluginHealth`、`ResolvedConfigSummary` 或对应的 `application` summary helper。 +- [x] 6.5.1f-3b-4c 收敛通用错误桥接： + - 收敛 `ApplicationError -> ApiError` 与 `ConversationRouteError` 的通用桥接，server 路由错误类型不再通过 `From` 作为正式桥接面。 + - 验证：`main.rs`、`routes/config.rs`、`routes/conversation.rs` 不再以 `ApplicationError` 的公共转换实现作为 server 正式错误桥接。 +- [x] 6.5.1f-3c 删除 `Cargo.toml` 中的 `astrcode-application` 依赖并做最终验证： + - 清理残余 `use astrcode_application::*`，移除 `server` crate 对 `astrcode-application` 的正式依赖。 + - 验证：`cargo check --workspace`、路由级冒烟测试和边界检查通过。 +- [x] 6.5.1f-3c-1 下沉 config/mode helper 与 validator： + - 为 server 引入本地 `config`/`mode` helper，`mapper.rs`、`view_projection.rs`、`routes/model.rs`、`routes/sessions/*`、`bootstrap/prompt_facts.rs` 不再直接调用 `application` 的 `resolve_current_model`、`list_model_options`、`is_env_var_name`、`validate_mode_transition`、`format_local_rfc3339` 等 helper。 + - 验证：上述文件不再直接引用这些 `application` helper，相关 route 测试通过。 +- [x] 6.5.1f-3c-2 收敛 provider/config bridge 的剩余 `application::config` helper： + - `bootstrap/providers.rs` 改为消费 server-owned config helper / resolver，避免继续直接依赖 `application::config::*` 常量与 URL/API key helper。 + - 验证：provider 装配代码不再直接引用 `application::config::*` helper。 +- [x] 6.5.1f-3c-3 抽离 agent/bootstrap/bridge 的最后一批 `application` 类型： + - 收敛 `agent_api.rs`、`bootstrap/runtime.rs`、`bootstrap/governance.rs`、`bootstrap/mcp.rs`、`profile_service.rs`、`governance_service.rs`、`mcp_service.rs`、`watch_service.rs` 中残余的 `application` 正式类型依赖，必要时补 server-owned contract。 + - 验证：server 生产代码仅保留迁移内聚实现文件中的最小兼容桥，不再由 runtime/state/routes 暴露 `application` 类型。 +- [x] 6.5.1f-3c-3a 引入 server-owned mode catalog bridge： + - `main.rs`、`bootstrap/runtime.rs`、`routes/sessions/*` 不再以 `application::ModeCatalog` 作为 server 状态面类型，mode 校验与列举改走 server-owned wrapper。 + - 验证：server runtime/state/routes 不再直接暴露 `ModeCatalog`。 +- [x] 6.5.1f-3c-3b 引入 server-owned config service bridge： + - `main.rs`、`bootstrap/runtime.rs`、`http/agent_api.rs`、`bootstrap/providers.rs`、`bootstrap/prompt_facts.rs` 不再以 `application::config::ConfigService` 作为 server 状态面类型。 + - 验证：server runtime/state 对外不再暴露 `ConfigService`。 +- [x] 6.5.1f-3c-3c 收敛 root execute / governance assembler bridge： + - `agent_api.rs` 与 runtime 组装不再直接暴露 `GovernanceSurfaceAssembler`、`execute_root_agent`、`RootExecutionRequest` 等 `application` 执行面类型，必要时补 server-owned execute bridge。 + - 验证：agent route bridge 不再直接暴露 `application` 执行入口类型。 +- [x] 6.5.1f-3c-3d 清理剩余 bridge service 的 `application` 内聚实现： + - 收敛 `profile_service.rs`、`governance_service.rs`、`mcp_service.rs`、`watch_service.rs` 及其 bootstrap 调用面中的残余 `application` 正式类型暴露，只允许最小内部兼容桥留在实现文件。 + - 验证：server 状态/路由/组合根不再把这些 `application` 类型作为正式 surface。 +- [x] 6.5.1f-3c-3d-1 下沉 route/main 的 `ApplicationError` 兼容桥： + - 将 `main.rs`、`http/routes/conversation.rs`、`http/composer_catalog.rs`、`http/agent_api.rs` 中残余的 `ApplicationError -> ApiError/ConversationRouteError` 映射收敛到 server-owned 兼容实现文件，路由与入口文件不再直接依赖 `astrcode_application::ApplicationError`。 + - 验证：上述路由/入口文件不再直接 `use astrcode_application::ApplicationError`。 +- [x] 6.5.1f-3c-3d-2 下沉 bootstrap/runtime 对旧 app service 的装配类型： + - 将 `bootstrap/runtime.rs`、`bootstrap/governance.rs`、`bootstrap/mcp.rs`、`bootstrap/providers.rs` 中残余的 `ModeCatalog`、`McpService`、`ProfileResolutionService`、`AppGovernance` 等旧 app service 装配细节收敛到 bridge builder/impl 文件，组合根只消费 server-owned wrapper。 + - 验证：`bootstrap/runtime.rs` 不再把这些 `application` 类型作为组合根装配 surface。 +- [x] 6.5.1f-3c-3d-3 约束 bridge service 内部的 `application` DTO/trait 转换面： + - 收敛 `mcp_service.rs`、`profile_service.rs`、`governance_service.rs`、`watch_service.rs`、`root_execute_service.rs` 内部残余的 `application` DTO/trait 转换，把旧类型使用限制在最小私有 helper/impl 块中，为 `6.5.1f-3c-4` 的依赖删除做准备。 + - 验证：server 对外 bridge 类型不再暴露 `application` 请求/摘要/trait 作为正式字段或公开参数。 +- [x] 6.5.1f-3c-3d-3a 收敛 MCP / watch bridge contract 的 `application` 错误与 service 暴露： + - 将 `mcp_service.rs` 改为 server-owned port/DTO surface，不再把 `McpService`、`ApplicationError` 或 `astrcode_application::*` 作为正式字段、构造参数或返回类型暴露；`bootstrap/mcp.rs` 只在私有 impl 内做必要转换。 + - 将 `watch_service.rs` 的 `WatchPort` / `WatchService` 错误面切到 server-owned error，`bootstrap/watch.rs` 只在私有 impl 内处理底层错误映射。 + - 验证：`mcp_service.rs`、`watch_service.rs` 的公开 bridge contract 不再直接引用 `astrcode_application::*`。 +- [x] 6.5.1f-3c-3d-3b 收敛 governance bridge 的 app snapshot / service 暴露： + - 收敛 `governance_service.rs` 中残余的 `AppGovernance`、`GovernanceSnapshot` / plugin-entry 依赖，把旧类型限制在私有存储或转换 helper，公开 bridge 输出只使用 server-owned summary。 + - 验证：`governance_service.rs` 的正式字段、公开参数和返回摘要不再直接使用 `astrcode_application` 类型。 +- [x] 6.5.1f-3c-3d-3c 收敛 profile / root execute bridge 的 app trait 与 governance-surface 暴露： + - 分阶段完成：先下沉 profile resolver contract，再下沉 root execute 治理/错误桥，最后清理 builder wiring 中残余的旧 app trait 暴露。 + - 只有全部子任务完成后，才能视为 `6.5.1f-3c-3d-3c` 完成。 +- [x] 6.5.1f-3c-3d-3c-1 下沉 profile resolver bridge contract： + - 将 `profile_service.rs` 的正式字段、构造参数和返回错误面切到 server-owned port / error，不再直接暴露 `ProfileResolutionService` 或 `ApplicationError`；`bootstrap/providers.rs` 只在私有 impl 内保留旧 profile loader / application 兼容。 + - 验证：`profile_service.rs` 的公开 bridge contract 不再直接引用 `astrcode_application::execution::ProfileResolutionService` 或 `ApplicationError`。 +- [x] 6.5.1f-3c-3d-3c-2 下沉 root execute governance/error contract： + - 将 `root_execute_service.rs` 的正式字段、构造参数和返回错误面切到 server-owned port / error，不再直接暴露 `GovernanceSurfaceAssembler`、`ApplicationError`；必要的旧治理装配只允许留在私有 adapter / builder 中。 + - 验证：`root_execute_service.rs` 的公开 bridge contract 不再直接引用这些 `astrcode_application` 类型。 +- [x] 6.5.1f-3c-3d-3c-3 清理 private builder wiring 中的旧 app trait 暴露： + - 收敛 `agent_runtime_bridge.rs`、`bootstrap/providers.rs` 等 builder/wiring 文件中为 profile/root execute bridge 暴露的旧 app trait / service 类型，把它们限制在私有 adapter helper 中。 + - 验证：server 生产 wiring 对外只消费 server-owned profile/root execute contract。 +- [x] 6.5.1f-3c-4 删除 `Cargo.toml` 中的 `astrcode-application` 依赖并做最终验证： + - 清理残余 `use astrcode_application::*`，移除 `server` crate 对 `astrcode-application` 的正式依赖。 + - 验证：`cargo check --workspace`、路由级冒烟测试和边界检查通过。 +- [x] 6.5.1f-3c-4a 移除已可直接替换的 `application` re-export / test-only trait 依赖： + - 将 `main.rs` 中仅作为错误壳使用的 `AstrError` 切到 server/core 自有来源，移除 server tests 中不再需要的 `AppKernelPort` import 与调用习惯。 + - 验证：`main.rs`、`agent_routes_tests.rs`、`session_contract_tests.rs` 不再直接 `use astrcode_application::*`，相关测试通过。 +- [x] 6.5.1f-3c-4b 下沉 mode catalog 的剩余 `application` 依赖： + - 为 server 引入不依赖 `application::ModeCatalog` 的 mode catalog snapshot / transition 校验实现，`mode_catalog_service.rs` 与相关 bootstrap/governance 预览路径不再直接引用 `application::mode::*`。 + - 验证：`mode_catalog_service.rs` 不再直接依赖 `astrcode_application::ModeCatalog` 或 `ModeCatalogSnapshot`。 +- [x] 6.5.1f-3c-4c 收敛 config/MCP bridge 的 `application::config` 与 DTO 依赖： + - 将 `config_service_bridge.rs`、`bootstrap/mcp.rs` 中残余的 `ConfigService`、`RegisterMcpServerInput`、`McpConfig*` application bridge 收敛到 server-owned contract 或私有 compat builder。 + - 验证：server 对外 config/MCP bridge 不再直接暴露这些 `application` 类型。 +- [x] 6.5.1f-3c-4d 收敛 governance/bootstrap/app-error 的最终 compat 依赖并删除 crate 依赖： + - 处理 `application_error_bridge.rs`、`bootstrap/governance.rs`、`bootstrap/runtime.rs`、其余残余 compat imports，完成 `crates/server/Cargo.toml` 中 `astrcode-application` 依赖删除与最终验证。 + - 验证：`crates/server/Cargo.toml` 不再依赖 `astrcode-application`，`cargo check --workspace`、路由级冒烟测试和边界检查通过。 +- [x] 6.5.1f-3c-4d-1 下沉 runtime/bootstrap 对 builtin mode seed 与 lifecycle/observability 类型的依赖： + - 处理 `bootstrap/runtime.rs` 中残余的 `builtin_mode_catalog`、`TaskRegistry`、`RuntimeObservabilityCollector` application import，为 server 提供自有 seed/wrapper/bridge。 + - 验证：`bootstrap/runtime.rs` 不再直接 `use astrcode_application::{ builtin_mode_catalog, RuntimeObservabilityCollector, lifecycle::TaskRegistry }`。 +- [x] 6.5.1f-3c-4d-2 收敛 `ApplicationError` 兼容桥与残余测试/runtime-name 耦合： + - 处理 `application_error_bridge.rs`、`bootstrap/mcp.rs`、相关测试中的 `astrcode-application` runtime name / compat expectation，把 application error 转换限制到最终私有 compat helper。 + - 验证：非私有 compat helper 之外不再直接依赖 `ApplicationError` 或 `astrcode-application` runtime name 常量。 +- [x] 6.5.1f-3c-4d-3 收敛 `AppGovernance` compat 并删除 `Cargo.toml` 依赖： + - 处理 `bootstrap/governance.rs`、`bootstrap/runtime.rs` 与 `crates/server/Cargo.toml` 中残余的 `AppGovernance` / `RuntimeReloader` / `RuntimeGovernancePort` compat，完成 crate 依赖删除与最终验证。 + - 验证：`crates/server/Cargo.toml` 不再依赖 `astrcode-application`，`cargo check --workspace`、路由级冒烟测试和边界检查通过。 +- [x] 6.5.2 切换旧 `kernel` 能力面： + - 将 `CapabilityRouter`、`Kernel`、`KernelGateway`、`SurfaceManager` 的正式调用方迁到 `plugin-host` active snapshot、tool dispatch、provider/resource catalog 或 `agent-runtime` 执行面。 + - 删除 `server` 和新边界中的 `astrcode-kernel` 正式依赖。 + - 分阶段完成：先切掉 route/root-execute 等 agent-control 摘要类型，再切 capability/router 装配与 owner bridge，最后删除 crate 依赖并做最终验证。 + - 只有全部子任务完成后，才能视为 `6.5.2` 完成。 + - 验证：仓库正式代码不再引用 `astrcode_kernel` / `astrcode-kernel`。 +- [x] 6.5.2a 收敛 route/root-execute 的 `kernel` agent-control 摘要类型依赖： + - 将 `http/agent_api.rs`、`root_execute_service.rs`、相关 route/mapper 输出里的 `Kernel`、`SubRunStatusView`、`CloseSubtreeResult` 等正式类型依赖切到 server-owned bridge DTO / service contract。 + - 迁移期允许私有 bridge impl 内部仍调用旧 `kernel` 能力面，但协议层和 server 状态面不能继续暴露这些类型。 + - 验证：agent route、root execute bridge、相关 mapper/summary 不再直接 `use astrcode_kernel::*`。 +- [x] 6.5.2b 切换 capability/router 装配到 `plugin-host` snapshot 与 dispatch： + - 将 `bootstrap/capabilities.rs`、`bootstrap/runtime.rs` 中的 `CapabilityRouter`、`ToolCapabilityInvoker`、surface sync 正式依赖改为 `plugin-host` active snapshot / dispatch / catalog surface，去掉 kernel router 作为 server 正式装配物。 + - 验证：server 组合根与 capability bootstrap 不再以 `CapabilityRouter` 作为正式共享状态。 +- [x] 6.5.2c 收敛剩余 owner bridge 对 `KernelGateway` / `SurfaceManager` 的依赖： + - 处理 `ports/app_kernel.rs`、`ports/agent_kernel.rs`、`ports/session_submission.rs`、`mode/compiler.rs`、`governance_surface/**`、`agent/context.rs`、`execution/subagent.rs` 等残余 owner bridge，把它们迁到 server-owned / plugin-host / agent-runtime / host-session 合同。 + - 验证：server 生产 bridge 与 owner 适配层不再直接暴露 `KernelGateway`、`SurfaceManager` 或其他 `astrcode_kernel` 合同。 +- [x] 6.5.2c-1 删除 governance/session submission/agent context 中的死 `CapabilityRouter` / `KernelGateway` 透传： + - 移除 `ports/session_submission.rs`、`mode/compiler.rs`、`governance_surface/**` 中永远为 `None` 的 router 透传字段与签名，把 root/fresh/resumed governance surface 编译切到纯 mode/runtime 输入。 + - 清理 `agent/context.rs` 中仅用于默认空 limits 的 `KernelGateway` 形参，避免 owner bridge 继续把 gateway 当作正式依赖向上传递。 + - 验证：上述 server bridge/assembler/compile surface 不再直接暴露 `CapabilityRouter` / `KernelGateway`。 +- [x] 6.5.2c-2 收敛 `AppKernelPort` / `AgentKernelPort` 的 kernel 合同类型： + - 将 `ports/app_kernel.rs`、`ports/agent_kernel.rs`、`execution/subagent.rs` 中残余的 `KernelGateway`、`SubRunStatusView`、`CloseSubtreeResult`、`AgentControlError` 等旧 kernel 合同切到 server-owned 最小错误/控制类型，只保留私有 compat impl 调用旧 kernel。 + - 验证：server 生产 port/执行桥不再以这些 `astrcode_kernel` 类型作为正式 trait 字段、参数或返回值。 +- [x] 6.5.2c-3 清理剩余 owner bridge / wiring 对旧 kernel compat 的正式暴露： + - 继续处理 `agent_runtime_bridge.rs`、`main.rs`、相关 owner bridge / 测试装配中的残余 kernel compat 暴露，把正式 surface 收敛到 server-owned contract，为 `6.5.2d` 的 crate 依赖删除做准备。 + - 验证：server 生产 bridge 与组合根不再把旧 kernel compat 类型作为正式对外 surface。 +- [x] 6.5.2d 删除 `server` 对 `astrcode-kernel` 的正式依赖并做最终验证： + - 清理残余 `use astrcode_kernel::*` 与 `Cargo.toml` 依赖，确保 `server` 和新边界不再以旧 `kernel` crate 作为正式依赖。 + - 验证：`cargo check --workspace`、相关路由/组合根测试、`node scripts/check-crate-boundaries.mjs` 通过，且仓库正式代码不再引用 `astrcode_kernel` / `astrcode-kernel`。 +- [x] 6.5.3 切换旧 `session-runtime` 剩余调用面： + - 将旧 `SessionRuntime` 的 session catalog、query/read-model、observe、branch/fork、compaction、turn 提交、child-session 驱动调用全部迁到 `host-session + agent-runtime`。 + - 旧 `session-runtime` 只允许作为迁移源文件存在，不能作为正式 crate 依赖。 + - 验证：仓库正式代码不再引用 `astrcode_session_runtime` / `astrcode-session-runtime`。 +- [x] 6.5.3a 收敛 session identity / catalog / fork / 基础 query bridge： + - 下沉 `session_identity.rs` 等纯 helper，清理 `ports/app_session.rs` 中对旧 `SessionRuntime` catalog/fork/query wrapper 的直接依赖，优先切到 `host-session::SessionCatalog` 与 server-owned 最小摘要类型。 + - 验证：server 基础 session catalog/query bridge 不再因为 session id/fork/catalog helper 正式依赖 `astrcode_session_runtime`。 +- [x] 6.5.3b 切换 conversation / terminal query-read-model 面： + - 将 `http/routes/conversation.rs`、`http/terminal_projection.rs`、相关 route/test 使用的 conversation projector / snapshot / replay DTO 从旧 `session-runtime` 下沉到 server-owned query bridge，并让 durable replay 来自 `host-session`。 + - 验证：conversation / terminal 正式路径不再以 `astrcode_session_runtime` 的 conversation projector / replay DTO 作为正式 surface。 +- [x] 6.5.3c 切换 observe / durable collaboration query 面： + - 将 agent observe、durable subrun status、input queue / parent delivery 恢复等剩余 query 面迁到 `host-session` owner bridge 或 server-owned 最小摘要，避免 server route/agent bridge 继续直接消费旧 `session-runtime` query 类型。 + - 验证：server 协作 query / observe bridge 不再直接暴露 `astrcode_session_runtime` 的 observe/subrun snapshot 类型。 +- [x] 6.5.3d 切换 root/subagent submit 与 child-session 驱动面： + - 将 `execution/root.rs`、`execution/subagent.rs`、`agent_runtime_bridge.rs`、`root_execute_service.rs`、相关 `AppSessionPort` / `AgentSessionPort` 提交入口切到 `host-session + agent-runtime` owner 合同，移除旧 monolith `SessionRuntime` 作为正式 session 提交入口。 + - 验证：server 生产执行桥不再以 `SessionRuntime` 作为 submit / child-session driver 的正式依赖。 +- [x] 6.5.3e 删除 `server` 对 `astrcode-session-runtime` 的正式依赖并做最终验证： + - 清理残余 `use astrcode_session_runtime::*` 与 `Cargo.toml` 依赖，只保留迁移源文件或测试专用引用。 + - 验证：`cargo check --workspace`、相关路由/组合根测试、`node scripts/check-crate-boundaries.mjs` 通过，且 `server` 正式代码不再引用 `astrcode_session_runtime` / `astrcode-session-runtime`。 +- [x] 6.5.3e-1 下沉 conversation / session compat DTO 与 projector 依赖： + - 处理 `conversation_read_model.rs`、`http/terminal_projection.rs`、`http/routes/conversation.rs`、`ports/app_session.rs` 中残余的 `Conversation*Facts`、`SessionReplay`、`SessionTranscriptSnapshot`、`ForkPoint`、stream projector compat，补齐 server-owned DTO / projector bridge。 + - 验证：上述 query/read-model 正式路径不再直接依赖 `astrcode_session_runtime` 的 replay/projector/DTO 类型。 +- [x] 6.5.3e-2 下沉 agent control / session submit compat 依赖： + - 处理 `agent_control_bridge.rs`、`ports/app_kernel.rs`、`ports/agent_kernel.rs`、`ports/agent_session.rs`、`ports/session_submission.rs` 中残余的 `SessionRuntime*` 错误、subrun status、submit payload compat，把旧 runtime 使用限制到最小私有 impl。 + - 验证：server 生产 bridge/port 不再以 `SessionRuntime`、`SessionRuntime*Error`、`SessionRuntimeSubRunStatus`、`astrcode_session_runtime::AgentPromptSubmission` 作为正式 surface。 +- [x] 6.5.3e-3 下沉 bootstrap/runtime/governance/capability 装配对旧 runtime 的正式依赖： + - 处理 `bootstrap/runtime.rs`、`bootstrap/governance.rs`、`bootstrap/capabilities.rs`、`agent_runtime_bridge.rs`、`bootstrap/deps.rs` 中残余的 `SessionRuntime` / `SessionRuntimeBootstrapInput` 装配面，为组合根补齐 host-session + agent-runtime owner bridge。 + - 验证：server 组合根不再把旧 `SessionRuntime` 作为正式共享状态或 bootstrap surface。 +- [x] 6.5.3e-4 删除 `Cargo.toml` 中的 `astrcode-session-runtime` 依赖并做最终验证： + - 清理剩余生产态 `use astrcode_session_runtime::*` 与 `Cargo.toml` 依赖，仅允许测试或迁移源文件保留必要引用。 + - 验证：`cargo check --workspace`、相关路由/组合根测试、`node scripts/check-crate-boundaries.mjs` 通过，且 `server` 生产代码不再引用 `astrcode_session_runtime` / `astrcode-session-runtime`。 +- [x] 6.5.3e-4a 引入 server-owned session bridge，收敛 catalog/query/collaboration durable surface： + - 将 `AppSessionPort` / `AgentSessionPort` 的生产实现从 `SessionRuntime` blanket impl 切到 server-owned bridge；优先使用 `host-session::SessionCatalog` 承接 catalog CRUD、fork、stored-events/query replay、durable subrun/input-queue 协作恢复与 collaboration append。 + - submit / compact / interrupt / observe 等 turn mutation 与 live control 暂允许继续通过私有 legacy runtime compat 调用，直到后续子任务完成。 + - 验证：server bootstrap 不再把 `SessionRuntime` 直接注册为 `AppSessionPort` / `AgentSessionPort` 的正式实现，相关 session contract / route 测试通过。 +- [x] 6.5.3e-4b 收敛剩余 session control / observe / transcript compat： + - 继续处理 `agent_control_bridge_runtime_compat.rs`、`ports/app_kernel_runtime_compat.rs`、`ports/agent_kernel_runtime_compat.rs`、`ports/session_submission_runtime_compat.rs`、session replay / observe 等残余 compat，使 server 正式 owner bridge 不再直接把旧 runtime 类型作为控制面。 + - 验证：server 正式 bridge/port 对外不再以 `SessionRuntime` 或其 query/control helper 作为共享 surface。 +- [x] 6.5.3e-4c 删除 `server` crate 对 `astrcode-session-runtime` 的正式依赖并做最终验证： + - 删除 `crates/server/Cargo.toml` 中的 `astrcode-session-runtime` 依赖，清理残余生产态 `use astrcode_session_runtime::*`，仅保留测试或迁移源文件中的必要引用。 + - 验证：`cargo check --workspace`、相关路由/组合根测试、`node scripts/check-crate-boundaries.mjs` 通过，且 `server` 生产代码不再引用 `astrcode_session_runtime` / `astrcode-session-runtime`。 +- [x] 6.5.3e-4c-1 引入 private legacy runtime compat port，收敛 bridge 层的直接 `SessionRuntime` 依赖： + - 为 server 新增私有 `LegacySessionRuntimePort` compat，把 submit / observe / subrun control / parent delivery 恢复等旧 runtime 能力限制在 compat impl 内，`session_bridge.rs`、`kernel_bridge.rs` 与相关测试 harness 只消费 server-owned trait。 + - 删除 `agent_control_bridge_runtime_compat.rs`、`ports/app_kernel_runtime_compat.rs`、`ports/agent_kernel_runtime_compat.rs`、`ports/session_submission_runtime_compat.rs` 等 blanket compat 模块，避免正式 bridge 继续直接暴露 `SessionRuntime`。 + - 验证：`cargo check -p astrcode-server`、`cargo test -p astrcode-server session_contract_tests -- --nocapture`、`cargo test -p astrcode-server agent_routes_tests -- --nocapture`、`cargo test -p astrcode-server --no-run`、`node scripts/check-crate-boundaries.mjs` 通过，且 `session_bridge.rs` / `kernel_bridge.rs` / `agent/test_support.rs` 不再直接依赖 `SessionRuntime`。 +- [x] 6.5.3e-4c-2 收敛 bootstrap owner bridge / keepalive / 测试 runtime handle 的剩余旧 runtime 依赖： + - 处理 `session_runtime_owner_bridge.rs`、`session_runtime_owner_bridge_compat.rs`、`bootstrap/runtime.rs` 中残余的 `SessionRuntime`、`SessionRuntimeBootstrapInput`、`AgentControlLimits`、`#[cfg(test)] session_runtime` 字段和 keepalive 资源守卫，收敛到 server-owned bootstrap/handle contract 或更小的私有 compat helper。 + - 同步清理仍要求原始 runtime 句柄的生产态 wiring / 测试辅助，让组合根和 owner bridge 不再把旧 runtime 作为正式共享状态或测试输出面。 + - 验证：server 组合根与 owner bridge 的正式字段/装配参数不再直接使用 `astrcode_session_runtime` 类型。 +- [x] 6.5.3e-4c-3 删除 `crates/server/Cargo.toml` 中的 `astrcode-session-runtime` 依赖并完成最终收尾： + - 清理 `legacy_session_runtime_port_compat.rs` 之外残余的 `astrcode_session_runtime` 引用，补齐 `bootstrap/governance.rs`、`bootstrap/capabilities.rs`、`agent/test_support.rs`、`agent/wake.rs` 等测试或迁移源路径的最终替代/下沉。 + - 删除 `crates/server/Cargo.toml` 中的 `astrcode-session-runtime` 依赖，并完成与 `6.5.3e-4` 验证一致的最终检查。 + - 验证：`cargo check --workspace`、相关路由/组合根测试、`node scripts/check-crate-boundaries.mjs` 通过，且 `server` crate 不再正式依赖 `astrcode-session-runtime`。 +- [x] 6.5.4 切换旧 `plugin` 进程宿主生产路径： + - 将 `server/bootstrap/plugins.rs` 和 `governance.rs` 对旧 `PluginLoader`、`Supervisor` 的依赖迁到 `plugin-host` 的等价类型（`PluginLoader`、`ExternalPluginRuntimeHandle` + 补齐 shutdown/health 接口）。 + - SDK 侧（`Worker`、`CapabilityHandler`）和 `examples/example-plugin/` 暂不迁移，后续统一设计新 SDK。 + - 验证：server 生产路径不再引用 `astrcode_plugin` / `astrcode-plugin`。 +- [x] 6.5.5 删除旧 crate 与 workspace 依赖： + - 按真实阻塞面拆分删除，避免 `application` / `session-runtime`、`kernel`、`plugin` 三条尾巴互相阻塞。 + - 只有全部子任务完成后，才能视为 `6.5.5` 完成。 + - 验证：`cargo check --workspace`、`node scripts/check-crate-boundaries.mjs --strict` 通过；仓库中无残留正式依赖路径；最终只剩 `agent-runtime`、`host-session`、`plugin-host` 与共享 `core` 合同。 +- [x] 6.5.5a 从 workspace 中移除旧 `application` / `session-runtime` crate： + - 从根 `Cargo.toml` 和其余活跃 crate 的 `Cargo.toml` 中删除 `application`、旧 `session-runtime` 的正式 workspace 成员与正式依赖。 + - 允许保留源码目录作为迁移归档源，但它们不得再参与 workspace 编译或边界规则判定。 + - 验证：`cargo metadata` / `cargo check --workspace` 中不再出现 `astrcode-application`、`astrcode-session-runtime`。 +- [x] 6.5.5b 删除旧 `kernel` crate 的残余 compat / test 正式依赖： + - 处理 `server` 中残余的 `astrcode-kernel` test-only / compat 依赖，把 `CapabilityRouter`、`Kernel`、`ToolCapabilityInvoker` 等旧类型替换到 server-owned 或 `plugin-host` / `agent-runtime` 最小测试夹具。 + - 删除 `crates/server/Cargo.toml` 与根 workspace 中的 `kernel` 正式依赖/成员。 + - 验证：`cargo check --workspace` 与相关测试通过，且活跃 crate 不再依赖 `astrcode-kernel`。 +- [x] 6.5.5c 删除旧 `plugin` crate 与 SDK/example 尾巴： + - 为 `sdk` / `examples/example-plugin` 提供不依赖旧 `astrcode-plugin` crate 的替代入口或迁移归档策略，再删除根 workspace 与示例中的旧 `plugin` 正式依赖。 + - SDK 侧旧 `Worker` / `CapabilityHandler` 示例不再阻塞宿主边界删除。 + - 验证：workspace 与示例构建路径不再依赖 `astrcode-plugin`。 + +## 7. 验证与清理 + +- [x] 7.1 为 `agent-runtime` 补齐测试：turn 执行、provider streaming、tool call/result、hook effect、取消与超时。 +- [x] 7.2 为 `host-session` 补齐测试：事件日志恢复、branch/fork、compaction、model_select、child-session 恢复、结果回传、取消传播。 +- [x] 7.3 为 `plugin-host` 补齐测试：reload 回滚、in-flight turn snapshot 固定、resource discovery、provider contribution、协作 surface 委托。 +- [x] 7.4 全量 CI 检查：`cargo check --workspace`、`cargo test --workspace --exclude astrcode --lib`、`node scripts/check-crate-boundaries.mjs`、`cargo clippy`、`cargo fmt`。 +- [x] 7.5 清理过渡桥接代码和迁移痕迹，确保最终仓库只剩新边界与新命名。 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/.openspec.yaml b/openspec/changes/unify-declarative-dsl-compiler-architecture/.openspec.yaml deleted file mode 100644 index 4b8c565f..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-04-21 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/design.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/design.md deleted file mode 100644 index be0716ac..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/design.md +++ /dev/null @@ -1,195 +0,0 @@ -## Context - -Astrcode 已经具备声明式治理与正式 workflow 的核心骨架，但当前实现把几类本应分开的真相揉在了一起： - -1. `mode` 想承载更多合同语义，但 compile / bind 的边界不清。 - - `compile_mode_envelope()` 与 `GovernanceSurfaceAssembler` 的职责边界没有统一命名。 - - builtin `plan` mode 的 artifact / exit / prompt 语义仍主要体现在专用工具和 session-specific helper 中。 - -2. `workflow` 已经拥有 `phase -> mode` 的正式绑定点，却缺少显式的 validate / compile owner。 - - `WorkflowPhaseDef.mode_id` 已经是现有真相。 - - 但 plan approval、bridge 生成、workflow bootstrap 与 reconcile 仍散落在 `session_plan.rs`、`session_use_cases.rs` 和工具 handler 中。 - -3. `reload` 已经有局部原子替换，但治理输入还不是统一快照。 - - capability surface 失败时会回滚。 - - mode catalog 与 skill catalog 还没有被纳入同一次提交/回滚。 - -4. 工具层缺少稳定的 mode contract 读取面。 - - `ToolContext` 只有 `current_mode_id`。 - - 需要 artifact / exit 语义的工具只能硬编码规则，或者不干净地回看 application/runtime 内部实现。 - -这次 change 的目标不是继续扩 scope，而是把 owner 收清楚： - -- `mode` 负责治理合同。 -- `workflow` 负责 phase 图与 phase -> mode 绑定。 -- `binder` 负责把 compile 结果与 runtime/session/profile/control 绑定。 -- `tool context` 只接收 pure-data snapshot，不接触 application 内部类型。 - -## Goals / Non-Goals - -**Goals** - -- 统一 `compile`、`bind`、`orchestrate` 术语与职责边界。 -- 扩展 `GovernanceModeSpec`，让 mode 能声明 artifact 合同、exit gate 与 prompt hooks。 -- 明确 workflow compiled artifact 是 phase -> mode 绑定的唯一 owner。 -- 为工具执行提供纯数据的 bound mode contract snapshot。 -- 让 prompt 结果继续沉淀到现有 `PromptPlan`。 -- 让 reload 在“无活跃 session”约束下对 mode catalog、capability surface、skill catalog 做统一候选快照提交/回滚。 -- 补上 duplicate `mode_id` 冲突策略。 - -**Non-Goals** - -- 不把 mode、workflow、prompt、capability 合并成单一 schema。 -- 不把 workflow 绑定反向塞进 `GovernanceModeSpec`。 -- 不在本次为 workflow 引入与当前规模不匹配的索引化结构。 -- 不让 `adapter-tools` 直接依赖 `application` 或 runtime 内部类型。 -- 不在本次直接设计新一代通用 mode transition DSL。 - -## Decisions - -### 决策 1：`GovernanceModeSpec` 只扩 artifact / exit / prompt 合同，不再承载 workflow phase 绑定 - -选择： - -- 在 `GovernanceModeSpec` 中新增： - - `ModeArtifactDef` - - `ModeExitGateDef` - - `ModePromptHooks` -- 不新增 `ModeWorkflowBinding`。 - -原因： - -- 仓库级架构已经明确 `mode` 与 `workflow phase` 是两层不同语义。 -- `WorkflowPhaseDef.mode_id` 已经是 phase -> mode 绑定真相，再在 mode spec 内保存 `workflow_id/phase_id/phase_role` 只会形成双写。 -- 同一个 `mode_id` 可以被多个 phase 复用；反向绑定会把这个合法关系错误收窄成一对一。 - -备选方案： - -- 在 `GovernanceModeSpec` 中加入 `workflow_binding` - - 未采纳原因：会复制已有 workflow 真相，并迫使 binder 做双向一致性校验。 - -### 决策 2：workflow compiled artifact 保持 phase -> mode 绑定 owner，mode 只提供可复用合同 - -选择： - -- `WorkflowDef`/compiled workflow artifact 持有： - - `phase_id` - - `mode_id` - - `role` - - `artifact_kind` - - `accepted_signals` -- workflow orchestration 通过 `phase.mode_id` 向治理编译链路索取 mode contract。 - -原因： - -- 这符合 `PROJECT_ARCHITECTURE.md` 中“mode 负责治理约束，workflow phase 负责业务阶段”的分层。 -- 可自然支持“多个 phase 复用同一个 mode”。 -- recovery / reconcile 时也应该从 `current_phase_id -> phase.mode_id` 出发，而不是反向从 mode 猜 phase。 - -### 决策 3：compile 与 bind 保持两层产物，但为工具执行补一层 pure-data 投影 - -选择： - -- compile 阶段产出 `CompiledModeSurface` / 等价编译产物，负责： - - selector 求值 - - child/grant 裁剪 - - artifact / exit / prompt contract 派生 - - diagnostics -- bind 阶段产出 `ResolvedGovernanceSurface`，负责： - - runtime config - - resolved limits - - profile / injected messages - - approval pipeline -- 对工具执行额外投影一份 pure-data `BoundModeToolContractSnapshot`（命名可渐进演化），只包含工具所需的 artifact / exit 合同字段。 - -原因： - -- `adapter-tools` 不能也不应该依赖 `GovernanceSurfaceAssembler`。 -- `ToolContext` 只有 `current_mode_id` 不足以支撑 contract-aware 工具。 -- 纯数据 snapshot 可以跨 `ResolvedGovernanceSurface -> AgentPromptSubmission -> ToolContext -> CapabilityContext` 稳定传递，不泄漏 application 内脏。 - -### 决策 4：通用工具化先不做“大一统工具”，先建立稳定 contract 读取面 - -选择： - -- 本次不再要求立即实现 `upsertModeArtifact` / `exitMode` 这类过度泛化的新工具。 -- 先让 plan-specific 工具通过 `BoundModeToolContractSnapshot` 读取 artifact / exit 合同，消除硬编码重复。 -- 后续若要做真正的通用 mode 工具，再基于该 snapshot 单独开 change。 - -原因： - -- 当前 generic tool 方案缺少稳定的 contract 输入面，也没有清楚定义“exit 到哪个 target mode”。 -- 直接推进会把不完整的治理语义硬塞进工具层。 - -### 决策 5：plan workflow 的副作用 owner 收回 application orchestration - -选择： - -- `enterPlanMode` 只负责 mode transition。 -- workflow bootstrap、approval、archive、bridge 生成、reconcile 回归 `application::workflow/*` 与对应 helper。 -- `session_plan.rs` 保留 plan artifact owner，但不再成为 workflow side effect 的隐式组合根。 - -原因： - -- workflow 迁移、副作用与 bridge 本就属于 application orchestration，而不是 tool handler。 -- 当前逻辑散落在 `session_plan.rs`、`session_use_cases.rs`、`enter_plan_mode.rs`，已经形成多个 owner。 - -### 决策 6：mode catalog 必须拒绝 duplicate `mode_id`，包括 plugin 对 builtin 的影子覆盖 - -选择： - -- `ModeCatalog` 在构造候选快照时检测 duplicate `mode_id`。 -- plugin mode 不允许覆盖 builtin `code` / `plan` / `review`，也不允许与其他 plugin 重名。 - -原因： - -- 扩展 mode contract 后，重复 id 已经不是“展示层小问题”，而是能直接篡改治理语义。 -- 静默覆盖会让 bootstrap / reload 结果不可预测，且难以诊断。 - -### 决策 7：reload 继续遵守 idle-only 合同，不再引入“running turn 用旧快照”的并行语义 - -选择： - -- `AppGovernance.reload()` 继续在存在 running session 时拒绝 reload。 -- reload 只在 idle 状态下组装候选治理快照： - - mode catalog - - capability surface - - skill catalog -- 成功时一次提交，失败时完整回滚。 - -原因： - -- 这是现有主 spec 和代码已经建立的治理合同。 -- 在这个前提下，不存在“执行中 turn 继续用旧快照、下一 turn 再切新快照”的混合语义；那是另一套模型，不能和 idle-only 同时存在。 - -## Risks / Trade-offs - -- [风险] 去掉 `workflow_binding` 后，change 看起来比最初 proposal 更收敛。 - - Mitigation：这是有意收敛，换来 owner 清晰与可实现性；workflow 绑定本来就已有正式 owner。 - -- [风险] 引入 `BoundModeToolContractSnapshot` 会扩大 core/tool 上下文字段。 - - Mitigation：只引入 pure-data snapshot，不携带 router、锁、channel 或 application 类型。 - -- [风险] plan workflow 副作用回收进 application 后，短期改动面横跨 `workflow`、`session_plan`、`session_use_cases`。 - - Mitigation：以“迁 owner 不改语义”为原则，先抽 helper，再移动调用点。 - -- [风险] duplicate `mode_id` 拒绝会让此前依赖覆盖行为的实验性插件失效。 - - Mitigation：仓库本身不追求向后兼容；这里优先保证治理语义确定性。 - -## Migration Plan - -1. 先更新架构文档和 change/spec 术语，删掉 `workflow_binding` 与 mixed-snapshot 语义。 -2. 在 `core` 扩展 `GovernanceModeSpec` 的 artifact / exit / prompt 合同，并增加 duplicate `mode_id` 校验需求。 -3. 在 `application` 中显式化 mode compile / governance bind 边界。 -4. 为 `ResolvedGovernanceSurface -> AgentPromptSubmission -> ToolContext` 增加 pure-data bound mode contract snapshot。 -5. 让 builtin `plan` mode 用新 mode contract 字段表达当前 artifact / exit / prompt 语义。 -6. 把 plan workflow 的 bootstrap / approval / bridge / reconcile 副作用收回 workflow/application owner。 -7. 重构 reload 路径为统一候选治理快照提交/回滚。 -8. 补充 duplicate mode id、workflow compile / reconcile、reload rollback、prompt source tracking 与 tool-contract bridge 测试。 - -## Resolved Questions - -- **workflow phase 绑定放哪里**：放在 workflow compiled artifact，不放在 `GovernanceModeSpec`。 -- **duplicate mode id 怎么处理**：一律拒绝；plugin 不允许影子覆盖 builtin mode。 -- **reload 是否支持执行中 session 混合版本**：不支持；继续遵守 idle-only reload。 -- **generic mode tools 是否纳入本次**：不纳入；本次先建立稳定的 tool contract snapshot。 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/proposal.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/proposal.md deleted file mode 100644 index f93ae23b..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/proposal.md +++ /dev/null @@ -1,44 +0,0 @@ -## Why - -Astrcode 当前已经形成 `CapabilitySpec`、`GovernanceModeSpec`、`WorkflowDef` 与 `PromptDeclaration` 多套声明模型，但 compile、bind、orchestrate 的边界还没有统一语言，导致治理编译、插件 mode 注册、reload 一致性与 prompt 注入路径难以收敛。 - -更具体地说，当前方案同时存在三类问题： - -- mode contract 想承载更多语义，但边界不清，容易把 workflow 真相和工具执行细节一起塞回 mode。 -- workflow phase 与 mode 的绑定已经有正式 owner（`WorkflowPhaseDef.mode_id`），却缺少显式的 validate/compile 语义，导致 phase 迁移、副作用与 bridge 逻辑继续散落。 -- reload 已经有“能力面失败则回滚”的雏形，但 mode catalog、capability surface、skill catalog 还没有被当作一个统一治理快照来提交。 - -这次 change 的目标是把这些边界收干净，而不是继续做一个过度扩张的“超级 DSL”。 - -## What Changes - -- 统一声明式治理链路里的 `compile`、`bind`、`orchestrate` 三类职责与命名约束。 -- 扩展 `GovernanceModeSpec` 的表达能力，使 mode 可声明 artifact 合同、exit gate 与动态 prompt hook；不再把 workflow phase 绑定反向塞进 mode spec。 -- 明确 workflow compiled artifact 是 phase -> mode 绑定的唯一 owner；同一个 `mode_id` 可以被多个 phase 复用。 -- 为工具执行引入纯数据的 bound mode contract snapshot，让需要 artifact / exit 语义的工具通过稳定上下文消费 contract，而不是依赖 application 内部类型或自行猜测 mode 语义。 -- 明确插件声明与消费路径，把 `InitializeResultData.modes`、mode catalog、capability surface 与治理编译阶段串成一致的 host 注册链路，并补齐 duplicate `mode_id` 拒绝策略。 -- 收敛 mode prompt program 与治理 helper prompt 的来源语义，要求统一沉淀到现有 `PromptPlan` 结果模型，而不是新增平行 prompt IR。 -- 补齐 governance reload 的一致性约束，要求 mode catalog、capability surface、skill catalog 在无活跃 session 的前提下以同一候选治理快照切换或完整回滚。 -- 把 plan workflow 的 bootstrap / approval / bridge / reconcile 副作用收回到 application 的 workflow orchestration，而不是继续散落在 tool handler 和 session-specific if/else 中。 - -## Capabilities - -### New Capabilities - -- 无 - -### Modified Capabilities - -- `governance-mode-system`: 扩展 mode spec 的声明能力，补齐 compile / bind 边界，并为工具执行增加纯数据 contract 投影视图。 -- `mode-capability-compilation`: 明确 selector 求值是 mode compiler 的核心算法，并要求 compile 结果与 child/grant 裁剪边界清晰稳定。 -- `mode-prompt-program`: 收敛 mode prompt、治理 helper prompt 与 prompt 结果模型之间的关系，明确来源与注入责任。 -- `workflow-phase-orchestration`: 增加轻量 workflow compile/validate 语义，并明确 phase -> mode 绑定由 workflow artifact 持有。 -- `governance-reload-surface`: 强化 mode catalog、capability surface、skill catalog 在 reload 时的一致性要求与失败回滚语义。 - -## Impact - -- 影响 `crates/core/src/mode/mod.rs`、`crates/application/src/mode/*`、`crates/application/src/governance_surface/*`、`crates/application/src/workflow/*` 的治理与编排边界。 -- 影响 `crates/core/src/tool.rs`、`crates/session-runtime/src/turn/submit.rs`、`crates/kernel/src/registry/tool.rs`，以承载稳定的 bound mode contract snapshot。 -- 影响 `crates/application/src/session_plan.rs`、`crates/application/src/session_use_cases.rs` 与 builtin `plan` mode 的职责拆分，使 workflow 副作用回归 application orchestration owner。 -- 影响 `crates/protocol/src/plugin/handshake.rs` 对 plugin mode 声明的消费约束，以及 `crates/server/src/bootstrap/governance.rs` / `capabilities.rs` 的 reload 路径。 -- 需要同步更新 `PROJECT_ARCHITECTURE.md` 或相关架构文档，使仓库级架构说明与新的 compile / bind / workflow-owner / governance-snapshot 术语保持一致。 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-mode-system/spec.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-mode-system/spec.md deleted file mode 100644 index 60d7d451..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-mode-system/spec.md +++ /dev/null @@ -1,89 +0,0 @@ -## ADDED Requirements - -### Requirement: governance mode spec SHALL describe mode contracts beyond capability selection - -`GovernanceModeSpec` MUST 能声明完整 mode 合同，而不只是 capability selector、action policy 与 child policy。该合同在本次至少覆盖：mode 级 artifact 定义、exit gate 与动态 prompt hooks。 - -#### Scenario: builtin plan mode declares its artifact contract through mode spec - -- **WHEN** builtin `plan` mode 需要维护 canonical plan artifact -- **THEN** 系统 SHALL 通过 `GovernanceModeSpec` 的 mode contract 字段声明该 artifact 的 kind、写入口约束与退出前置条件 -- **AND** SHALL NOT 只依赖 `upsertSessionPlan` / `exitPlanMode` 的硬编码约定表达这些语义 - -#### Scenario: plugin mode registers a complete mode contract - -- **WHEN** 插件通过 `InitializeResultData.modes` 声明自定义 mode -- **THEN** 该 mode SHALL 可以同时声明 capability surface、artifact contract、exit gate 与 prompt hooks -- **AND** host SHALL 用与 builtin mode 相同的校验与编译流程消费该合同 - -### Requirement: compile and bind responsibilities SHALL remain explicitly separated in governance mode processing - -mode processing MUST 维持“compile 产物”和“bound surface”两层边界。compile 阶段 SHALL 负责 selector 求值、mode contract 派生与 diagnostics；bind 阶段 SHALL 负责 runtime/session/profile/control 绑定，并生成最终可执行治理面。 - -#### Scenario: compiler derives mode contract without reading session runtime state - -- **WHEN** 系统编译一个 `GovernanceModeSpec` -- **THEN** compile 阶段 SHALL 只依赖当前 capability semantic model、mode spec 与显式输入 -- **AND** SHALL NOT 直接读取 session-runtime 的运行时状态来决定 artifact contract 或 exit gate 语义 - -#### Scenario: binder consumes compiled mode artifact to produce the final governance surface - -- **WHEN** 系统在 root、session、fresh child 或 resumed child 入口解析治理面 -- **THEN** binder SHALL 在已编译的 mode artifact 基础上绑定 runtime config、resolved limits、profile、injected messages 与 approval pipeline -- **AND** SHALL NOT 回流承担 selector 解释或 mode contract 语义校验 - -### Requirement: tool-consumable mode contracts SHALL be projected as pure data - -凡是工具执行需要消费的 mode contract 语义，系统 MUST 通过纯数据的 bound mode contract snapshot 投影到工具上下文，而不是要求工具依赖 application 内部类型或自行重建治理语义。 - -#### Scenario: plan tools consume artifact and exit contract through tool context - -- **WHEN** builtin `plan` 工具需要读取 artifact 写约束或 exit gate checklist -- **THEN** 系统 SHALL 在 tool / capability context 中提供 pure-data bound contract snapshot -- **AND** 工具 SHALL NOT 直接依赖 `GovernanceSurfaceAssembler`、`ModeCatalog` 或 session-runtime 内部状态来重建同类 contract - -#### Scenario: capability bridge preserves the bound mode contract snapshot - -- **WHEN** 工具上下文被桥接成 capability context 再回到 tool context -- **THEN** 该 pure-data bound contract snapshot SHALL 被稳定保留 -- **AND** SHALL NOT 因桥接路径丢失 contract 语义 - -### Requirement: mode catalog SHALL reject duplicate stable IDs across builtin and plugin registries - -mode catalog MUST 拒绝 duplicate `mode_id`。插件 mode SHALL NOT 覆盖 builtin `code` / `plan` / `review`，也 SHALL NOT 与其他 plugin mode 使用同一个稳定 id。 - -#### Scenario: plugin mode cannot shadow a builtin mode - -- **WHEN** 某个插件声明 `mode_id = "plan"` 或其他已存在 builtin id -- **THEN** host SHALL 拒绝该候选治理快照 -- **AND** 错误结果 SHALL 能指出冲突的 `mode_id` - -#### Scenario: duplicate plugin mode ids are rejected before catalog swap - -- **WHEN** 同一轮 bootstrap / reload 中两个 plugin mode 使用同一个 `mode_id` -- **THEN** 系统 SHALL 在 mode catalog 候选快照阶段拒绝该输入 -- **AND** SHALL NOT 进入后续 capability surface 提交 - -## MODIFIED Requirements - -### Requirement: governance mode SHALL compile to a turn-scoped execution envelope - -> 修改自 `openspec/specs/governance-mode-system/spec.md` 中同名 requirement。 -> 变更：envelope 编译结果现在包含 mode contract 派生的 artifact / exit / prompt 治理输入； -> workflow phase 绑定仍由 workflow artifact 持有，而不是反向塞进 mode spec。 - -系统 SHALL 在 turn 边界把当前 mode 编译为 turn-scoped 的治理执行包络。该编译结果 MUST 至少包含当前 turn 的 capability surface、prompt declarations、execution limits、action policies、child policy，以及 mode contract 派生出的 artifact / exit / prompt 相关治理输入。 - -#### Scenario: plan mode compiles a restricted capability surface through declarative mode contract - -- **WHEN** 当前 session 的 mode 为一个规划型 mode -- **THEN** 系统 SHALL 为该 turn 编译出收缩后的 capability router -- **AND** 规划型 mode 的 selector SHALL 能排除 `SideEffect::Local`、`SideEffect::Workspace`、`SideEffect::External` 与 `Tag("agent")` 的工具，或通过等价组合表达式得到同等结果 -- **AND** 若该 mode 需要额外的 artifact 写约束或 exit gate 语义，SHALL 通过 `ModeArtifactDef` 和 `ModeExitGateDef` 显式声明，而不是把具体工具名硬编码进 selector 或编译器 -- **AND** 当前 turn 模型可见的工具集合 SHALL 与该 router 保持一致 - -#### Scenario: code mode compiles the full default envelope - -- **WHEN** 当前 session 的 mode 为 builtin `code` -- **THEN** 系统 SHALL 编译出与当前默认执行行为等价的 envelope -- **AND** SHALL NOT 因引入 mode contract 而额外改变 turn loop 语义 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-reload-surface/spec.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-reload-surface/spec.md deleted file mode 100644 index 3ecf60c8..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/governance-reload-surface/spec.md +++ /dev/null @@ -1,31 +0,0 @@ -## ADDED Requirements - -### Requirement: governance reload SHALL treat mode catalog, capability surface, and skill catalog as one consistency unit - -治理级 reload MUST 把 mode catalog、capability surface 与 skill catalog 视为同一个候选治理快照进行提交，而不是允许三者按各自顺序局部成功。成功时三者 SHALL 一起切换，失败时 SHALL 一起回滚到旧快照。 - -本要求与现有 `governance-reload-surface` 主 spec 中“存在运行中 session 时拒绝 reload”的约束并存：reload 只在无活跃 session 时触发，因此本次 change 不引入 mixed-snapshot 的执行语义。 - -#### Scenario: candidate governance snapshot commits all three registries together - -- **WHEN** runtime reload 成功组装新的 plugin modes、external invokers 与 base skills，且无运行中 session -- **THEN** 系统 SHALL 以单次治理提交切换 mode catalog、capability surface 与 skill catalog -- **AND** 后续治理快照 SHALL 反映同一版本的三类输入 - -#### Scenario: candidate governance snapshot rolls back completely on failure - -- **WHEN** reload 过程中任一环节失败，例如 capability surface 校验失败 -- **THEN** 系统 SHALL 恢复旧的 mode catalog、旧的 capability surface 与旧的 skill catalog -- **AND** SHALL NOT 留下“新 mode catalog + 旧 capability surface”或等价的部分更新状态 - -#### Scenario: reload remains blocked while sessions are running - -- **WHEN** 存在 running session 且上层触发治理级 reload -- **THEN** 系统 SHALL 继续拒绝 reload -- **AND** SHALL NOT 同时宣称“running turn 继续用旧快照、下一 turn 再切新快照” - -#### Scenario: reload emits diagnostics for governance snapshot version changes - -- **WHEN** reload 成功切换到新的 mode catalog / capability surface / skill catalog -- **THEN** 系统 SHALL 记录可观测的版本边界或诊断信息 -- **AND** 诊断结果 SHALL 能说明新快照包含哪些 mode、capability、skill 的变更 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-capability-compilation/spec.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-capability-compilation/spec.md deleted file mode 100644 index e800d374..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-capability-compilation/spec.md +++ /dev/null @@ -1,34 +0,0 @@ -## ADDED Requirements - -### Requirement: CapabilitySelector evaluation SHALL remain the deterministic core of mode compilation - -`CapabilitySelector` 的递归求值 MUST 继续作为 mode compiler 的核心算法，并 SHALL 对 root turn、child policy 裁剪与 capability grant 裁剪提供一致、可复用的选择语义。相同 selector 在相同 capability semantic model 上 MUST 产出相同结果。 - -#### Scenario: root mode compilation and child derivation reuse the same selector semantics - -- **WHEN** 同一个 selector 同时用于 root mode 编译和 child policy 裁剪 -- **THEN** 系统 SHALL 复用同一套 selector 求值语义 -- **AND** SHALL NOT 在 child 派生路径上引入另一套与 root mode 不一致的筛选规则 - -#### Scenario: selector result remains stable across builtin and plugin capabilities - -- **WHEN** 当前 capability surface 同时包含 builtin、MCP 与 plugin capabilities -- **THEN** selector evaluation SHALL 只基于 `CapabilitySpec` 字段求值 -- **AND** SHALL NOT 因能力来源不同而改变并集、交集、差集的结果 - -### Requirement: mode compilation SHALL produce a reusable compiled capability projection before runtime binding - -mode capability compilation MUST 先产出可复用的 compiled capability projection，再由 binder 将其绑定到具体 turn 上。该 compiled projection SHALL 表达 allowed tools、child capability projection、subset router 描述与编译期 diagnostics。 - -#### Scenario: compiler reports an empty projection before runtime submission - -- **WHEN** 某个 mode 的 selector 编译结果为空 -- **THEN** 编译阶段 SHALL 在 compiled projection 中记录诊断信息 -- **AND** binder SHALL 继续消费该诊断，而不是在运行时重新猜测 selector 问题 - -#### Scenario: capability grant intersects after compiled projection is derived - -- **WHEN** spawn 调用提供 `SpawnCapabilityGrant` -- **THEN** 系统 SHALL 先得到 mode 与 child policy 的 compiled capability projection -- **AND** 再与 grant 求交集得到 child 最终能力面 -- **AND** SHALL NOT 让 grant 反向改变 mode compiler 对 selector 的基础解释 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-prompt-program/spec.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-prompt-program/spec.md deleted file mode 100644 index 08da6815..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/mode-prompt-program/spec.md +++ /dev/null @@ -1,40 +0,0 @@ -## ADDED Requirements - -### Requirement: governance prompt inputs SHALL resolve into the existing PromptPlan result model - -mode prompt program、governance helper prompt、child contract prompt、skill-selected prompt 与其他治理级 prompt 输入 MUST 继续通过统一绑定路径汇入现有 `PromptPlan` 结果模型。系统 SHALL NOT 为治理侧单独引入平行的 prompt result IR。 - -#### Scenario: mode prompt declarations and governance helper prompts converge into PromptPlan - -- **WHEN** 当前 turn 同时需要 mode prompt declarations、协作 guidance 与 child contract prompt -- **THEN** 系统 SHALL 先绑定这些治理 prompt 输入 -- **AND** 由现有 prompt composer 产出单一 `PromptPlan` -- **AND** SHALL NOT 让其中任一路径绕过 `PromptPlan` 直接拼接最终 system prompt - -#### Scenario: governance prompt binding preserves source metadata into prompt blocks - -- **WHEN** 治理层注入一个由 mode contract 或 governance helper 生成的 prompt block -- **THEN** 该 block SHALL 能在结果模型中保留来源信息 -- **AND** 调试或诊断时 SHALL 能区分它来自 mode prompt program、治理 helper、child contract 或 skill selection - -### Requirement: mode prompt hooks SHALL extend governance prompt behavior without replacing the prompt pipeline - -mode contract MAY 声明动态 prompt hooks，用于根据 artifact 状态、exit gate 状态或 workflow phase facts 调整 prompt 输入，但这些 facts MUST 由 binder / workflow orchestration 以显式输入提供；hooks 自身 MUST 继续通过既有 `PromptDeclaration` / prompt composition 路径生效。 - -#### Scenario: mode prompt hook adds artifact-aware guidance - -- **WHEN** 某个 mode 声明了与 artifact 状态相关的 prompt hook -- **THEN** 系统 SHALL 基于已绑定的 mode contract 产出额外 prompt input -- **AND** 这些输入 SHALL 通过现有 prompt declaration 与 prompt composer 路径渲染 - -#### Scenario: mode prompt hook reacts to workflow phase facts without owning workflow truth - -- **WHEN** binder 已经把当前 workflow phase 或 bridge facts 作为显式输入传给 mode prompt hook -- **THEN** 该 hook SHALL 可以基于这些 facts 调整治理 prompt 输入 -- **AND** SHALL NOT 通过在 `GovernanceModeSpec` 中反向声明 workflow binding 来拥有 workflow 真相 - -#### Scenario: prompt hook cannot replace contributor internals - -- **WHEN** 一个 mode prompt hook 试图改变 contributor 内部排序或渲染实现 -- **THEN** 系统 SHALL 仅允许它追加或约束治理输入 -- **AND** SHALL NOT 允许 mode hook 直接替换 `adapter-prompt` 的内部组装逻辑 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/workflow-phase-orchestration/spec.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/workflow-phase-orchestration/spec.md deleted file mode 100644 index 92c94497..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/specs/workflow-phase-orchestration/spec.md +++ /dev/null @@ -1,56 +0,0 @@ -## ADDED Requirements - -### Requirement: workflow definitions SHALL be validated and compiled before orchestration - -正式 workflow 在进入 `WorkflowOrchestrator` 前 MUST 先经过显式校验与轻量编译，形成可被 application 消费的 workflow artifact。该 compiled workflow artifact SHALL 保留 phase、transition、signal 与 bridge 语义，但当前规模下 MUST NOT 强制引入额外索引结构。 - -#### Scenario: builtin workflow is validated before orchestration - -- **WHEN** 系统装载 builtin `plan_execute` workflow -- **THEN** 它 SHALL 先校验 initial phase、phase 引用、transition 来源/目标与 signal 合法性 -- **AND** 仅在校验通过后才进入 orchestration 路径 - -#### Scenario: compiled workflow artifact keeps the existing vector-oriented shape - -- **WHEN** 当前 workflow 规模仍然很小 -- **THEN** 系统 MAY 继续以 `Vec` 形状承载 phase 与 transition -- **AND** SHALL NOT 为了满足 compile artifact 概念而强制引入与当前规模不匹配的索引化结构 - -### Requirement: workflow artifacts SHALL own phase-to-mode binding - -workflow phase 与 mode 的关系 MUST 由 workflow artifact 显式持有：phase 通过 `mode_id` 绑定到 mode contract，由治理 compiler / binder 生成治理面；`GovernanceModeSpec` 自身 SHALL NOT 反向声明它属于哪个 workflow phase。 - -#### Scenario: planning phase resolves its governance through phase mode binding - -- **WHEN** `planning` phase 进入执行 -- **THEN** 系统 SHALL 通过 `phase.mode_id` 获取对应 mode contract -- **AND** SHALL 由治理编译链路生成该 phase 的 capability surface、prompt 与 artifact / exit 语义 -- **AND** SHALL NOT 在 workflow orchestrator 内直接硬编码 plan artifact 或 exit 规则 - -#### Scenario: the same mode can be reused by multiple phases - -- **WHEN** 两个 workflow phase 绑定到同一个 `mode_id` -- **THEN** 系统 SHALL 允许它们复用同一份 mode contract -- **AND** SHALL NOT 因 workflow owner 设计要求为每个 phase 复制一份 mode 定义 - -#### Scenario: workflow reconcile uses phase-to-mode binding after recovery - -- **WHEN** workflow state 已恢复但 mode 状态需要 reconcile -- **THEN** 系统 SHALL 基于 `current_phase_id -> phase.mode_id` 进行 reconcile -- **AND** SHALL NOT 反向从当前 mode 猜测 workflow phase - -### Requirement: workflow transition side effects SHALL be owned by application orchestration - -workflow phase 迁移附带的业务副作用 MUST 收敛到 application workflow orchestration owner，而不是散落在 tool handler、session-specific helper 和 submit if/else 中。 - -#### Scenario: plan approval transition owns archive and bridge creation centrally - -- **WHEN** planning -> executing 迁移因用户批准而触发 -- **THEN** 系统 SHALL 由 application workflow helper 统一执行 plan approval、archive、bridge 生成与 workflow state 持久化 -- **AND** SHALL NOT 把这些副作用拆散到 `exitPlanMode`、`session_plan.rs` 与 `session_use_cases.rs` 多处各自维护 - -#### Scenario: entering plan mode does not bootstrap workflow inside the tool handler - -- **WHEN** `enterPlanMode` 触发一次合法的 mode 切换 -- **THEN** 工具 handler SHALL 只负责 mode transition 本身 -- **AND** workflow bootstrap SHALL 由 application orchestration 在统一边界完成 diff --git a/openspec/changes/unify-declarative-dsl-compiler-architecture/tasks.md b/openspec/changes/unify-declarative-dsl-compiler-architecture/tasks.md deleted file mode 100644 index 08e59b23..00000000 --- a/openspec/changes/unify-declarative-dsl-compiler-architecture/tasks.md +++ /dev/null @@ -1,47 +0,0 @@ -## 1. 文档与契约对齐 - -- [x] 1.1 更新 `PROJECT_ARCHITECTURE.md` 与 `docs/architecture/declarative-dsl-compiler-target.md`，明确 `compile` / `bind` / `orchestrate` 术语、mode contract 边界、workflow artifact owner 与 governance snapshot 一致性约束。验证：人工审阅文档；`git diff --check`. -- [x] 1.2 盘点并更新相关 OpenSpec 主 spec 与实现注释中的旧术语，删除 `workflow_binding` 与 mixed-snapshot 的过时表述，避免继续把 `ResolvedTurnEnvelope` 和 `ResolvedGovernanceSurface` 混称为同一层结果。验证：`rg -n "ResolvedTurnEnvelope|ResolvedGovernanceSurface|workflow_binding|running turn.*old snapshot" openspec crates`. - -## 2. 扩展 GovernanceModeSpec - -- [x] 2.1a 在 `crates/core/src/mode/mod.rs` 新增 `ModeArtifactDef` 结构体（artifact_type, file_template, schema_template, required_headings, actionable_sections），补充序列化与校验。验证：新增 `cargo test -p astrcode-core mode::mode_artifact_def`. -- [x] 2.1b 新增 `ModeExitGateDef` 结构体（review_passes, review_checklist），补充序列化与校验。验证：新增 `cargo test -p astrcode-core mode::mode_exit_gate_def`. -- [x] 2.1c 新增 `ModePromptHooks` 结构体（reentry_prompt, initial_template, exit_prompt, facts_template），补充序列化与校验。验证：新增 `cargo test -p astrcode-core mode::mode_prompt_hooks`. -- [x] 2.1d 在 `GovernanceModeSpec` 上增加三个 `Option` 字段（artifact, exit_gate, prompt_hooks），扩展 `validate()` 递归校验新字段。验证：`cargo test -p astrcode-core mode`. -- [x] 2.2 调整 `crates/protocol/src/plugin/handshake.rs` 及其测试，确保插件通过 `InitializeResultData.modes` 声明扩展后的 mode contract 时仍保持纯 DTO 形状（字段可选，缺失时与旧行为等价）。验证：`cargo test -p astrcode-protocol plugin`. -- [x] 2.3 让 builtin `plan` mode 在 `crates/application/src/mode/catalog.rs` 中以新 mode contract 字段表达当前 artifact / exit / prompt 语义，而不是只靠工具名约定。验证：新增/更新 `cargo test -p astrcode-application mode::catalog`. -- [x] 2.4 为 `ModeCatalog` 增加 duplicate `mode_id` 检测，拒绝 plugin 覆盖 builtin mode 或多个 plugin 共享同一 `mode_id`。验证：新增/更新 `cargo test -p astrcode-application mode::catalog`. - -## 3. 显式化治理 compile / bind 边界 - -- [x] 3.1 重构 `crates/application/src/mode/compiler.rs`，把 selector 求值、mode contract 派生、child/grant 裁剪与 diagnostics 明确收敛到编译阶段产物中。验证：新增/更新 `cargo test -p astrcode-application mode::compiler`. -- [x] 3.2 调整 `crates/application/src/governance_surface/assembler.rs` 与 `mod.rs`，把 runtime/profile/session/control 绑定责任与 compile 责任分开；必要时仅做渐进命名收束，不强求一次性全量改名。验证：新增/更新 `cargo test -p astrcode-application governance_surface`. -- [x] 3.3 为工具执行新增 pure-data `BoundModeToolContractSnapshot`（命名可渐进演化），并沿 `ResolvedGovernanceSurface -> AgentPromptSubmission -> ToolContext / CapabilityContext` 传递，禁止 `adapter-tools` 依赖 application 内部类型。验证：新增/更新 `cargo test -p astrcode-core tool`, `cargo test -p astrcode-kernel registry::tool`, `cargo test -p astrcode-session-runtime turn::submit`. -- [x] 3.4 收敛治理 prompt 来源，在 `crates/application/src/governance_surface/prompt.rs`、`crates/adapter-prompt/src/plan.rs`、`crates/adapter-prompt/src/block.rs` 之间保留单一 `PromptPlan` 结果模型，并补充来源 metadata。验证：`cargo test -p astrcode-adapter-prompt`. - -## 4. workflow 轻量编译与 owner 收敛 - -- [x] 4.1 在 `crates/core/src/workflow.rs` 或 `crates/application/src/workflow/*` 中补充 workflow validate/compile 边界，使 workflow 在进入 orchestrator 前先完成显式校验。验证：新增/更新 `cargo test -p astrcode-application workflow`. -- [x] 4.2 调整 `crates/application/src/workflow/orchestrator.rs`，让 phase -> mode 绑定继续由 workflow artifact 的 `phase.mode_id` 持有，而不是反向从 mode spec 查 workflow binding。验证：新增/更新 `cargo test -p astrcode-application workflow::orchestrator`. -- [x] 4.3 把 plan workflow 的 bootstrap / approval / archive / bridge / reconcile 副作用从 `session_plan.rs`、`session_use_cases.rs` 的散落逻辑中收回到 `crates/application/src/workflow/*` 的统一 helper / service。验证：新增/更新 `cargo test -p astrcode-application workflow`. -- [x] 4.4 简化 `crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs`，使其只负责 mode transition；workflow bootstrap 改由 application workflow orchestration 统一触发。验证：更新 `cargo test -p astrcode-adapter-tools builtin_tools::enter_plan_mode`。 -- [x] 4.5 保持当前 workflow 数据结构克制，不引入与现有规模不匹配的索引化结构，同时补充对应注释与测试断言。验证：人工审阅实现；相关 workflow 单测通过。 - -## 5. reload 一致性与回滚 - -- [x] 5.1 重构 `crates/server/src/bootstrap/governance.rs`，把 mode catalog、capability surface、skill catalog 组织成统一候选治理快照，并在失败时完整回滚。验证：新增/更新 `cargo test -p astrcode-server bootstrap::governance`. -- [x] 5.2 调整 `crates/server/src/bootstrap/capabilities.rs` 与相关组合根逻辑，继续保持“存在 running session 时拒绝 reload”的治理合同，并删除 mixed-snapshot 假设。验证：新增/更新 `cargo test -p astrcode-server bootstrap::capabilities`. -- [x] 5.3 为 reload 成功/失败路径补充 observability 或日志诊断，能够说明 mode catalog / capability surface / skill catalog 的快照切换边界。验证：自动化测试或手动检查日志输出。 - -## 6. plan 合同清理 - -- [x] 6.1 在 `crates/application/src/session_plan.rs` 中引入 `build_mode_prompt_declarations(spec, artifact_state, workflow_facts)`，由 `ModePromptHooks` 驱动 facts / reentry / template / exit prompt 逻辑；`build_plan_prompt_declarations()` 改为委托新函数。验证：更新 `cargo test -p astrcode-application session_plan`. -- [x] 6.2 调整 `crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs` 与 `exit_plan_mode.rs`，让它们通过 `BoundModeToolContractSnapshot` 读取 artifact / exit 合同，而不是继续硬编码 heading / checklist / writer 约束。验证：更新 `cargo test -p astrcode-adapter-tools builtin_tools::upsert_session_plan`, `cargo test -p astrcode-adapter-tools builtin_tools::exit_plan_mode`. -- [x] 6.3 更新 builtin `plan` mode prompt 与相关说明文案，移除对 `workflow_binding`、generic mode tool 和 mixed-snapshot 的错误假设。验证：新增/更新相关单测；`rg -n "workflow_binding|upsertModeArtifact|exitMode|running turn.*old snapshot" openspec crates`. - -## 7. 回归验证 - -- [x] 7.1 增加 selector 稳定性、duplicate mode id 拒绝、plugin mode 注册（含新 contract 字段）、workflow compile / reconcile、reload 回滚、tool-contract bridge 与 prompt 来源追踪的回归测试。验证：`cargo test --workspace --exclude astrcode --lib`. -- [x] 7.2 清理其他已经无用的代码路径或测试断言，确认没有残留对旧术语、旧 owner 或旧假设的依赖。 -- [x] 7.3 运行仓库级边界检查，确认治理 / 工作流改造没有破坏 crate 依赖方向。验证：`node scripts/check-crate-boundaries.mjs`. diff --git a/openspec/config.yaml b/openspec/config.yaml index 5435487c..96b1f3c0 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,10 +1,11 @@ -schema: spec-driven +schema: my-workflow context: | # 语言与文档规范 - 所有文档、分析、设计说明、任务拆解、验收标准必须使用中文。 - 术语应保持前后一致，优先使用项目既有命名；若引入新术语，必须先定义其含义与边界。 - 文档应强调可执行性，避免空泛表述，优先给出明确约束、边界、输入输出与验收方式。 + - 本项目不需要向后兼容旧版本和api # 项目事实 - 技术栈： @@ -55,43 +56,4 @@ context: | - 流式场景必须考虑中断、取消、部分输出、重试与一致性问题。 - 若涉及事件模型，必须说明事件定义、追加时机、回放行为、恢复策略与投影视图关系。 -rules: - proposal: - - 必须明确：问题、目标、约束、最终方案、关键取舍。 - - 必须说明：用户可见影响、开发者可见影响、系统边界影响。 - - 必须列出 non-goals，明确本次不解决的问题。 - - 若涉及替换旧结构，必须给出迁移路径、兼容策略与回滚思路。 - - 若涉及架构演进，必须说明是否需要同步更新 PROJECT_ARCHITECTURE.md。 - - 避免只描述“想做什么”，必须解释“为什么这样做而不是其他方案”。 - - specs: - - 验收条件必须具体、清晰、可验证，避免模糊词汇。 - - 必须覆盖正常路径、边界情况、失败路径与流式场景。 - - 优先复用现有模式；若新增抽象，必须说明其必要性与替代方案为何不足。 - - 若涉及架构边界，必须明确模块职责、交互约束与禁止事项。 - - 若涉及状态变化，必须说明状态来源、状态持久化方式与一致性要求。 - - 验收标准应尽量从外部行为出发，而不是只描述内部实现。 - - design: - - 必须明确依赖方向与核心数据流(重要)。 - - 必须明确持久化方案、事件模型以及回放 / 恢复机制。 - - 若涉及 server / runtime / storage / frontend，必须分别说明职责变化。 - - 若涉及协议或 DTO，必须保证其为纯数据结构，不承载业务逻辑。 - - 若涉及会话、子 agent、工具调用，必须说明生命周期、所有权边界、通信语义与失败恢复。 - - 必须指出新增文件、修改文件、删除文件及其原因。 - - 必须标注高风险点、兼容性影响、性能影响与可观测性需求。 - - 设计应优先服务实现，不要写成抽象口号。 - - tasks: - - 每个任务应尽量可独立实现、独立验证、独立回滚。 - - 每个任务应尽量包含准确文件路径；若暂时不能确定，也应明确模块范围。 - - 每个任务必须附带至少一种验证方式： - - 自动化测试 - - 命令行验证 - - 手动验收步骤 - - 生成任务时必须考虑实现细节 - - 优先按可独立交付的阶段拆分，而不是按技术层大块堆叠。 - - 每个任务应避免同时跨越多个无强依赖的关注点。 - - 生成 tasks 时必须关注修改后目录结构、文件命名、模块归属的合理性，保持项目结构清晰、一致、可维护。 - - 若任务涉及迁移、重构或替换，必须包含清理旧结构或保留兼容层的后续任务。 - - 若任务较大，应进一步拆成可以在单次实现中稳定完成的小任务。 \ No newline at end of file +rules: \ No newline at end of file diff --git a/openspec/schemas/my-workflow/schema.yaml b/openspec/schemas/my-workflow/schema.yaml new file mode 100644 index 00000000..33452e60 --- /dev/null +++ b/openspec/schemas/my-workflow/schema.yaml @@ -0,0 +1,210 @@ +name: my-workflow +version: 1 +description: 自定义 OpenSpec 工作流：research → proposal → specs → dto → design → tasks +artifacts: + - id: research + generates: research.md + requires: [] + description: 调研当前现状、约束、风险与可复用点的背景文档 + template: research.md + instruction: | + 目标： + - 先弄清楚“项目现在是什么样”，再进入提案、规格和设计。 + + 主要输入： + - 用户需求 + - 当前代码、文档、脚本、测试、既有 specs + + 必须回答： + - 相关功能、模块、接口、数据结构现在在哪里、如何工作 + - 哪些内容可以直接复用，哪些是限制、风险或潜在冲突 + - 如果是改已有能力，当前行为与目标行为差异是什么 + - 哪些事实已经确认，哪些仍然只是推测 + + 写作要求： + - 用通俗中文，少空话，优先写清楚事实 + - 尽量引用真实文件路径、目录、接口名、spec 名称 + - 事实与判断分开写，方便后续文档直接引用 + - 这一阶段聚焦现状与问题，不展开具体实现方案 + + 输出要求： + - 按模板整理为可复用上下文，供 proposal / specs / dto / design 直接消费 + + - id: proposal + generates: proposal.md + description: 说明为什么做、做什么、影响范围是什么的变更提案 + template: proposal.md + instruction: | + 目标： + - 说明这次变更为什么值得做，以及本次到底要改什么。 + + 主要输入： + - `research.md` + + 必须回答： + - 当前问题或机会是什么，为什么现在处理 + - 本次要新增、修改、删除什么 + - 本次明确不做什么 + - 会影响哪些模块、接口、数据、流程或使用方式 + - 哪些能力需要写新 spec，哪些能力需要修改现有 spec + + 写作要求： + - 先讲“为什么”，再讲“做什么”，不要提前写实现细节 + - `新增能力` 和 `修改能力` 要写得足够明确，因为后续 specs 会直接据此展开 + - 若存在 breaking change，要显式标注 `BREAKING` + - 内容简洁、边界明确，通常控制在 1-2 页 + + 输出要求： + - 让读者看完后能明确本次变更的目标、边界、影响范围和 spec 拆分方式 + requires: + - research + + - id: specs + generates: specs/**/*.md + description: 定义系统应表现为什么样的行为规格 + template: spec.md + instruction: | + 目标： + - 用清晰、可验证的方式定义“系统应该做什么”。 + + 主要输入： + - `proposal.md` + - `research.md` + + 必须回答： + - 每个能力的预期行为是什么 + - 正常路径、边界条件、失败路径分别怎么表现 + - 哪些需求是新增，哪些是修改、删除或重命名 + + 写作要求： + - 每个能力写一个 spec 文件 + - 新能力使用 proposal 中给出的 kebab-case 名称：`specs//spec.md` + - 修改已有能力时，沿用 `openspec/specs//` 的既有目录名 + - 保留以下 delta 头，不要翻译： + - `## ADDED Requirements` + - `## MODIFIED Requirements` + - `## REMOVED Requirements` + - `## RENAMED Requirements` + - 每条需求使用 `### Requirement: <名称>` + - 每个场景使用 `#### Scenario: <名称>` + - 场景正文使用 `WHEN` / `THEN` + - 每条需求至少有一个场景 + - 修改已有需求时，必须粘贴并改写完整 requirement block，不要只改一半 + - 删除需求时，必须写 `Reason` 和 `Migration` + - 重命名需求时，使用 `FROM:` / `TO:` 格式 + + 输出要求： + - 需求必须能被测试或验收，不要写“优化一下”“支持一下”这类模糊描述 + requires: + - proposal + - research + + - id: dto + generates: dto.md + description: 梳理边界数据模型、字段约束与映射关系的数据说明 + template: dto.md + instruction: | + 目标： + - 把本次变更涉及的数据模型讲清楚，减少实现阶段对字段和边界的反复猜测。 + + 主要输入： + - `proposal.md` + - `research.md` + - `specs/**/*.md` + + 必须回答： + - 本次涉及哪些模型：新增、修改、复用各有哪些 + - 每个模型属于哪个边界：请求 / 响应 / 命令 / 事件 / 持久化 / 内部视图 / 其他 + - 字段名、类型、必填性、默认值、约束、不变量分别是什么 + - 模型之间是什么关系，数据从哪里来、流向哪里 + - 与现有结构如何映射，是否有兼容性或 breaking 影响 + + 写作要求： + - 区分“对外边界 DTO”和“内部核心模型” + - 优先基于真实需求和现有结构，不要凭空发明字段 + - 如果本次不需要新增 DTO，也要明确说明沿用了哪些现有模型，以及为什么够用 + - 重点是让实现者和 LLM 一眼看懂每个模型的职责、边界和字段约束 + + 输出要求： + - 每个模型都应能独立被实现、序列化、校验或映射 + requires: + - proposal + - research + - specs + + - id: design + generates: design.md + description: 说明方案如何落地、为什么这样落地的技术设计文档 + template: design.md + instruction: | + 目标： + - 说明“准备怎么做”，以及“为什么这样做而不是别的做法”。 + + 主要输入： + - `proposal.md` + - `research.md` + - `specs/**/*.md` + - `dto.md` + + 必须回答： + - 关键模块、职责和边界如何划分 + - 主要数据流、控制流、错误流如何走 + - 关键技术决策是什么，备选方案为什么没选 + - 迁移、回滚、兼容性、性能、安全、可观测性需要注意什么 + - 本次实现如何满足 spec 与 dto 的要求 + + 写作要求： + - design 是本工作流的正式 artifact，简单变更可以写短版，但不要留空 + - 重点解释边界、方案和取舍，不要写成逐行代码说明 + - 复杂点要说明风险与缓解方式 + - 如果会新增、修改、删除关键文件或模块，尽量明确指出 + + 输出要求： + - 让实现者能据此开展编码，也让审阅者能快速判断方案是否合理 + requires: + - proposal + - research + - specs + - dto + + - id: tasks + generates: tasks.md + description: 按依赖顺序拆分、可跟踪执行的任务清单 + template: tasks.md + instruction: | + 目标： + - 把实现工作拆成按顺序执行、可验证、可勾选的任务。 + + 主要输入： + - `specs/**/*.md` + - `dto.md` + - `design.md` + + 必须回答： + - 先做什么，后做什么，哪些任务互相依赖 + - 每个任务修改哪里、产出什么、怎么验证 + + 写作要求： + - 保持以下格式，不要改： + - 分组标题：`## 1. 分组名称` + - 任务项：`- [ ] 1.1 任务描述` + - 每个任务尽量只做一件明确的事 + - 任务描述尽量带上模块、文件、接口或对象名称 + - 优先按依赖顺序拆分，而不是按技术层机械分组 + - 大任务继续拆小，不要把整块重构写成一条 + - 每个任务都应具备完成判定，最好能看出验证方式 + + 输出要求： + - 让实现阶段可以直接按清单推进，并在完成后逐条勾选 + requires: + - specs + - dto + - design +apply: + requires: + - tasks + tracks: tasks.md + instruction: | + 先读取所有上下文文件，再按未完成任务顺序实施。 + 每完成一项就立即更新 `tasks.md`。 + 如果发现阻塞、事实与文档不一致、或需要回写 proposal/specs/dto/design，先停下来更新对应 artifact，再继续。 diff --git a/openspec/schemas/my-workflow/templates/design.md b/openspec/schemas/my-workflow/templates/design.md new file mode 100644 index 00000000..745a3737 --- /dev/null +++ b/openspec/schemas/my-workflow/templates/design.md @@ -0,0 +1,48 @@ +## 背景与现状 + + + +## 设计目标 + + + +## 非目标 + + + +## 方案概览 + + + +## 关键决策 + +### 决策 1 + +- 决策： +- 原因： +- 备选方案： +- 为什么没选： + +## 数据流 / 控制流 / 错误流 + + + +## 与 DTO / Spec 的对应关系 + + + +## 风险与取舍 + + + +## 实施与迁移 + + + +## 验证方案 + + + +## 未决问题 + + diff --git a/openspec/schemas/my-workflow/templates/dto.md b/openspec/schemas/my-workflow/templates/dto.md new file mode 100644 index 00000000..0830c5d1 --- /dev/null +++ b/openspec/schemas/my-workflow/templates/dto.md @@ -0,0 +1,47 @@ +## 概览 + + + +## 模型清单 + +### `` + +- 用途： +- 类型： +- 所属边界： +- 来源： +- 去向： + +#### 字段定义 + +| 字段 | 类型 | 必填 | 默认值 | 约束 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `id` | `string` | 是 | - | 唯一 | 主键或稳定标识 | + +#### 与其他模型的关系 + +- 与 ``： + +#### 校验规则与不变量 + +- + +#### 生命周期 / 状态变化 + +- 如不适用，写“无” + +#### 映射关系 + +- 例如：`ApiRequest -> Command -> DomainModel -> ApiResponse` + +## 兼容性与迁移 + + + +## 复用说明 + + + +## 未决问题 + + diff --git a/openspec/schemas/my-workflow/templates/proposal.md b/openspec/schemas/my-workflow/templates/proposal.md new file mode 100644 index 00000000..2d919334 --- /dev/null +++ b/openspec/schemas/my-workflow/templates/proposal.md @@ -0,0 +1,33 @@ +## 背景 + + + +## 目标 + + + +## 非目标 + + + +## 变更内容 + + + +## 能力变更 + +### 新增能力 + +- ``: <一句话说明这个能力负责什么> + +### 修改能力 + +- ``: <本次具体改动了什么行为或约束> + +## 影响范围 + + + +## 约束与风险 + + diff --git a/openspec/schemas/my-workflow/templates/research.md b/openspec/schemas/my-workflow/templates/research.md new file mode 100644 index 00000000..bf7f18d2 --- /dev/null +++ b/openspec/schemas/my-workflow/templates/research.md @@ -0,0 +1,47 @@ +## 调研目标 + + + +## 当前现状 + +### 相关代码与模块 + + + +### 相关接口与能力 + + + +### 相关数据与模型 + + + +### 测试、约束与边界 + + + +## 关键发现 + +### 发现 1 + +- 事实： +- 证据： +- 影响： +- 可复用点： + +## 可选方案比较 + +| 方案 | 适用前提 | 优点 | 风险/代价 | 结论 | +| --- | --- | --- | --- | --- | +| A | | | | | +| B | | | | | + +## 结论 + +- 推荐方向： +- 理由： +- 暂不采用的方案： + +## 未决问题 + + diff --git a/openspec/schemas/my-workflow/templates/spec.md b/openspec/schemas/my-workflow/templates/spec.md new file mode 100644 index 00000000..311dd18f --- /dev/null +++ b/openspec/schemas/my-workflow/templates/spec.md @@ -0,0 +1,38 @@ +## ADDED Requirements + + + +### Requirement: <需求名称> + + +#### Scenario: <场景名称> +- **WHEN** <触发条件、前置条件或用户动作> +- **THEN** <系统可观察到的结果> + +## MODIFIED Requirements + + + +### Requirement: <已有需求名称> + + +#### Scenario: <场景名称> +- **WHEN** <触发条件、前置条件或用户动作> +- **THEN** <系统可观察到的结果> + +## REMOVED Requirements + + + +### Requirement: <已删除需求名称> + +**Reason**: <为什么删除> + +**Migration**: <如何迁移；如果不需要迁移可写 None> + +## RENAMED Requirements + + + +- FROM: `### Requirement: <旧名称>` +- TO: `### Requirement: <新名称>` diff --git a/openspec/schemas/my-workflow/templates/tasks.md b/openspec/schemas/my-workflow/templates/tasks.md new file mode 100644 index 00000000..44c13b4e --- /dev/null +++ b/openspec/schemas/my-workflow/templates/tasks.md @@ -0,0 +1,14 @@ +## 1. 准备与结构调整 + +- [ ] 1.1 <明确要修改的模块、文件或接口> +- [ ] 1.2 <补充或调整必要的数据结构 / DTO / 配置> + +## 2. 核心实现 + +- [ ] 2.1 <实现主要能力或主流程> +- [ ] 2.2 <补齐边界条件、错误处理或兼容逻辑> + +## 3. 验证与清理 + +- [ ] 3.1 <补充或更新测试 / 校验脚本 / 手动验证步骤> +- [ ] 3.2 <清理旧逻辑、无用代码、文档或迁移痕迹> diff --git a/scripts/check-crate-boundaries.mjs b/scripts/check-crate-boundaries.mjs index b1d4b287..99162506 100644 --- a/scripts/check-crate-boundaries.mjs +++ b/scripts/check-crate-boundaries.mjs @@ -56,25 +56,40 @@ function buildRules() { }, { id: 'R003', - description: 'kernel 仅承载全局控制面，只允许依赖 core', + description: 'kernel 是迁移源，只允许依赖 core 与新 owner 边界', source: 'astrcode-kernel', - allowedExact: new Set(['astrcode-core']), + allowedExact: new Set([ + 'astrcode-core', + 'astrcode-agent-runtime', + 'astrcode-host-session', + 'astrcode-plugin-host', + ]), }, { id: 'R004', - description: 'session-runtime 仅允许依赖 core、support 与 kernel', + description: 'session-runtime 是迁移源，只允许依赖 core、support、kernel 与新 owner 边界', source: 'astrcode-session-runtime', - allowedExact: new Set(['astrcode-core', 'astrcode-support', 'astrcode-kernel']), + allowedExact: new Set([ + 'astrcode-core', + 'astrcode-support', + 'astrcode-kernel', + 'astrcode-agent-runtime', + 'astrcode-host-session', + 'astrcode-plugin-host', + ]), }, { id: 'R005', - description: 'application 仅允许依赖 core、support、kernel、session-runtime', + description: 'application 是迁移源，只允许依赖 core、support、旧迁移源与新 owner 边界', source: 'astrcode-application', allowedExact: new Set([ 'astrcode-core', 'astrcode-support', 'astrcode-kernel', 'astrcode-session-runtime', + 'astrcode-agent-runtime', + 'astrcode-host-session', + 'astrcode-plugin-host', ]), }, { @@ -83,6 +98,29 @@ function buildRules() { source: 'astrcode-support', allowedExact: new Set(['astrcode-core']), }, + { + id: 'R007', + description: 'agent-runtime 是最小执行内核，只允许依赖 core', + source: 'astrcode-agent-runtime', + allowedExact: new Set(['astrcode-core']), + }, + { + id: 'R008', + description: 'plugin-host 只承载统一插件宿主，只允许依赖 core、protocol、support', + source: 'astrcode-plugin-host', + allowedExact: new Set(['astrcode-core', 'astrcode-protocol', 'astrcode-support']), + }, + { + id: 'R009', + description: 'host-session 只承载 session owner 逻辑，只允许依赖 core、support、agent-runtime、plugin-host', + source: 'astrcode-host-session', + allowedExact: new Set([ + 'astrcode-core', + 'astrcode-support', + 'astrcode-agent-runtime', + 'astrcode-plugin-host', + ]), + }, ]; } From 659dedc50f377696754148ac7068425b942b2b8c Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 17:40:24 +0800 Subject: [PATCH 02/10] =?UTF-8?q?=E2=9C=A8=20feat(server):=20=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=20runtime=20mode=20tool=20contract=20=E5=AE=9E?= =?UTF-8?q?=E6=97=B6=E7=83=AD=E6=9B=B4=E6=96=B0=EF=BC=8C=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=20SSE=20decode=20=E9=94=99=E8=AF=AF=E6=9C=AA=E8=A2=AB=E9=87=8D?= =?UTF-8?q?=E8=AF=95=E7=9A=84=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit crates/adapter-llm/src/openai.rs - 将 SSE 流解码错误（is_decode）纳入可重试错误条件，避免 decode 失败直接终止流 crates/server/src/mode_catalog_service.rs - 新增 bound_tool_contract_snapshot 方法，按 mode_id 查询绑定工具合约快照 crates/server/src/session_runtime_port_adapter.rs - 将 RouterToolDispatcher 中 mode/contract 快照从不可变字段改为 Mutex 保护的 RuntimeModeToolState， 使 mode 切换时 tool dispatcher 能实时获取最新 contract - RuntimeToolEventSink 在 ModeChanged 事件时校验 from 与当前 runtime mode 一致性， 并自动刷新 bound_tool_contract_snapshot - 新增 enterPlanMode → upsertSessionPlan → exitPlanMode 全链路集成测试 --- crates/adapter-llm/src/openai.rs | 5 +- crates/server/src/mode_catalog_service.rs | 18 +- .../src/session_runtime_port_adapter.rs | 213 ++++++++++++++++-- 3 files changed, 221 insertions(+), 15 deletions(-) diff --git a/crates/adapter-llm/src/openai.rs b/crates/adapter-llm/src/openai.rs index cfd4d077..8faaeddb 100644 --- a/crates/adapter-llm/src/openai.rs +++ b/crates/adapter-llm/src/openai.rs @@ -496,7 +496,10 @@ impl OpenAiProvider { let bytes = item.map_err(|error| { AstrError::http_with_source( "failed to read openai response stream", - error.is_timeout() || error.is_connect() || error.is_body(), + error.is_timeout() + || error.is_connect() + || error.is_body() + || error.is_decode(), error, ) })?; diff --git a/crates/server/src/mode_catalog_service.rs b/crates/server/src/mode_catalog_service.rs index 5c868a6c..8dd71667 100644 --- a/crates/server/src/mode_catalog_service.rs +++ b/crates/server/src/mode_catalog_service.rs @@ -3,7 +3,7 @@ use std::{ sync::{Arc, RwLock}, }; -use astrcode_core::{AstrError, GovernanceModeSpec, ModeId, Result}; +use astrcode_core::{AstrError, BoundModeToolContractSnapshot, GovernanceModeSpec, ModeId, Result}; use crate::mode::{ModeCatalog, validate_mode_transition}; @@ -114,6 +114,22 @@ impl ServerModeCatalog { validate_mode_transition(&catalog, from_mode_id, to_mode_id)?; Ok(()) } + + pub(crate) fn bound_tool_contract_snapshot( + &self, + mode_id: &ModeId, + ) -> Result { + let snapshot = self.snapshot(); + let entry = snapshot + .entries + .get(mode_id.as_str()) + .ok_or_else(|| AstrError::Validation(format!("unknown mode '{}'", mode_id)))?; + Ok(BoundModeToolContractSnapshot { + mode_id: entry.spec.id.clone(), + artifact: entry.spec.artifact.clone(), + exit_gate: entry.spec.exit_gate.clone(), + }) + } } fn build_snapshot( diff --git a/crates/server/src/session_runtime_port_adapter.rs b/crates/server/src/session_runtime_port_adapter.rs index b99d7a64..129d6386 100644 --- a/crates/server/src/session_runtime_port_adapter.rs +++ b/crates/server/src/session_runtime_port_adapter.rs @@ -1,4 +1,7 @@ -use std::{path::PathBuf, sync::Arc}; +use std::{ + path::PathBuf, + sync::{Arc, Mutex}, +}; use astrcode_agent_runtime::{ AgentRuntime, AgentRuntimeExecutionSurface, LlmEvent, LlmProvider, RuntimeEventSink, @@ -67,9 +70,58 @@ struct RouterToolDispatcher { working_dir: PathBuf, cancel: CancelToken, agent: astrcode_core::AgentEventContext, + mode_tool_state: RuntimeModeToolState, + event_sink: Arc, +} + +#[derive(Clone)] +struct RuntimeModeToolState { + inner: Arc>, +} + +#[derive(Clone)] +struct RuntimeModeToolStateSnapshot { current_mode_id: ModeId, bound_mode_tool_contract: Option, - event_sink: Arc, +} + +impl RuntimeModeToolState { + fn new( + current_mode_id: ModeId, + bound_mode_tool_contract: Option, + ) -> Self { + Self { + inner: Arc::new(Mutex::new(RuntimeModeToolStateSnapshot { + current_mode_id, + bound_mode_tool_contract, + })), + } + } + + fn snapshot(&self) -> RuntimeModeToolStateSnapshot { + self.inner + .lock() + .expect("runtime mode tool state lock poisoned") + .clone() + } + + fn current_mode_id(&self) -> ModeId { + self.snapshot().current_mode_id + } + + fn replace( + &self, + current_mode_id: ModeId, + bound_mode_tool_contract: Option, + ) { + *self + .inner + .lock() + .expect("runtime mode tool state lock poisoned") = RuntimeModeToolStateSnapshot { + current_mode_id, + bound_mode_tool_contract, + }; + } } struct SpawnTurnExecutionInput { @@ -111,10 +163,11 @@ impl ToolDispatcher for RouterToolDispatcher { ) .with_turn_id(request.turn_id) .with_tool_call_id(request.tool_call.id.clone()) - .with_agent_context(self.agent.clone()) - .with_current_mode_id(self.current_mode_id.clone()); - if let Some(snapshot) = &self.bound_mode_tool_contract { - tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot.clone()); + .with_agent_context(self.agent.clone()); + let mode_snapshot = self.mode_tool_state.snapshot(); + tool_ctx = tool_ctx.with_current_mode_id(mode_snapshot.current_mode_id); + if let Some(snapshot) = mode_snapshot.bound_mode_tool_contract { + tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot); } if let Some(sender) = request.tool_output_sender { tool_ctx = tool_ctx.with_tool_output_sender(sender); @@ -226,6 +279,8 @@ impl SessionRuntimeCompatPort { let resolved_overrides = submission.resolved_overrides.clone(); let current_mode_id = submission.current_mode_id.clone(); let bound_mode_tool_contract = submission.bound_mode_tool_contract.clone(); + let mode_tool_state = + RuntimeModeToolState::new(current_mode_id, bound_mode_tool_contract); let (runtime_event_sink, runtime_event_bridge) = spawn_runtime_event_bridge( Arc::clone(&session_catalog), session_id.clone(), @@ -235,6 +290,7 @@ impl SessionRuntimeCompatPort { let tool_event_sink = Arc::new(RuntimeToolEventSink { runtime_event_sink: Arc::clone(&runtime_event_sink), mode_catalog: Arc::clone(&mode_catalog), + mode_tool_state: mode_tool_state.clone(), }); let _ = session_catalog @@ -276,8 +332,7 @@ impl SessionRuntimeCompatPort { working_dir: working_dir.clone(), cancel: CancelToken::new(), agent: agent.clone(), - current_mode_id, - bound_mode_tool_contract, + mode_tool_state, event_sink: tool_event_sink, })) .with_working_dir(working_dir) @@ -745,6 +800,7 @@ impl SessionRuntimePort for SessionRuntimeCompatPort { struct RuntimeToolEventSink { runtime_event_sink: Arc, mode_catalog: Arc, + mode_tool_state: RuntimeModeToolState, } #[async_trait] @@ -752,6 +808,16 @@ impl ToolEventSink for RuntimeToolEventSink { async fn emit(&self, event: StorageEvent) -> astrcode_core::Result<()> { if let StorageEventPayload::ModeChanged { from, to, .. } = &event.payload { self.mode_catalog.validate_transition(from, to)?; + let current_mode_id = self.mode_tool_state.current_mode_id(); + if ¤t_mode_id != from { + return Err(AstrError::Validation(format!( + "mode transition from '{}' does not match current runtime mode '{}'", + from, current_mode_id + ))); + } + let bound_mode_tool_contract = self.mode_catalog.bound_tool_contract_snapshot(to)?; + self.mode_tool_state + .replace(to.clone(), Some(bound_mode_tool_contract)); } self.runtime_event_sink .emit_event(RuntimeTurnEvent::StorageEvent { @@ -1220,7 +1286,10 @@ fn map_pending_parent_deliveries( mod tests { use std::sync::Arc; - use astrcode_adapter_tools::builtin_tools::enter_plan_mode::EnterPlanModeTool; + use astrcode_adapter_tools::builtin_tools::{ + enter_plan_mode::EnterPlanModeTool, exit_plan_mode::ExitPlanModeTool, + upsert_session_plan::UpsertSessionPlanTool, + }; use astrcode_agent_runtime::{RuntimeEventSink, ToolDispatchRequest, ToolDispatcher}; use astrcode_core::{ AgentEvent, AgentEventContext, CancelToken, CapabilityInvoker, ModeId, StorageEvent, @@ -1228,7 +1297,7 @@ mod tests { }; use super::{ - RouterToolDispatcher, RuntimeToolEventSink, RuntimeTurnEvent, + RouterToolDispatcher, RuntimeModeToolState, RuntimeToolEventSink, RuntimeTurnEvent, runtime_event_to_live_agent_events, }; use crate::{ @@ -1287,16 +1356,18 @@ mod tests { Arc::new(move |event: RuntimeTurnEvent| { let _ = event_tx.send(event); }); + let mode_catalog = builtin_server_mode_catalog(); + let mode_tool_state = RuntimeModeToolState::new(ModeId::code(), None); let dispatcher = RouterToolDispatcher { capability_router, working_dir: std::env::temp_dir(), cancel: CancelToken::new(), agent: AgentEventContext::root_execution("agent-root", "default"), - current_mode_id: ModeId::code(), - bound_mode_tool_contract: None, + mode_tool_state: mode_tool_state.clone(), event_sink: Arc::new(RuntimeToolEventSink { runtime_event_sink, - mode_catalog: builtin_server_mode_catalog(), + mode_catalog, + mode_tool_state, }), }; @@ -1330,6 +1401,122 @@ mod tests { )); } + #[tokio::test] + async fn router_tool_dispatcher_updates_mode_contract_after_enter_plan_mode() { + let capability_router = CapabilityRouter::builder() + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(EnterPlanModeTool)) + .expect("enterPlanMode should register"), + ) as Arc) + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(UpsertSessionPlanTool)) + .expect("upsertSessionPlan should register"), + ) as Arc) + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(ExitPlanModeTool)) + .expect("exitPlanMode should register"), + ) as Arc) + .build() + .expect("capability router should build"); + let (event_tx, mut event_rx) = tokio::sync::mpsc::unbounded_channel(); + let runtime_event_sink: Arc = + Arc::new(move |event: RuntimeTurnEvent| { + let _ = event_tx.send(event); + }); + let mode_catalog = builtin_server_mode_catalog(); + let mode_tool_state = RuntimeModeToolState::new(ModeId::code(), None); + let temp = tempfile::tempdir().expect("tempdir should exist"); + let dispatcher = RouterToolDispatcher { + capability_router, + working_dir: temp.path().to_path_buf(), + cancel: CancelToken::new(), + agent: AgentEventContext::root_execution("agent-root", "default"), + mode_tool_state: mode_tool_state.clone(), + event_sink: Arc::new(RuntimeToolEventSink { + runtime_event_sink, + mode_catalog, + mode_tool_state, + }), + }; + + dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-enter".to_string(), + name: "enterPlanMode".to_string(), + args: serde_json::json!({ "reason": "need a plan" }), + }, + tool_output_sender: None, + }) + .await + .expect("enterPlanMode dispatch should succeed"); + let event = event_rx.recv().await.expect("mode event should emit"); + assert!(matches!( + event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + &event.payload, + StorageEventPayload::ModeChanged { from, to, .. } + if *from == ModeId::code() && *to == ModeId::plan() + ) + )); + + let upsert_result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-upsert".to_string(), + name: "upsertSessionPlan".to_string(), + args: serde_json::json!({ + "title": "Cleanup crates", + "content": "# Plan: Cleanup crates\n\n## Context\n- inspect first\n\n## Goal\n- produce a plan\n\n## Implementation Steps\n- update the code\n\n## Verification\n- run tests", + "status": "draft" + }), + }, + tool_output_sender: None, + }) + .await + .expect("upsertSessionPlan dispatch should succeed"); + assert!(upsert_result.ok); + let upsert_metadata = upsert_result + .metadata + .as_ref() + .expect("upsertSessionPlan metadata should exist"); + assert_eq!( + upsert_metadata["artifactType"], + serde_json::json!("canonical-plan") + ); + + let exit_result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-exit".to_string(), + name: "exitPlanMode".to_string(), + args: serde_json::json!({}), + }, + tool_output_sender: None, + }) + .await + .expect("exitPlanMode dispatch should succeed"); + assert!(exit_result.ok); + let exit_metadata = exit_result + .metadata + .as_ref() + .expect("exitPlanMode metadata should exist"); + assert_eq!( + exit_metadata["schema"], + serde_json::json!("sessionPlanExitReviewPending") + ); + } + fn builtin_server_mode_catalog() -> Arc { let builtin_catalog = builtin_mode_catalog().expect("builtin catalog should build"); let builtin_mode_specs = builtin_catalog From a52bfbed23a96464a59e09c13ef48486d8b1d314 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 18:08:25 +0800 Subject: [PATCH 03/10] =?UTF-8?q?=E2=9C=85=20test(server,frontend):=20?= =?UTF-8?q?=E8=A1=A5=E5=85=85=20mode=20exit=E2=86=92reenter=20=E5=85=A8?= =?UTF-8?q?=E9=93=BE=E8=B7=AF=E6=B5=8B=E8=AF=95=EF=BC=8C=E6=B8=85=E7=90=86?= =?UTF-8?q?=E6=AD=BB=E4=BB=A3=E7=A0=81=EF=BC=8C=E9=87=8D=E6=9E=84=20sessio?= =?UTF-8?q?n=20=E5=88=B7=E6=96=B0=E9=80=89=E6=8B=A9=E9=80=BB=E8=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit crates/server/src/mcp/mod.rs - 删除未使用的 McpServerStatusView/McpServerStatusSummary/McpActionSummary/McpPort/McpService（消除 7 个 dead_code warning） crates/server/src/session_runtime_port_adapter.rs - 新增从 plan 模式 exit→code→reenter plan 的完整集成测试，覆盖 review-pending 两步退出和二次进入 frontend/src/hooks/app/useSessionCoordinator.ts - 将 session 刷新的目标选择逻辑提取为独立函数 resolveRefreshTargetSelection - 新增 pendingPreferredSessionIdRef 跟踪跨刷新周期待激活的 session，避免因异步竞态丢失用户选择 - 清理 activateSession/reset 时的 pending 状态 frontend/src/hooks/app/useSessionCoordinator.test.ts - 新增 resolveRefreshTargetSelection 单元测试（pending preferred 优先、保留 active subRun path） frontend/src/hooks/useAgent.ts - 为 JSON.parse 结果添加 unknown 类型注解（类型安全） frontend/src/lib/api/conversation.ts - 格式化长行（isApprovalLikeTurnText、buildTurnProjectionFlags 签名） frontend/src/components/Chat/*.test.tsx, frontend/src/lib/subRunView.test.ts - 清理尾部空行、格式化 path 字符串 --- crates/server/src/mcp/mod.rs | 195 +----------------- .../src/session_runtime_port_adapter.rs | 150 ++++++++++++++ .../src/components/Chat/SubRunBlock.test.tsx | 1 - .../src/components/Chat/TaskPanel.test.tsx | 3 +- frontend/src/components/Chat/TopBar.test.tsx | 3 +- .../hooks/app/useSessionCoordinator.test.ts | 33 +++ .../src/hooks/app/useSessionCoordinator.ts | 112 ++++++++-- frontend/src/hooks/useAgent.ts | 7 +- frontend/src/lib/api/conversation.ts | 10 +- frontend/src/lib/subRunView.test.ts | 1 - 10 files changed, 283 insertions(+), 232 deletions(-) create mode 100644 frontend/src/hooks/app/useSessionCoordinator.test.ts diff --git a/crates/server/src/mcp/mod.rs b/crates/server/src/mcp/mod.rs index c7db29d2..99faa260 100644 --- a/crates/server/src/mcp/mod.rs +++ b/crates/server/src/mcp/mod.rs @@ -6,14 +6,8 @@ //! - 配置管理（注册/移除/启禁用） //! - 重连服务器 //! -//! IO 和连接管理通过 `McpPort` 端口委托给 adapter 层。 -//! 传输协议细节（stdio/http/sse）不属于 application 层。 - -use std::sync::Arc; - -use async_trait::async_trait; - -use crate::ApplicationError; +//! 这里保留 HTTP 配置写路径共用的业务输入类型。运行时 MCP 管理端口和服务入口 +//! 位于 `server::mcp_service`，由 server 组合根直接接线到 adapter 层。 // ============================================================ // 业务模型 @@ -27,45 +21,6 @@ pub enum McpConfigScope { Local, } -/// MCP 服务器状态的业务视图。 -/// -/// 只包含业务关心的信息，不暴露连接协议细节。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct McpServerStatusView { - pub name: String, - pub scope: String, - pub enabled: bool, - pub state: String, - pub error: Option, - pub tool_count: usize, - pub prompt_count: usize, - pub resource_count: usize, - pub pending_approval: bool, - pub server_signature: String, -} - -/// MCP 服务器状态的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct McpServerStatusSummary { - pub name: String, - pub scope: String, - pub enabled: bool, - pub status: String, - pub error: Option, - pub tool_count: usize, - pub prompt_count: usize, - pub resource_count: usize, - pub pending_approval: bool, - pub server_signature: String, -} - -/// MCP 动作返回的共享摘要输入。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct McpActionSummary { - pub ok: bool, - pub message: Option, -} - /// 注册 MCP 服务器的业务输入。 /// /// 包含业务层面的配置信息（名称、超时等）， @@ -82,149 +37,3 @@ pub struct RegisterMcpServerInput { /// 用 `serde_json::Value` 避免在 application 层定义传输协议类型。 pub transport_config: serde_json::Value, } - -// ============================================================ -// MCP 用例端口 -// ============================================================ - -/// MCP 操作端口，由 adapter-mcp 实现。 -/// -/// 将 MCP 连接管理和协议细节从 application 层剥离。 -/// 方法为 async 以支持底层异步 I/O 操作（连接、握手、传输层管理）。 -#[async_trait] -pub trait McpPort: Send + Sync { - /// 列出所有 MCP 服务器状态。 - async fn list_server_status(&self) -> Vec; - /// 审批服务器连接。 - async fn approve_server(&self, server_signature: &str) -> Result<(), ApplicationError>; - /// 拒绝服务器连接。 - async fn reject_server(&self, server_signature: &str) -> Result<(), ApplicationError>; - /// 重新连接指定服务器。 - async fn reconnect_server(&self, name: &str) -> Result<(), ApplicationError>; - /// 重置项目级审批选择。 - async fn reset_project_choices(&self) -> Result<(), ApplicationError>; - /// 注册或更新 MCP 服务器配置。 - async fn upsert_server(&self, input: &RegisterMcpServerInput) -> Result<(), ApplicationError>; - /// 移除指定作用域和名称的 MCP 服务器配置。 - async fn remove_server( - &self, - scope: McpConfigScope, - name: &str, - ) -> Result<(), ApplicationError>; - /// 启用或禁用 MCP 服务器。 - async fn set_server_enabled( - &self, - scope: McpConfigScope, - name: &str, - enabled: bool, - ) -> Result<(), ApplicationError>; -} - -// ============================================================ -// MCP 用例服务 -// ============================================================ - -/// MCP 管理用例入口。 -/// -/// 所有方法都是业务操作，通过 `McpPort` 委托给适配器层。 -pub struct McpService { - port: Arc, -} - -impl McpService { - pub fn new(port: Arc) -> Self { - Self { port } - } - - /// 用例：查看所有 MCP 服务器状态。 - pub async fn list_status(&self) -> Vec { - self.port.list_server_status().await - } - - pub async fn list_status_summary(&self) -> Vec { - self.list_status() - .await - .into_iter() - .map(McpServerStatusSummary::from) - .collect() - } - - /// 用例：审批 MCP 服务器。 - pub async fn approve_server(&self, server_signature: &str) -> Result<(), ApplicationError> { - self.port.approve_server(server_signature).await - } - - /// 用例：拒绝 MCP 服务器。 - pub async fn reject_server(&self, server_signature: &str) -> Result<(), ApplicationError> { - self.port.reject_server(server_signature).await - } - - /// 用例：重新连接 MCP 服务器。 - pub async fn reconnect_server(&self, name: &str) -> Result<(), ApplicationError> { - self.port.reconnect_server(name).await - } - - /// 用例：重置项目级审批选择。 - pub async fn reset_project_choices(&self) -> Result<(), ApplicationError> { - self.port.reset_project_choices().await - } - - /// 用例：注册或更新 MCP 服务器。 - pub async fn upsert_config( - &self, - input: RegisterMcpServerInput, - ) -> Result<(), ApplicationError> { - self.port.upsert_server(&input).await - } - - /// 用例：移除 MCP 服务器配置。 - pub async fn remove_config( - &self, - scope: McpConfigScope, - name: &str, - ) -> Result<(), ApplicationError> { - self.port.remove_server(scope, name).await - } - - /// 用例：启用或禁用 MCP 服务器。 - pub async fn set_enabled( - &self, - scope: McpConfigScope, - name: &str, - enabled: bool, - ) -> Result<(), ApplicationError> { - self.port.set_server_enabled(scope, name, enabled).await - } -} - -impl McpActionSummary { - pub fn ok() -> Self { - Self { - ok: true, - message: None, - } - } -} - -impl From for McpServerStatusSummary { - fn from(value: McpServerStatusView) -> Self { - Self { - name: value.name, - scope: value.scope, - enabled: value.enabled, - status: value.state, - error: value.error, - tool_count: value.tool_count, - prompt_count: value.prompt_count, - resource_count: value.resource_count, - pending_approval: value.pending_approval, - server_signature: value.server_signature, - } - } -} - -impl std::fmt::Debug for McpService { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_struct("McpService").finish_non_exhaustive() - } -} diff --git a/crates/server/src/session_runtime_port_adapter.rs b/crates/server/src/session_runtime_port_adapter.rs index 129d6386..7ac64229 100644 --- a/crates/server/src/session_runtime_port_adapter.rs +++ b/crates/server/src/session_runtime_port_adapter.rs @@ -1517,6 +1517,156 @@ mod tests { ); } + #[tokio::test] + async fn router_tool_dispatcher_updates_mode_context_after_exit_plan_mode() { + let capability_router = CapabilityRouter::builder() + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(EnterPlanModeTool)) + .expect("enterPlanMode should register"), + ) as Arc) + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(UpsertSessionPlanTool)) + .expect("upsertSessionPlan should register"), + ) as Arc) + .register_invoker(Arc::new( + ToolCapabilityInvoker::new(Arc::new(ExitPlanModeTool)) + .expect("exitPlanMode should register"), + ) as Arc) + .build() + .expect("capability router should build"); + let (event_tx, mut event_rx) = tokio::sync::mpsc::unbounded_channel(); + let runtime_event_sink: Arc = + Arc::new(move |event: RuntimeTurnEvent| { + let _ = event_tx.send(event); + }); + let mode_catalog = builtin_server_mode_catalog(); + let plan_contract = mode_catalog + .bound_tool_contract_snapshot(&ModeId::plan()) + .expect("plan mode contract should exist"); + let mode_tool_state = RuntimeModeToolState::new(ModeId::plan(), Some(plan_contract)); + let temp = tempfile::tempdir().expect("tempdir should exist"); + let dispatcher = RouterToolDispatcher { + capability_router, + working_dir: temp.path().to_path_buf(), + cancel: CancelToken::new(), + agent: AgentEventContext::root_execution("agent-root", "default"), + mode_tool_state: mode_tool_state.clone(), + event_sink: Arc::new(RuntimeToolEventSink { + runtime_event_sink, + mode_catalog, + mode_tool_state, + }), + }; + + dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-upsert".to_string(), + name: "upsertSessionPlan".to_string(), + args: serde_json::json!({ + "title": "Cleanup crates", + "content": "# Plan: Cleanup crates\n\n## Context\n- current crates are inconsistent\n\n## Goal\n- align crate boundaries\n\n## Scope\n- runtime and adapter cleanup\n\n## Non-Goals\n- change transport protocol\n\n## Existing Code To Reuse\n- reuse current capability routing\n\n## Implementation Steps\n- audit crate dependencies\n- update the dispatcher context\n\n## Verification\n- run targeted Rust checks\n\n## Open Questions\n- none", + "status": "draft" + }), + }, + tool_output_sender: None, + }) + .await + .expect("upsertSessionPlan dispatch should succeed"); + + let review_result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-exit-review".to_string(), + name: "exitPlanMode".to_string(), + args: serde_json::json!({}), + }, + tool_output_sender: None, + }) + .await + .expect("first exitPlanMode dispatch should succeed"); + assert_eq!( + review_result + .metadata + .as_ref() + .expect("review metadata should exist")["schema"], + serde_json::json!("sessionPlanExitReviewPending") + ); + + let exit_result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-exit-final".to_string(), + name: "exitPlanMode".to_string(), + args: serde_json::json!({}), + }, + tool_output_sender: None, + }) + .await + .expect("second exitPlanMode dispatch should succeed"); + assert_eq!( + exit_result + .metadata + .as_ref() + .expect("exit metadata should exist")["schema"], + serde_json::json!("sessionPlanExit") + ); + let exit_event = event_rx.recv().await.expect("exit mode event should emit"); + assert!(matches!( + exit_event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + &event.payload, + StorageEventPayload::ModeChanged { from, to, .. } + if *from == ModeId::plan() && *to == ModeId::code() + ) + )); + + let reenter_result = dispatcher + .dispatch_tool(ToolDispatchRequest { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + agent_id: "agent-root".to_string(), + tool_call: ToolCallRequest { + id: "call-reenter".to_string(), + name: "enterPlanMode".to_string(), + args: serde_json::json!({ "reason": "revise again" }), + }, + tool_output_sender: None, + }) + .await + .expect("enterPlanMode dispatch should succeed after exit"); + assert_eq!( + reenter_result + .metadata + .as_ref() + .expect("reenter metadata should exist")["modeChanged"], + serde_json::json!(true) + ); + let reenter_event = event_rx + .recv() + .await + .expect("reenter mode event should emit"); + assert!(matches!( + reenter_event, + RuntimeTurnEvent::StorageEvent { event } + if matches!( + &event.payload, + StorageEventPayload::ModeChanged { from, to, .. } + if *from == ModeId::code() && *to == ModeId::plan() + ) + )); + } + fn builtin_server_mode_catalog() -> Arc { let builtin_catalog = builtin_mode_catalog().expect("builtin catalog should build"); let builtin_mode_specs = builtin_catalog diff --git a/frontend/src/components/Chat/SubRunBlock.test.tsx b/frontend/src/components/Chat/SubRunBlock.test.tsx index 850e7763..84a2f71f 100644 --- a/frontend/src/components/Chat/SubRunBlock.test.tsx +++ b/frontend/src/components/Chat/SubRunBlock.test.tsx @@ -551,4 +551,3 @@ describe('SubRunBlock result rendering', () => { expect(html).not.toContain('最终回复'); }); }); - diff --git a/frontend/src/components/Chat/TaskPanel.test.tsx b/frontend/src/components/Chat/TaskPanel.test.tsx index 9e23bbdb..3ecb9502 100644 --- a/frontend/src/components/Chat/TaskPanel.test.tsx +++ b/frontend/src/components/Chat/TaskPanel.test.tsx @@ -21,8 +21,7 @@ const contextValueWithTasks: ChatScreenContextValue = { currentModeId: 'plan', activePlan: { slug: 'cleanup-crates', - path: - 'D:/GitObjectsOwn/Astrcode/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md', + path: 'D:/GitObjectsOwn/Astrcode/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md', status: 'draft', title: 'Cleanup crates', }, diff --git a/frontend/src/components/Chat/TopBar.test.tsx b/frontend/src/components/Chat/TopBar.test.tsx index 0a75b848..1237c169 100644 --- a/frontend/src/components/Chat/TopBar.test.tsx +++ b/frontend/src/components/Chat/TopBar.test.tsx @@ -21,8 +21,7 @@ const baseContextValue: ChatScreenContextValue = { currentModeId: 'plan', activePlan: { slug: 'cleanup-crates', - path: - 'D:/GitObjectsOwn/Astrcode/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md', + path: 'D:/GitObjectsOwn/Astrcode/.astrcode/projects/demo/sessions/session-1/plan/cleanup-crates.md', status: 'awaiting_approval', title: 'Cleanup crates', }, diff --git a/frontend/src/hooks/app/useSessionCoordinator.test.ts b/frontend/src/hooks/app/useSessionCoordinator.test.ts new file mode 100644 index 00000000..85649414 --- /dev/null +++ b/frontend/src/hooks/app/useSessionCoordinator.test.ts @@ -0,0 +1,33 @@ +import { describe, expect, it } from 'vitest'; + +import { resolveRefreshTargetSelection } from './useSessionCoordinator'; + +describe('resolveRefreshTargetSelection', () => { + it('keeps a pending preferred session ahead of a later generic refresh', () => { + const selection = resolveRefreshTargetSelection({ + availableSessionIds: ['session-old', 'session-new'], + requestedPreferredSessionId: undefined, + pendingPreferredSessionId: 'session-new', + activeSessionId: 'session-old', + activeSubRunPath: ['subrun-old'], + fallbackSessionId: 'session-old', + }); + + expect(selection.nextSessionId).toBe('session-new'); + expect(selection.nextActiveSubRunPath).toEqual([]); + }); + + it('preserves the active sub-run path when no preferred session is pending', () => { + const selection = resolveRefreshTargetSelection({ + availableSessionIds: ['session-old', 'session-new'], + requestedPreferredSessionId: undefined, + pendingPreferredSessionId: null, + activeSessionId: 'session-old', + activeSubRunPath: ['subrun-old'], + fallbackSessionId: 'session-new', + }); + + expect(selection.nextSessionId).toBe('session-old'); + expect(selection.nextActiveSubRunPath).toEqual(['subrun-old']); + }); +}); diff --git a/frontend/src/hooks/app/useSessionCoordinator.ts b/frontend/src/hooks/app/useSessionCoordinator.ts index fb135f14..d5a464e4 100644 --- a/frontend/src/hooks/app/useSessionCoordinator.ts +++ b/frontend/src/hooks/app/useSessionCoordinator.ts @@ -1,4 +1,4 @@ -import { useCallback, useState, type Dispatch, type MutableRefObject } from 'react'; +import { useCallback, useRef, useState, type Dispatch, type MutableRefObject } from 'react'; import { ensureKnownProjects } from '../../lib/knownProjects'; import { groupSessionsByProject, replaceSessionMessages } from '../../store/utils'; import { findMatchingSessionId, normalizeSessionIdForCompare } from '../../lib/sessionId'; @@ -23,6 +23,65 @@ interface RefreshSessionsOptions { preferredSubRunPath?: string[]; } +interface RefreshTargetInput { + availableSessionIds: string[]; + requestedPreferredSessionId?: string | null; + pendingPreferredSessionId?: string | null; + activeSessionId?: string | null; + activeSubRunPath: string[]; + requestedSubRunPath?: string[]; + fallbackSessionId?: string | null; +} + +interface RefreshTargetSelection { + effectivePreferredSessionId: string | null; + matchedPreferredSessionId: string | null; + nextSessionId: string | null; + nextActiveSubRunPath: string[]; +} + +export function resolveRefreshTargetSelection({ + availableSessionIds, + requestedPreferredSessionId, + pendingPreferredSessionId, + activeSessionId, + activeSubRunPath, + requestedSubRunPath, + fallbackSessionId, +}: RefreshTargetInput): RefreshTargetSelection { + const effectivePreferredSessionId = + requestedPreferredSessionId ?? pendingPreferredSessionId ?? null; + const matchedPreferredSessionId = findMatchingSessionId( + availableSessionIds, + effectivePreferredSessionId + ); + const matchedActiveSessionId = findMatchingSessionId(availableSessionIds, activeSessionId); + const nextSessionId = + matchedPreferredSessionId ?? matchedActiveSessionId ?? fallbackSessionId ?? null; + const nextActiveSubRunPath = + nextSessionId !== null && + effectivePreferredSessionId !== null && + normalizeSessionIdForCompare(nextSessionId) === + normalizeSessionIdForCompare(effectivePreferredSessionId) + ? requestedPreferredSessionId + ? (requestedSubRunPath ?? []) + : [] + : nextSessionId !== null && + activeSessionId !== null && + activeSessionId !== undefined && + normalizeSessionIdForCompare(nextSessionId) === + normalizeSessionIdForCompare(activeSessionId) + ? activeSubRunPath + : []; + + return { + effectivePreferredSessionId, + matchedPreferredSessionId, + nextSessionId, + nextActiveSubRunPath, + }; +} + interface UseSessionCoordinatorOptions { dispatch: Dispatch; activeSessionIdRef: MutableRefObject; @@ -67,6 +126,7 @@ export function useSessionCoordinator({ durable: null, live: null, }); + const pendingPreferredSessionIdRef = useRef(null); const loadSessionBundle = useCallback( async (sessionId: string, subRunPath: string[]) => { @@ -92,6 +152,7 @@ export function useSessionCoordinator({ async (projectId: string, sessionId: string, subRunPath: string[] = []) => { const activationGeneration = ++sessionActivationGenerationRef.current; const previousSessionId = activeSessionIdRef.current; + pendingPreferredSessionIdRef.current = null; disconnectSession(); const loaded = await loadSessionBundle(sessionId, subRunPath); if (activationGeneration !== sessionActivationGenerationRef.current) { @@ -163,39 +224,38 @@ export function useSessionCoordinator({ async (options?: RefreshSessionsOptions) => { const activationGeneration = ++sessionActivationGenerationRef.current; const previousSessionId = activeSessionIdRef.current; + const requestedPreferredSessionId = options?.preferredSessionId; + if (requestedPreferredSessionId) { + pendingPreferredSessionIdRef.current = requestedPreferredSessionId; + } + const effectivePreferredSessionId = + requestedPreferredSessionId ?? pendingPreferredSessionIdRef.current; const sessionMetas = await listSessionsWithMeta(); const knownWorkingDirs = ensureKnownProjects(sessionMetas.map((meta) => meta.workingDir)); const availableSessionIds = sessionMetas.map((meta) => meta.sessionId); - const preferredSessionId = options?.preferredSessionId; - const matchedPreferredSessionId = findMatchingSessionId( + const preferredSessionIdForGrouping = findMatchingSessionId( availableSessionIds, - preferredSessionId + effectivePreferredSessionId ); - const matchedActiveSessionId = findMatchingSessionId( + const activeSessionIdForGrouping = findMatchingSessionId( availableSessionIds, activeSessionIdRef.current ); const projects = groupSessionsByProject(sessionMetas, knownWorkingDirs, { includeSessionIds: [ - ...(matchedPreferredSessionId ? [matchedPreferredSessionId] : []), - ...(matchedActiveSessionId ? [matchedActiveSessionId] : []), + ...(preferredSessionIdForGrouping ? [preferredSessionIdForGrouping] : []), + ...(activeSessionIdForGrouping ? [activeSessionIdForGrouping] : []), ], }); - const nextSessionId = - matchedPreferredSessionId ?? matchedActiveSessionId ?? projects[0]?.sessions[0]?.id ?? null; - const nextActiveSubRunPath = - nextSessionId !== null && - preferredSessionId !== null && - preferredSessionId !== undefined && - normalizeSessionIdForCompare(nextSessionId) === - normalizeSessionIdForCompare(preferredSessionId) - ? (options?.preferredSubRunPath ?? []) - : nextSessionId !== null && - activeSessionIdRef.current !== null && - normalizeSessionIdForCompare(nextSessionId) === - normalizeSessionIdForCompare(activeSessionIdRef.current) - ? activeSubRunPathRef.current - : []; + const { nextSessionId, nextActiveSubRunPath } = resolveRefreshTargetSelection({ + availableSessionIds, + requestedPreferredSessionId, + pendingPreferredSessionId: pendingPreferredSessionIdRef.current, + activeSessionId: activeSessionIdRef.current, + activeSubRunPath: activeSubRunPathRef.current, + requestedSubRunPath: options?.preferredSubRunPath, + fallbackSessionId: projects[0]?.sessions[0]?.id ?? null, + }); const nextProjectId = projects.find((project) => project.sessions.some((session) => session.id === nextSessionId)) ?.id ?? @@ -215,6 +275,13 @@ export function useSessionCoordinator({ loaded.messageTree ); activeSessionIdRef.current = nextSessionId; + if ( + pendingPreferredSessionIdRef.current && + normalizeSessionIdForCompare(nextSessionId) === + normalizeSessionIdForCompare(pendingPreferredSessionIdRef.current) + ) { + pendingPreferredSessionIdRef.current = null; + } phaseRef.current = loaded.phase; setActiveSubRunChildren({ subRuns: loaded.childSubRuns, @@ -264,6 +331,7 @@ export function useSessionCoordinator({ } activeSessionIdRef.current = null; + pendingPreferredSessionIdRef.current = null; phaseRef.current = 'idle'; setActiveSubRunChildren({ subRuns: [], diff --git a/frontend/src/hooks/useAgent.ts b/frontend/src/hooks/useAgent.ts index dd0afdb9..e607146f 100644 --- a/frontend/src/hooks/useAgent.ts +++ b/frontend/src/hooks/useAgent.ts @@ -77,7 +77,7 @@ export function processConversationStreamEnvelope( | { kind: 'rehydrate_required'; } { - const envelope = JSON.parse(payload); + const envelope: unknown = JSON.parse(payload); if (isRehydrateRequiredEnvelope(envelope)) { return { kind: 'rehydrate_required' }; } @@ -322,10 +322,7 @@ export function useAgent() { messageTreeRef.current ?? undefined ); if (result.kind === 'rehydrate_required') { - void recoverConversationProjection( - sessionId, - connectedSessionFilterRef.current - ); + void recoverConversationProjection(sessionId, connectedSessionFilterRef.current); return; } const projection = result.projection; diff --git a/frontend/src/lib/api/conversation.ts b/frontend/src/lib/api/conversation.ts index 2a58d0b6..a405d4cf 100644 --- a/frontend/src/lib/api/conversation.ts +++ b/frontend/src/lib/api/conversation.ts @@ -445,11 +445,7 @@ function normalizeSnapshotState(payload: unknown): ConversationSnapshotState { } function isApprovalLikeTurnText(text: string): boolean { - const normalizedEnglish = text - .toLowerCase() - .split(/\s+/) - .filter(Boolean) - .join(' '); + const normalizedEnglish = text.toLowerCase().split(/\s+/).filter(Boolean).join(' '); for (const phrase of ['approved', 'go ahead', 'implement it']) { if ( normalizedEnglish === phrase || @@ -475,7 +471,9 @@ function isApprovalLikeTurnText(text: string): boolean { return false; } -function buildTurnProjectionFlags(state: ConversationSnapshotState): Map { +function buildTurnProjectionFlags( + state: ConversationSnapshotState +): Map { const flags = new Map(); const turnFacts = new Map< string, diff --git a/frontend/src/lib/subRunView.test.ts b/frontend/src/lib/subRunView.test.ts index a821cca5..64ef3826 100644 --- a/frontend/src/lib/subRunView.test.ts +++ b/frontend/src/lib/subRunView.test.ts @@ -1536,4 +1536,3 @@ describe('buildSubRunView', () => { expect(patchSubRunThreadTreeMessages(tree, nextMessages)).toBeNull(); }); }); - From d9979f63b4375f9300c54865e5505d6ca347803e Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 18:32:58 +0800 Subject: [PATCH 04/10] =?UTF-8?q?refactor(server):=20=E6=B8=85=E7=90=86?= =?UTF-8?q?=E6=9C=AA=E4=BD=BF=E7=94=A8=E6=8E=A5=E5=8F=A3=E4=B8=8E=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=E5=86=97=E4=BD=99=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将运行时和治理链路中与死代码、仅测试入口相关的 `allow(dead_code)` 与未使用辅助实现下调为测试范围或移除， 同步删除 `composer_skill` 端口定义文件并清理不再需要的治理面诊断/校验方法，保持主行为接口更小更清晰。 Constraint: 仅进行行为等价前提下的清理，不引入新依赖或 API 改造 Rejected: 保留陈旧未用项 | 会持续放大误报与后续维护负担 Confidence: high Scope-risk: narrow Tested: cargo check -p astrcode-server --all-features Not-tested: 未做完整端到端回归和 UI 手工回归 --- crates/adapter-mcp/src/manager/mod.rs | 1 - crates/adapter-mcp/src/manager/reconnect.rs | 4 +- crates/server/src/agent/test_support.rs | 52 +++---------------- crates/server/src/bootstrap/runtime.rs | 10 ++-- .../src/bootstrap/runtime_coordinator.rs | 11 +--- crates/server/src/capability_router.rs | 2 +- crates/server/src/config/env_resolver.rs | 6 --- crates/server/src/config/mod.rs | 18 ------- crates/server/src/config/selection.rs | 23 +------- crates/server/src/execution/profiles.rs | 2 +- .../src/governance_surface/assembler.rs | 33 +----------- crates/server/src/governance_surface/mod.rs | 30 +---------- crates/server/src/governance_surface/tests.rs | 26 ++-------- crates/server/src/lifecycle/governance.rs | 14 ----- crates/server/src/main.rs | 4 +- crates/server/src/ports/composer_skill.rs | 25 --------- crates/server/src/ports/session_bridge.rs | 2 + crates/server/src/tests/test_support.rs | 1 - src-tauri/src/desktop_frontend_mode.rs | 4 -- 19 files changed, 23 insertions(+), 245 deletions(-) delete mode 100644 crates/server/src/ports/composer_skill.rs diff --git a/crates/adapter-mcp/src/manager/mod.rs b/crates/adapter-mcp/src/manager/mod.rs index e1ce88ff..cc95dfd3 100644 --- a/crates/adapter-mcp/src/manager/mod.rs +++ b/crates/adapter-mcp/src/manager/mod.rs @@ -47,7 +47,6 @@ pub struct McpReloadSnapshot { } /// 单个服务器的完整管理信息。 -#[allow(dead_code)] pub(crate) struct McpManagedConnection { /// 连接状态机。 pub(crate) connection: McpConnection, diff --git a/crates/adapter-mcp/src/manager/reconnect.rs b/crates/adapter-mcp/src/manager/reconnect.rs index 7bc71cff..9d3f23a1 100644 --- a/crates/adapter-mcp/src/manager/reconnect.rs +++ b/crates/adapter-mcp/src/manager/reconnect.rs @@ -103,7 +103,7 @@ impl McpReconnectManager { } /// 指定服务器是否有活跃的重连任务。 - #[allow(dead_code)] + #[cfg(test)] pub fn is_reconnecting(&self, server_name: &str) -> bool { let tasks = self.tasks_guard(); tasks @@ -113,7 +113,7 @@ impl McpReconnectManager { } /// 清理已完成的重连任务。 - #[allow(dead_code)] + #[cfg(test)] pub fn cleanup_finished(&self) { let mut tasks = self.tasks_guard(); tasks.retain(|_, h| !h.is_finished()); diff --git a/crates/server/src/agent/test_support.rs b/crates/server/src/agent/test_support.rs index 9bd5561b..178b7c03 100644 --- a/crates/server/src/agent/test_support.rs +++ b/crates/server/src/agent/test_support.rs @@ -9,14 +9,11 @@ use std::{ sync::{Arc, Mutex}, }; -use astrcode_agent_runtime::{ - LlmEvent, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, -}; +use astrcode_agent_runtime::{LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits}; use astrcode_core::{ AgentLifecycleStatus, AgentMode, AgentProfile, AstrError, Config, ConfigOverlay, - DeleteProjectResult, Phase, ReasoningContent, Result, SessionId, SessionMeta, - SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StorageEvent, StoredEvent, - SubRunStorageMode, + DeleteProjectResult, Phase, Result, SessionId, SessionMeta, SessionTurnAcquireResult, + SessionTurnBusy, SessionTurnLease, StorageEvent, StoredEvent, SubRunStorageMode, ports::{ConfigStore, McpConfigFileScope}, }; use astrcode_host_session::{ @@ -396,19 +393,8 @@ impl Drop for AgentTestEnvGuard { #[derive(Debug, Clone)] pub(crate) enum TestLlmBehavior { - Succeed { - content: String, - }, - #[allow(dead_code)] - Stream { - reasoning_chunks: Vec, - text_chunks: Vec, - final_content: String, - final_reasoning: Option, - }, - Fail { - message: String, - }, + Succeed { content: String }, + Fail { message: String }, } #[derive(Debug)] @@ -427,7 +413,7 @@ impl LlmProvider for TestLlmProvider { async fn generate( &self, _request: LlmRequest, - sink: Option, + _sink: Option, ) -> Result { match &self.behavior { TestLlmBehavior::Succeed { content } => Ok(LlmOutput { @@ -438,32 +424,6 @@ impl LlmProvider for TestLlmProvider { finish_reason: LlmFinishReason::Stop, prompt_cache_diagnostics: None, }), - TestLlmBehavior::Stream { - reasoning_chunks, - text_chunks, - final_content, - final_reasoning, - } => { - if let Some(sink) = sink { - for chunk in reasoning_chunks { - sink(LlmEvent::ThinkingDelta(chunk.clone())); - } - for chunk in text_chunks { - sink(LlmEvent::TextDelta(chunk.clone())); - } - } - Ok(LlmOutput { - content: final_content.clone(), - tool_calls: Vec::new(), - reasoning: final_reasoning.clone().map(|content| ReasoningContent { - content, - signature: None, - }), - usage: None, - finish_reason: LlmFinishReason::Stop, - prompt_cache_diagnostics: None, - }) - }, TestLlmBehavior::Fail { message } => { Err(AstrError::Internal(format!("test llm failure: {message}"))) }, diff --git a/crates/server/src/bootstrap/runtime.rs b/crates/server/src/bootstrap/runtime.rs index e12582d6..876594f0 100644 --- a/crates/server/src/bootstrap/runtime.rs +++ b/crates/server/src/bootstrap/runtime.rs @@ -12,7 +12,7 @@ use std::{ use astrcode_adapter_storage::session::FileSystemSessionRepository; use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; use astrcode_core::SkillCatalog; -use astrcode_host_session::{CollaborationExecutor, EventStore, SessionCatalog, SubAgentExecutor}; +use astrcode_host_session::{EventStore, SessionCatalog, SubAgentExecutor}; use astrcode_plugin_host::{ CommandDescriptor, PluginActiveSnapshot, PluginDescriptor, PluginRegistry, ProviderContributionCatalog, ResourceCatalog, builtin_collaboration_tools_descriptor, @@ -68,8 +68,6 @@ pub struct ServerRuntime { pub session_catalog: Arc, pub profiles: Arc, pub subagent_executor: Arc, - #[allow(dead_code)] - pub collaboration_executor: Arc, pub mcp_service: Arc, pub skill_catalog: Arc, pub resource_catalog: Arc>, @@ -81,8 +79,7 @@ pub struct ServerRuntime { pub struct ServerRuntimeHandles { // Why: server 集成测试需要直接操纵底层 session-runtime，避免把原始状态访问重新暴露给 // application 端口；生产路径只把它当作资源守卫持有。 - #[allow(dead_code)] - pub(crate) session_runtime_guard: Arc, + pub(crate) _session_runtime_guard: Arc, #[cfg(test)] pub(crate) session_runtime_test_support: Arc, @@ -354,14 +351,13 @@ pub async fn bootstrap_server_runtime_with_options( session_catalog, profiles, subagent_executor: agent_runtime.subagent_executor, - collaboration_executor: agent_runtime.collaboration_executor, mcp_service, skill_catalog: skill_catalog_bridge, resource_catalog: Arc::clone(&plugin_resource_catalog_state), mode_catalog, governance, handles: Arc::new(ServerRuntimeHandles { - session_runtime_guard: session_runtime.keepalive, + _session_runtime_guard: session_runtime.keepalive, #[cfg(test)] session_runtime_test_support: session_runtime.test_support, _profile_watch_runtime: profile_watch_runtime, diff --git a/crates/server/src/bootstrap/runtime_coordinator.rs b/crates/server/src/bootstrap/runtime_coordinator.rs index 64a3ece2..bfe9c93a 100644 --- a/crates/server/src/bootstrap/runtime_coordinator.rs +++ b/crates/server/src/bootstrap/runtime_coordinator.rs @@ -43,7 +43,7 @@ impl RuntimeCoordinator { } } - #[cfg_attr(not(test), allow(dead_code))] + #[cfg(test)] pub(crate) fn with_managed_components( self, managed_components: Vec>, @@ -72,15 +72,6 @@ impl RuntimeCoordinator { ) } - #[allow(dead_code)] - pub(crate) fn managed_components(&self) -> Vec> { - support::with_read_lock_recovery( - &self.managed_components, - "runtime coordinator managed components", - Clone::clone, - ) - } - pub(crate) fn replace_runtime_surface( &self, plugin_entries: Vec, diff --git a/crates/server/src/capability_router.rs b/crates/server/src/capability_router.rs index bc621667..85ecdfd1 100644 --- a/crates/server/src/capability_router.rs +++ b/crates/server/src/capability_router.rs @@ -68,7 +68,7 @@ impl CapabilityRouterBuilder { } } - #[allow(dead_code)] + #[cfg(test)] pub(crate) fn register_invoker(mut self, invoker: Arc) -> Self { self.invokers.push(invoker); self diff --git a/crates/server/src/config/env_resolver.rs b/crates/server/src/config/env_resolver.rs index 84b0b221..fd05836c 100644 --- a/crates/server/src/config/env_resolver.rs +++ b/crates/server/src/config/env_resolver.rs @@ -74,12 +74,6 @@ pub fn resolve_env_value(raw: &str) -> Result { } } -/// 构建序列化的 `env:` 引用字符串。 -#[allow(dead_code)] -pub fn env_reference(env_name: &str) -> String { - format!("{ENV_REFERENCE_PREFIX}{env_name}") -} - /// 判断值是否看起来像环境变量名（大写字母+数字+下划线，至少含一个下划线）。 pub fn is_env_var_name(value: &str) -> bool { value diff --git a/crates/server/src/config/mod.rs b/crates/server/src/config/mod.rs index 97f3b4e5..53176a35 100644 --- a/crates/server/src/config/mod.rs +++ b/crates/server/src/config/mod.rs @@ -166,24 +166,6 @@ impl ConfigService { )), }) } - - /// 解析指定 profile 的 API key。 - #[cfg(test)] - #[allow(dead_code)] - pub fn resolve_api_key_for_profile( - &self, - profile_name: &str, - ) -> Result { - let config = self.config.blocking_read(); - let profile = config - .profiles - .iter() - .find(|p| p.name == profile_name) - .ok_or_else(|| { - ApplicationError::NotFound(format!("profile '{}' not found", profile_name)) - })?; - api_key::resolve_api_key(profile).map_err(|e| ApplicationError::Internal(e.to_string())) - } } /// 生成配置摘要输入，供协议层投影复用。 diff --git a/crates/server/src/config/selection.rs b/crates/server/src/config/selection.rs index a6219539..8075e7f9 100644 --- a/crates/server/src/config/selection.rs +++ b/crates/server/src/config/selection.rs @@ -8,7 +8,7 @@ use astrcode_core::{ActiveSelection, Profile}; #[cfg(test)] -use astrcode_core::{Config, CurrentModelSelection, ModelConfig, ModelOption, ModelSelection}; +use astrcode_core::{Config, CurrentModelSelection, ModelOption, ModelSelection}; use crate::ApplicationError; @@ -87,27 +87,6 @@ pub fn resolve_current_model(config: &Config) -> Result( - profile: &'a Profile, - active_model: &str, -) -> Result, ApplicationError> { - if profile.models.is_empty() { - return Err(ApplicationError::InvalidArgument(format!( - "profile '{}' has no models", - profile.name - ))); - } - - Ok(profile - .models - .iter() - .find(|m| m.id == active_model) - .or_else(|| profile.models.first())) -} - fn first_model_id(profile: &Profile) -> Result<&str, ApplicationError> { profile .models diff --git a/crates/server/src/execution/profiles.rs b/crates/server/src/execution/profiles.rs index 3e8593c2..af86e4d0 100644 --- a/crates/server/src/execution/profiles.rs +++ b/crates/server/src/execution/profiles.rs @@ -114,7 +114,7 @@ impl ProfileResolutionService { } /// 按 profile ID 查找全局 profile。 - #[allow(dead_code)] + #[cfg(test)] pub fn find_global_profile(&self, profile_id: &str) -> Result { let profiles = self.resolve_global()?; profiles diff --git a/crates/server/src/governance_surface/assembler.rs b/crates/server/src/governance_surface/assembler.rs index 11e0a06d..b946fc95 100644 --- a/crates/server/src/governance_surface/assembler.rs +++ b/crates/server/src/governance_surface/assembler.rs @@ -95,7 +95,7 @@ impl GovernanceSurfaceAssembler { runtime.agent.max_subrun_depth, runtime.agent.max_spawn_per_turn, )); - let busy_policy = super::policy::resolve_busy_policy( + let _busy_policy = super::policy::resolve_busy_policy( compiled.envelope.submit_busy_policy, requested_busy_policy, ); @@ -121,8 +121,6 @@ impl GovernanceSurfaceAssembler { &compiled.envelope, ), governance_revision: super::GOVERNANCE_POLICY_REVISION.to_string(), - busy_policy, - diagnostics: compiled.envelope.diagnostics.clone(), }; surface.validate()?; Ok(surface) @@ -233,35 +231,6 @@ impl GovernanceSurfaceAssembler { )), }) } - - #[allow(dead_code)] - pub fn tool_collaboration_context( - &self, - runtime: ResolvedRuntimeConfig, - session_id: String, - turn_id: String, - parent_agent_id: Option, - source_tool_call_id: Option, - mode_id: astrcode_core::ModeId, - ) -> super::ToolCollaborationGovernanceContext { - super::ToolCollaborationGovernanceContext::new( - super::ToolCollaborationGovernanceContextInput { - runtime: runtime.clone(), - session_id, - turn_id, - parent_agent_id, - source_tool_call_id, - policy: super::collaboration_policy_context(&runtime), - governance_revision: super::GOVERNANCE_POLICY_REVISION.to_string(), - mode_id, - }, - ) - } - - #[allow(dead_code)] - pub fn mode_catalog(&self) -> &ModeCatalog { - &self.mode_catalog - } } impl Default for GovernanceSurfaceAssembler { diff --git a/crates/server/src/governance_surface/mod.rs b/crates/server/src/governance_surface/mod.rs index 642b9770..b5506cd4 100644 --- a/crates/server/src/governance_surface/mod.rs +++ b/crates/server/src/governance_surface/mod.rs @@ -29,9 +29,7 @@ pub(crate) use inherited::resolve_inherited_parent_messages; #[cfg(test)] pub(crate) use inherited::{build_inherited_messages, select_inherited_recent_tail}; pub use policy::{ - GOVERNANCE_APPROVAL_MODE_INHERIT, GOVERNANCE_POLICY_REVISION, - ToolCollaborationGovernanceContext, ToolCollaborationGovernanceContextInput, - collaboration_policy_context, + GOVERNANCE_APPROVAL_MODE_INHERIT, GOVERNANCE_POLICY_REVISION, collaboration_policy_context, }; pub use prompt::{ build_delegation_metadata, build_fresh_child_contract, build_resumed_child_contract, @@ -77,10 +75,6 @@ pub struct ResolvedGovernanceSurface { pub collaboration_policy: AgentCollaborationPolicyContext, pub approval: GovernanceApprovalPipeline, pub governance_revision: String, - #[allow(dead_code)] - pub busy_policy: GovernanceBusyPolicy, - #[allow(dead_code)] - pub diagnostics: Vec, } impl ResolvedGovernanceSurface { @@ -134,28 +128,6 @@ impl ResolvedGovernanceSurface { prompt_governance: Some(prompt_governance), } } - - #[allow(dead_code)] - pub async fn check_model_request( - &self, - engine: &dyn astrcode_core::PolicyEngine, - request: astrcode_core::ModelRequest, - ) -> astrcode_core::Result { - engine - .check_model_request(request, &self.policy_context) - .await - } - - #[allow(dead_code)] - pub async fn check_capability_call( - &self, - engine: &dyn astrcode_core::PolicyEngine, - call: CapabilityCall, - ) -> astrcode_core::Result> { - engine - .check_capability_call(call, &self.policy_context) - .await - } } struct BuildSurfaceInput { diff --git a/crates/server/src/governance_surface/tests.rs b/crates/server/src/governance_surface/tests.rs index a6a9244a..b2700c60 100644 --- a/crates/server/src/governance_surface/tests.rs +++ b/crates/server/src/governance_surface/tests.rs @@ -7,9 +7,8 @@ //! - 各种 capability selector（all / subset / none / union / difference）的编译结果 use astrcode_core::{ - AllowAllPolicyEngine, ApprovalDefault, BoundModeToolContractSnapshot, CapabilityKind, - CapabilitySpec, LlmMessage, ModeId, ModelRequest, ResolvedExecutionLimitsSnapshot, - ResolvedRuntimeConfig, UserMessageOrigin, + ApprovalDefault, BoundModeToolContractSnapshot, CapabilityKind, CapabilitySpec, LlmMessage, + ModeId, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, UserMessageOrigin, }; use serde_json::{Value, json}; @@ -102,23 +101,7 @@ async fn surface_policy_pipeline_defaults_to_allow_all() { }), }, governance_revision: GOVERNANCE_POLICY_REVISION.to_string(), - busy_policy: GovernanceBusyPolicy::BranchOnBusy, - diagnostics: Vec::new(), }; - let request = ModelRequest { - messages: vec![LlmMessage::User { - content: "hello".to_string(), - origin: UserMessageOrigin::User, - }], - tools: Vec::new(), - system_prompt: Some("system".to_string()), - system_prompt_blocks: Vec::new(), - }; - let checked = surface - .check_model_request(&AllowAllPolicyEngine, request) - .await - .expect("request should pass"); - assert_eq!(checked.system_prompt.as_deref(), Some("system")); assert!(surface.approval.pending.is_some()); } @@ -157,7 +140,7 @@ fn inherited_messages_follow_compact_and_tail_policy() { #[test] fn root_surface_applies_execution_control_without_special_case_logic() { let assembler = GovernanceSurfaceAssembler::default(); - let surface = assembler + let _surface = assembler .root_surface(RootGovernanceInput { session_id: "session-1".to_string(), turn_id: "turn-1".to_string(), @@ -170,8 +153,6 @@ fn root_surface_applies_execution_control_without_special_case_logic() { }), }) .expect("surface should build"); - - assert_eq!(surface.busy_policy, GovernanceBusyPolicy::BranchOnBusy); } #[tokio::test] @@ -223,7 +204,6 @@ fn resumed_child_surface_reuses_existing_limits_and_contract_source() { }) .expect("surface should build"); assert_eq!(surface.resolved_limits, limits); - assert_eq!(surface.busy_policy, GovernanceBusyPolicy::RejectOnBusy); assert!( surface .prompt_declarations diff --git a/crates/server/src/lifecycle/governance.rs b/crates/server/src/lifecycle/governance.rs index 16a965a3..08f45398 100644 --- a/crates/server/src/lifecycle/governance.rs +++ b/crates/server/src/lifecycle/governance.rs @@ -124,15 +124,6 @@ impl AppGovernance { } } - /// 获取当前纯 observability 快照。 - /// - /// 为什么单独暴露：debug-only 治理读取面只关心指标本身， - /// 不需要重新拼完整 runtime status，也不应强依赖 plugin search path 等外围信息。 - #[allow(dead_code)] - pub fn observability_snapshot(&self) -> RuntimeObservabilitySnapshot { - self.observability.snapshot() - } - /// 重载运行时能力面。 /// /// 需要在构造时通过 `with_reloader` 设置重载策略， @@ -174,11 +165,6 @@ impl AppGovernance { pub fn runtime(&self) -> &Arc { &self.runtime } - - #[allow(dead_code)] - pub fn task_registry(&self) -> &Arc { - &self.task_registry - } } impl std::fmt::Debug for AppGovernance { diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index 948292be..6d0ff1f2 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -181,21 +181,19 @@ pub(crate) const AUTH_HEADER_NAME: &str = "x-astrcode-token"; /// 包含运行时入口、server 侧 owner bridge、治理模型、认证管理器和前端构建产物。 /// 所有字段均为 `Arc` 或可 `Clone` 类型，支持多线程共享。 #[derive(Clone)] +#[allow(dead_code)] pub(crate) struct AppState { /// server-owned agent route bridge；agent routes 不再经由 `application::agent` 用例入口。 agent_api: Arc, /// server-owned agent control bridge；测试和路由不直接暴露底层 kernel。 - #[allow(dead_code)] agent_control: Arc, /// server-owned 配置服务桥接；配置/模型 API 不再经由 App 访问配置。 config: Arc, /// server-owned 会话目录桥接；catalog API 不再经由 App 访问 session catalog。 session_catalog: Arc, /// server-owned profile resolver；watch/profile 测试不再经由 `App::profiles()`. - #[allow(dead_code)] profiles: Arc, /// subagent 启动桥接；测试直接消费 host-session 合同。 - #[allow(dead_code)] subagent_executor: Arc, /// server-owned MCP service；MCP API 不再经由 App facade。 mcp_service: Arc, diff --git a/crates/server/src/ports/composer_skill.rs b/crates/server/src/ports/composer_skill.rs deleted file mode 100644 index 82c0b9ab..00000000 --- a/crates/server/src/ports/composer_skill.rs +++ /dev/null @@ -1,25 +0,0 @@ -//! Composer 输入补全的 skill 查询端口。 -//! -//! 定义 `ComposerSkillPort` trait 和 `ComposerResolvedSkill` 类型， -//! 将 composer 输入补全与 adapter-skills 的实现细节解耦。 -//! 应用层不应直接依赖 `adapter-skills`，而是通过此端口获取当前会话可见的 skill 信息。 - -use std::path::Path; - -use crate::ComposerSkillSummary; - -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ComposerResolvedSkill { - pub id: String, - pub description: String, - pub guide: String, -} - -/// `App` 依赖的 skill 补全端口。 -/// -/// Why: composer 输入补全需要看到当前会话可见的 skill， -/// 但应用层不应直接依赖 `adapter-skills` 的实现细节。 -pub trait ComposerSkillPort: Send + Sync { - fn list_skill_summaries(&self, working_dir: &Path) -> Vec; - fn resolve_skill(&self, working_dir: &Path, skill_id: &str) -> Option; -} diff --git a/crates/server/src/ports/session_bridge.rs b/crates/server/src/ports/session_bridge.rs index 5a242e3a..97f704fb 100644 --- a/crates/server/src/ports/session_bridge.rs +++ b/crates/server/src/ports/session_bridge.rs @@ -51,6 +51,7 @@ impl ServerSessionBridge { SessionId::from(normalize_external_session_id(session_id)) } + #[allow(dead_code)] async fn replay_history( &self, session_id: &SessionId, @@ -65,6 +66,7 @@ impl ServerSessionBridge { Ok(replay_records(&stored, last_event_id)) } + #[allow(dead_code)] async fn session_phase( &self, session_id: &SessionId, diff --git a/crates/server/src/tests/test_support.rs b/crates/server/src/tests/test_support.rs index d54862bc..ef29ccdc 100644 --- a/crates/server/src/tests/test_support.rs +++ b/crates/server/src/tests/test_support.rs @@ -192,7 +192,6 @@ pub(crate) struct RecordedModeSwitch { } #[derive(Debug)] -#[allow(dead_code)] pub(crate) struct StubSessionPort { pub(crate) stored_events: Vec, pub(crate) working_dir: Option, diff --git a/src-tauri/src/desktop_frontend_mode.rs b/src-tauri/src/desktop_frontend_mode.rs index 411636ce..326277b6 100644 --- a/src-tauri/src/desktop_frontend_mode.rs +++ b/src-tauri/src/desktop_frontend_mode.rs @@ -20,7 +20,6 @@ impl DesktopFrontendMode { } } - #[cfg_attr(not(test), allow(dead_code))] pub fn parse(mode: &str) -> Result { match mode { "tauri-dev-cli" => Ok(Self::TauriDevCli), @@ -30,7 +29,6 @@ impl DesktopFrontendMode { } } - #[cfg_attr(not(test), allow(dead_code))] pub fn resolve(tauri_cli_invoked: bool, tauri_is_dev: bool) -> Self { match (tauri_cli_invoked, tauri_is_dev) { (true, true) => Self::TauriDevCli, @@ -40,12 +38,10 @@ impl DesktopFrontendMode { } } -#[cfg_attr(not(test), allow(dead_code))] pub fn tauri_cli_invoked_from_env() -> bool { std::env::var_os(TAURI_CLI_VERBOSITY_ENV).is_some() } -#[cfg_attr(not(test), allow(dead_code))] pub fn tauri_is_dev_from_env() -> bool { matches!( std::env::var(DEP_TAURI_DEV_ENV).as_deref(), From 9adad8e75034a2768d4d47daead7fbdd8c99dca9 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 22:12:55 +0800 Subject: [PATCH 05/10] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20?= =?UTF-8?q?=E6=8F=90=E5=8F=96=20contract=20=E5=B1=82=E4=B8=8E=20context-wi?= =?UTF-8?q?ndow=20crate=EF=BC=8C=E5=AE=8C=E6=88=90=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E8=BE=B9=E7=95=8C=E6=94=B6=E6=95=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从 core 中拆出 5 个窄领域契约 crate（prompt-contract、governance-contract、 tool-contract、llm-contract、runtime-contract），从 agent-runtime 中拆出 context-window crate。core 只保留稳定值对象和事件模型，不再承载工具/LLM/ 治理/运行时边界 trait。所有 adapter、owner、server 调用点已迁移至新 crate 导入路径，core 旧 re-export 标记为 #[doc(hidden)] 以引导新代码使用契约层。 同时新增 HTTP 插件 backend 支持，更新 crate 边界检查规则与架构文档。 --- CODE_REVIEW_ISSUES.md | 94 -- Cargo.lock | 102 ++- Cargo.toml | 6 + PROJECT_ARCHITECTURE.md | 457 +++++++--- crates/adapter-llm/Cargo.toml | 4 +- crates/adapter-llm/src/cache_tracker.rs | 2 +- crates/adapter-llm/src/lib.rs | 4 +- crates/adapter-llm/src/openai.rs | 22 +- crates/adapter-llm/src/openai/dto.rs | 2 +- crates/adapter-llm/src/openai/responses.rs | 4 +- crates/adapter-mcp/Cargo.toml | 3 +- .../adapter-mcp/src/bridge/prompt_bridge.rs | 11 +- crates/adapter-mcp/src/manager/mod.rs | 7 +- crates/adapter-mcp/src/manager/surface.rs | 2 +- crates/adapter-prompt/Cargo.toml | 4 +- crates/adapter-prompt/src/block.rs | 2 +- crates/adapter-prompt/src/composer.rs | 2 +- crates/adapter-prompt/src/contribution.rs | 2 +- .../src/contributors/capability_prompt.rs | 8 +- crates/adapter-prompt/src/core_port.rs | 15 +- crates/adapter-prompt/src/layered_builder.rs | 2 +- crates/adapter-prompt/src/plan.rs | 3 +- .../adapter-prompt/src/prompt_declaration.rs | 102 +-- .../adapter-storage/src/session/repository.rs | 4 +- crates/adapter-tools/Cargo.toml | 2 + .../src/agent_tools/close_tool.rs | 7 +- .../src/agent_tools/collab_result_mapping.rs | 5 +- .../src/agent_tools/observe_tool.rs | 7 +- .../src/agent_tools/result_mapping.rs | 3 +- .../src/agent_tools/send_tool.rs | 7 +- .../src/agent_tools/spawn_tool.rs | 9 +- crates/adapter-tools/src/agent_tools/tests.rs | 4 +- .../src/builtin_tools/apply_patch.rs | 7 +- .../src/builtin_tools/edit_file.rs | 7 +- .../src/builtin_tools/enter_plan_mode.rs | 14 +- .../src/builtin_tools/exit_plan_mode.rs | 20 +- .../src/builtin_tools/find_files.rs | 9 +- .../src/builtin_tools/fs_common.rs | 5 +- .../adapter-tools/src/builtin_tools/grep.rs | 7 +- .../src/builtin_tools/list_dir.rs | 7 +- crates/adapter-tools/src/builtin_tools/mod.rs | 2 +- .../src/builtin_tools/mode_transition.rs | 10 +- .../src/builtin_tools/read_file.rs | 9 +- .../src/builtin_tools/session_plan.rs | 4 +- .../adapter-tools/src/builtin_tools/shell.rs | 11 +- .../src/builtin_tools/skill_tool.rs | 10 +- .../src/builtin_tools/task_write.rs | 7 +- .../src/builtin_tools/tool_search.rs | 10 +- .../src/builtin_tools/upsert_session_plan.rs | 16 +- .../src/builtin_tools/write_file.rs | 7 +- crates/adapter-tools/src/lib.rs | 2 +- crates/adapter-tools/src/test_support.rs | 3 +- crates/agent-runtime/Cargo.toml | 5 + .../agent-runtime/src/context_window/mod.rs | 18 +- .../src/context_window/request.rs | 71 +- crates/agent-runtime/src/lib.rs | 16 +- crates/agent-runtime/src/loop.rs | 49 +- crates/agent-runtime/src/runtime.rs | 3 +- crates/agent-runtime/src/tool_dispatch.rs | 3 +- crates/agent-runtime/src/types.rs | 185 +--- crates/context-window/Cargo.toml | 19 + crates/context-window/src/compaction.rs | 615 +++++++++++++ .../context-window/src/compaction/protocol.rs | 253 ++++++ .../context-window/src/compaction/sanitize.rs | 243 ++++++ .../src/compaction/xml_parsing.rs | 236 +++++ crates/context-window/src/file_access.rs | 238 +++++ crates/context-window/src/lib.rs | 10 + crates/context-window/src/micro_compact.rs | 187 ++++ crates/context-window/src/mod.rs | 17 + crates/context-window/src/prune_pass.rs | 100 +++ crates/context-window/src/request.rs | 277 ++++++ crates/context-window/src/settings.rs | 67 ++ .../src/templates/compact/base.md | 113 +++ .../src/templates/compact/incremental.md | 11 + crates/context-window/src/token_usage.rs | 142 +++ .../context-window/src/tool_result_budget.rs | 373 ++++++++ crates/context-window/src/tool_results.rs | 16 + crates/core/src/agent/collaboration.rs | 3 +- crates/core/src/config.rs | 12 +- crates/core/src/event/domain.rs | 3 +- crates/core/src/event/mod.rs | 2 - crates/core/src/event/types.rs | 7 +- crates/core/src/home.rs | 39 - crates/core/src/hook.rs | 5 +- crates/core/src/lib.rs | 135 +-- crates/core/src/mode/mod.rs | 28 +- crates/core/src/policy/engine.rs | 398 +-------- crates/core/src/policy/mod.rs | 17 +- crates/core/src/prompt.rs | 38 +- crates/core/src/registry/mod.rs | 4 +- crates/core/src/registry/router.rs | 61 +- crates/core/src/runtime/traits.rs | 4 +- crates/core/src/tool.rs | 12 +- crates/core/src/tool_result_persist.rs | 142 +-- crates/eval/src/trace/extractor.rs | 3 +- crates/eval/src/trace/mod.rs | 4 +- crates/governance-contract/Cargo.toml | 14 + crates/governance-contract/src/lib.rs | 5 + crates/governance-contract/src/mode.rs | 821 ++++++++++++++++++ crates/governance-contract/src/policy.rs | 312 +++++++ crates/host-session/Cargo.toml | 4 + crates/host-session/src/catalog.rs | 14 +- crates/host-session/src/collaboration.rs | 9 +- crates/host-session/src/compaction.rs | 4 +- .../src/event_translate.rs} | 27 +- crates/host-session/src/lib.rs | 2 + crates/host-session/src/ports.rs | 10 +- crates/host-session/src/projection.rs | 8 +- .../host-session/src/projection_registry.rs | 4 +- crates/host-session/src/query.rs | 8 +- crates/host-session/src/state.rs | 21 +- crates/host-session/src/turn_mutation.rs | 17 +- crates/host-session/src/workflow.rs | 4 +- crates/llm-contract/Cargo.toml | 13 + crates/llm-contract/src/lib.rs | 189 ++++ crates/plugin-host/Cargo.toml | 2 +- crates/plugin-host/src/descriptor.rs | 3 +- crates/plugin-host/src/host_dispatch.rs | 1 + crates/plugin-host/src/host_reload.rs | 2 + crates/plugin-host/src/host_tests.rs | 7 +- crates/plugin-host/src/modes.rs | 2 +- crates/plugin-host/src/snapshot.rs | 3 +- crates/prompt-contract/Cargo.toml | 10 + crates/prompt-contract/src/lib.rs | 134 +++ crates/protocol/Cargo.toml | 1 + crates/protocol/src/plugin/handshake.rs | 2 +- crates/protocol/src/plugin/tests.rs | 2 +- crates/runtime-contract/Cargo.toml | 14 + crates/runtime-contract/src/lib.rs | 5 + crates/runtime-contract/src/traits.rs | 140 +++ crates/runtime-contract/src/turn.rs | 165 ++++ crates/server/Cargo.toml | 8 +- crates/server/src/agent/context.rs | 3 +- crates/server/src/agent/mod.rs | 7 +- crates/server/src/agent/observe.rs | 6 +- crates/server/src/agent/routing.rs | 13 +- crates/server/src/agent/routing/child_send.rs | 6 +- .../src/agent/routing/parent_delivery.rs | 8 +- crates/server/src/agent/routing/tests.rs | 2 +- .../src/agent/routing_collaboration_flow.rs | 2 +- crates/server/src/agent/test_support.rs | 6 +- crates/server/src/agent_runtime_bridge.rs | 2 +- crates/server/src/bootstrap/capabilities.rs | 7 +- crates/server/src/bootstrap/governance.rs | 11 +- crates/server/src/bootstrap/plugins.rs | 320 ++++++- crates/server/src/bootstrap/providers.rs | 4 +- crates/server/src/bootstrap/runtime.rs | 14 +- .../src/bootstrap/runtime_coordinator.rs | 9 +- crates/server/src/capability_router.rs | 4 +- crates/server/src/conversation_read_model.rs | 2 +- .../src/conversation_read_model/facts.rs | 3 +- .../plan_projection.rs | 1 + crates/server/src/execution/subagent.rs | 5 +- .../src/governance_surface/assembler.rs | 11 +- crates/server/src/governance_surface/mod.rs | 17 +- .../server/src/governance_surface/policy.rs | 15 +- .../server/src/governance_surface/prompt.rs | 5 +- crates/server/src/governance_surface/tests.rs | 13 +- crates/server/src/http/routes/conversation.rs | 3 +- .../src/http/routes/sessions/mutation.rs | 8 +- crates/server/src/mode/catalog.rs | 8 +- crates/server/src/mode/compiler.rs | 29 +- crates/server/src/mode/validator.rs | 23 +- crates/server/src/mode_catalog_service.rs | 3 +- crates/server/src/observability/collector.rs | 8 +- crates/server/src/ports/agent_session.rs | 7 +- crates/server/src/ports/app_session.rs | 10 +- crates/server/src/ports/session_bridge.rs | 11 +- crates/server/src/ports/session_submission.rs | 9 +- crates/server/src/runtime_owner_bridge.rs | 3 +- .../src/session_runtime_owner_bridge.rs | 2 +- .../src/session_runtime_owner_bridge_impl.rs | 6 +- crates/server/src/session_runtime_port.rs | 10 +- .../src/session_runtime_port_adapter.rs | 64 +- crates/server/src/tests/agent_routes_tests.rs | 3 +- .../src/tests/session_contract_tests.rs | 3 +- crates/server/src/tests/test_support.rs | 21 +- crates/server/src/tool_capability_invoker.rs | 75 +- crates/tool-contract/Cargo.toml | 15 + crates/tool-contract/src/lib.rs | 707 +++++++++++++++ scripts/check-crate-boundaries.mjs | 125 ++- src-tauri/src/desktop_frontend_mode.rs | 2 + 182 files changed, 7135 insertions(+), 1762 deletions(-) delete mode 100644 CODE_REVIEW_ISSUES.md create mode 100644 crates/context-window/Cargo.toml create mode 100644 crates/context-window/src/compaction.rs create mode 100644 crates/context-window/src/compaction/protocol.rs create mode 100644 crates/context-window/src/compaction/sanitize.rs create mode 100644 crates/context-window/src/compaction/xml_parsing.rs create mode 100644 crates/context-window/src/file_access.rs create mode 100644 crates/context-window/src/lib.rs create mode 100644 crates/context-window/src/micro_compact.rs create mode 100644 crates/context-window/src/mod.rs create mode 100644 crates/context-window/src/prune_pass.rs create mode 100644 crates/context-window/src/request.rs create mode 100644 crates/context-window/src/settings.rs create mode 100644 crates/context-window/src/templates/compact/base.md create mode 100644 crates/context-window/src/templates/compact/incremental.md create mode 100644 crates/context-window/src/token_usage.rs create mode 100644 crates/context-window/src/tool_result_budget.rs create mode 100644 crates/context-window/src/tool_results.rs delete mode 100644 crates/core/src/home.rs create mode 100644 crates/governance-contract/Cargo.toml create mode 100644 crates/governance-contract/src/lib.rs create mode 100644 crates/governance-contract/src/mode.rs create mode 100644 crates/governance-contract/src/policy.rs rename crates/{core/src/event/translate.rs => host-session/src/event_translate.rs} (98%) create mode 100644 crates/llm-contract/Cargo.toml create mode 100644 crates/llm-contract/src/lib.rs create mode 100644 crates/prompt-contract/Cargo.toml create mode 100644 crates/prompt-contract/src/lib.rs create mode 100644 crates/runtime-contract/Cargo.toml create mode 100644 crates/runtime-contract/src/lib.rs create mode 100644 crates/runtime-contract/src/traits.rs create mode 100644 crates/runtime-contract/src/turn.rs create mode 100644 crates/tool-contract/Cargo.toml create mode 100644 crates/tool-contract/src/lib.rs diff --git a/CODE_REVIEW_ISSUES.md b/CODE_REVIEW_ISSUES.md deleted file mode 100644 index 0937c52e..00000000 --- a/CODE_REVIEW_ISSUES.md +++ /dev/null @@ -1,94 +0,0 @@ -# Code Review — dev (未提交变更 + 暂存区大规模重构) - -## Summary -- 审查范围：未提交变更（6 个 Rust 文件）+ 暂存区关键新模块抽样 -- 未提交变更：7 个文件，+164 / -232 行 -- 暂存区：407 文件，+33,468 / -45,009 行（application→server 重构、session-runtime→agent-runtime、新 host-session/plugin-host crate） -- 新问题：3（1 high, 1 medium, 1 low） -- 测试结果：24 passed, 0 failed（agent-runtime 16, core 2, adapter-llm 3, server 3） -- 编译检查：通过（workspace cargo check 无 warning） -- 视角：4/4 - ---- - -## Security - -无安全新问题。 - -- 所有 HTTP 路由（mutation/query/stream/conversation）均调用 `require_auth` -- `validate_session_path_id` 白名单校验（`[a-zA-Z0-9\-_T]`），有效阻止路径注入 -- `delete_project` 使用 `fs::canonicalize` 规范化路径 -- `copy_dir_recursive` 跳过 symlink，防止符号链接穿越 -- `normalize_prompt_request_text` 正确验证 skill invocation 一致性 - ---- - -## Code Quality - -| Sev | Issue | File:Line | Consequence | -|-----|-------|-----------|-------------| -| High | `max_consecutive_failures` 错误用于 output continuation 限制 | session_runtime_port_adapter.rs:255（已修复） | output continuation 次数受失败重试上限控制，语义混淆。此 bug 已在未提交变更中修复。 | -| Medium | `copy_dir_recursive` 无递归深度限制 | mutation.rs:349 | 恶意或损坏的深层目录树可能导致栈溢出（桌面应用风险极低） | - -### 已修复问题确认 - -`session_runtime_port_adapter.rs:255` 的修复是正确的——新增 `max_output_continuation_attempts` 配置项，在 `core/config.rs` 中独立声明（默认 3），带有 `.max(1)` 下限、serde skip_serializing_if、Debug 展示、validation 注册、以及 resolver 测试覆盖。修复将 `with_max_output_continuations(runtime.max_consecutive_failures)` 改为 `with_max_output_continuations(runtime.max_output_continuation_attempts)`。 - ---- - -## Tests - -**Run results**: 24 passed, 0 failed, 0 skipped - -| Test Suite | Result | -|---|---| -| agent-runtime::loop::tests (16) | OK | -| core::config::tests (2) | OK | -| adapter-llm::openai::dto::tests (3) | OK | -| server::mode::compiler::tests (3) | OK | - -| Sev | Issue | Location | -|-----|-------|----------| -| Low | `copy_dir_recursive` 无单元测试 | mutation.rs:349 | - -新增测试覆盖： -- `repeated_max_tokens_stops_at_configured_continuation_limit` — 直接验证 continuation 限制生效，与 bug 修复对应 -- `child_mode_compile_uses_child_fork_mode_for_child_execution_fallback` — 验证 child fork mode 降级逻辑 -- `assistant_message_*` / `user_and_tool_messages_*` (dto) — 验证 OpenAI 消息序列化边界 - ---- - -## Architecture - -| Sev | Inconsistency | Files | -|-----|--------------|-------| -| — | 无新架构不一致 | — | - -暂存区核心变更审查： -- **application → server 迁移**：`ApplicationError` → `ServerRouteError` 映射完整，conversation routes 正确切换 -- **新 crate 边界**：`agent-runtime`（纯 runtime loop）、`host-session`（状态机 + mutation）、`plugin-host`（插件生命周期）职责清晰 -- **AgentControlRegistry**：`spawn_with_storage` 正确校验 depth/concurrent 限制，`prune_finalized_agents_locked` 防止内存泄漏 -- **host-session ports**：`EventStore` trait 提供 `recover_session` 默认实现（全量 replay），`SessionRecoveryCheckpoint` 结构合理 -- **Crate 边界需验证**：`cargo check` 通过，建议合并前跑 `node scripts/check-crate-boundaries.mjs --strict` - ---- - -## Must Fix Before Merge - -*(无 Critical/High 级别阻断项——High 级 bug 已在未提交变更中修复。)* - -确认修复已提交即可。 - ---- - -## Pre-Existing Issues (not blocking) - -- `host-session/src/state.rs` 测试中使用 `unwrap()`（仅限 `#[cfg(test)]`，可接受） -- `plugin-host` reload 逻辑中 `commit_candidate().ok_or_else(...)` 的错误信息 `"candidate commit unexpectedly failed"` 缺少上下文，可考虑补充 snapshot_id - ---- - -## Low-Confidence Observations - -- `create_session(request.working_dir)` 未对 `working_dir` 做 `canonicalize`，与 `delete_project` 行为不一致。桌面应用中风险极低，但建议统一处理方式。 -- `loop.rs` 中 `TurnExecutionContext` 有 15 个字段，构造复杂。当前通过 `new()` 封装，暂可接受，但若继续增长建议引入 builder。 diff --git a/Cargo.lock b/Cargo.lock index e6a09f5e..a8c15a4b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -160,8 +160,10 @@ name = "astrcode-adapter-llm" version = "0.1.0" dependencies = [ "anyhow", - "astrcode-agent-runtime", "astrcode-core", + "astrcode-governance-contract", + "astrcode-llm-contract", + "astrcode-prompt-contract", "async-trait", "futures-util", "log", @@ -175,9 +177,10 @@ dependencies = [ name = "astrcode-adapter-mcp" version = "0.1.0" dependencies = [ - "astrcode-adapter-prompt", "astrcode-core", "astrcode-plugin-host", + "astrcode-prompt-contract", + "astrcode-runtime-contract", "astrcode-support", "async-trait", "base64 0.22.1", @@ -198,10 +201,12 @@ name = "astrcode-adapter-prompt" version = "0.1.0" dependencies = [ "anyhow", - "astrcode-agent-runtime", "astrcode-core", + "astrcode-governance-contract", "astrcode-host-session", + "astrcode-prompt-contract", "astrcode-support", + "astrcode-tool-contract", "async-trait", "chrono", "dirs", @@ -249,8 +254,10 @@ name = "astrcode-adapter-tools" version = "0.1.0" dependencies = [ "astrcode-core", + "astrcode-governance-contract", "astrcode-host-session", "astrcode-support", + "astrcode-tool-contract", "async-trait", "base64 0.22.1", "chrono", @@ -270,7 +277,12 @@ dependencies = [ name = "astrcode-agent-runtime" version = "0.1.0" dependencies = [ + "astrcode-context-window", "astrcode-core", + "astrcode-llm-contract", + "astrcode-prompt-contract", + "astrcode-runtime-contract", + "astrcode-tool-contract", "async-trait", "chrono", "futures-util", @@ -318,6 +330,23 @@ dependencies = [ "tokio", ] +[[package]] +name = "astrcode-context-window" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "astrcode-llm-contract", + "astrcode-runtime-contract", + "astrcode-support", + "astrcode-tool-contract", + "chrono", + "log", + "regex", + "serde", + "serde_json", + "tokio", +] + [[package]] name = "astrcode-core" version = "0.1.0" @@ -352,14 +381,30 @@ dependencies = [ "tokio", ] +[[package]] +name = "astrcode-governance-contract" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "astrcode-prompt-contract", + "async-trait", + "serde", + "serde_json", + "tokio", +] + [[package]] name = "astrcode-host-session" version = "0.1.0" dependencies = [ "astrcode-agent-runtime", "astrcode-core", + "astrcode-governance-contract", "astrcode-plugin-host", + "astrcode-prompt-contract", + "astrcode-runtime-contract", "astrcode-support", + "astrcode-tool-contract", "async-trait", "chrono", "dashmap", @@ -369,13 +414,24 @@ dependencies = [ "tokio", ] +[[package]] +name = "astrcode-llm-contract" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "astrcode-governance-contract", + "astrcode-prompt-contract", + "async-trait", + "serde", +] + [[package]] name = "astrcode-plugin-host" version = "0.1.0" dependencies = [ "astrcode-core", + "astrcode-governance-contract", "astrcode-protocol", - "astrcode-support", "async-trait", "log", "serde", @@ -384,16 +440,36 @@ dependencies = [ "toml 1.1.2+spec-1.1.0", ] +[[package]] +name = "astrcode-prompt-contract" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "serde", +] + [[package]] name = "astrcode-protocol" version = "0.1.0" dependencies = [ "astrcode-core", + "astrcode-governance-contract", "serde", "serde_json", "thiserror 2.0.18", ] +[[package]] +name = "astrcode-runtime-contract" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "astrcode-llm-contract", + "astrcode-tool-contract", + "async-trait", + "chrono", +] + [[package]] name = "astrcode-server" version = "0.1.0" @@ -407,11 +483,17 @@ dependencies = [ "astrcode-adapter-storage", "astrcode-adapter-tools", "astrcode-agent-runtime", + "astrcode-context-window", "astrcode-core", + "astrcode-governance-contract", "astrcode-host-session", + "astrcode-llm-contract", "astrcode-plugin-host", + "astrcode-prompt-contract", "astrcode-protocol", + "astrcode-runtime-contract", "astrcode-support", + "astrcode-tool-contract", "async-stream", "async-trait", "axum", @@ -444,6 +526,18 @@ dependencies = [ "tempfile", ] +[[package]] +name = "astrcode-tool-contract" +version = "0.1.0" +dependencies = [ + "astrcode-core", + "astrcode-governance-contract", + "async-trait", + "serde", + "serde_json", + "tokio", +] + [[package]] name = "async-broadcast" version = "0.7.2" diff --git a/Cargo.toml b/Cargo.toml index ac552c7b..231d3c3e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,12 @@ [workspace] members = [ "crates/core", + "crates/prompt-contract", + "crates/governance-contract", + "crates/tool-contract", + "crates/llm-contract", + "crates/runtime-contract", + "crates/context-window", "crates/support", "crates/agent-runtime", "crates/host-session", diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md index 3d78590b..5ab1a21a 100644 --- a/PROJECT_ARCHITECTURE.md +++ b/PROJECT_ARCHITECTURE.md @@ -1,169 +1,392 @@ -# Astrcode 架构约束 +# Astrcode 项目架构 -本文档是当前仓库的权威架构说明。目标不是解释历史，而是约束未来实现。 +本文档描述仓库的**当前实际架构**。目标不是解释历史，而是约束未来实现。 -## 总原则 +## 架构原则 -- 不维护向后兼容，优先最终边界和干净代码。 -- `server` 是唯一组合根，只负责装配，不承载长期业务真相。 -- `core` 只保留真正跨 owner 共享的稳定语义，不再充当 DTO/trait 总仓库。 -- runtime、session host、plugin host 分离，避免“大核心 + 补丁式扩展”。 -- 多 agent 协作继续遵循“一个 session 即一个 agent”，durable truth 统一归 `host-session`。 +- 不维护向后兼容。发现旧边界阻碍正确架构时，优先一次性迁移调用点，而不是保留兼容 re-export。 +- `server` 是唯一组合根。它可以依赖所有实现 crate，用于装配、热替换和 HTTP 暴露，但不能成为长期业务真相的持有者。 +- `core` 只承载稳定、无副作用、无宿主策略的共享语义对象和事件数据模型。禁止放入工具 trait、LLM/runtime 边界、治理默认实现、prompt 契约、有状态投影翻译或环境读取。 +- `*-contract` crate 只承载窄领域契约。契约 crate 不能包含宿主耦合默认实现、宿主 I/O、adapter 逻辑或运行时编排；少量纯策略兜底实现必须无状态、无副作用，避免变成第二个 `core`。 +- owner crate 持有各自真相：`host-session` 持有 durable session truth，`plugin-host` 持有插件 truth，`agent-runtime` 只负责编排单 turn 执行，`context-window` 负责上下文窗口与请求整形。 +- adapter 之间禁止横向依赖。跨 adapter 共享的类型必须下沉到对应 contract crate。 +- durable/live 分层必须清晰：JSONL durable events 是刷新、恢复、fork、历史回放的权威事实；SSE live events 只承担低延迟体验和临时草稿。 +- 类型边界显式转换。不同层的 `ModeId`、prompt、tool、runtime 事件不得通过根 crate re-export 偷渡。 -## 目标分层 +## Crate 一览 -### `astrcode-core` +仓库当前包含 `src-tauri` 薄壳在内的多 crate 工作区，核心分层如下： -只保留跨 owner 共享的稳定值对象和最小合同： +```text +┌─────────────────────────────────────────────────────────────┐ +│ shell / entry │ +│ src-tauri (Tauri 桌面壳) │ cli (TUI) │ eval (评测框架) │ +├─────────────────────────────────────────────────────────────┤ +│ client (HTTP SDK) │ +├─────────────────────────────────────────────────────────────┤ +│ server (唯一组合根 + HTTP 路由) │ +├─────────────────────────────────────────────────────────────┤ +│ adapters │ +│ adapter-agents │ adapter-llm │ adapter-mcp │ adapter-prompt │ +│ adapter-skills │ adapter-storage │ adapter-tools │ +├─────────────────────────────────────────────────────────────┤ +│ owners / runtime │ +│ host-session │ plugin-host │ agent-runtime │ context-window │ +├─────────────────────────────────────────────────────────────┤ +│ contracts │ +│ prompt-contract │ governance-contract │ tool-contract │ +│ llm-contract │ runtime-contract │ +├─────────────────────────────────────────────────────────────┤ +│ base │ +│ core │ protocol │ support │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 各 Crate 职责 + +### `astrcode-core` — 共享语义层 + +跨 crate 共享的稳定值对象和事件模型： + +- **强类型 ID**：`SessionId` / `TurnId` / `AgentId` / `SubRunId` +- **稳定语义对象**：`CapabilitySpec`、动作/能力描述、消息与阶段枚举 +- **事件数据模型**：`StorageEvent`、`AgentEvent` 以及可回放的 durable payload +- **基础对象**：`CancelToken`、`AstrError`、环境变量名常量 + +`core` 不依赖任何其他工作区 crate，也不主动读取宿主环境。环境解析、路径探测和文件系统 I/O 放在 `support` 或组合根。 + +### Contract Crates + +契约 crate 只定义跨层边界，不拥有实现： + +- `astrcode-prompt-contract`：`PromptDeclaration`、prompt source/kind/render target、prompt cache hints/diagnostics、prompt layer/fingerprint。 +- `astrcode-governance-contract`：`ModeId`、mode DSL、tool policy、`PolicyEngine` trait、`AllowAllPolicyEngine`、`ModelRequest`、`SystemPromptBlock`。 +- `astrcode-tool-contract`：`Tool`、`ToolContext`、`ToolEventSink`、工具元数据、工具结果、工具输出 delta sender。 +- `astrcode-llm-contract`：`LlmProvider`、`LlmRequest`、`LlmOutput`、`LlmEvent`、`LlmEventSink`、`ModelLimits`、`LlmUsage`。 +- `astrcode-runtime-contract`：`RuntimeHandle`、runtime boundary traits、`RuntimeTurnEvent`。 + +### `astrcode-context-window` — 上下文窗口 + +从 `agent-runtime` 拆出的请求整形子系统： + +- LLM 驱动 compaction、prompt-too-long recovery、contract retry 与 sanitization。 +- tool-result budget、超大工具输出的文件引用恢复。 +- `assemble_runtime_request`，将 session state、prompt、tool result 与模型限制组装成 provider 请求。 + +仅允许依赖 `core`、`llm-contract`、`runtime-contract`、`tool-contract`、`support`。 + +### `astrcode-protocol` — 传输层 DTO + +纯数据契约层，所有类型为可序列化 DTO，不含业务逻辑： + +- `capability/`：`CapabilityWireDescriptor`、`InvocationContext`、`PeerDescriptor`。 +- `http/`：HTTP API 请求/响应 DTO，包含 auth、session、conversation、agent、config、model、SSE 事件信封。 +- `plugin/`：JSON-RPC 插件协议。 + +仅允许依赖 `core` 与对外传输需要暴露的 contract crate（当前为 `governance-contract`）。 + +### `astrcode-support` — 宿主环境工具 + +不应落在 `core` 中的环境依赖工具： + +- `hostpaths`：ASTRCODE_HOME / 项目目录解析。 +- `shell`：跨平台 shell 检测。 +- `tool_results`：大型 tool 输出的磁盘持久化。 + +仅允许依赖 `core`。 + +### `astrcode-agent-runtime` — 最小执行内核 + +单 turn / 单 agent 的 live 执行编排： + +- **Turn 循环**：初始化 → hook dispatch → provider 调用 → tool dispatch → 输出 → 终结。 +- **Provider 调用**：消费 `llm-contract`，不定义 LLM 公共契约。 +- **Tool 调度**：消费 `tool-contract`，支持并行执行与实时流式输出。 +- **Hook 调度**：支持 Continue / Block / CancelTurn / AugmentPrompt / Diagnostic 效果。 +- **Pending event 编排**：将运行时事件交给 host/session bridge 处理 durable 与 live 投影。 + +仅允许依赖 `core`、`context-window`、`llm-contract`、`prompt-contract`、`runtime-contract`、`tool-contract`。 + +### `astrcode-host-session` — Session Owner + +统一承接 durable truth 和 host use-case： + +- **事件持久化**：`SessionWriter` 双路径写入，生产使用 `EventStore` 异步追加，测试可同步写入。 +- **恢复与回放**：checkpoint + tail events 追放。 +- **投影 / 查询 / 观察**：`ProjectionRegistry` 维护 phase、agent state、mode、child node、active task、input queue 等投影。 +- **Turn 变更**：accept → begin → persist inputs → persist runtime events → complete/interrupt。 +- **EventTranslator**：作为 session durable/live 投影实现细节，不能回流到 `core`。 +- **多 Agent 协作**：child session、sub-run lineage、输入队列和协作事件统一持久化。 +- **Session Plan**：结构化计划生命周期。 + +仅允许依赖 `core`、`support`、`agent-runtime`、`plugin-host`、`governance-contract`、`prompt-contract`、`runtime-contract`、`tool-contract`。 -- `ids` -- LLM / tool / message 基础模型 -- `CapabilitySpec` -- 极少数共享 prompt 语义 -- hooks 的稳定事件键和 effect kind +### `astrcode-plugin-host` — 统一插件宿主 -不得继续承载： +builtin / external plugin 的统一管理： -- session recovery / projection / read model -- workflow / mode / session catalog -- plugin registry / active snapshot / plugin manifest -- owner 专属 config / observability / store / composer / ports -- 多 agent 协作 durable truth +- **描述符模型**：tools、hooks、providers、resources、commands、prompts、skills、themes、modes。 +- **校验与快照**：全局唯一性约束、候选快照、原子 commit / rollback。 +- **后端统一**：Builtin / Process / Command / Http 统一到 `PluginRuntimeHandleRef`。 +- **能力调度管线**：binding → plan → readiness check → dispatch。 +- **Hook Bus**：优先级排序、dispatch mode、failure policy。 +- **传输层**：JSON-RPC over stdio。 -### `astrcode-agent-runtime` +仅允许依赖 `core`、`protocol`、`governance-contract`、`support`。 -最小执行内核，只负责单 turn / 单 agent live 执行： +### Adapter Crates -- `execute_turn` -- provider stream 调用 -- tool dispatch -- hook dispatch -- 流式状态机 -- 取消 / 超时传播 +7 个 adapter 遵循端口-适配器模式，实现各自的上层 trait： -不得负责： +| Crate | 实现的 Port | 职责 | +|---|---|---| +| `adapter-agents` | 无（纯数据注册表） | Agent profile 多源加载（builtin < user < project），YAML/Markdown 解析 | +| `adapter-llm` | `LlmProvider`（llm-contract） | OpenAI 兼容 API，Chat Completions + Responses API，SSE 流式，指数退避重试，prompt cache 诊断 | +| `adapter-mcp` | `ResourceProvider`（plugin-host）/ `CapabilityInvoker`（core） | MCP JSON-RPC 客户端，工具/提示/资源桥接，直接产出 `prompt-contract::PromptDeclaration`，工具名命名空间 `mcp__{server}__{tool}` | +| `adapter-prompt` | `PromptProvider`（host-session） | 四层缓存架构、贡献者模式、波拓扑排序，直接消费 `prompt-contract` | +| `adapter-skills` | `SkillCatalog`（core） | 多源技能叠加，编译时 builtin 打包，运行时资产物化 | +| `adapter-storage` | `EventStore` + `SessionManager`（host-session）/ `ConfigStore` + `McpSettingsStore`（core） | JSONL 追加日志、原子文件写入、OS 级文件锁、checkpoint 恢复 | +| `adapter-tools` | `Tool`（tool-contract）× 15+ | 文件操作、shell、搜索、Skill 加载、任务管理、模式切换、Agent 协作 | -- session catalog -- 事件日志与恢复 -- branch / fork / compact -- resource discovery -- 多 agent 协作 durable truth +### `astrcode-server` — 组合根 + HTTP 服务 -### `astrcode-host-session` +唯一允许同时依赖所有 adapter、owner、runtime 与 contract crate 的地方： -session owner，统一承接 durable truth 和 host use-case： +- **Bootstrap**：配置 → MCP → 插件 → 工具索引 → 能力快照 → session 运行时 → agent 运行时包 → governance → `ServerRuntime`。 +- **Runtime Coordinator**：原子热替换 runtime surface。 +- **Ports 模块**：六边形架构端口接口和 bridge 适配器。 +- **Governance Surface**：每 turn 治理决策、审批策略、子 agent 委托、协作引导。 +- **Capability Router**：本地 builtin + 动态外部双层能力模型。 +- **HTTP 路由**：Auth / Session CRUD / Conversation SSE / Config / Model / Agent / MCP / Logs。 +- **Lifecycle**：追踪 turn 和 subagent 任务句柄，关闭时批量终止。 -- 事件日志 -- 恢复与回放 -- projection / query / observe -- session catalog -- branch / fork / compact -- 模型选择 -- 输入入口 -- `AgentRuntimeExecutionSurface` 组装 -- 多 agent 协作真相：`SubRunHandle`、`InputQueueProjection`、父子 lineage、结果投递、取消传播 +### `astrcode-client` — HTTP SDK -### `astrcode-plugin-host` +类型化异步 Rust SDK： -统一 builtin / external plugin 宿主： +- `AstrcodeClient` 泛型 transport，默认 Reqwest transport。 +- 覆盖 session CRUD、prompt 提交、conversation SSE、model 查询、compact、mode 切换。 +- SSE 解析与 `ConversationStream`。 -- plugin descriptor 校验 -- candidate / active snapshot -- reload commit / rollback -- hooks / providers / resources / commands / prompts / skills / themes 聚合 -- builtin backend 与 external backend 的统一语义 +仅依赖 `protocol`。 -### `astrcode-server` +### `astrcode-cli` — 终端 UI -唯一组合根： +基于 ratatui / crossterm 的 TUI： -- 装配 `agent-runtime`、`host-session`、`plugin-host` -- 装配 `adapter-*` -- 暴露 HTTP / RPC / CLI 所需入口 +- 事件循环、流式对话、slash 命令面板、model 选择、session 切换、mode 切换、thinking 动画、markdown 渲染。 +- 自动发现或 spawn 服务器。 -不得继续承载： +依赖 `client`、`core`、`support`。 -- builtin / plugin / MCP / governance / workflow / mode 的并列事实源 -- provider kind 硬编码选择逻辑 -- 旧运行时协调壳层 +### `astrcode-eval` — 评测框架 -## 迁移中的旧边界 +离线 agent 质量评测： -以下 crate 已不再是长期权威边界，只允许作为迁移源存在，最终必须删除： +- YAML 任务定义与多维评分。 +- 隔离工作区 → 创建 session → 提交 prompt → 轮询完成 → 提取 trace → 诊断 → 评分。 +- 失败模式检测。 -- `astrcode-application` -- `astrcode-kernel` -- `astrcode-session-runtime` -- 旧 `astrcode-plugin` +依赖 `core`、`protocol`、`support`。 -要求： +### `src-tauri` — Tauri 桌面壳 -- 新 crate 不得回头依赖这些旧边界。 -- 新功能不得继续落在这些 crate 中。 -- 组合根不得继续把这些 crate 当成正式装配主链。 +Tauri v2 薄壳，不含业务逻辑： + +- 服务器生命周期管理。 +- 桌面前端模式检测。 +- 系统对话框。 + +仅依赖 `core`。 + +--- ## 依赖方向 -允许的高层方向如下： +### 分层方向 ```text -adapter-* ───────────────┐ - ├──> plugin-host ──┐ -storage / protocol ──────┘ │ - │ -core <──────────── agent-runtime <──────────┤ - ^ ^ │ - | | │ - └──────────── host-session <──────────────┘ - ^ - | - server +entry crates + └─ client + └─ protocol + └─ core + +server + ├─ adapters + ├─ owner/runtime crates + ├─ contract crates + └─ base crates + +adapters + ├─ contract crates + ├─ owner ports + └─ core/support + +owner/runtime crates + ├─ contract crates + └─ core/support + +contract crates + └─ core + +support + └─ core + +core + └─ 无工作区依赖 ``` +adapter 到 adapter 的依赖一律禁止。需要共享 prompt、tool、LLM、runtime 或 governance 类型时，必须放入对应 contract crate。 +部分 contract crate 可以依赖更底层 contract，具体以“强约束”表为准。 + ### 强约束 -- `core` 不得依赖任何其他工作区 crate。 -- `protocol` 仅允许依赖 `core`。 -- `support` 仅允许依赖 `core`。 -- `agent-runtime` 仅允许依赖 `core`，必要时可依赖极少数纯工具 crate；不得依赖 `application`、`kernel`、`session-runtime`。 -- `plugin-host` 仅允许依赖 `core`、`protocol`、`support`；不得依赖 `application`、`kernel`、`session-runtime`。 -- `host-session` 仅允许依赖 `core`、`support`、`agent-runtime`、`plugin-host`；不得依赖 `application`、`kernel`、`session-runtime`。 -- `server` 是唯一允许同时装配新旧边界的地方，但目标是逐步只装配 `agent-runtime + host-session + plugin-host + adapters`。 +| Crate | 允许依赖 | +|---|---| +| `core` | 无（零工作区依赖） | +| `protocol` | `core`、`governance-contract` | +| `support` | `core` | +| `agent-runtime` | `core`、`context-window`、`llm-contract`、`prompt-contract`、`runtime-contract`、`tool-contract` | +| `plugin-host` | `core`、`protocol`、`governance-contract`、`support` | +| `host-session` | `core`、`support`、`agent-runtime`、`plugin-host`、`governance-contract`、`prompt-contract`、`runtime-contract`、`tool-contract` | +| `prompt-contract` | `core` | +| `governance-contract` | `core`、`prompt-contract` | +| `tool-contract` | `core`、`governance-contract` | +| `llm-contract` | `core`、`governance-contract`、`prompt-contract` | +| `runtime-contract` | `core`、`llm-contract`、`tool-contract` | +| `context-window` | `core`、`llm-contract`、`runtime-contract`、`tool-contract`、`support` | +| `adapter-agents` | `core`、`support` | +| `adapter-llm` | `core`、`llm-contract`、`prompt-contract` | +| `adapter-mcp` | `core`、`prompt-contract`、`plugin-host`、`support` | +| `adapter-prompt` | `core`、`governance-contract`、`host-session`、`prompt-contract`、`support` | +| `adapter-skills` | `core`、`support` | +| `adapter-storage` | `core`、`host-session`、`support` | +| `adapter-tools` | `core`、`governance-contract`、`host-session`、`tool-contract`、`support` | +| `server` | 所有 crate | +| `client` | `protocol` | +| `cli` | `client`、`core`、`support` | +| `eval` | `core`、`protocol`、`support` | +| `src-tauri` | `core` | + +### 边界备注 + +- `protocol -> governance-contract` 是传输 DTO 暴露 mode 信息的显式例外，不能扩展成任意 contract 依赖。 +- `host-session -> agent-runtime` 只用于 runtime event 与 turn orchestration 的宿主集成，不能把 agent-runtime 的执行细节扩散回 session owner。 +- `context-window` 已经是 `agent-runtime` 的外置子系统，不得把 compaction、tool-result 文件恢复或 request shaping 移回 turn loop。 + +--- + +## 核心设计模式 + +### 事件溯源（Event Sourcing） + +Session 使用 JSONL 追加日志持久化事件流： + +- **写入**：`SessionWriter` → `EventStore::append()` → JSONL 文件。 +- **广播**：durable event 先更新投影，再翻译为 live event 广播到订阅者。 +- **恢复**：checkpoint + tail events 追放。 +- **Compaction**：LLM 驱动摘要替换旧消息前缀，并自动 checkpoint。 + +durable JSONL 是权威事实。LLM token/thinking delta 属于 live 草稿，默认不逐 token 写入 JSONL；最终 assistant 文本、最终 reasoning、工具事件、错误和完成事件必须持久化。 + +### 端口-适配器（Hexagonal Architecture） + +系统边界通过 trait 端口定义，adapter 提供具体实现： + +| 端口（定义于） | 适配器 | +|---|---| +| `Tool`（tool-contract） | `adapter-tools` 中 15+ 工具 | +| `LlmProvider`（llm-contract） | `adapter-llm` OpenAI 兼容 | +| `EventStore`（host-session） | `adapter-storage` JSONL | +| `PromptProvider`（host-session） | `adapter-prompt` 四层缓存构建器 | +| `SkillCatalog`（core） | `adapter-skills` 多源叠加 | +| `SubAgentExecutor`（host-session） | `server` 中注入 | +| `CollaborationExecutor`（host-session） | `server` 中注入 | +| `ResourceProvider`（plugin-host） | `adapter-mcp` MCP 资源桥接 | +| `ConfigStore`（core） | `adapter-storage` 文件系统 | +| `BuiltinCapabilityExecutor`（plugin-host） | `server` 中注册 | + +### 插件系统 -## 多 agent 协作约束 +统一四后端模型（Builtin / Process / Command / Http）： -- 一个 session 就是一个 agent。 -- child agent 必须表现为 child session，而不是同一 session 内的“子人格切换”。 -- `host-session` 是 collaboration durable truth 的唯一 owner。 -- `agent-runtime` 只保留 child session 的最小执行合同。 -- `plugin-host` 只暴露协作 surface，例如 `spawn_agent`、`send_to_child`、`send_to_parent`、`observe_subtree`、`terminate_subtree`；这些 surface 不得持有 durable truth。 +1. **加载**：扫描 plugin manifest。 +2. **校验**：全局唯一性约束。 +3. **暂存**：构建候选快照。 +4. **启动后端**：builtin 使用 in-process handle，external 使用子进程或 HTTP 后端。 +5. **提交**：原子替换 active snapshot。 +6. **调度**：binding → plan → readiness check → dispatch。 -## hooks 约束 +热替换通过 `RuntimeCoordinator` 原子执行。 -- hooks 是唯一扩展总线。 -- governance、workflow overlay、tool policy、resource discovery、model selection 必须逐步统一到 hooks catalog。 -- hook effect 只能表达受约束的流程影响，不能直接突变 durable truth。 -- prompt augment 必须继续走 `PromptDeclaration` / `PromptGovernanceContext` 链路，不引入平行 prompt 系统。 +### 多 Agent 协作 -## 实施顺序 +- 一个 session 就是一个 agent，child agent 表现为 child session。 +- `SubRunHandle` 承载完整 lineage。 +- 协作通过 `SubAgentExecutor` / `CollaborationExecutor` trait 注入。 +- Durable truth 统一归 `host-session`。 +- 输入队列状态机、协作事件和取消传播都必须可回放。 -1. 先更新本文档和 crate boundary 守卫。 -2. 新建 `agent-runtime`、`host-session`、`plugin-host` crate 骨架。 -3. 收缩 `core`，先删共享面污染，再迁 owner 专属模型。 -4. 迁移最小 runtime 核心到 `agent-runtime`。 -5. 迁移 session durable truth 和协作真相到 `host-session`。 -6. 迁移 plugin 宿主与统一 snapshot 到 `plugin-host`。 -7. 重写 `server` 组合根。 -8. 删除 `application`、`kernel`、旧 `session-runtime`、旧 `plugin` 边界。 +### Prompt 组装 + +四层缓存友好架构： + +| 层 | 稳定性 | 内容 | +|---|---|---| +| Stable | 极少变化 | Identity + Environment + ResponseStyle | +| SemiStable | 配置变更时失效 | AgentProfile + CapabilityPrompt + SkillSummary | +| Inherited | 按 prompt declaration 变化 | Plugin / MCP / 用户 prompt 声明 | +| Dynamic | 每 turn 变化 | Workflow 示例 | + +贡献者模式 + 波拓扑排序解决依赖，最终渲染为 `SystemPromptBlock` 送入 LLM。 + +### Hook 总线 + +Hook bus 是唯一扩展总线。Governance、tool policy、model selection 通过 hook bus dispatch，避免 adapter 或 runtime 私自绕过治理面。 + +--- + +## 治理模式 DSL + +`GovernanceModeSpec`（governance-contract）定义声明式模式 DSL： + +- `mode_id` / `display_name` / `description` +- `capabilities`：`CapabilitySelector` +- `tool_policy`：按工具与能力描述限制 +- `action_policies`：读、写、shell、network、agent spawn 等动作策略 +- `child_agent_policy` / `execution_policy` +- `prompt_program` / `artifact_contract` / `exit_gate` +- `prompt_hooks` / `transition_policy` + +运行时通过治理 surface 解析为每 turn 上下文快照。mode 的 durable 表达和 runtime 表达允许不同类型，但转换必须发生在明确边界： + +- session durable events 与历史回放使用 `core` 中的 mode 事件数据。 +- runtime、tool policy、prompt 组装使用 `governance-contract` 中的 mode 契约。 +- 转换点应位于 `server`、`host-session` 或工具事件桥接处，禁止用旧 re-export 隐式兼容。 + +--- ## 验证要求 每次涉及边界变更时，至少验证： -- `node scripts/check-crate-boundaries.mjs` -- `cargo check --workspace` +```bash +node scripts/check-crate-boundaries.mjs --strict +cargo check --workspace +cargo test --workspace --exclude astrcode --lib +``` + +完整 CI 检查见仓库 `AGENTS.md` 的“常用命令”。 + +--- -进入大规模迁移后，再逐步补齐： +## 当前风险与例外 -- `cargo test --workspace --exclude astrcode --lib` -- 新 crate 的单元测试与集成测试 +| 项目 | 约束 | +|---|---| +| `protocol -> governance-contract` | 仅用于传输层 mode DTO，不得扩展为协议层依赖任意运行时契约 | +| `host-session -> agent-runtime` | 只允许用于 turn/runtime 事件宿主集成，不得让 session owner 直接持有 provider/tool 细节 | +| `context-window` 体量 | 允许先作为整体 crate 存在；继续增长时应按 compaction、tool-result budget、file recovery 再拆分 | +| 插件 HTTP 后端 | 已有后端形态，只有实际产品需求出现时再补齐实现 | diff --git a/crates/adapter-llm/Cargo.toml b/crates/adapter-llm/Cargo.toml index 45b4e9ec..c1a0265d 100644 --- a/crates/adapter-llm/Cargo.toml +++ b/crates/adapter-llm/Cargo.toml @@ -6,8 +6,10 @@ license-file.workspace = true authors.workspace = true [dependencies] -astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } +astrcode-llm-contract = { path = "../llm-contract" } +astrcode-prompt-contract = { path = "../prompt-contract" } anyhow.workspace = true async-trait.workspace = true futures-util.workspace = true diff --git a/crates/adapter-llm/src/cache_tracker.rs b/crates/adapter-llm/src/cache_tracker.rs index e64d646a..97661e33 100644 --- a/crates/adapter-llm/src/cache_tracker.rs +++ b/crates/adapter-llm/src/cache_tracker.rs @@ -4,7 +4,7 @@ //! - 请求发送前记录一次 prompt/tool/cache 策略快照 //! - 响应返回后根据真实 `cache_read_input_tokens` 跌幅判断是否发生 cache break -use astrcode_agent_runtime::{ +use astrcode_llm_contract::{ LlmUsage, PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, }; use serde::Serialize; diff --git a/crates/adapter-llm/src/lib.rs b/crates/adapter-llm/src/lib.rs index 3342a248..6634d632 100644 --- a/crates/adapter-llm/src/lib.rs +++ b/crates/adapter-llm/src/lib.rs @@ -39,8 +39,8 @@ use std::{collections::HashMap, time::Duration}; -use astrcode_agent_runtime::LlmEvent; use astrcode_core::{AstrError, CancelToken, ReasoningContent, Result, ToolCallRequest}; +use astrcode_llm_contract::LlmEvent; use log::warn; use serde_json::Value; use tokio::{select, time::sleep}; @@ -48,7 +48,7 @@ use tokio::{select, time::sleep}; pub mod cache_tracker; pub mod openai; -pub use astrcode_agent_runtime::{ +pub use astrcode_llm_contract::{ LlmEventSink as EventSink, LlmFinishReason as FinishReason, LlmOutput, LlmProvider, LlmRequest, LlmUsage, ModelLimits, PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, PromptLayerFingerprints, diff --git a/crates/adapter-llm/src/openai.rs b/crates/adapter-llm/src/openai.rs index 8faaeddb..69231029 100644 --- a/crates/adapter-llm/src/openai.rs +++ b/crates/adapter-llm/src/openai.rs @@ -604,7 +604,7 @@ fn is_official_openai_api_url(url: &str) -> bool { fn build_prompt_cache_key( model: &str, system_prompt: Option<&str>, - system_prompt_blocks: &[astrcode_core::SystemPromptBlock], + system_prompt_blocks: &[astrcode_governance_contract::SystemPromptBlock], prompt_cache_hints: Option<&PromptCacheHints>, tools: &[&ToolDefinition], ) -> String { @@ -1121,7 +1121,7 @@ struct OpenAiBuildRequestInput<'a> { messages: &'a [LlmMessage], tools: &'a [ToolDefinition], system_prompt: Option<&'a str>, - system_prompt_blocks: &'a [astrcode_core::SystemPromptBlock], + system_prompt_blocks: &'a [astrcode_governance_contract::SystemPromptBlock], prompt_cache_hints: Option<&'a PromptCacheHints>, max_output_tokens_override: Option, stream: bool, @@ -1361,29 +1361,29 @@ mod tests { origin: UserMessageOrigin::User, }]; let system_blocks = vec![ - astrcode_core::SystemPromptBlock { + astrcode_governance_contract::SystemPromptBlock { title: "Stable 1".to_string(), content: "stable content 1".to_string(), cache_boundary: false, - layer: astrcode_core::SystemPromptLayer::Stable, + layer: astrcode_prompt_contract::SystemPromptLayer::Stable, }, - astrcode_core::SystemPromptBlock { + astrcode_governance_contract::SystemPromptBlock { title: "Stable 2".to_string(), content: "stable content 2".to_string(), cache_boundary: true, - layer: astrcode_core::SystemPromptLayer::Stable, + layer: astrcode_prompt_contract::SystemPromptLayer::Stable, }, - astrcode_core::SystemPromptBlock { + astrcode_governance_contract::SystemPromptBlock { title: "Semi 1".to_string(), content: "semi content 1".to_string(), cache_boundary: true, - layer: astrcode_core::SystemPromptLayer::SemiStable, + layer: astrcode_prompt_contract::SystemPromptLayer::SemiStable, }, - astrcode_core::SystemPromptBlock { + astrcode_governance_contract::SystemPromptBlock { title: "Inherited 1".to_string(), content: "inherited content 1".to_string(), cache_boundary: true, - layer: astrcode_core::SystemPromptLayer::Inherited, + layer: astrcode_prompt_contract::SystemPromptLayer::Inherited, }, ]; let request = provider.build_request(OpenAiBuildRequestInput { @@ -1669,7 +1669,7 @@ mod tests { }]; let ordered_tools = order_tools_for_cache(&tools); let base_hints = PromptCacheHints { - layer_fingerprints: astrcode_core::PromptLayerFingerprints { + layer_fingerprints: astrcode_prompt_contract::PromptLayerFingerprints { stable: Some("stable-a".to_string()), semi_stable: Some("semi-a".to_string()), inherited: Some("inherited-a".to_string()), diff --git a/crates/adapter-llm/src/openai/dto.rs b/crates/adapter-llm/src/openai/dto.rs index 26d348d8..1cbcedd7 100644 --- a/crates/adapter-llm/src/openai/dto.rs +++ b/crates/adapter-llm/src/openai/dto.rs @@ -11,8 +11,8 @@ //! - Responses 专有类型继续使用 `serde_json::Value`（在 `responses.rs`） //! - 本模块只存放"两个路径都会用到"的类型和函数 -use astrcode_agent_runtime::LlmUsage; use astrcode_core::{LlmMessage, ToolDefinition}; +use astrcode_llm_contract::LlmUsage; use serde::{Deserialize, Serialize}; use serde_json::Value; diff --git a/crates/adapter-llm/src/openai/responses.rs b/crates/adapter-llm/src/openai/responses.rs index 85be8619..9145178b 100644 --- a/crates/adapter-llm/src/openai/responses.rs +++ b/crates/adapter-llm/src/openai/responses.rs @@ -165,12 +165,12 @@ pub(super) fn flush_sse_buffer( fn build_instructions( system_prompt: Option<&str>, - system_prompt_blocks: &[astrcode_core::SystemPromptBlock], + system_prompt_blocks: &[astrcode_governance_contract::SystemPromptBlock], ) -> Option { if !system_prompt_blocks.is_empty() { let rendered = system_prompt_blocks .iter() - .map(astrcode_core::SystemPromptBlock::render) + .map(astrcode_governance_contract::SystemPromptBlock::render) .collect::>() .join("\n\n"); return (!rendered.is_empty()).then_some(rendered); diff --git a/crates/adapter-mcp/Cargo.toml b/crates/adapter-mcp/Cargo.toml index 3b808c0b..2176538f 100644 --- a/crates/adapter-mcp/Cargo.toml +++ b/crates/adapter-mcp/Cargo.toml @@ -7,7 +7,8 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } -astrcode-adapter-prompt = { path = "../adapter-prompt" } +astrcode-prompt-contract = { path = "../prompt-contract" } +astrcode-runtime-contract = { path = "../runtime-contract" } astrcode-plugin-host = { path = "../plugin-host" } astrcode-support = { path = "../support" } async-trait.workspace = true diff --git a/crates/adapter-mcp/src/bridge/prompt_bridge.rs b/crates/adapter-mcp/src/bridge/prompt_bridge.rs index f1650af3..13100b1d 100644 --- a/crates/adapter-mcp/src/bridge/prompt_bridge.rs +++ b/crates/adapter-mcp/src/bridge/prompt_bridge.rs @@ -3,12 +3,9 @@ //! 将 MCP 服务器握手响应中的 `instructions` //! 转换为 `PromptDeclaration`，注入到 Astrcode 的 prompt 组装管线。 -use astrcode_adapter_prompt::{ - block::PromptLayer, - prompt_declaration::{ - PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, - PromptDeclarationSource, - }, +use astrcode_prompt_contract::{ + PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, + PromptDeclarationSource, SystemPromptLayer, }; /// 将 MCP 服务器的 instructions 转换为 PromptDeclaration。 @@ -24,7 +21,7 @@ pub fn instructions_to_prompt_declaration( title: format!("MCP Server: {}", server_name), content: instructions.to_string(), render_target: PromptDeclarationRenderTarget::System, - layer: PromptLayer::default(), + layer: SystemPromptLayer::default(), kind: PromptDeclarationKind::ExtensionInstruction, priority_hint: None, always_include: false, diff --git a/crates/adapter-mcp/src/manager/mod.rs b/crates/adapter-mcp/src/manager/mod.rs index cc95dfd3..53ebfaa0 100644 --- a/crates/adapter-mcp/src/manager/mod.rs +++ b/crates/adapter-mcp/src/manager/mod.rs @@ -11,8 +11,9 @@ use std::{ }, }; -use astrcode_adapter_prompt::PromptDeclaration; -use astrcode_core::{AstrError, CapabilityInvoker, ManagedRuntimeComponent, Result}; +use astrcode_core::{AstrError, CapabilityInvoker, Result}; +use astrcode_prompt_contract::PromptDeclaration; +use astrcode_runtime_contract::ManagedRuntimeComponent; use async_trait::async_trait; use connection::McpConnection; use futures_util::stream::{self, StreamExt}; @@ -77,7 +78,7 @@ pub struct McpConnectionResults { /// 所有注册的能力调用器。 pub invokers: Vec>, /// MCP 服务器的 prompt 声明。 - pub prompt_declarations: Vec, + pub prompt_declarations: Vec, } /// 批量连接中单个服务器的结果。 diff --git a/crates/adapter-mcp/src/manager/surface.rs b/crates/adapter-mcp/src/manager/surface.rs index 0853ea80..dff3ca30 100644 --- a/crates/adapter-mcp/src/manager/surface.rs +++ b/crates/adapter-mcp/src/manager/surface.rs @@ -5,8 +5,8 @@ use std::{collections::HashMap, sync::Arc}; -use astrcode_adapter_prompt::PromptDeclaration; use astrcode_core::CapabilityInvoker; +use astrcode_prompt_contract::PromptDeclaration; use log::{info, warn}; use serde::Serialize; use tokio::sync::Mutex; diff --git a/crates/adapter-prompt/Cargo.toml b/crates/adapter-prompt/Cargo.toml index f64264fa..e3d336ff 100644 --- a/crates/adapter-prompt/Cargo.toml +++ b/crates/adapter-prompt/Cargo.toml @@ -6,10 +6,12 @@ license-file.workspace = true authors.workspace = true [dependencies] -astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } astrcode-host-session = { path = "../host-session" } +astrcode-prompt-contract = { path = "../prompt-contract" } astrcode-support = { path = "../support" } +astrcode-tool-contract = { path = "../tool-contract" } anyhow.workspace = true async-trait.workspace = true chrono.workspace = true diff --git a/crates/adapter-prompt/src/block.rs b/crates/adapter-prompt/src/block.rs index b9c4940e..0e9981f4 100644 --- a/crates/adapter-prompt/src/block.rs +++ b/crates/adapter-prompt/src/block.rs @@ -14,7 +14,7 @@ use std::{borrow::Cow, collections::HashMap}; -pub use astrcode_core::SystemPromptLayer as PromptLayer; +pub use astrcode_prompt_contract::SystemPromptLayer as PromptLayer; use super::template::PromptTemplate; diff --git a/crates/adapter-prompt/src/composer.rs b/crates/adapter-prompt/src/composer.rs index f65d8b78..14f8432d 100644 --- a/crates/adapter-prompt/src/composer.rs +++ b/crates/adapter-prompt/src/composer.rs @@ -31,8 +31,8 @@ use std::{ }; use anyhow::{Result, anyhow}; -use astrcode_agent_runtime::PromptCacheHints; use astrcode_core::{LlmMessage, UserMessageOrigin}; +use astrcode_prompt_contract::PromptCacheHints; use super::{ BlockCondition, BlockContent, BlockKind, BlockSpec, PromptBlock, PromptContext, diff --git a/crates/adapter-prompt/src/contribution.rs b/crates/adapter-prompt/src/contribution.rs index 936307a8..63606d1b 100644 --- a/crates/adapter-prompt/src/contribution.rs +++ b/crates/adapter-prompt/src/contribution.rs @@ -5,7 +5,7 @@ use std::collections::{HashMap, HashSet}; -use astrcode_core::ToolDefinition; +use astrcode_tool_contract::ToolDefinition; use super::BlockSpec; diff --git a/crates/adapter-prompt/src/contributors/capability_prompt.rs b/crates/adapter-prompt/src/contributors/capability_prompt.rs index bbfdb8ea..e3763e52 100644 --- a/crates/adapter-prompt/src/contributors/capability_prompt.rs +++ b/crates/adapter-prompt/src/contributors/capability_prompt.rs @@ -9,7 +9,8 @@ //! - 非外部工具保持详细指南可见，不再因为工具总数被整体折叠 //! - 只负责工具指南；外部 `PromptDeclaration` 由独立 contributor 承接 -use astrcode_core::{CapabilitySpec, ToolPromptMetadata}; +use astrcode_core::CapabilitySpec; +use astrcode_tool_contract::ToolPromptMetadata; use async_trait::async_trait; use crate::{BlockKind, BlockSpec, PromptContext, PromptContribution, PromptContributor}; @@ -300,9 +301,8 @@ fn build_detailed_tool_block(guide: &ToolGuideEntry) -> BlockSpec { #[cfg(test)] mod tests { - use astrcode_core::{ - CapabilityKind, CapabilitySpec, ToolPromptMetadata, test_support::TestEnvGuard, - }; + use astrcode_core::{CapabilityKind, CapabilitySpec, test_support::TestEnvGuard}; + use astrcode_tool_contract::ToolPromptMetadata; use serde_json::json; use super::*; diff --git a/crates/adapter-prompt/src/core_port.rs b/crates/adapter-prompt/src/core_port.rs index 819fb920..75d2db3c 100644 --- a/crates/adapter-prompt/src/core_port.rs +++ b/crates/adapter-prompt/src/core_port.rs @@ -3,18 +3,19 @@ //! `core::ports::PromptProvider` 是 kernel 消费的简化端口接口， //! 本模块将其适配到 `LayeredPromptBuilder` 的完整 prompt 构建能力上。 -use astrcode_agent_runtime::{PromptCacheGlobalStrategy, PromptCacheHints}; -use astrcode_core::{Result, SystemPromptBlock, SystemPromptLayer}; +use astrcode_core::Result; +use astrcode_governance_contract::SystemPromptBlock; use astrcode_host_session::{ PromptAgentProfileSummary as HostPromptAgentProfileSummary, PromptBuildCacheMetrics, PromptBuildOutput, PromptBuildRequest, PromptProvider, PromptSkillSummary as HostPromptSkillSummary, }; +use astrcode_prompt_contract::{PromptCacheGlobalStrategy, PromptCacheHints, SystemPromptLayer}; use async_trait::async_trait; use serde_json::Value; use crate::{ - PromptAgentProfileSummary, PromptContext, PromptDeclaration, PromptSkillSummary, + PromptAgentProfileSummary, PromptContext, PromptSkillSummary, diagnostics::DiagnosticReason, layered_builder::{LayeredPromptBuilder, default_layered_prompt_builder}, }; @@ -59,11 +60,7 @@ impl PromptProvider for ComposerPromptProvider { .map(|capability| capability.name.to_string()) .collect(), capability_specs: request.capabilities, - prompt_declarations: request - .prompt_declarations - .into_iter() - .map(PromptDeclaration::from) - .collect(), + prompt_declarations: request.prompt_declarations, agent_profiles: request .agent_profiles .into_iter() @@ -250,9 +247,9 @@ fn insert_json_string( mod tests { use std::path::PathBuf; - use astrcode_agent_runtime::PromptCacheGlobalStrategy; use astrcode_core::{CapabilityKind, CapabilitySpec}; use astrcode_host_session::PromptBuildRequest; + use astrcode_prompt_contract::PromptCacheGlobalStrategy; use super::{build_output_metadata, build_prompt_vars, select_global_cache_strategy}; use crate::{BlockKind, PromptBlock, PromptDiagnostics, PromptPlan, block::BlockMetadata}; diff --git a/crates/adapter-prompt/src/layered_builder.rs b/crates/adapter-prompt/src/layered_builder.rs index bbbc266a..e351f319 100644 --- a/crates/adapter-prompt/src/layered_builder.rs +++ b/crates/adapter-prompt/src/layered_builder.rs @@ -11,7 +11,7 @@ use std::{ }; use anyhow::Result; -use astrcode_agent_runtime::{PromptCacheHints, PromptLayerFingerprints}; +use astrcode_prompt_contract::{PromptCacheHints, PromptLayerFingerprints}; use super::{ PromptBuildOutput, PromptComposer, PromptComposerOptions, PromptContext, PromptContributor, diff --git a/crates/adapter-prompt/src/plan.rs b/crates/adapter-prompt/src/plan.rs index 715011fb..936c7434 100644 --- a/crates/adapter-prompt/src/plan.rs +++ b/crates/adapter-prompt/src/plan.rs @@ -8,7 +8,8 @@ //! `render_system()` 将 system blocks 按优先级排序后拼接为完整的 system prompt 字符串。 //! prepend/append 消息则直接作为 LLM 对话消息的一部分。 -use astrcode_core::{LlmMessage, ToolDefinition}; +use astrcode_core::LlmMessage; +use astrcode_tool_contract::ToolDefinition; use serde::Serialize; use super::{PromptBlock, append_unique_tools, block::PromptLayer}; diff --git a/crates/adapter-prompt/src/prompt_declaration.rs b/crates/adapter-prompt/src/prompt_declaration.rs index 88b6872a..6a8d2654 100644 --- a/crates/adapter-prompt/src/prompt_declaration.rs +++ b/crates/adapter-prompt/src/prompt_declaration.rs @@ -8,11 +8,10 @@ //! - Skill：system prompt 中仅暴露索引（名称+描述），正文通过 `Skill` tool 按需加载 //! - PromptDeclaration：直接注入到 system prompt 或对话消息中，始终可见 -pub use astrcode_core::{ - PromptDeclarationKind, PromptDeclarationRenderTarget, PromptDeclarationSource, - SystemPromptLayer as PromptLayer, +pub use astrcode_prompt_contract::{ + PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, + PromptDeclarationSource, SystemPromptLayer as PromptLayer, }; -use serde::{Deserialize, Serialize}; use crate::{BlockKind, RenderTarget}; @@ -49,98 +48,3 @@ pub(crate) fn prompt_declaration_render_target( PromptDeclarationRenderTarget::AppendAssistant => RenderTarget::AppendAssistant, } } - -impl From for PromptDeclaration { - fn from(value: astrcode_core::PromptDeclaration) -> Self { - Self { - block_id: value.block_id, - title: value.title, - content: value.content, - render_target: value.render_target, - layer: value.layer, - kind: value.kind, - priority_hint: value.priority_hint, - always_include: value.always_include, - source: value.source, - capability_name: value.capability_name, - origin: value.origin, - } - } -} - -/// 插件或 MCP 服务器声明的 prompt 内容。 -/// -/// 这是一种"直接注入"式的 prompt 贡献，与 contributor 的编程式生成不同， -/// prompt declaration 通过序列化数据（通常来自插件 API）直接定义 block 内容。 -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] -#[serde(rename_all = "camelCase", deny_unknown_fields)] -pub struct PromptDeclaration { - pub block_id: String, - pub title: String, - pub content: String, - #[serde(default)] - pub render_target: PromptDeclarationRenderTarget, - #[serde(default, skip_serializing_if = "is_unspecified_prompt_layer")] - pub layer: PromptLayer, - #[serde(default)] - pub kind: PromptDeclarationKind, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub priority_hint: Option, - #[serde(default)] - pub always_include: bool, - #[serde(default)] - pub source: PromptDeclarationSource, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub capability_name: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub origin: Option, -} - -impl From for astrcode_core::PromptDeclaration { - fn from(value: PromptDeclaration) -> Self { - Self { - block_id: value.block_id, - title: value.title, - content: value.content, - render_target: value.render_target, - layer: value.layer, - kind: value.kind, - priority_hint: value.priority_hint, - always_include: value.always_include, - source: value.source, - capability_name: value.capability_name, - origin: value.origin, - } - } -} - -fn is_unspecified_prompt_layer(layer: &PromptLayer) -> bool { - matches!(layer, PromptLayer::Unspecified) -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn prompt_declaration_round_trip_matches_core_shape() { - let declaration = PromptDeclaration { - block_id: "tool.shell".to_string(), - title: "Shell Tool".to_string(), - content: "use shell carefully".to_string(), - render_target: PromptDeclarationRenderTarget::PrependAssistant, - layer: PromptLayer::Inherited, - kind: PromptDeclarationKind::ToolGuide, - priority_hint: Some(42), - always_include: true, - source: PromptDeclarationSource::Builtin, - capability_name: Some("shell".to_string()), - origin: Some("builtin:test".to_string()), - }; - - let core: astrcode_core::PromptDeclaration = declaration.clone().into(); - let round_trip: PromptDeclaration = core.into(); - - assert_eq!(round_trip, declaration); - } -} diff --git a/crates/adapter-storage/src/session/repository.rs b/crates/adapter-storage/src/session/repository.rs index 7e202775..9f6e4662 100644 --- a/crates/adapter-storage/src/session/repository.rs +++ b/crates/adapter-storage/src/session/repository.rs @@ -378,8 +378,8 @@ mod tests { use std::time::Instant; use astrcode_core::{ - AgentEventContext, LlmMessage, ModeId, Phase, StorageEvent, StorageEventPayload, - UserMessageOrigin, + AgentEventContext, LlmMessage, Phase, StorageEvent, StorageEventPayload, UserMessageOrigin, + mode::ModeId, }; use astrcode_host_session::{ AgentState, EventStore, ProjectionRegistrySnapshot, SessionRecoveryCheckpoint, diff --git a/crates/adapter-tools/Cargo.toml b/crates/adapter-tools/Cargo.toml index 4d9160af..2317b795 100644 --- a/crates/adapter-tools/Cargo.toml +++ b/crates/adapter-tools/Cargo.toml @@ -7,8 +7,10 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } astrcode-host-session = { path = "../host-session" } astrcode-support = { path = "../support" } +astrcode-tool-contract = { path = "../tool-contract" } async-trait.workspace = true base64.workspace = true chrono.workspace = true diff --git a/crates/adapter-tools/src/agent_tools/close_tool.rs b/crates/adapter-tools/src/agent_tools/close_tool.rs index eb93c72c..30c5cf3f 100644 --- a/crates/adapter-tools/src/agent_tools/close_tool.rs +++ b/crates/adapter-tools/src/agent_tools/close_tool.rs @@ -1,8 +1,9 @@ use std::sync::Arc; -use astrcode_core::{ - CloseAgentParams, Result, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{CloseAgentParams, Result}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/agent_tools/collab_result_mapping.rs b/crates/adapter-tools/src/agent_tools/collab_result_mapping.rs index 3c4a9ed5..7607135a 100644 --- a/crates/adapter-tools/src/agent_tools/collab_result_mapping.rs +++ b/crates/adapter-tools/src/agent_tools/collab_result_mapping.rs @@ -10,9 +10,8 @@ //! - `summary` → output（LLM 可见的文本摘要） //! - 整个 CollaborationResult 序列化为 metadata（供前端消费） -use astrcode_core::{ - CollaborationResult, DelegationMetadata, ExecutionResultCommon, ToolExecutionResult, -}; +use astrcode_core::{CollaborationResult, DelegationMetadata, ExecutionResultCommon}; +use astrcode_tool_contract::ToolExecutionResult; use serde_json::json; /// 协作工具的错误结果（参数校验失败等）。 diff --git a/crates/adapter-tools/src/agent_tools/observe_tool.rs b/crates/adapter-tools/src/agent_tools/observe_tool.rs index 37824766..df93da28 100644 --- a/crates/adapter-tools/src/agent_tools/observe_tool.rs +++ b/crates/adapter-tools/src/agent_tools/observe_tool.rs @@ -5,9 +5,10 @@ use std::sync::Arc; -use astrcode_core::{ - ObserveParams, Result, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{ObserveParams, Result}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/agent_tools/result_mapping.rs b/crates/adapter-tools/src/agent_tools/result_mapping.rs index 9bba2d55..8b94acc7 100644 --- a/crates/adapter-tools/src/agent_tools/result_mapping.rs +++ b/crates/adapter-tools/src/agent_tools/result_mapping.rs @@ -6,8 +6,9 @@ use astrcode_core::{ ChildAgentRef, ChildSessionLineageKind, ExecutionContinuation, ExecutionResultCommon, - SubRunResult, SubRunStatus, ToolExecutionResult, + SubRunResult, SubRunStatus, }; +use astrcode_tool_contract::ToolExecutionResult; use serde_json::{Value, json}; const TOOL_NAME: &str = "spawn"; diff --git a/crates/adapter-tools/src/agent_tools/send_tool.rs b/crates/adapter-tools/src/agent_tools/send_tool.rs index 685f220e..0500b5a0 100644 --- a/crates/adapter-tools/src/agent_tools/send_tool.rs +++ b/crates/adapter-tools/src/agent_tools/send_tool.rs @@ -1,8 +1,9 @@ use std::sync::Arc; -use astrcode_core::{ - Result, SendAgentParams, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{Result, SendAgentParams}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/agent_tools/spawn_tool.rs b/crates/adapter-tools/src/agent_tools/spawn_tool.rs index 67e1e763..d54ef294 100644 --- a/crates/adapter-tools/src/agent_tools/spawn_tool.rs +++ b/crates/adapter-tools/src/agent_tools/spawn_tool.rs @@ -1,10 +1,11 @@ use std::sync::Arc; -use astrcode_core::{ - Result, SpawnAgentParams, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, -}; +use astrcode_core::{Result, SpawnAgentParams}; use astrcode_host_session::SubAgentExecutor; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, +}; use async_trait::async_trait; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/agent_tools/tests.rs b/crates/adapter-tools/src/agent_tools/tests.rs index 0227ee67..45e0a7f8 100644 --- a/crates/adapter-tools/src/agent_tools/tests.rs +++ b/crates/adapter-tools/src/agent_tools/tests.rs @@ -7,10 +7,10 @@ use astrcode_core::{ FailedSubRunOutcome, ObserveParams, ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ParentExecutionRef, ProgressParentDeliveryPayload, SendAgentParams, SendToChildParams, SendToParentParams, - SpawnAgentParams, SubRunFailure, SubRunFailureCode, SubRunHandoff, SubRunResult, Tool, - ToolContext, + SpawnAgentParams, SubRunFailure, SubRunFailureCode, SubRunHandoff, SubRunResult, }; use astrcode_host_session::SubAgentExecutor; +use astrcode_tool_contract::{Tool, ToolContext}; use async_trait::async_trait; use serde_json::json; diff --git a/crates/adapter-tools/src/builtin_tools/apply_patch.rs b/crates/adapter-tools/src/builtin_tools/apply_patch.rs index f8baac44..c681564c 100644 --- a/crates/adapter-tools/src/builtin_tools/apply_patch.rs +++ b/crates/adapter-tools/src/builtin_tools/apply_patch.rs @@ -17,9 +17,10 @@ use std::time::Instant; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; diff --git a/crates/adapter-tools/src/builtin_tools/edit_file.rs b/crates/adapter-tools/src/builtin_tools/edit_file.rs index dd35ae0d..ab919600 100644 --- a/crates/adapter-tools/src/builtin_tools/edit_file.rs +++ b/crates/adapter-tools/src/builtin_tools/edit_file.rs @@ -23,9 +23,10 @@ use std::{ time::Instant, }; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; diff --git a/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs b/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs index b1b81127..9e229c4f 100644 --- a/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs +++ b/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs @@ -5,9 +5,11 @@ use std::time::Instant; -use astrcode_core::{ - AstrError, ModeId, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, - ToolDefinition, ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_governance_contract::ModeId; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; @@ -146,7 +148,7 @@ fn mode_metadata( mod tests { use std::sync::{Arc, Mutex}; - use astrcode_core::{StorageEvent, StorageEventPayload}; + use astrcode_core::{StorageEvent, StorageEventPayload, mode::ModeId as StoredModeId}; use super::*; use crate::test_support::test_tool_context_for; @@ -156,7 +158,7 @@ mod tests { } #[async_trait] - impl astrcode_core::ToolEventSink for RecordingSink { + impl astrcode_tool_contract::ToolEventSink for RecordingSink { async fn emit(&self, event: StorageEvent) -> Result<()> { self.events .lock() @@ -192,7 +194,7 @@ mod tests { [StorageEvent { payload: StorageEventPayload::ModeChanged { from, to, .. }, .. - }] if *from == ModeId::code() && *to == ModeId::plan() + }] if *from == StoredModeId::code() && *to == StoredModeId::plan() )); } } diff --git a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs index 00dd521e..8bd3173d 100644 --- a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs +++ b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs @@ -5,12 +5,15 @@ use std::{fs, path::Path, time::Instant}; -use astrcode_core::{ - AstrError, BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, ModeId, Result, - SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, - ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_governance_contract::{ + BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, ModeId, }; use astrcode_host_session::session_plan_content_digest; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, +}; use async_trait::async_trait; use chrono::Utc; use serde_json::json; @@ -318,10 +321,7 @@ fn require_plan_mode_contract(ctx: &ToolContext) -> Result<&BoundModeToolContrac mod tests { use std::sync::{Arc, Mutex}; - use astrcode_core::{ - BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, StorageEvent, - StorageEventPayload, - }; + use astrcode_core::{StorageEvent, StorageEventPayload, mode::ModeId as StoredModeId}; use super::*; use crate::{ @@ -376,7 +376,7 @@ mod tests { } #[async_trait] - impl astrcode_core::ToolEventSink for RecordingSink { + impl astrcode_tool_contract::ToolEventSink for RecordingSink { async fn emit(&self, event: StorageEvent) -> Result<()> { self.events .lock() @@ -462,7 +462,7 @@ mod tests { [StorageEvent { payload: StorageEventPayload::ModeChanged { from, to, .. }, .. - }] if *from == ModeId::plan() && *to == ModeId::code() + }] if *from == StoredModeId::plan() && *to == StoredModeId::code() )); } diff --git a/crates/adapter-tools/src/builtin_tools/find_files.rs b/crates/adapter-tools/src/builtin_tools/find_files.rs index 51f08441..8531089e 100644 --- a/crates/adapter-tools/src/builtin_tools/find_files.rs +++ b/crates/adapter-tools/src/builtin_tools/find_files.rs @@ -15,11 +15,12 @@ use std::{ time::Instant, }; -use astrcode_core::{ - AstrError, CancelToken, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, - ToolDefinition, ToolExecutionResult, ToolPromptMetadata, -}; +use astrcode_core::{AstrError, CancelToken, Result, SideEffect}; use astrcode_support::tool_results::maybe_persist_tool_result; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, +}; use async_trait::async_trait; use serde::Deserialize; use serde_json::json; diff --git a/crates/adapter-tools/src/builtin_tools/fs_common.rs b/crates/adapter-tools/src/builtin_tools/fs_common.rs index ce156da5..a7ed9193 100644 --- a/crates/adapter-tools/src/builtin_tools/fs_common.rs +++ b/crates/adapter-tools/src/builtin_tools/fs_common.rs @@ -24,10 +24,9 @@ use std::{ time::SystemTime, }; -use astrcode_core::{ - AstrError, CancelToken, PersistedToolOutput, PersistedToolResult, Result, ToolContext, -}; +use astrcode_core::{AstrError, CancelToken, PersistedToolOutput, PersistedToolResult, Result}; use astrcode_support::{hostpaths::project_dir, tool_results::maybe_persist_tool_result}; +use astrcode_tool_contract::ToolContext; use serde::{Deserialize, Serialize}; use serde_json::{Value, json}; diff --git a/crates/adapter-tools/src/builtin_tools/grep.rs b/crates/adapter-tools/src/builtin_tools/grep.rs index c8248599..c9b4ba6f 100644 --- a/crates/adapter-tools/src/builtin_tools/grep.rs +++ b/crates/adapter-tools/src/builtin_tools/grep.rs @@ -20,9 +20,10 @@ use std::{ time::Instant, }; -use astrcode_core::{ - AstrError, CancelToken, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, - ToolDefinition, ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, CancelToken, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use log::warn; diff --git a/crates/adapter-tools/src/builtin_tools/list_dir.rs b/crates/adapter-tools/src/builtin_tools/list_dir.rs index 0a8646e3..e6ccca31 100644 --- a/crates/adapter-tools/src/builtin_tools/list_dir.rs +++ b/crates/adapter-tools/src/builtin_tools/list_dir.rs @@ -13,9 +13,10 @@ use std::{fs, path::PathBuf, time::Instant}; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use chrono::{DateTime, Utc}; diff --git a/crates/adapter-tools/src/builtin_tools/mod.rs b/crates/adapter-tools/src/builtin_tools/mod.rs index b37eefcf..ceee852e 100644 --- a/crates/adapter-tools/src/builtin_tools/mod.rs +++ b/crates/adapter-tools/src/builtin_tools/mod.rs @@ -2,7 +2,7 @@ //! //! 所有内置工具的具体实现，每个工具对应一个独立模块。 //! -//! 工具通过实现 `astrcode_core::Tool` trait 提供： +//! 工具通过实现 `astrcode_tool_contract::Tool` trait 提供： //! - `definition()`: 工具名称、描述、JSON Schema 参数定义 //! - `capability_metadata()`: 权限、副作用级别、Prompt 元数据 //! - `execute()`: 实际执行逻辑 diff --git a/crates/adapter-tools/src/builtin_tools/mode_transition.rs b/crates/adapter-tools/src/builtin_tools/mode_transition.rs index b011ad8f..03e87aa6 100644 --- a/crates/adapter-tools/src/builtin_tools/mode_transition.rs +++ b/crates/adapter-tools/src/builtin_tools/mode_transition.rs @@ -3,9 +3,9 @@ //! `enterPlanMode` 与 `exitPlanMode` 都需要发出相同的 `ModeChanged` 事件， //! 这里集中实现，避免工具层对同一条领域事件各自维护一份写法。 -use astrcode_core::{ - AgentEventContext, AstrError, ModeId, Result, StorageEvent, StorageEventPayload, ToolContext, -}; +use astrcode_core::{AgentEventContext, AstrError, Result, StorageEvent, StorageEventPayload}; +use astrcode_governance_contract::ModeId; +use astrcode_tool_contract::ToolContext; use chrono::Utc; pub async fn emit_mode_changed( @@ -24,8 +24,8 @@ pub async fn emit_mode_changed( turn_id: None, agent: AgentEventContext::default(), payload: StorageEventPayload::ModeChanged { - from, - to, + from: from.into(), + to: to.into(), timestamp: Utc::now(), }, }) diff --git a/crates/adapter-tools/src/builtin_tools/read_file.rs b/crates/adapter-tools/src/builtin_tools/read_file.rs index df1fb881..d455e0d6 100644 --- a/crates/adapter-tools/src/builtin_tools/read_file.rs +++ b/crates/adapter-tools/src/builtin_tools/read_file.rs @@ -18,11 +18,12 @@ use std::{ time::Instant, }; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, -}; +use astrcode_core::{AstrError, Result, SideEffect}; use astrcode_support::tool_results::maybe_persist_tool_result; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, +}; use async_trait::async_trait; use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64}; use serde::Deserialize; diff --git a/crates/adapter-tools/src/builtin_tools/session_plan.rs b/crates/adapter-tools/src/builtin_tools/session_plan.rs index 5104d0cb..dd4e0cde 100644 --- a/crates/adapter-tools/src/builtin_tools/session_plan.rs +++ b/crates/adapter-tools/src/builtin_tools/session_plan.rs @@ -9,11 +9,13 @@ use std::{ path::{Path, PathBuf}, }; -use astrcode_core::{AstrError, ModeArtifactDef, Result, ToolContext}; +use astrcode_core::{AstrError, Result}; +use astrcode_governance_contract::ModeArtifactDef; pub use astrcode_host_session::{SessionPlanState, SessionPlanStatus}; use astrcode_host_session::{ WorkflowArtifactRef, WorkflowInstanceState, session_plan_content_digest, }; +use astrcode_tool_contract::ToolContext; use chrono::Utc; use crate::builtin_tools::fs_common::session_dir_for_tool_results; diff --git a/crates/adapter-tools/src/builtin_tools/shell.rs b/crates/adapter-tools/src/builtin_tools/shell.rs index 9b60ec0a..8535e12a 100644 --- a/crates/adapter-tools/src/builtin_tools/shell.rs +++ b/crates/adapter-tools/src/builtin_tools/shell.rs @@ -32,14 +32,15 @@ use std::{ time::{Duration, Instant}, }; -use astrcode_core::{ - AstrError, ResolvedShell, Result, ShellFamily, SideEffect, Tool, ToolCapabilityMetadata, - ToolContext, ToolDefinition, ToolExecutionResult, ToolOutputStream, ToolPromptMetadata, -}; +use astrcode_core::{AstrError, ResolvedShell, Result, ShellFamily, SideEffect}; use astrcode_support::{ shell::{default_shell_label, resolve_shell}, tool_results::maybe_persist_tool_result, }; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolOutputStream, ToolPromptMetadata, +}; use async_trait::async_trait; use serde::Deserialize; use serde_json::json; @@ -680,8 +681,8 @@ fn default_shell_for_prompt() -> String { mod tests { use std::{collections::VecDeque, io, path::Path}; - use astrcode_core::ToolOutputDelta; use astrcode_support::shell::detect_shell_family; + use astrcode_tool_contract::ToolOutputDelta; use tokio::sync::mpsc; use super::*; diff --git a/crates/adapter-tools/src/builtin_tools/skill_tool.rs b/crates/adapter-tools/src/builtin_tools/skill_tool.rs index 27ca6e7a..60248d35 100644 --- a/crates/adapter-tools/src/builtin_tools/skill_tool.rs +++ b/crates/adapter-tools/src/builtin_tools/skill_tool.rs @@ -14,9 +14,10 @@ use std::sync::Arc; -use astrcode_core::{ - Result, SideEffect, SkillCatalog, SkillSpec, Tool, ToolCapabilityMetadata, ToolContext, - ToolDefinition, ToolExecutionResult, ToolPromptMetadata, normalize_skill_name, +use astrcode_core::{Result, SideEffect, SkillCatalog, SkillSpec, normalize_skill_name}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; @@ -204,7 +205,8 @@ fn normalize_skill_path(path: &str) -> String { mod tests { use std::sync::{Arc, RwLock}; - use astrcode_core::{CancelToken, SkillCatalog, SkillSource, SkillSpec, ToolContext}; + use astrcode_core::{CancelToken, SkillCatalog, SkillSource, SkillSpec}; + use astrcode_tool_contract::ToolContext; use serde_json::json; use super::*; diff --git a/crates/adapter-tools/src/builtin_tools/task_write.rs b/crates/adapter-tools/src/builtin_tools/task_write.rs index 3a5b910a..79072d18 100644 --- a/crates/adapter-tools/src/builtin_tools/task_write.rs +++ b/crates/adapter-tools/src/builtin_tools/task_write.rs @@ -6,8 +6,11 @@ use std::time::Instant; use astrcode_core::{ AstrError, ExecutionTaskItem, ExecutionTaskSnapshotMetadata, ExecutionTaskStatus, Result, - SideEffect, TaskSnapshot, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, + SideEffect, TaskSnapshot, +}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; diff --git a/crates/adapter-tools/src/builtin_tools/tool_search.rs b/crates/adapter-tools/src/builtin_tools/tool_search.rs index 25ab38d9..e66c7597 100644 --- a/crates/adapter-tools/src/builtin_tools/tool_search.rs +++ b/crates/adapter-tools/src/builtin_tools/tool_search.rs @@ -10,9 +10,10 @@ use std::sync::{Arc, RwLock}; -use astrcode_core::{ - CapabilitySpec, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{CapabilitySpec, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; @@ -197,7 +198,8 @@ impl Tool for ToolSearchTool { #[cfg(test)] mod tests { - use astrcode_core::{CancelToken, ToolContext}; + use astrcode_core::CancelToken; + use astrcode_tool_contract::ToolContext; use serde_json::json; use super::*; diff --git a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs index a28a954e..20a9b991 100644 --- a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs +++ b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs @@ -5,11 +5,13 @@ use std::{fs, time::Instant}; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, -}; +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_governance_contract::ModeId; use astrcode_host_session::{SessionPlanState, SessionPlanStatus}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, +}; use async_trait::async_trait; use chrono::Utc; use serde::Deserialize; @@ -198,7 +200,7 @@ impl Tool for UpsertSessionPlanTool { archived_at: existing.as_ref().and_then(|state| state.archived_at), }; persist_session_plan_state(&paths.state_path, &state)?; - if ctx.current_mode_id() == &astrcode_core::ModeId::plan() { + if ctx.current_mode_id() == &ModeId::plan() { persist_planning_workflow_state(ctx, Some(&state))?; } @@ -252,7 +254,9 @@ fn slugify(input: &str) -> Option { #[cfg(test)] mod tests { - use astrcode_core::{BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, ModeId}; + use astrcode_governance_contract::{ + BoundModeToolContractSnapshot, ModeArtifactDef, ModeExitGateDef, ModeId, + }; use serde_json::json; use super::*; diff --git a/crates/adapter-tools/src/builtin_tools/write_file.rs b/crates/adapter-tools/src/builtin_tools/write_file.rs index 180f3852..ee3c7865 100644 --- a/crates/adapter-tools/src/builtin_tools/write_file.rs +++ b/crates/adapter-tools/src/builtin_tools/write_file.rs @@ -10,9 +10,10 @@ use std::{path::PathBuf, time::Instant}; -use astrcode_core::{ - AstrError, Result, SideEffect, Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, - ToolExecutionResult, ToolPromptMetadata, +use astrcode_core::{AstrError, Result, SideEffect}; +use astrcode_tool_contract::{ + Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, + ToolPromptMetadata, }; use async_trait::async_trait; use serde::Deserialize; diff --git a/crates/adapter-tools/src/lib.rs b/crates/adapter-tools/src/lib.rs index 3c5aae0c..328ff3d6 100644 --- a/crates/adapter-tools/src/lib.rs +++ b/crates/adapter-tools/src/lib.rs @@ -5,7 +5,7 @@ //! listDir、findFiles、grep、shell、tool_search、Skill //! - **agent tools**（`agent_tools`）：spawn、send、observe、close //! -//! 所有工具均实现 `astrcode_core::Tool` trait。 +//! 所有工具均实现 `astrcode_tool_contract::Tool` trait。 //! //! ## 架构约束 //! diff --git a/crates/adapter-tools/src/test_support.rs b/crates/adapter-tools/src/test_support.rs index 613d9990..34d1fcbe 100644 --- a/crates/adapter-tools/src/test_support.rs +++ b/crates/adapter-tools/src/test_support.rs @@ -1,6 +1,7 @@ use std::path::{Path, PathBuf}; -use astrcode_core::{CancelToken, ToolContext}; +use astrcode_core::CancelToken; +use astrcode_tool_contract::ToolContext; pub fn test_tool_context_for(path: impl Into) -> ToolContext { let cwd = path.into(); diff --git a/crates/agent-runtime/Cargo.toml b/crates/agent-runtime/Cargo.toml index ec7a2b4e..90a1d004 100644 --- a/crates/agent-runtime/Cargo.toml +++ b/crates/agent-runtime/Cargo.toml @@ -7,6 +7,10 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-context-window = { path = "../context-window" } +astrcode-llm-contract = { path = "../llm-contract" } +astrcode-runtime-contract = { path = "../runtime-contract" } +astrcode-tool-contract = { path = "../tool-contract" } async-trait.workspace = true chrono.workspace = true log.workspace = true @@ -17,4 +21,5 @@ futures-util.workspace = true tokio.workspace = true [dev-dependencies] +astrcode-prompt-contract = { path = "../prompt-contract" } tempfile.workspace = true diff --git a/crates/agent-runtime/src/context_window/mod.rs b/crates/agent-runtime/src/context_window/mod.rs index 997ba385..9f58559a 100644 --- a/crates/agent-runtime/src/context_window/mod.rs +++ b/crates/agent-runtime/src/context_window/mod.rs @@ -1,17 +1,5 @@ -//! Runtime-owned context window management. -//! -//! This module contains the local prompt-window work that must happen inside -//! the execution loop: token estimation, tool-result pruning, idle cleanup, -//! aggregate tool-result budgeting, file recovery, and LLM-backed compaction. +pub(crate) use astrcode_context_window::{ + ContextWindowSettings, compaction, file_access, micro_compact, token_usage, tool_result_budget, +}; -pub(crate) mod compaction; -pub(crate) mod file_access; -pub(crate) mod micro_compact; -pub(crate) mod prune_pass; pub(crate) mod request; -pub(crate) mod settings; -pub(crate) mod token_usage; -pub(crate) mod tool_result_budget; -pub(crate) mod tool_results; - -pub(crate) use settings::ContextWindowSettings; diff --git a/crates/agent-runtime/src/context_window/request.rs b/crates/agent-runtime/src/context_window/request.rs index 150b4ef1..682622db 100644 --- a/crates/agent-runtime/src/context_window/request.rs +++ b/crates/agent-runtime/src/context_window/request.rs @@ -1,25 +1,23 @@ use std::{sync::Arc, time::Instant}; +use astrcode_context_window::{ + compaction::{ + auto_compact, build_post_compact_events, build_post_compact_recovery_messages, + compact_config_from_settings, + }, + prune_pass::apply_prune_pass, + token_usage::{PromptTokenSnapshot, build_prompt_snapshot, should_compact}, + tool_result_budget::{ + ApplyToolResultBudgetRequest, ToolResultBudgetStats, apply_tool_result_budget, + }, +}; use astrcode_core::{ AgentEventContext, CompactTrigger, PromptMetricsPayload, StorageEvent, StorageEventPayload, }; +use astrcode_llm_contract::{LlmProvider, LlmRequest, LlmUsage, PromptCacheDiagnostics}; +use astrcode_runtime_contract::RuntimeTurnEvent; -use crate::{ - context_window::{ - compaction::{ - auto_compact, build_post_compact_events, build_post_compact_recovery_messages, - compact_config_from_settings, - }, - prune_pass::apply_prune_pass, - token_usage::{PromptTokenSnapshot, build_prompt_snapshot, should_compact}, - tool_result_budget::{ - ApplyToolResultBudgetRequest, ToolResultBudgetStats, apply_tool_result_budget, - }, - }, - r#loop::{TurnExecutionContext, TurnExecutionResources}, - provider::{LlmProvider, LlmRequest}, - types::RuntimeTurnEvent, -}; +use crate::r#loop::{TurnExecutionContext, TurnExecutionResources}; pub(crate) async fn assemble_runtime_request( execution: &mut TurnExecutionContext, @@ -191,8 +189,8 @@ pub(crate) async fn recover_from_prompt_too_long( pub(crate) fn apply_prompt_metrics_usage( events: &mut [RuntimeTurnEvent], step_index: usize, - usage: Option, - diagnostics: Option, + usage: Option, + diagnostics: Option, ) { if usage.is_none() && diagnostics.is_none() { return; @@ -219,7 +217,42 @@ pub(crate) fn apply_prompt_metrics_usage( metrics.cache_read_input_tokens = Some(saturating_u32(usage.cache_read_input_tokens)); } if let Some(diagnostics) = diagnostics { - metrics.prompt_cache_diagnostics = Some(diagnostics); + metrics.prompt_cache_diagnostics = Some(core_prompt_cache_diagnostics(diagnostics)); + } +} + +fn core_prompt_cache_diagnostics( + diagnostics: PromptCacheDiagnostics, +) -> astrcode_core::PromptCacheDiagnostics { + astrcode_core::PromptCacheDiagnostics { + reasons: diagnostics + .reasons + .into_iter() + .map(|reason| match reason { + astrcode_llm_contract::PromptCacheBreakReason::SystemPromptChanged => { + astrcode_core::PromptCacheBreakReason::SystemPromptChanged + }, + astrcode_llm_contract::PromptCacheBreakReason::ToolSchemasChanged => { + astrcode_core::PromptCacheBreakReason::ToolSchemasChanged + }, + astrcode_llm_contract::PromptCacheBreakReason::ModelChanged => { + astrcode_core::PromptCacheBreakReason::ModelChanged + }, + astrcode_llm_contract::PromptCacheBreakReason::GlobalCacheStrategyChanged => { + astrcode_core::PromptCacheBreakReason::GlobalCacheStrategyChanged + }, + astrcode_llm_contract::PromptCacheBreakReason::CompactedPrompt => { + astrcode_core::PromptCacheBreakReason::CompactedPrompt + }, + astrcode_llm_contract::PromptCacheBreakReason::ToolResultRebudgeted => { + astrcode_core::PromptCacheBreakReason::ToolResultRebudgeted + }, + }) + .collect(), + previous_cache_read_input_tokens: diagnostics.previous_cache_read_input_tokens, + current_cache_read_input_tokens: diagnostics.current_cache_read_input_tokens, + expected_drop: diagnostics.expected_drop, + cache_break_detected: diagnostics.cache_break_detected, } } diff --git a/crates/agent-runtime/src/lib.rs b/crates/agent-runtime/src/lib.rs index e7b12b63..a8385991 100644 --- a/crates/agent-runtime/src/lib.rs +++ b/crates/agent-runtime/src/lib.rs @@ -12,27 +12,21 @@ mod context_window; pub mod hook_dispatch; pub mod r#loop; -pub mod provider; pub mod runtime; pub mod stream; pub mod tool_dispatch; pub mod types; -pub use context_window::tool_result_budget::ToolResultReplacementRecord; +pub use astrcode_context_window::tool_result_budget::ToolResultReplacementRecord; +pub use astrcode_runtime_contract::{ + RuntimeEventSink, RuntimeTurnEvent, TurnIdentity, TurnLoopTransition, TurnStopCause, +}; pub use hook_dispatch::{ HookDispatchOutcome, HookDispatchRequest, HookDispatcher, HookEffect, HookEffectKind, }; pub use r#loop::{ StepOutcome, TurnExecutionContext, TurnExecutionResources, TurnLoop, TurnStepRunner, }; -pub use provider::{ - LlmEvent, LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, LlmUsage, - ModelLimits, PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, - PromptCacheHints, PromptLayerFingerprints, -}; pub use runtime::AgentRuntime; pub use tool_dispatch::{ToolDispatchRequest, ToolDispatcher}; -pub use types::{ - AgentRuntimeExecutionSurface, RuntimeEventSink, RuntimeTurnEvent, TurnIdentity, TurnInput, - TurnLoopTransition, TurnOutput, TurnStopCause, -}; +pub use types::{AgentRuntimeExecutionSurface, TurnInput, TurnOutput}; diff --git a/crates/agent-runtime/src/loop.rs b/crates/agent-runtime/src/loop.rs index ffbac3ae..511f4836 100644 --- a/crates/agent-runtime/src/loop.rs +++ b/crates/agent-runtime/src/loop.rs @@ -7,9 +7,13 @@ use std::{ use astrcode_core::{ AgentEventContext, AstrError, CapabilitySpec, HookEventKey, LlmMessage, ResolvedRuntimeConfig, - StorageEvent, StorageEventPayload, ToolCallRequest, ToolDefinition, ToolExecutionResult, - ToolOutputDelta, UserMessageOrigin, + StorageEvent, StorageEventPayload, ToolCallRequest, UserMessageOrigin, }; +use astrcode_llm_contract::{LlmEventSink, LlmOutput, LlmProvider}; +use astrcode_runtime_contract::{ + RuntimeEventSink, RuntimeTurnEvent, StepError, TurnIdentity, TurnLoopTransition, TurnStopCause, +}; +use astrcode_tool_contract::{ToolDefinition, ToolExecutionResult, ToolOutputDelta}; use async_trait::async_trait; use chrono::Utc; @@ -26,12 +30,8 @@ use crate::{ tool_result_budget::{ToolResultBudgetStats, ToolResultReplacementState}, }, hook_dispatch::{HookDispatchRequest, HookDispatcher, HookEffectKind}, - provider::{LlmEventSink, LlmOutput, LlmProvider}, tool_dispatch::{ToolDispatchRequest, ToolDispatcher}, - types::{ - RuntimeEventSink, RuntimeTurnEvent, StepError, TurnInput, TurnLoopTransition, TurnOutput, - TurnStopCause, - }, + types::{TurnInput, TurnOutput}, }; const OUTPUT_CONTINUATION_PROMPT: &str = "Continue from the exact point where the previous \ @@ -110,8 +110,8 @@ impl std::fmt::Debug for TurnExecutionResources { } impl TurnExecutionResources { - fn turn_identity(&self) -> crate::types::TurnIdentity { - crate::types::TurnIdentity::new( + fn turn_identity(&self) -> TurnIdentity { + TurnIdentity::new( self.session_id.clone(), self.turn_id.clone(), self.agent_id.clone(), @@ -754,7 +754,7 @@ fn tool_definitions_from_specs(specs: &[CapabilitySpec]) -> Arc<[ToolDefinition] } fn flush_pending_events( - event_sink: &dyn crate::types::RuntimeEventSink, + event_sink: &dyn RuntimeEventSink, execution: &mut TurnExecutionContext, emitted_events: &mut Vec, ) { @@ -786,8 +786,8 @@ fn is_immediate_tool_storage_event(event: &RuntimeTurnEvent) -> bool { } fn finalize_turn( - event_sink: &dyn crate::types::RuntimeEventSink, - identity: &crate::types::TurnIdentity, + event_sink: &dyn RuntimeEventSink, + identity: &TurnIdentity, execution: &mut TurnExecutionContext, emitted_events: &mut Vec, stop_cause: TurnStopCause, @@ -826,8 +826,15 @@ mod tests { use astrcode_core::{ AgentEventContext, AstrError, CancelToken, HookEventKey, Result, SubRunStorageMode, - ToolExecutionResult, TurnTerminalKind, + TurnTerminalKind, + }; + use astrcode_llm_contract::{ + LlmEvent, LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, }; + use astrcode_runtime_contract::{ + RuntimeTurnEvent, StepError, TurnLoopTransition, TurnStopCause, + }; + use astrcode_tool_contract::{ToolExecutionResult, ToolOutputDelta, ToolOutputStream}; use async_trait::async_trait; use super::{ @@ -835,14 +842,8 @@ mod tests { }; use crate::{ hook_dispatch::{HookDispatchOutcome, HookDispatchRequest, HookDispatcher, HookEffect}, - provider::{ - LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, - }, tool_dispatch::{ToolDispatchRequest, ToolDispatcher}, - types::{ - AgentRuntimeExecutionSurface, RuntimeTurnEvent, StepError, TurnInput, - TurnLoopTransition, TurnStopCause, - }, + types::{AgentRuntimeExecutionSurface, TurnInput}, }; fn input() -> TurnInput { @@ -1013,7 +1014,7 @@ mod tests { sink: Option, ) -> Result { if let Some(sink) = sink { - sink(crate::provider::LlmEvent::TextDelta("delta".to_string())); + sink(LlmEvent::TextDelta("delta".to_string())); } Ok(self .outputs @@ -1038,7 +1039,7 @@ mod tests { sink: Option, ) -> Result { if let Some(sink) = sink { - sink(crate::provider::LlmEvent::TextDelta("live".to_string())); + sink(LlmEvent::TextDelta("live".to_string())); } if let Some(sender) = self .delta_sent @@ -1145,10 +1146,10 @@ mod tests { impl ToolDispatcher for BlockingStreamingToolDispatcher { async fn dispatch_tool(&self, request: ToolDispatchRequest) -> Result { if let Some(sender) = request.tool_output_sender { - let _ = sender.send(astrcode_core::ToolOutputDelta { + let _ = sender.send(ToolOutputDelta { tool_call_id: request.tool_call.id.clone(), tool_name: request.tool_call.name.clone(), - stream: astrcode_core::ToolOutputStream::Stdout, + stream: ToolOutputStream::Stdout, delta: "tool-live\n".to_string(), }); } diff --git a/crates/agent-runtime/src/runtime.rs b/crates/agent-runtime/src/runtime.rs index 71f75cd2..34ef9ddb 100644 --- a/crates/agent-runtime/src/runtime.rs +++ b/crates/agent-runtime/src/runtime.rs @@ -20,9 +20,10 @@ impl AgentRuntime { #[cfg(test)] mod tests { use astrcode_core::TurnTerminalKind; + use astrcode_runtime_contract::TurnStopCause; use super::AgentRuntime; - use crate::types::{AgentRuntimeExecutionSurface, TurnInput, TurnStopCause}; + use crate::types::{AgentRuntimeExecutionSurface, TurnInput}; #[tokio::test] async fn execute_turn_drives_empty_lifecycle() { diff --git a/crates/agent-runtime/src/tool_dispatch.rs b/crates/agent-runtime/src/tool_dispatch.rs index 6e2dcdf8..74548fcd 100644 --- a/crates/agent-runtime/src/tool_dispatch.rs +++ b/crates/agent-runtime/src/tool_dispatch.rs @@ -1,4 +1,5 @@ -use astrcode_core::{Result, ToolCallRequest, ToolExecutionResult, ToolOutputDelta}; +use astrcode_core::{Result, ToolCallRequest}; +use astrcode_tool_contract::{ToolExecutionResult, ToolOutputDelta}; use async_trait::async_trait; use tokio::sync::mpsc::UnboundedSender; diff --git a/crates/agent-runtime/src/types.rs b/crates/agent-runtime/src/types.rs index 15b36fc3..8f4269f2 100644 --- a/crates/agent-runtime/src/types.rs +++ b/crates/agent-runtime/src/types.rs @@ -1,17 +1,14 @@ use std::{fmt, path::PathBuf, sync::Arc}; +use astrcode_context_window::tool_result_budget::ToolResultReplacementRecord; use astrcode_core::{ - AgentEventContext, AstrError, CancelToken, CapabilitySpec, LlmMessage, ReasoningContent, - ResolvedRuntimeConfig, StorageEvent, TurnTerminalKind, + AgentEventContext, CapabilitySpec, LlmMessage, ResolvedRuntimeConfig, TurnTerminalKind, }; +use astrcode_llm_contract::LlmProvider; +use astrcode_runtime_contract::{RuntimeEventSink, RuntimeTurnEvent, TurnIdentity, TurnStopCause}; use chrono::{DateTime, Utc}; -use crate::{ - context_window::tool_result_budget::ToolResultReplacementRecord, - hook_dispatch::HookDispatcher, - provider::{LlmEvent, LlmProvider}, - tool_dispatch::ToolDispatcher, -}; +use crate::{hook_dispatch::HookDispatcher, tool_dispatch::ToolDispatcher}; /// `host-session -> agent-runtime` 的最小执行面骨架。 #[derive(Debug, Clone, Default, PartialEq)] @@ -25,23 +22,6 @@ pub struct AgentRuntimeExecutionSurface { pub hook_snapshot_id: String, } -/// runtime 事件发射回调。 -/// -/// `agent-runtime` 只通过这个回调把 turn 生命周期事件交还给宿主，不持有 -/// EventStore、SessionState 或 plugin registry。 -pub trait RuntimeEventSink: Send + Sync { - fn emit_event(&self, event: RuntimeTurnEvent); -} - -impl RuntimeEventSink for F -where - F: Fn(RuntimeTurnEvent) + Send + Sync, -{ - fn emit_event(&self, event: RuntimeTurnEvent) { - self(event); - } -} - #[derive(Clone, Default)] pub struct TurnInput { pub surface: AgentRuntimeExecutionSurface, @@ -55,7 +35,7 @@ pub struct TurnInput { pub provider: Option>, pub tool_dispatcher: Option>, pub hook_dispatcher: Option>, - pub cancel: CancelToken, + pub cancel: astrcode_core::CancelToken, pub event_sink: Option>, pub max_output_continuations: usize, pub working_dir: PathBuf, @@ -114,7 +94,7 @@ impl TurnInput { provider: None, tool_dispatcher: None, hook_dispatcher: None, - cancel: CancelToken::new(), + cancel: astrcode_core::CancelToken::new(), event_sink: None, max_output_continuations: 0, working_dir: PathBuf::new(), @@ -150,7 +130,7 @@ impl TurnInput { self } - pub fn with_cancel(mut self, cancel: CancelToken) -> Self { + pub fn with_cancel(mut self, cancel: astrcode_core::CancelToken) -> Self { self.cancel = cancel; self } @@ -194,152 +174,6 @@ impl TurnInput { } } -/// 内部 loop 的“继续下一轮”原因。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TurnLoopTransition { - ToolCycleCompleted, - ReactiveCompactRecovered, - OutputContinuationRequested, -} - -/// turn 停止的细粒度原因。 -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum TurnStopCause { - Completed, - Cancelled, - Error, -} - -impl TurnStopCause { - pub fn terminal_kind(self, error_message: Option<&str>) -> TurnTerminalKind { - match self { - Self::Completed => TurnTerminalKind::Completed, - Self::Cancelled => TurnTerminalKind::Cancelled, - Self::Error => TurnTerminalKind::Error { - message: error_message.unwrap_or("turn failed").to_string(), - }, - } - } -} - -#[derive(Debug, Clone, PartialEq, Eq, Default)] -pub struct TurnIdentity { - pub session_id: String, - pub turn_id: String, - pub agent_id: String, -} - -impl TurnIdentity { - pub fn new(session_id: String, turn_id: String, agent_id: String) -> Self { - Self { - session_id, - turn_id, - agent_id, - } - } -} - -/// 单步执行中产生的错误，保留可重试/致命区分。 -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct StepError { - pub message: String, - pub kind: StepErrorKind, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum StepErrorKind { - Fatal, - Retryable, -} - -impl StepError { - pub fn fatal(message: impl Into) -> Self { - Self { - message: message.into(), - kind: StepErrorKind::Fatal, - } - } - - pub fn retryable(message: impl Into) -> Self { - Self { - message: message.into(), - kind: StepErrorKind::Retryable, - } - } -} - -impl From<&AstrError> for StepError { - fn from(error: &AstrError) -> Self { - Self { - message: error.to_string(), - kind: if error.is_retryable() { - StepErrorKind::Retryable - } else { - StepErrorKind::Fatal - }, - } - } -} - -#[derive(Debug, Clone)] -pub enum RuntimeTurnEvent { - TurnStarted { - identity: TurnIdentity, - }, - ProviderStream { - identity: TurnIdentity, - event: LlmEvent, - }, - AssistantFinal { - identity: TurnIdentity, - content: String, - reasoning: Option, - tool_call_count: usize, - }, - ToolUseRequested { - identity: TurnIdentity, - tool_call_count: usize, - }, - ToolCallStarted { - identity: TurnIdentity, - tool_call_id: String, - tool_name: String, - }, - ToolResultReady { - identity: TurnIdentity, - tool_call_id: String, - tool_name: String, - ok: bool, - }, - HookDispatched { - identity: TurnIdentity, - event: astrcode_core::HookEventKey, - effect_count: usize, - }, - HookPromptAugmented { - identity: TurnIdentity, - event: astrcode_core::HookEventKey, - content: String, - }, - StorageEvent { - event: Box, - }, - StepContinued { - identity: TurnIdentity, - step_index: usize, - transition: TurnLoopTransition, - }, - TurnCompleted { - identity: TurnIdentity, - stop_cause: TurnStopCause, - terminal_kind: TurnTerminalKind, - }, - TurnErrored { - identity: TurnIdentity, - message: String, - }, -} - #[derive(Debug, Clone, Default)] pub struct TurnOutput { pub identity: TurnIdentity, @@ -371,8 +205,9 @@ impl TurnOutput { #[cfg(test)] mod tests { use astrcode_core::{AgentEventContext, SubRunStorageMode, TurnTerminalKind}; + use astrcode_runtime_contract::TurnStopCause; - use super::{AgentRuntimeExecutionSurface, TurnInput, TurnOutput, TurnStopCause}; + use super::{AgentRuntimeExecutionSurface, TurnInput, TurnOutput}; #[test] fn empty_output_keeps_turn_identity() { diff --git a/crates/context-window/Cargo.toml b/crates/context-window/Cargo.toml new file mode 100644 index 00000000..7e1abcdd --- /dev/null +++ b/crates/context-window/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "astrcode-context-window" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +astrcode-llm-contract = { path = "../llm-contract" } +astrcode-runtime-contract = { path = "../runtime-contract" } +astrcode-support = { path = "../support" } +astrcode-tool-contract = { path = "../tool-contract" } +log.workspace = true +regex.workspace = true +serde.workspace = true +serde_json.workspace = true +chrono.workspace = true +tokio.workspace = true diff --git a/crates/context-window/src/compaction.rs b/crates/context-window/src/compaction.rs new file mode 100644 index 00000000..d5d2a939 --- /dev/null +++ b/crates/context-window/src/compaction.rs @@ -0,0 +1,615 @@ +use std::{collections::HashSet, sync::OnceLock}; + +use astrcode_core::{ + AstrError, CancelToken, CompactAppliedMeta, CompactMode, CompactSummaryEnvelope, + CompactTrigger, LlmMessage, Result, StorageEvent, StorageEventPayload, UserMessageOrigin, + format_compact_summary, parse_compact_summary_message, +}; +use astrcode_llm_contract::{LlmProvider, LlmRequest, ModelLimits}; +use astrcode_runtime_contract::RuntimeTurnEvent; +use chrono::{DateTime, Utc}; +use regex::Regex; + +use super::{ + file_access::FileAccessTracker, + settings::ContextWindowSettings, + token_usage::{effective_context_window, estimate_request_tokens}, +}; + +const BASE_COMPACT_PROMPT_TEMPLATE: &str = include_str!("templates/compact/base.md"); +const INCREMENTAL_COMPACT_PROMPT_TEMPLATE: &str = include_str!("templates/compact/incremental.md"); + +#[path = "compaction/protocol.rs"] +mod protocol; +use protocol::*; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct CompactConfig { + pub keep_recent_turns: usize, + pub keep_recent_user_messages: usize, + pub trigger: CompactTrigger, + pub summary_reserve_tokens: usize, + pub max_output_tokens: usize, + pub max_retry_attempts: usize, + pub history_path: Option, + pub custom_instructions: Option, +} + +#[derive(Debug, Clone)] +pub struct CompactResult { + pub messages: Vec, + pub summary: String, + pub recent_user_context_digest: Option, + pub recent_user_context_messages: Vec, + pub preserved_recent_turns: usize, + pub pre_tokens: usize, + pub post_tokens_estimate: usize, + pub messages_removed: usize, + pub tokens_freed: usize, + pub timestamp: DateTime, + pub meta: CompactAppliedMeta, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum CompactionBoundary { + RealUserTurn, + AssistantStep, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +struct CompactionUnit { + start: usize, + boundary: CompactionBoundary, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +enum CompactPromptMode { + Fresh, + Incremental { previous_summary: String }, +} + +impl CompactPromptMode { + fn compact_mode(&self, retry_count: usize) -> CompactMode { + if retry_count > 0 { + CompactMode::RetrySalvage + } else if matches!(self, Self::Incremental { .. }) { + CompactMode::Incremental + } else { + CompactMode::Full + } + } +} + +#[derive(Debug, Clone)] +struct PreparedCompactInput { + messages: Vec, + prompt_mode: CompactPromptMode, + input_units: usize, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +struct CompactContractViolation { + detail: String, +} + +impl CompactContractViolation { + fn from_parsed_output(parsed: &ParsedCompactOutput) -> Option { + if parsed.used_fallback { + return Some(Self { + detail: "response did not contain a strict XML block and required \ + fallback parsing" + .to_string(), + }); + } + if !parsed.has_analysis { + return Some(Self { + detail: "response omitted the required block".to_string(), + }); + } + if !parsed.has_recent_user_context_digest_block { + return Some(Self { + detail: "response omitted the required block" + .to_string(), + }); + } + None + } +} + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +struct CompactRetryState { + salvage_attempts: usize, + contract_retry_count: usize, + contract_repair_feedback: Option, +} + +impl CompactRetryState { + fn schedule_contract_retry(&mut self, detail: String) { + self.contract_retry_count = self.contract_retry_count.saturating_add(1); + self.contract_repair_feedback = Some(detail); + } + + fn note_salvage_attempt(&mut self) { + self.salvage_attempts = self.salvage_attempts.saturating_add(1); + } +} + +#[derive(Debug, Clone)] +struct CompactExecutionResult { + parsed_output: ParsedCompactOutput, + prepared_input: PreparedCompactInput, + retry_state: CompactRetryState, +} + +pub async fn auto_compact( + provider: &dyn LlmProvider, + messages: &[LlmMessage], + compact_prompt_context: Option<&str>, + config: CompactConfig, + cancel: CancelToken, +) -> Result> { + let recent_user_context_messages = + collect_recent_user_context_messages(messages, config.keep_recent_user_messages); + let preserved_recent_turns = config + .keep_recent_turns + .max(config.keep_recent_user_messages) + .max(1); + let Some(mut split) = split_for_compaction(messages, preserved_recent_turns) else { + return Ok(None); + }; + + let pre_tokens = estimate_request_tokens(messages, compact_prompt_context); + let effective_max_output_tokens = config + .max_output_tokens + .min(provider.model_limits().max_output_tokens) + .max(1); + let Some(execution) = execute_compact_request_with_retries( + provider, + &mut split, + compact_prompt_context, + &config, + &recent_user_context_messages, + effective_max_output_tokens, + cancel, + ) + .await? + else { + return Ok(None); + }; + + let summary = { + let summary = sanitize_compact_summary(&execution.parsed_output.summary); + if let Some(history_path) = config.history_path.as_deref() { + CompactSummaryEnvelope::new(summary) + .with_history_path(history_path) + .render_body() + } else { + summary + } + }; + let recent_user_context_digest = execution + .parsed_output + .recent_user_context_digest + .as_deref() + .map(sanitize_recent_user_context_digest) + .filter(|value| !value.is_empty()); + let compacted_messages = compacted_messages( + &summary, + recent_user_context_digest.as_deref(), + &recent_user_context_messages, + split.keep_start, + split.suffix, + ); + + Ok(Some(build_compact_result( + CompactResultInput { + compacted_messages, + summary, + recent_user_context_digest, + recent_user_context_messages, + preserved_recent_turns, + pre_tokens, + messages_removed: split.keep_start, + }, + compact_prompt_context, + &config, + execution, + ))) +} + +pub fn build_post_compact_events( + turn_id: Option<&str>, + agent: &astrcode_core::AgentEventContext, + trigger: CompactTrigger, + compaction: &CompactResult, +) -> Vec { + let _ = ( + &compaction.recent_user_context_digest, + &compaction.recent_user_context_messages, + ); + vec![RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: turn_id.map(str::to_string), + agent: agent.clone(), + payload: StorageEventPayload::CompactApplied { + trigger, + summary: compaction.summary.clone(), + meta: compaction.meta.clone(), + preserved_recent_turns: saturating_u32(compaction.preserved_recent_turns), + pre_tokens: saturating_u32(compaction.pre_tokens), + post_tokens_estimate: saturating_u32(compaction.post_tokens_estimate), + messages_removed: saturating_u32(compaction.messages_removed), + tokens_freed: saturating_u32(compaction.tokens_freed), + timestamp: compaction.timestamp, + }, + }), + }] +} + +pub fn build_post_compact_recovery_messages( + tracker: &FileAccessTracker, + settings: &ContextWindowSettings, +) -> Vec { + tracker.build_recovery_messages(settings.file_recovery_config()) +} + +pub fn compact_config_from_settings( + settings: &ContextWindowSettings, + trigger: CompactTrigger, + history_path: Option, + custom_instructions: Option, +) -> CompactConfig { + CompactConfig { + keep_recent_turns: settings.compact_keep_recent_turns, + keep_recent_user_messages: settings.compact_keep_recent_user_messages, + trigger, + summary_reserve_tokens: settings.summary_reserve_tokens, + max_output_tokens: settings.compact_max_output_tokens, + max_retry_attempts: settings.compact_max_retry_attempts, + history_path, + custom_instructions, + } +} + +pub fn is_prompt_too_long_message(message: &str) -> bool { + contains_ascii_case_insensitive(message, "prompt too long") + || contains_ascii_case_insensitive(message, "context length") + || contains_ascii_case_insensitive(message, "maximum context") + || contains_ascii_case_insensitive(message, "too many tokens") +} + +struct CompactionSplit { + prefix: Vec, + suffix: Vec, + keep_start: usize, +} + +fn split_for_compaction( + messages: &[LlmMessage], + keep_recent_turns: usize, +) -> Option { + if messages.is_empty() { + return None; + } + + let real_user_indices = real_user_turn_indices(messages); + let primary_keep_start = real_user_indices + .len() + .checked_sub(keep_recent_turns.max(1)) + .map(|index| real_user_indices[index]); + let keep_start = primary_keep_start + .filter(|index| *index > 0) + .or_else(|| fallback_keep_start(messages))?; + Some(CompactionSplit { + prefix: messages[..keep_start].to_vec(), + suffix: messages[keep_start..].to_vec(), + keep_start, + }) +} + +fn real_user_turn_indices(messages: &[LlmMessage]) -> Vec { + messages + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } => Some(index), + _ => None, + }) + .collect() +} + +fn fallback_keep_start(messages: &[LlmMessage]) -> Option { + compaction_units(messages) + .into_iter() + .rev() + .find(|unit| unit.boundary == CompactionBoundary::AssistantStep && unit.start > 0) + .map(|unit| unit.start) +} + +fn compaction_units(messages: &[LlmMessage]) -> Vec { + messages + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } => Some(CompactionUnit { + start: index, + boundary: CompactionBoundary::RealUserTurn, + }), + LlmMessage::Assistant { .. } => Some(CompactionUnit { + start: index, + boundary: CompactionBoundary::AssistantStep, + }), + _ => None, + }) + .collect() +} + +fn drop_oldest_compaction_unit(prefix: &mut Vec) -> bool { + let mut boundary_starts = + prefix + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } + | LlmMessage::Assistant { .. } => Some(index), + _ => None, + }); + let _current_start = boundary_starts.next(); + let Some(next_start) = boundary_starts.next() else { + prefix.clear(); + return false; + }; + if next_start == 0 || next_start >= prefix.len() { + prefix.clear(); + return false; + } + + prefix.drain(..next_start); + !prefix.is_empty() +} + +fn trim_prefix_until_compact_request_fits( + prefix: &mut Vec, + compact_prompt_context: Option<&str>, + limits: ModelLimits, + config: &CompactConfig, + recent_user_context_messages: &[RecentUserContextMessage], +) -> bool { + loop { + let prepared_input = prepare_compact_input(prefix); + if prepared_input.messages.is_empty() { + return false; + } + + let system_prompt = render_compact_system_prompt( + compact_prompt_context, + prepared_input.prompt_mode, + config + .max_output_tokens + .min(limits.max_output_tokens) + .max(1), + recent_user_context_messages, + config.custom_instructions.as_deref(), + None, + ); + if compact_request_fits_window( + &prepared_input.messages, + &system_prompt, + limits, + config.summary_reserve_tokens, + ) { + return true; + } + + if !drop_oldest_compaction_unit(prefix) { + return false; + } + } +} + +async fn execute_compact_request_with_retries( + provider: &dyn LlmProvider, + split: &mut CompactionSplit, + compact_prompt_context: Option<&str>, + config: &CompactConfig, + recent_user_context_messages: &[RecentUserContextMessage], + effective_max_output_tokens: usize, + cancel: CancelToken, +) -> Result> { + let mut retry_state = CompactRetryState::default(); + loop { + if !trim_prefix_until_compact_request_fits( + &mut split.prefix, + compact_prompt_context, + provider.model_limits(), + config, + recent_user_context_messages, + ) { + return Err(AstrError::Internal( + "compact request could not fit within summarization window".to_string(), + )); + } + + let prepared_input = prepare_compact_input(&split.prefix); + if prepared_input.messages.is_empty() { + return Ok(None); + } + + let request = LlmRequest::new(prepared_input.messages.clone(), Vec::new(), cancel.clone()) + .with_system(render_compact_system_prompt( + compact_prompt_context, + prepared_input.prompt_mode.clone(), + effective_max_output_tokens, + recent_user_context_messages, + config.custom_instructions.as_deref(), + retry_state.contract_repair_feedback.as_deref(), + )) + .with_max_output_tokens_override(effective_max_output_tokens); + + match provider.generate(request, None).await { + Ok(output) => match parse_compact_output(&output.content) { + Ok(parsed_output) => { + if let Some(violation) = + CompactContractViolation::from_parsed_output(&parsed_output) + { + if retry_state.contract_retry_count < config.max_retry_attempts { + retry_state.schedule_contract_retry(violation.detail); + continue; + } + } + return Ok(Some(CompactExecutionResult { + parsed_output, + prepared_input, + retry_state, + })); + }, + Err(error) if retry_state.contract_retry_count < config.max_retry_attempts => { + retry_state.schedule_contract_retry(error.to_string()); + continue; + }, + Err(error) => return Err(error), + }, + Err(error) + if is_prompt_too_long_message(&error.to_string()) + && retry_state.salvage_attempts < config.max_retry_attempts => + { + retry_state.note_salvage_attempt(); + if !drop_oldest_compaction_unit(&mut split.prefix) { + return Err(AstrError::Internal(error.to_string())); + } + split.keep_start = split.prefix.len(); + }, + Err(error) => return Err(AstrError::Internal(error.to_string())), + } + } +} + +struct CompactResultInput { + compacted_messages: Vec, + summary: String, + recent_user_context_digest: Option, + recent_user_context_messages: Vec, + preserved_recent_turns: usize, + pre_tokens: usize, + messages_removed: usize, +} + +fn build_compact_result( + input: CompactResultInput, + compact_prompt_context: Option<&str>, + _config: &CompactConfig, + execution: CompactExecutionResult, +) -> CompactResult { + let CompactResultInput { + compacted_messages, + summary, + recent_user_context_digest, + recent_user_context_messages, + preserved_recent_turns, + pre_tokens, + messages_removed, + } = input; + let CompactExecutionResult { + parsed_output, + prepared_input, + retry_state, + } = execution; + let post_tokens_estimate = estimate_request_tokens(&compacted_messages, compact_prompt_context); + let output_summary_chars = summary.chars().count().min(u32::MAX as usize) as u32; + + CompactResult { + messages: compacted_messages, + summary, + recent_user_context_digest, + recent_user_context_messages: recent_user_context_messages + .into_iter() + .map(|message| message.content) + .collect(), + preserved_recent_turns, + pre_tokens, + post_tokens_estimate, + messages_removed, + tokens_freed: pre_tokens.saturating_sub(post_tokens_estimate), + timestamp: Utc::now(), + meta: CompactAppliedMeta { + mode: prepared_input + .prompt_mode + .compact_mode(retry_state.salvage_attempts), + instructions_present: false, + fallback_used: parsed_output.used_fallback || retry_state.salvage_attempts > 0, + retry_count: retry_state.salvage_attempts.min(u32::MAX as usize) as u32, + input_units: prepared_input.input_units.min(u32::MAX as usize) as u32, + output_summary_chars, + }, + } +} + +fn compact_request_fits_window( + request_messages: &[LlmMessage], + system_prompt: &str, + limits: ModelLimits, + summary_reserve_tokens: usize, +) -> bool { + estimate_request_tokens(request_messages, Some(system_prompt)) + <= effective_context_window(limits, summary_reserve_tokens) +} + +fn compacted_messages( + summary: &str, + recent_user_context_digest: Option<&str>, + recent_user_context_messages: &[RecentUserContextMessage], + keep_start: usize, + suffix: Vec, +) -> Vec { + let recent_user_context_indices = recent_user_context_messages + .iter() + .map(|message| message.index) + .collect::>(); + let mut messages = vec![LlmMessage::User { + content: format_compact_summary(summary), + origin: UserMessageOrigin::CompactSummary, + }]; + if let Some(digest) = recent_user_context_digest.filter(|value| !value.trim().is_empty()) { + messages.push(LlmMessage::User { + content: digest.trim().to_string(), + origin: UserMessageOrigin::RecentUserContextDigest, + }); + } + for message in recent_user_context_messages { + messages.push(LlmMessage::User { + content: message.content.clone(), + origin: UserMessageOrigin::RecentUserContext, + }); + } + messages.extend( + suffix + .into_iter() + .enumerate() + .filter(|(offset, message)| { + let is_reinjected_real_user_message = matches!( + message, + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } + ) && recent_user_context_indices + .contains(&(keep_start + offset)); + !is_reinjected_real_user_message + }) + .map(|(_, message)| message), + ); + messages +} + +fn saturating_u32(value: usize) -> u32 { + value.min(u32::MAX as usize) as u32 +} diff --git a/crates/context-window/src/compaction/protocol.rs b/crates/context-window/src/compaction/protocol.rs new file mode 100644 index 00000000..c2c213c0 --- /dev/null +++ b/crates/context-window/src/compaction/protocol.rs @@ -0,0 +1,253 @@ +use super::*; + +mod sanitize; +mod xml_parsing; +use sanitize as sanitize_impl; +use xml_parsing as xml_parsing_impl; + +pub(super) fn render_compact_system_prompt( + compact_prompt_context: Option<&str>, + mode: CompactPromptMode, + effective_max_output_tokens: usize, + recent_user_context_messages: &[RecentUserContextMessage], + custom_instructions: Option<&str>, + contract_repair_feedback: Option<&str>, +) -> String { + let incremental_block = match mode { + CompactPromptMode::Fresh => String::new(), + CompactPromptMode::Incremental { previous_summary } => INCREMENTAL_COMPACT_PROMPT_TEMPLATE + .replace("{{PREVIOUS_SUMMARY}}", previous_summary.trim()), + }; + let runtime_context = compact_prompt_context + .filter(|value| !value.trim().is_empty()) + .map(|value| format!("\nCurrent runtime system prompt for context:\n{value}")) + .unwrap_or_default(); + let custom_instruction_block = custom_instructions + .filter(|value| !value.trim().is_empty()) + .map(|value| { + format!( + "\n## Manual Compact Instructions\nFollow these extra requirements for this \ + compact only:\n{value}" + ) + }) + .unwrap_or_default(); + let contract_repair_block = contract_repair_feedback + .filter(|value| !value.trim().is_empty()) + .map(|value| { + format!( + "\n## Contract Repair\nThe previous compact response violated the required XML \ + contract.\nReturn all three XML blocks exactly as specified and do not add any \ + preamble, explanation, or Markdown fence.\nViolation details:\n{value}" + ) + }) + .unwrap_or_default(); + let recent_user_context_block = + render_recent_user_context_candidates(recent_user_context_messages); + + BASE_COMPACT_PROMPT_TEMPLATE + .replace("{{INCREMENTAL_MODE}}", incremental_block.trim()) + .replace("{{CUSTOM_INSTRUCTIONS}}", custom_instruction_block.trim()) + .replace("{{CONTRACT_REPAIR}}", contract_repair_block.trim()) + .replace( + "{{COMPACT_OUTPUT_TOKEN_CAP}}", + &effective_max_output_tokens.to_string(), + ) + .replace( + "{{RECENT_USER_CONTEXT_MESSAGES}}", + recent_user_context_block.trim_end(), + ) + .replace("{{RUNTIME_CONTEXT}}", runtime_context.trim_end()) +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(super) struct RecentUserContextMessage { + pub(super) index: usize, + pub(super) content: String, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(super) struct ParsedCompactOutput { + pub(super) summary: String, + pub(super) recent_user_context_digest: Option, + pub(super) has_analysis: bool, + pub(super) has_recent_user_context_digest_block: bool, + pub(super) used_fallback: bool, +} + +fn render_recent_user_context_candidates(messages: &[RecentUserContextMessage]) -> String { + if messages.is_empty() { + return "(none)".to_string(); + } + + messages + .iter() + .enumerate() + .map(|(position, message)| format!("Message {}:\n{}", position + 1, message.content.trim())) + .collect::>() + .join("\n\n") +} + +pub(super) fn collect_recent_user_context_messages( + messages: &[LlmMessage], + keep_recent_user_messages: usize, +) -> Vec { + if keep_recent_user_messages == 0 { + return Vec::new(); + } + + let mut collected = messages + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + content, + origin: UserMessageOrigin::User, + } => Some(RecentUserContextMessage { + index, + content: content.clone(), + }), + _ => None, + }) + .collect::>(); + let keep_start = collected + .len() + .saturating_sub(keep_recent_user_messages.max(1)); + collected.drain(..keep_start); + collected +} + +pub(super) fn prepare_compact_input(messages: &[LlmMessage]) -> PreparedCompactInput { + let prompt_mode = latest_previous_summary(messages) + .map(|previous_summary| CompactPromptMode::Incremental { previous_summary }) + .unwrap_or(CompactPromptMode::Fresh); + let messages = messages + .iter() + .filter_map(normalize_compaction_message) + .collect::>(); + let input_units = compaction_units(&messages).len().max(1); + PreparedCompactInput { + messages, + prompt_mode, + input_units, + } +} + +fn latest_previous_summary(messages: &[LlmMessage]) -> Option { + messages.iter().rev().find_map(|message| match message { + LlmMessage::User { + content, + origin: UserMessageOrigin::CompactSummary, + } => parse_compact_summary_message(content) + .map(|envelope| sanitize_impl::sanitize_compact_summary(&envelope.summary)), + _ => None, + }) +} + +fn normalize_compaction_message(message: &LlmMessage) -> Option { + match message { + LlmMessage::User { + content, + origin: UserMessageOrigin::User, + } => Some(LlmMessage::User { + content: content.trim().to_string(), + origin: UserMessageOrigin::User, + }), + LlmMessage::User { .. } => None, + LlmMessage::Assistant { + content, + tool_calls, + .. + } => { + let mut lines = Vec::new(); + let visible = collapse_compaction_whitespace(content); + if !visible.is_empty() { + lines.push(visible); + } + if !tool_calls.is_empty() { + let names = tool_calls + .iter() + .map(|call| call.name.trim()) + .filter(|name| !name.is_empty()) + .collect::>(); + if !names.is_empty() { + lines.push(format!("Requested tools: {}", names.join(", "))); + } + } + let normalized = lines.join("\n"); + if normalized.trim().is_empty() { + None + } else { + Some(LlmMessage::Assistant { + content: normalized, + tool_calls: Vec::new(), + reasoning: None, + }) + } + }, + LlmMessage::Tool { + tool_call_id, + content, + } => { + let normalized = normalize_compaction_tool_content(content); + if normalized.is_empty() { + None + } else { + Some(LlmMessage::Tool { + tool_call_id: tool_call_id.clone(), + content: normalized, + }) + } + }, + } +} + +fn collapse_compaction_whitespace(content: &str) -> String { + content + .lines() + .map(str::trim) + .collect::>() + .join("\n") + .split("\n\n\n") + .collect::>() + .join("\n\n") + .trim() + .to_string() +} + +pub(super) fn normalize_compaction_tool_content(content: &str) -> String { + let stripped_child_ref = sanitize_impl::strip_child_agent_reference_hint(content); + let collapsed = collapse_compaction_whitespace(&stripped_child_ref); + if collapsed.is_empty() { + return String::new(); + } + if astrcode_core::is_persisted_output(&collapsed) { + return summarize_persisted_tool_output(&collapsed); + } + collapsed +} + +pub(super) fn sanitize_compact_summary(summary: &str) -> String { + sanitize_impl::sanitize_compact_summary(summary) +} + +pub(super) fn sanitize_recent_user_context_digest(digest: &str) -> String { + sanitize_impl::sanitize_recent_user_context_digest(digest) +} + +pub(super) fn parse_compact_output(content: &str) -> Result { + xml_parsing_impl::parse_compact_output(content) +} + +pub(super) fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool { + xml_parsing_impl::contains_ascii_case_insensitive(haystack, needle) +} + +fn summarize_persisted_tool_output(content: &str) -> String { + let persisted_path = + astrcode_core::tool_result_persist::persisted_output_absolute_path(content) + .unwrap_or_else(|| "unknown persisted path".to_string()); + format!( + "Large tool output was persisted instead of inlined.\nPersisted path: \ + {persisted_path}\nPreserve only the conclusion, referenced path, and any error." + ) +} diff --git a/crates/context-window/src/compaction/sanitize.rs b/crates/context-window/src/compaction/sanitize.rs new file mode 100644 index 00000000..e01377b4 --- /dev/null +++ b/crates/context-window/src/compaction/sanitize.rs @@ -0,0 +1,243 @@ +use super::*; + +type RegexAccessor = fn() -> &'static Regex; + +#[derive(Clone, Copy)] +struct ReplacementRule { + regex: RegexAccessor, + replacement: &'static str, +} + +#[derive(Clone, Copy)] +struct RouteKeyRule { + key: &'static str, + replacement: &'static str, +} + +const SANITIZE_REPLACEMENT_RULES: &[ReplacementRule] = &[ + ReplacementRule { + regex: direct_child_validation_regex, + replacement: "direct-child validation rejected a stale child reference; use the live \ + direct-child snapshot or the latest live tool result instead.", + }, + ReplacementRule { + regex: child_agent_reference_block_regex, + replacement: "Child agent reference metadata existed earlier, but compacted history is \ + not an authoritative routing source.", + }, + ReplacementRule { + regex: exact_agent_instruction_regex, + replacement: "Use only the latest live child snapshot or tool result for agent routing.", + }, + ReplacementRule { + regex: raw_root_agent_id_regex, + replacement: "", + }, + ReplacementRule { + regex: raw_agent_id_regex, + replacement: "", + }, + ReplacementRule { + regex: raw_subrun_id_regex, + replacement: "", + }, + ReplacementRule { + regex: raw_session_id_regex, + replacement: "", + }, +]; + +const ROUTE_KEY_RULES: &[RouteKeyRule] = &[ + RouteKeyRule { + key: "agentId", + replacement: "${key}", + }, + RouteKeyRule { + key: "childAgentId", + replacement: "${key}", + }, + RouteKeyRule { + key: "parentAgentId", + replacement: "${key}", + }, + RouteKeyRule { + key: "subRunId", + replacement: "${key}", + }, + RouteKeyRule { + key: "parentSubRunId", + replacement: "${key}", + }, + RouteKeyRule { + key: "sessionId", + replacement: "${key}", + }, + RouteKeyRule { + key: "childSessionId", + replacement: "${key}", + }, + RouteKeyRule { + key: "openSessionId", + replacement: "${key}", + }, +]; + +struct CompiledRouteKeyRule { + replacement: &'static str, + regex: Regex, +} + +pub(super) fn sanitize_compact_summary(summary: &str) -> String { + let had_route_sensitive_content = summary_has_route_sensitive_content(summary); + let mut sanitized = summary.trim().to_string(); + for rule in SANITIZE_REPLACEMENT_RULES { + sanitized = (rule.regex)() + .replace_all(&sanitized, rule.replacement) + .into_owned(); + } + for rule in route_key_rules() { + sanitized = rule + .regex + .replace_all(&sanitized, rule.replacement) + .into_owned(); + } + sanitized = super::collapse_compaction_whitespace(&sanitized); + if had_route_sensitive_content { + ensure_compact_boundary_section(&sanitized) + } else { + sanitized + } +} + +pub(super) fn sanitize_recent_user_context_digest(digest: &str) -> String { + super::collapse_compaction_whitespace(digest) +} + +fn ensure_compact_boundary_section(summary: &str) -> String { + if summary.contains("## Compact Boundary") { + return summary.to_string(); + } + format!( + "## Compact Boundary\n- Historical `agentId`, `subRunId`, and `sessionId` values from \ + compacted history are non-authoritative.\n- Use the live direct-child snapshot or the \ + latest live tool result / child notification for routing.\n\n{}", + summary.trim() + ) +} + +fn summary_has_route_sensitive_content(summary: &str) -> bool { + SANITIZE_REPLACEMENT_RULES + .iter() + .any(|rule| (rule.regex)().is_match(summary)) + || route_key_rules() + .iter() + .any(|rule| rule.regex.is_match(summary)) +} + +fn child_agent_reference_block_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"(?is)Child agent reference:\s*(?:\n- .*)+") + .expect("child agent reference regex should compile") + }) +} + +fn direct_child_validation_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"(?i)not a direct child of caller[^\n]*") + .expect("direct child validation regex should compile") + }) +} + +fn route_key_rules() -> &'static [CompiledRouteKeyRule] { + static RULES: OnceLock> = OnceLock::new(); + RULES.get_or_init(|| { + ROUTE_KEY_RULES + .iter() + .map(|rule| CompiledRouteKeyRule { + replacement: rule.replacement, + regex: compile_route_key_regex(rule.key), + }) + .collect() + }) +} + +fn compile_route_key_regex(key: &str) -> Regex { + Regex::new(&format!( + r"(?i)(?P`?{key}`?\s*[:=]\s*`?)[^`\s,;\])]+`?" + )) + .expect("route key regex should compile") +} + +fn exact_agent_instruction_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new( + r"(?i)(use this exact `agentid` value[^\n]*|copy it byte-for-byte[^\n]*|keep `agentid` exact[^\n]*)", + ) + .expect("exact agent instruction regex should compile") + }) +} + +fn raw_root_agent_id_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"\broot-agent:[A-Za-z0-9._:-]+\b") + .expect("raw root agent id regex should compile") + }) +} + +fn raw_agent_id_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"\bagent-[A-Za-z0-9._:-]+\b").expect("raw agent id regex should compile") + }) +} + +fn raw_subrun_id_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"\bsubrun-[A-Za-z0-9._:-]+\b").expect("raw subrun regex should compile") + }) +} + +fn raw_session_id_regex() -> &'static Regex { + static REGEX: OnceLock = OnceLock::new(); + REGEX.get_or_init(|| { + Regex::new(r"\bsession-[A-Za-z0-9._:-]+\b").expect("raw session regex should compile") + }) +} + +pub(super) fn strip_child_agent_reference_hint(content: &str) -> String { + let Some((prefix, child_ref_block)) = content.split_once("\n\nChild agent reference:") else { + return content.to_string(); + }; + let mut has_reference_fields = false; + for line in child_ref_block.lines() { + let trimmed = line.trim(); + if trimmed.starts_with("- agentId:") + || trimmed.starts_with("- subRunId:") + || trimmed.starts_with("- openSessionId:") + || trimmed.starts_with("- status:") + { + has_reference_fields = true; + } + } + let child_ref_summary = if has_reference_fields { + "Child agent reference existed in the original tool result. Do not reuse any agentId, \ + subRunId, or sessionId from compacted history; rely on the latest live tool result or \ + current direct-child snapshot instead." + .to_string() + } else { + "Child agent reference metadata existed in the original tool result, but compacted history \ + is not an authoritative source for later agent routing." + .to_string() + }; + let prefix = prefix.trim(); + if prefix.is_empty() { + child_ref_summary + } else { + format!("{prefix}\n\n{child_ref_summary}") + } +} diff --git a/crates/context-window/src/compaction/xml_parsing.rs b/crates/context-window/src/compaction/xml_parsing.rs new file mode 100644 index 00000000..77b549b2 --- /dev/null +++ b/crates/context-window/src/compaction/xml_parsing.rs @@ -0,0 +1,236 @@ +use super::*; + +pub(super) fn parse_compact_output(content: &str) -> Result { + let normalized = strip_outer_markdown_code_fence(content); + let has_analysis = extract_xml_block(&normalized, "analysis").is_some(); + let recent_user_context_digest = extract_xml_block(&normalized, "recent_user_context_digest"); + let has_recent_user_context_digest_block = recent_user_context_digest.is_some(); + if !has_analysis { + log::warn!("compact: missing block in LLM response"); + } + + if has_opening_xml_tag(&normalized, "summary") && !has_closing_xml_tag(&normalized, "summary") { + return Err(AstrError::LlmStreamError( + "compact response missing closing tag".to_string(), + )); + } + if has_opening_xml_tag(&normalized, "recent_user_context_digest") + && !has_closing_xml_tag(&normalized, "recent_user_context_digest") + { + return Err(AstrError::LlmStreamError( + "compact response missing closing tag".to_string(), + )); + } + + let mut used_fallback = false; + let summary = if let Some(summary) = extract_xml_block(&normalized, "summary") { + summary.to_string() + } else if let Some(structured) = extract_structured_summary_fallback(&normalized) { + used_fallback = true; + structured + } else { + let fallback = strip_xml_block(&normalized, "analysis"); + let fallback = clean_compact_fallback_text(&fallback); + if fallback.is_empty() { + return Err(AstrError::LlmStreamError( + "compact response missing block".to_string(), + )); + } + log::warn!("compact: missing block, falling back to raw content"); + used_fallback = true; + fallback + }; + if summary.is_empty() { + return Err(AstrError::LlmStreamError( + "compact summary response was empty".to_string(), + )); + } + + Ok(ParsedCompactOutput { + summary, + recent_user_context_digest: recent_user_context_digest.map(str::to_string), + has_analysis, + has_recent_user_context_digest_block, + used_fallback, + }) +} + +fn extract_structured_summary_fallback(content: &str) -> Option { + let cleaned = clean_compact_fallback_text(content); + let lower = cleaned.to_ascii_lowercase(); + let candidates = ["## summary", "# summary", "summary:"]; + for marker in candidates { + if let Some(start) = lower.find(marker) { + let body = cleaned[start + marker.len()..].trim(); + if !body.is_empty() { + return Some(body.to_string()); + } + } + } + None +} + +fn extract_xml_block<'a>(content: &'a str, tag: &str) -> Option<&'a str> { + xml_block_regex(tag) + .captures(content) + .and_then(|captures| captures.name("body")) + .map(|body| body.as_str().trim()) +} + +fn strip_xml_block(content: &str, tag: &str) -> String { + xml_block_regex(tag).replace(content, "").into_owned() +} + +fn has_opening_xml_tag(content: &str, tag: &str) -> bool { + xml_opening_tag_regex(tag).is_match(content) +} + +fn has_closing_xml_tag(content: &str, tag: &str) -> bool { + xml_closing_tag_regex(tag).is_match(content) +} + +fn strip_markdown_code_fence(content: &str) -> String { + let trimmed = content.trim(); + if !trimmed.starts_with("```") { + return trimmed.to_string(); + } + + let mut lines = trimmed.lines(); + let Some(first_line) = lines.next() else { + return trimmed.to_string(); + }; + if !first_line.trim_start().starts_with("```") { + return trimmed.to_string(); + } + + let body = lines.collect::>().join("\n"); + let body = body.trim_end(); + body.strip_suffix("```").unwrap_or(body).trim().to_string() +} + +fn strip_outer_markdown_code_fence(content: &str) -> String { + let mut current = content.trim().to_string(); + loop { + let stripped = strip_markdown_code_fence(¤t); + if stripped == current { + return current; + } + current = stripped; + } +} + +fn clean_compact_fallback_text(content: &str) -> String { + let without_code_fence = strip_outer_markdown_code_fence(content); + let lines = without_code_fence + .lines() + .map(str::trim_end) + .collect::>(); + let first_meaningful = lines + .iter() + .position(|line| !line.trim().is_empty()) + .unwrap_or(lines.len()); + let cleaned = lines + .into_iter() + .skip(first_meaningful) + .collect::>() + .join("\n") + .trim() + .to_string(); + strip_leading_summary_preamble(&cleaned) +} + +fn strip_leading_summary_preamble(content: &str) -> String { + let mut lines = content.lines(); + let Some(first_line) = lines.next() else { + return String::new(); + }; + let trimmed_first_line = first_line.trim(); + if is_summary_preamble_line(trimmed_first_line) { + return lines.collect::>().join("\n").trim().to_string(); + } + content.trim().to_string() +} + +fn is_summary_preamble_line(line: &str) -> bool { + let normalized = line + .trim_matches(|ch: char| matches!(ch, '*' | '#' | '-' | ':' | ' ')) + .trim(); + normalized.eq_ignore_ascii_case("summary") + || normalized.eq_ignore_ascii_case("here is the summary") + || normalized.eq_ignore_ascii_case("compact summary") + || normalized.eq_ignore_ascii_case("here's the summary") +} + +fn xml_block_regex(tag: &str) -> &'static Regex { + static SUMMARY_REGEX: OnceLock = OnceLock::new(); + static ANALYSIS_REGEX: OnceLock = OnceLock::new(); + static RECENT_USER_CONTEXT_DIGEST_REGEX: OnceLock = OnceLock::new(); + + match tag { + "summary" => SUMMARY_REGEX.get_or_init(|| { + Regex::new(r"(?is)]*)?\s*>(?P.*?)") + .expect("summary regex should compile") + }), + "analysis" => ANALYSIS_REGEX.get_or_init(|| { + Regex::new(r"(?is)]*)?\s*>(?P.*?)") + .expect("analysis regex should compile") + }), + "recent_user_context_digest" => RECENT_USER_CONTEXT_DIGEST_REGEX.get_or_init(|| { + Regex::new( + r"(?is)]*)?\s*>(?P.*?)", + ) + .expect("recent user context digest regex should compile") + }), + other => panic!("unsupported compact xml tag: {other}"), + } +} + +fn xml_opening_tag_regex(tag: &str) -> &'static Regex { + static SUMMARY_REGEX: OnceLock = OnceLock::new(); + static ANALYSIS_REGEX: OnceLock = OnceLock::new(); + static RECENT_USER_CONTEXT_DIGEST_REGEX: OnceLock = OnceLock::new(); + + match tag { + "summary" => SUMMARY_REGEX.get_or_init(|| { + Regex::new(r"(?i)]*)?\s*>") + .expect("summary opening regex should compile") + }), + "analysis" => ANALYSIS_REGEX.get_or_init(|| { + Regex::new(r"(?i)]*)?\s*>") + .expect("analysis opening regex should compile") + }), + "recent_user_context_digest" => RECENT_USER_CONTEXT_DIGEST_REGEX.get_or_init(|| { + Regex::new(r"(?i)]*)?\s*>") + .expect("recent user context digest opening regex should compile") + }), + other => panic!("unsupported compact xml tag: {other}"), + } +} + +fn xml_closing_tag_regex(tag: &str) -> &'static Regex { + static SUMMARY_REGEX: OnceLock = OnceLock::new(); + static ANALYSIS_REGEX: OnceLock = OnceLock::new(); + static RECENT_USER_CONTEXT_DIGEST_REGEX: OnceLock = OnceLock::new(); + + match tag { + "summary" => SUMMARY_REGEX.get_or_init(|| { + Regex::new(r"(?i)").expect("summary closing regex should compile") + }), + "analysis" => ANALYSIS_REGEX.get_or_init(|| { + Regex::new(r"(?i)").expect("analysis closing regex should compile") + }), + "recent_user_context_digest" => RECENT_USER_CONTEXT_DIGEST_REGEX.get_or_init(|| { + Regex::new(r"(?i)") + .expect("recent user context digest closing regex should compile") + }), + other => panic!("unsupported compact xml tag: {other}"), + } +} + +pub(super) fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool { + let needle = needle.as_bytes(); + haystack + .as_bytes() + .windows(needle.len()) + .any(|window| window.eq_ignore_ascii_case(needle)) +} diff --git a/crates/context-window/src/file_access.rs b/crates/context-window/src/file_access.rs new file mode 100644 index 00000000..347cadbf --- /dev/null +++ b/crates/context-window/src/file_access.rs @@ -0,0 +1,238 @@ +use std::{ + collections::{HashMap, VecDeque}, + fs, + path::{Path, PathBuf}, +}; + +use astrcode_core::{LlmMessage, ToolCallRequest, UserMessageOrigin}; +use astrcode_tool_contract::ToolExecutionResult; +use serde::Deserialize; + +use super::token_usage::estimate_text_tokens; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct FileRecoveryConfig { + pub max_tracked_files: usize, + pub max_recovered_files: usize, + pub recovery_token_budget: usize, +} + +#[derive(Debug, Clone)] +struct TrackedFileAccess { + path: PathBuf, + offset: Option, + limit: Option, +} + +#[derive(Debug, Clone, Default)] +pub struct FileAccessTracker { + accesses: VecDeque, + max_tracked_files: usize, +} + +#[derive(Debug, Deserialize)] +struct ReadFileArgs { + path: String, + #[serde(default)] + offset: Option, + #[serde(default)] + limit: Option, +} + +impl FileAccessTracker { + pub fn new(max_tracked_files: usize) -> Self { + Self { + accesses: VecDeque::new(), + max_tracked_files: max_tracked_files.max(1), + } + } + + pub fn seed_from_messages( + messages: &[LlmMessage], + max_tracked_files: usize, + working_dir: &Path, + ) -> Self { + let mut tracker = Self::new(max_tracked_files); + let mut pending_reads = HashMap::::new(); + + for message in messages { + match message { + LlmMessage::Assistant { tool_calls, .. } => { + for call in tool_calls { + if call.name != "readFile" { + continue; + } + if let Ok(args) = serde_json::from_value::(call.args.clone()) + { + pending_reads.insert(call.id.clone(), args); + } + } + }, + LlmMessage::Tool { tool_call_id, .. } => { + let Some(args) = pending_reads.remove(tool_call_id) else { + continue; + }; + tracker.record_access(access_from_args(&args, None, working_dir)); + }, + _ => {}, + } + } + + tracker + } + + pub fn record_tool_result( + &mut self, + tool_call: &ToolCallRequest, + result: &ToolExecutionResult, + working_dir: &Path, + ) { + if tool_call.name != "readFile" || !result.ok { + return; + } + let Ok(args) = serde_json::from_value::(tool_call.args.clone()) else { + return; + }; + self.record_access(access_from_args( + &args, + result.metadata.as_ref(), + working_dir, + )); + } + + pub fn build_recovery_messages(&self, config: FileRecoveryConfig) -> Vec { + let mut recovered = Vec::new(); + let mut remaining_tokens = config.recovery_token_budget.max(1); + + for access in self.accesses.iter().rev() { + if recovered.len() >= config.max_recovered_files.max(1) { + break; + } + + let Some(content) = render_recovery_message(access, remaining_tokens) else { + continue; + }; + let used_tokens = estimate_text_tokens(&content); + if used_tokens > remaining_tokens { + continue; + } + + remaining_tokens = remaining_tokens.saturating_sub(used_tokens); + recovered.push(LlmMessage::User { + content, + origin: UserMessageOrigin::ReactivationPrompt, + }); + } + + recovered.reverse(); + recovered + } + + fn record_access(&mut self, access: TrackedFileAccess) { + self.accesses.retain(|entry| !same_access(entry, &access)); + self.accesses.push_back(access); + + while self.accesses.len() > self.max_tracked_files { + self.accesses.pop_front(); + } + } +} + +fn access_from_args( + args: &ReadFileArgs, + metadata: Option<&serde_json::Value>, + working_dir: &Path, +) -> TrackedFileAccess { + let path = metadata + .and_then(|value| value.get("path")) + .and_then(serde_json::Value::as_str) + .map(PathBuf::from) + .unwrap_or_else(|| resolve_path(working_dir, &args.path)); + + TrackedFileAccess { + path, + offset: args.offset, + limit: args.limit, + } +} + +fn resolve_path(working_dir: &Path, raw_path: &str) -> PathBuf { + let path = PathBuf::from(raw_path); + if path.is_absolute() { + path + } else { + working_dir.join(path) + } +} + +fn same_access(left: &TrackedFileAccess, right: &TrackedFileAccess) -> bool { + left.path == right.path && left.offset == right.offset && left.limit == right.limit +} + +fn render_recovery_message(access: &TrackedFileAccess, budget_tokens: usize) -> Option { + let raw_text = match fs::read_to_string(&access.path) { + Ok(text) => slice_text(text, access.offset, access.limit), + Err(error) => { + return Some(format!( + "Recovered file context after compaction is unavailable.\nPath: {}\nReason: {}", + access.path.display(), + error + )); + }, + }; + + let header = format!( + "Recovered file context after compaction.\nPath: {}\n{}Content:\n", + access.path.display(), + format_range(access.offset, access.limit) + ); + let available_body_tokens = budget_tokens + .saturating_sub(estimate_text_tokens(&header)) + .max(32); + let body = truncate_to_token_budget(&raw_text, available_body_tokens); + if body.trim().is_empty() { + return None; + } + + Some(format!("{header}```text\n{body}\n```")) +} + +fn slice_text(text: String, offset: Option, limit: Option) -> String { + if offset.is_none() && limit.is_none() { + return text; + } + + let lines = text.lines().collect::>(); + let start = offset.unwrap_or(0).min(lines.len()); + let end = limit + .map(|value| start.saturating_add(value).min(lines.len())) + .unwrap_or(lines.len()); + lines[start..end].join("\n") +} + +fn format_range(offset: Option, limit: Option) -> String { + match (offset, limit) { + (Some(offset), Some(limit)) => format!("Line range: {}-{}\n", offset + 1, offset + limit), + (Some(offset), None) => format!("Line start: {}\n", offset + 1), + _ => String::new(), + } +} + +fn truncate_to_token_budget(text: &str, budget_tokens: usize) -> String { + let target_chars = budget_tokens.saturating_mul(4).max(64); + if text.chars().count() <= target_chars { + return text.to_string(); + } + + let mut end = 0usize; + for (index, _) in text.char_indices().take(target_chars) { + end = index; + } + if end == 0 { + return text.chars().take(target_chars).collect::(); + } + format!( + "{}\n[truncated after compaction recovery budget]", + &text[..end] + ) +} diff --git a/crates/context-window/src/lib.rs b/crates/context-window/src/lib.rs new file mode 100644 index 00000000..6a93b989 --- /dev/null +++ b/crates/context-window/src/lib.rs @@ -0,0 +1,10 @@ +pub mod compaction; +pub mod file_access; +pub mod micro_compact; +pub mod prune_pass; +pub mod settings; +pub mod token_usage; +pub mod tool_result_budget; +pub mod tool_results; + +pub use settings::ContextWindowSettings; diff --git a/crates/context-window/src/micro_compact.rs b/crates/context-window/src/micro_compact.rs new file mode 100644 index 00000000..feb0a682 --- /dev/null +++ b/crates/context-window/src/micro_compact.rs @@ -0,0 +1,187 @@ +use std::{ + collections::{HashSet, VecDeque}, + time::{Duration, Instant}, +}; + +use astrcode_core::LlmMessage; +use chrono::{DateTime, Utc}; + +use super::tool_results::tool_call_name_map; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct MicroCompactConfig { + pub gap_threshold: Duration, + pub keep_recent_results: usize, +} + +#[derive(Debug, Clone)] +pub struct MicroCompactOutcome { + pub messages: Vec, +} + +#[derive(Debug, Clone)] +struct TrackedToolResult { + tool_call_id: String, + recorded_at: Instant, +} + +#[derive(Debug, Clone, Default)] +pub struct MicroCompactState { + tracked_results: VecDeque, + last_prompt_activity: Option, +} + +impl MicroCompactState { + pub fn seed_from_messages( + messages: &[LlmMessage], + config: MicroCompactConfig, + now: Instant, + last_assistant_at: Option>, + ) -> Self { + let mut state = Self::default(); + let stale_at = now.checked_sub(config.gap_threshold).unwrap_or(now); + let restored_activity = last_assistant_at + .and_then(|timestamp| instant_from_timestamp(now, timestamp)) + .unwrap_or(stale_at); + + for message in messages { + match message { + LlmMessage::Assistant { .. } | LlmMessage::Tool { .. } => { + state.last_prompt_activity = Some(restored_activity); + }, + _ => {}, + } + + let LlmMessage::Tool { tool_call_id, .. } = message else { + continue; + }; + state.tracked_results.push_back(TrackedToolResult { + tool_call_id: tool_call_id.clone(), + recorded_at: stale_at, + }); + } + + state + } + + pub fn record_tool_result(&mut self, tool_call_id: impl Into, now: Instant) { + let tool_call_id = tool_call_id.into(); + self.tracked_results + .retain(|entry| entry.tool_call_id != tool_call_id); + self.tracked_results.push_back(TrackedToolResult { + tool_call_id, + recorded_at: now, + }); + self.last_prompt_activity = Some(now); + } + + pub fn record_assistant_activity(&mut self, now: Instant) { + self.last_prompt_activity = Some(now); + } + + pub fn apply_if_idle( + &mut self, + messages: &[LlmMessage], + clearable_tools: &HashSet, + config: MicroCompactConfig, + now: Instant, + ) -> MicroCompactOutcome { + self.retain_live_tool_results(messages); + + let Some(last_activity) = self.last_prompt_activity else { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + }; + + if now.duration_since(last_activity) < config.gap_threshold { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let keep_recent_results = config.keep_recent_results.max(1); + if self.tracked_results.len() <= keep_recent_results { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let tool_call_names = tool_call_name_map(messages); + let protected_ids = self + .tracked_results + .iter() + .rev() + .take(keep_recent_results) + .map(|entry| entry.tool_call_id.as_str()) + .collect::>(); + + let stale_ids = self + .tracked_results + .iter() + .filter(|entry| !protected_ids.contains(entry.tool_call_id.as_str())) + .filter(|entry| now.duration_since(entry.recorded_at) >= config.gap_threshold) + .filter_map(|entry| { + tool_call_names + .get(&entry.tool_call_id) + .filter(|tool_name| clearable_tools.contains(*tool_name)) + .map(|_| entry.tool_call_id.clone()) + }) + .collect::>(); + + if stale_ids.is_empty() { + return MicroCompactOutcome { + messages: messages.to_vec(), + }; + } + + let mut compacted = messages.to_vec(); + for message in &mut compacted { + let LlmMessage::Tool { + tool_call_id, + content, + } = message + else { + continue; + }; + + if !stale_ids.contains(tool_call_id) || is_micro_compacted(content) { + continue; + } + + let tool_name = tool_call_names + .get(tool_call_id) + .map(String::as_str) + .unwrap_or("tool"); + *content = format!( + "[micro-compacted stale tool result from '{tool_name}' after idle gap; rerun the \ + tool if exact output is needed]" + ); + } + + MicroCompactOutcome { + messages: compacted, + } + } + + fn retain_live_tool_results(&mut self, messages: &[LlmMessage]) { + let live_tool_ids = messages + .iter() + .filter_map(|message| match message { + LlmMessage::Tool { tool_call_id, .. } => Some(tool_call_id.as_str()), + _ => None, + }) + .collect::>(); + self.tracked_results + .retain(|entry| live_tool_ids.contains(entry.tool_call_id.as_str())); + } +} + +fn is_micro_compacted(content: &str) -> bool { + content.contains("[micro-compacted stale tool result") +} + +fn instant_from_timestamp(now: Instant, timestamp: DateTime) -> Option { + let elapsed = (Utc::now() - timestamp).to_std().ok()?; + now.checked_sub(elapsed).or(Some(now)) +} diff --git a/crates/context-window/src/mod.rs b/crates/context-window/src/mod.rs new file mode 100644 index 00000000..997ba385 --- /dev/null +++ b/crates/context-window/src/mod.rs @@ -0,0 +1,17 @@ +//! Runtime-owned context window management. +//! +//! This module contains the local prompt-window work that must happen inside +//! the execution loop: token estimation, tool-result pruning, idle cleanup, +//! aggregate tool-result budgeting, file recovery, and LLM-backed compaction. + +pub(crate) mod compaction; +pub(crate) mod file_access; +pub(crate) mod micro_compact; +pub(crate) mod prune_pass; +pub(crate) mod request; +pub(crate) mod settings; +pub(crate) mod token_usage; +pub(crate) mod tool_result_budget; +pub(crate) mod tool_results; + +pub(crate) use settings::ContextWindowSettings; diff --git a/crates/context-window/src/prune_pass.rs b/crates/context-window/src/prune_pass.rs new file mode 100644 index 00000000..4a393f93 --- /dev/null +++ b/crates/context-window/src/prune_pass.rs @@ -0,0 +1,100 @@ +use std::collections::HashSet; + +use astrcode_core::{LlmMessage, UserMessageOrigin}; + +use super::tool_results::tool_call_name_map; + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct PruneStats { + pub truncated_tool_results: usize, + pub cleared_tool_results: usize, +} + +#[derive(Debug, Clone)] +pub struct PruneOutcome { + pub messages: Vec, + pub stats: PruneStats, +} + +pub fn apply_prune_pass( + messages: &[LlmMessage], + clearable_tools: &HashSet, + max_tool_result_bytes: usize, + keep_recent_turns: usize, +) -> PruneOutcome { + let tool_call_names = tool_call_name_map(messages); + let keep_start = recent_turn_start_index(messages, keep_recent_turns.max(1)); + let mut truncated_tool_results = 0usize; + let mut cleared_tool_results = 0usize; + let mut compacted = messages.to_vec(); + + for (index, message) in compacted.iter_mut().enumerate() { + let LlmMessage::Tool { + tool_call_id, + content, + } = message + else { + continue; + }; + + if content.len() > max_tool_result_bytes { + *content = truncate_tool_content(content, max_tool_result_bytes); + truncated_tool_results += 1; + } + + if index >= keep_start { + continue; + } + + let Some(tool_name) = tool_call_names.get(tool_call_id) else { + continue; + }; + if clearable_tools.contains(tool_name) { + *content = format!( + "[cleared older tool result from '{tool_name}' to reduce prompt size; reload it \ + if needed]" + ); + cleared_tool_results += 1; + } + } + + PruneOutcome { + messages: compacted, + stats: PruneStats { + truncated_tool_results, + cleared_tool_results, + }, + } +} + +fn truncate_tool_content(content: &str, max_bytes: usize) -> String { + let total_bytes = content.len(); + let mut visible_bytes = max_bytes.saturating_sub(96).max(64).min(total_bytes); + while !content.is_char_boundary(visible_bytes) { + visible_bytes = visible_bytes.saturating_sub(1); + } + let visible = &content[..visible_bytes]; + format!( + "[truncated: original {total_bytes} bytes, showing first {visible_bytes} bytes]\n{visible}" + ) +} + +fn recent_turn_start_index(messages: &[LlmMessage], requested_recent_turns: usize) -> usize { + let user_turn_indices = messages + .iter() + .enumerate() + .filter_map(|(index, message)| match message { + LlmMessage::User { + origin: UserMessageOrigin::User, + .. + } => Some(index), + _ => None, + }) + .collect::>(); + if user_turn_indices.is_empty() { + return messages.len(); + } + + let keep_turns = requested_recent_turns.min(user_turn_indices.len()).max(1); + user_turn_indices[user_turn_indices.len() - keep_turns] +} diff --git a/crates/context-window/src/request.rs b/crates/context-window/src/request.rs new file mode 100644 index 00000000..150b4ef1 --- /dev/null +++ b/crates/context-window/src/request.rs @@ -0,0 +1,277 @@ +use std::{sync::Arc, time::Instant}; + +use astrcode_core::{ + AgentEventContext, CompactTrigger, PromptMetricsPayload, StorageEvent, StorageEventPayload, +}; + +use crate::{ + context_window::{ + compaction::{ + auto_compact, build_post_compact_events, build_post_compact_recovery_messages, + compact_config_from_settings, + }, + prune_pass::apply_prune_pass, + token_usage::{PromptTokenSnapshot, build_prompt_snapshot, should_compact}, + tool_result_budget::{ + ApplyToolResultBudgetRequest, ToolResultBudgetStats, apply_tool_result_budget, + }, + }, + r#loop::{TurnExecutionContext, TurnExecutionResources}, + provider::{LlmProvider, LlmRequest}, + types::RuntimeTurnEvent, +}; + +pub(crate) async fn assemble_runtime_request( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, +) -> astrcode_core::Result { + let budget_outcome = apply_tool_result_budget(ApplyToolResultBudgetRequest { + messages: &execution.messages, + session_id: &resources.session_id, + working_dir: &resources.working_dir, + replacement_state: &mut execution.tool_result_replacement_state, + aggregate_budget_bytes: resources.settings.aggregate_result_bytes_budget, + turn_id: &resources.turn_id, + agent: &resources.agent, + })?; + execution + .pending_events + .extend( + budget_outcome + .events + .into_iter() + .map(|event| RuntimeTurnEvent::StorageEvent { + event: Box::new(event), + }), + ); + accumulate_tool_result_budget_stats( + &mut execution.tool_result_budget_stats, + budget_outcome.stats, + ); + + let micro_outcome = execution.micro_compact_state.apply_if_idle( + &budget_outcome.messages, + &resources.clearable_tools, + resources.settings.micro_compact_config(), + Instant::now(), + ); + + let prune_outcome = apply_prune_pass( + µ_outcome.messages, + &resources.clearable_tools, + resources.settings.tool_result_max_bytes, + resources.settings.compact_keep_recent_turns, + ); + let mut messages = prune_outcome.messages; + + let Some(provider) = &resources.provider else { + execution.messages = messages.clone(); + return Ok(LlmRequest::new( + messages, + Arc::clone(&resources.tools), + resources.cancel.clone(), + )); + }; + + let mut snapshot = build_prompt_snapshot( + &execution.token_tracker, + &messages, + None, + provider.model_limits(), + resources.settings.compact_threshold_percent, + resources.settings.summary_reserve_tokens, + resources.settings.reserved_context_size, + ); + + if should_compact(snapshot) { + if resources.settings.auto_compact_enabled { + if let Some(compaction) = auto_compact( + provider.as_ref(), + &messages, + None, + compact_config_from_settings( + &resources.settings, + CompactTrigger::Auto, + resources.events_history_path.clone(), + None, + ), + resources.cancel.clone(), + ) + .await? + { + messages = compaction.messages.clone(); + messages.extend(build_post_compact_recovery_messages( + &execution.file_access_tracker, + &resources.settings, + )); + execution.pending_events.extend(build_post_compact_events( + Some(&resources.turn_id), + &resources.agent, + CompactTrigger::Auto, + &compaction, + )); + execution.auto_compaction_count = execution.auto_compaction_count.saturating_add(1); + snapshot = build_prompt_snapshot( + &execution.token_tracker, + &messages, + None, + provider.model_limits(), + resources.settings.compact_threshold_percent, + resources.settings.summary_reserve_tokens, + resources.settings.reserved_context_size, + ); + } + } else { + log::warn!( + "turn {} step {}: context tokens ({}) exceed threshold ({}) but auto compact is \ + disabled", + resources.turn_id, + execution.step_index, + snapshot.context_tokens, + snapshot.threshold_tokens, + ); + } + } + + execution.pending_events.push(prompt_metrics_runtime_event( + &resources.turn_id, + &resources.agent, + execution.step_index, + snapshot, + prune_outcome.stats.truncated_tool_results, + provider.supports_cache_metrics(), + )); + execution.messages = messages.clone(); + + Ok(LlmRequest::new( + messages, + Arc::clone(&resources.tools), + resources.cancel.clone(), + )) +} + +pub(crate) async fn recover_from_prompt_too_long( + execution: &mut TurnExecutionContext, + resources: &TurnExecutionResources, + provider: &dyn LlmProvider, +) -> astrcode_core::Result { + execution.reactive_compact_attempts = execution.reactive_compact_attempts.saturating_add(1); + let Some(compaction) = auto_compact( + provider, + &execution.messages, + None, + compact_config_from_settings( + &resources.settings, + CompactTrigger::Auto, + resources.events_history_path.clone(), + None, + ), + resources.cancel.clone(), + ) + .await? + else { + return Ok(false); + }; + + let mut messages = compaction.messages.clone(); + messages.extend(build_post_compact_recovery_messages( + &execution.file_access_tracker, + &resources.settings, + )); + execution.messages = messages; + execution.pending_events.extend(build_post_compact_events( + Some(&resources.turn_id), + &resources.agent, + CompactTrigger::Auto, + &compaction, + )); + Ok(true) +} + +pub(crate) fn apply_prompt_metrics_usage( + events: &mut [RuntimeTurnEvent], + step_index: usize, + usage: Option, + diagnostics: Option, +) { + if usage.is_none() && diagnostics.is_none() { + return; + } + + let step_index = saturating_u32(step_index); + let Some(metrics) = events.iter_mut().rev().find_map(|event| { + let RuntimeTurnEvent::StorageEvent { event } = event else { + return None; + }; + let StorageEventPayload::PromptMetrics { metrics } = &mut event.payload else { + return None; + }; + (metrics.step_index == step_index).then_some(metrics) + }) else { + return; + }; + + if let Some(usage) = usage { + metrics.provider_input_tokens = Some(saturating_u32(usage.input_tokens)); + metrics.provider_output_tokens = Some(saturating_u32(usage.output_tokens)); + metrics.cache_creation_input_tokens = + Some(saturating_u32(usage.cache_creation_input_tokens)); + metrics.cache_read_input_tokens = Some(saturating_u32(usage.cache_read_input_tokens)); + } + if let Some(diagnostics) = diagnostics { + metrics.prompt_cache_diagnostics = Some(diagnostics); + } +} + +fn accumulate_tool_result_budget_stats( + total: &mut ToolResultBudgetStats, + next: ToolResultBudgetStats, +) { + total.replacement_count = total + .replacement_count + .saturating_add(next.replacement_count); + total.reapply_count = total.reapply_count.saturating_add(next.reapply_count); + total.bytes_saved = total.bytes_saved.saturating_add(next.bytes_saved); + total.over_budget_message_count = total + .over_budget_message_count + .saturating_add(next.over_budget_message_count); +} + +fn prompt_metrics_runtime_event( + turn_id: &str, + agent: &AgentEventContext, + step_index: usize, + snapshot: PromptTokenSnapshot, + truncated_tool_results: usize, + provider_cache_metrics_supported: bool, +) -> RuntimeTurnEvent { + RuntimeTurnEvent::StorageEvent { + event: Box::new(StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::PromptMetrics { + metrics: PromptMetricsPayload { + step_index: saturating_u32(step_index), + estimated_tokens: saturating_u32(snapshot.context_tokens), + context_window: saturating_u32(snapshot.context_window), + effective_window: saturating_u32(snapshot.effective_window), + threshold_tokens: saturating_u32(snapshot.threshold_tokens), + truncated_tool_results: saturating_u32(truncated_tool_results), + provider_input_tokens: None, + provider_output_tokens: None, + cache_creation_input_tokens: None, + cache_read_input_tokens: None, + provider_cache_metrics_supported, + prompt_cache_reuse_hits: 0, + prompt_cache_reuse_misses: 0, + prompt_cache_unchanged_layers: Vec::new(), + prompt_cache_diagnostics: None, + }, + }, + }), + } +} + +fn saturating_u32(value: usize) -> u32 { + value.min(u32::MAX as usize) as u32 +} diff --git a/crates/context-window/src/settings.rs b/crates/context-window/src/settings.rs new file mode 100644 index 00000000..cd317c2a --- /dev/null +++ b/crates/context-window/src/settings.rs @@ -0,0 +1,67 @@ +use std::time::Duration; + +use astrcode_core::ResolvedRuntimeConfig; + +use super::{file_access::FileRecoveryConfig, micro_compact::MicroCompactConfig}; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ContextWindowSettings { + pub auto_compact_enabled: bool, + pub compact_threshold_percent: u8, + pub reserved_context_size: usize, + pub summary_reserve_tokens: usize, + pub compact_max_output_tokens: usize, + pub compact_max_retry_attempts: usize, + pub tool_result_max_bytes: usize, + pub compact_keep_recent_turns: usize, + pub compact_keep_recent_user_messages: usize, + pub max_tracked_files: usize, + pub max_recovered_files: usize, + pub recovery_token_budget: usize, + pub aggregate_result_bytes_budget: usize, + pub micro_compact_gap_threshold: Duration, + pub micro_compact_keep_recent_results: usize, +} + +impl ContextWindowSettings { + pub fn micro_compact_config(&self) -> MicroCompactConfig { + MicroCompactConfig { + gap_threshold: self.micro_compact_gap_threshold, + keep_recent_results: self.micro_compact_keep_recent_results, + } + } + + pub fn file_recovery_config(&self) -> FileRecoveryConfig { + FileRecoveryConfig { + max_tracked_files: self.max_tracked_files, + max_recovered_files: self.max_recovered_files, + recovery_token_budget: self.recovery_token_budget, + } + } +} + +impl From<&ResolvedRuntimeConfig> for ContextWindowSettings { + fn from(config: &ResolvedRuntimeConfig) -> Self { + Self { + auto_compact_enabled: config.auto_compact_enabled, + compact_threshold_percent: config.compact_threshold_percent, + reserved_context_size: config.reserved_context_size.max(1), + summary_reserve_tokens: config.summary_reserve_tokens.max(1), + compact_max_output_tokens: config.compact_max_output_tokens.max(1), + compact_max_retry_attempts: usize::from(config.compact_max_retry_attempts.max(1)), + tool_result_max_bytes: config.tool_result_max_bytes, + compact_keep_recent_turns: usize::from(config.compact_keep_recent_turns), + compact_keep_recent_user_messages: usize::from( + config.compact_keep_recent_user_messages.max(1), + ), + max_tracked_files: config.max_tracked_files, + max_recovered_files: config.max_recovered_files.max(1), + recovery_token_budget: config.recovery_token_budget.max(1), + aggregate_result_bytes_budget: config.aggregate_result_bytes_budget.max(1), + micro_compact_gap_threshold: Duration::from_secs( + config.micro_compact_gap_threshold_secs.max(1), + ), + micro_compact_keep_recent_results: config.micro_compact_keep_recent_results.max(1), + } + } +} diff --git a/crates/context-window/src/templates/compact/base.md b/crates/context-window/src/templates/compact/base.md new file mode 100644 index 00000000..32a332fc --- /dev/null +++ b/crates/context-window/src/templates/compact/base.md @@ -0,0 +1,113 @@ +You are a context summarization assistant for a coding-agent session. +Your summary will be placed at the start of a continuing session so another agent can continue seamlessly. + +## CRITICAL RULES +**DO NOT CALL ANY TOOLS.** This is for summary generation only. +**Do NOT continue the conversation.** Only output the structured summary. +**Do NOT wrap the answer in Markdown code fences.** +**Even if context is incomplete, still return ``, ``, and `` blocks.** +**The entire output must stay within {{COMPACT_OUTPUT_TOKEN_CAP}} tokens.** + +## Compression Priorities (highest -> lowest) +1. Current task state and exact next step +2. Errors, failures, and how they were resolved +3. User constraints and corrections +4. Code changes, exact file paths, and exact function/type names +5. Important decisions and why they were made +6. Discoveries about the codebase or environment that matter for continuation + +## Compression Rules +**MUST KEEP:** Error messages, stack traces, working solutions, current task, exact file paths, function names +**DO NOT PRESERVE AS AUTHORITATIVE FACTS:** Historical `agentId`, `subRunId`, `sessionId`, copied child reference payloads, or stale direct-child ownership errors from compacted history +**MERGE:** Similar discussions into single summary points +**REMOVE:** Redundant explanations, failed attempts (keep only lessons learned), boilerplate code +**CONDENSE:** Long code blocks -> signatures + key logic; long explanations -> bullet points +**FOR RECENT USER CONTEXT DIGEST:** Focus only on current goal, newly added constraints/corrections, and the most recent explicit next step. +**IGNORE AS NOISE:** Tool outputs, tool echoes, file recovery content, internal helper prompts, and repeated restatements of the recent user messages. + +{{INCREMENTAL_MODE}} + +{{CUSTOM_INSTRUCTIONS}} + +{{CONTRACT_REPAIR}} + +## Recently Preserved Real User Messages +These messages will be preserved verbatim after compaction. Do not restate them in full inside the main summary. + +{{RECENT_USER_CONTEXT_MESSAGES}} + +## Output Format +Return exactly three XML blocks: + + +[Self-check before writing] +- Did I cover ALL user messages? +- Is the current task state accurate? +- Are all errors and their solutions captured? +- Are file paths and function names exact? + + + + +## Goal +- [What the user is trying to accomplish] + +## Constraints & Preferences +- [User-specified constraints, preferences, requirements] +- [Or "(none)" if not mentioned] + +## Progress +### Done +- [x] [Completed tasks with brief outcome] + +### In Progress +- [ ] [Current work with status] + +### Blocked +- [Issues preventing progress, or "(none)"] + +## Key Decisions +- **[Decision]**: [Rationale - why this choice was made] + +## Discoveries +- [Important learnings about codebase/APIs/constraints that future agent should know] + +## Files +### Read +- `path/to/file` - [Why read, key findings] + +### Modified/Created +- `path/to/file` - [What changed, why] + +## Errors & Fixes +- **Error**: [Exact error message/stack trace] + - **Cause**: [Root cause] + - **Fix**: [How it was resolved] + +## Context for Continuing Work +1. [Ordered list of what should happen next] + +## Critical Context +[Any essential information not covered above, or "(none)"] + + + + +- [Very short digest of the recent real user messages, ideally 2-4 bullets total] +- [If there are no recent user messages, write "(none)"] + + +## Rules +- Output **only** the , , and blocks - no preamble, no closing remarks. +- Be concise. Prefer bullet points over paragraphs. +- Ignore synthetic compact-summary helper messages. +- Write in third-person, factual tone. Do not address the end user. +- Preserve exact file paths, function names, error messages - never paraphrase these. +- Keep `` extremely short. +- Keep `` extremely short and do not quote the preserved messages verbatim unless unavoidable. +- Preserve child-agent routing state semantically, but redact exact historical `agentId`, `subRunId`, and `sessionId` values from compacted history. +- If child-agent routing matters, say that the next agent must rely on the latest live child snapshot or tool result instead of historical IDs. +- If a value is unknown, write a short best-effort placeholder instead of omitting the section. +- If a section has no content, write "(none)" rather than omitting it. + +{{RUNTIME_CONTEXT}} diff --git a/crates/context-window/src/templates/compact/incremental.md b/crates/context-window/src/templates/compact/incremental.md new file mode 100644 index 00000000..c249338e --- /dev/null +++ b/crates/context-window/src/templates/compact/incremental.md @@ -0,0 +1,11 @@ +## Incremental Mode +A prior compact summary already exists below. Do NOT rewrite from scratch. +1. Read the previous summary carefully. +2. Identify what is NEW since the last summary. +3. Merge new information into the existing summary. +4. Preserve important details from the previous summary unless they are clearly obsolete. +5. Output the complete merged summary, not a delta. + + +{{PREVIOUS_SUMMARY}} + diff --git a/crates/context-window/src/token_usage.rs b/crates/context-window/src/token_usage.rs new file mode 100644 index 00000000..4b3138fd --- /dev/null +++ b/crates/context-window/src/token_usage.rs @@ -0,0 +1,142 @@ +use astrcode_core::{LlmMessage, UserMessageOrigin}; +use astrcode_llm_contract::{LlmUsage, ModelLimits}; + +const MESSAGE_BASE_TOKENS: usize = 6; +const TOOL_CALL_BASE_TOKENS: usize = 12; +const REQUEST_ESTIMATE_PADDING_NUMERATOR: usize = 4; +const REQUEST_ESTIMATE_PADDING_DENOMINATOR: usize = 3; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PromptTokenSnapshot { + pub context_tokens: usize, + pub budget_tokens: usize, + pub context_window: usize, + pub effective_window: usize, + pub threshold_tokens: usize, + pub remaining_context_tokens: usize, + pub reserved_context_size: usize, +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct TokenUsageTracker { + anchored_budget_tokens: usize, +} + +impl TokenUsageTracker { + pub fn record_usage(&mut self, usage: Option) { + let Some(usage) = usage else { + return; + }; + self.anchored_budget_tokens = self + .anchored_budget_tokens + .saturating_add(usage.total_tokens()); + } + + pub fn budget_tokens(&self, estimated_context_tokens: usize) -> usize { + if self.anchored_budget_tokens > 0 { + self.anchored_budget_tokens + } else { + estimated_context_tokens + } + } +} + +pub fn build_prompt_snapshot( + tracker: &TokenUsageTracker, + messages: &[LlmMessage], + system_prompt: Option<&str>, + limits: ModelLimits, + threshold_percent: u8, + summary_reserve_tokens: usize, + reserved_context_size: usize, +) -> PromptTokenSnapshot { + let context_tokens = estimate_request_tokens(messages, system_prompt); + let effective_window = effective_context_window(limits, summary_reserve_tokens); + PromptTokenSnapshot { + context_tokens, + budget_tokens: tracker.budget_tokens(context_tokens), + context_window: limits.context_window, + effective_window, + threshold_tokens: compact_threshold_tokens(effective_window, threshold_percent), + remaining_context_tokens: effective_window.saturating_sub(context_tokens), + reserved_context_size, + } +} + +pub fn effective_context_window(limits: ModelLimits, summary_reserve_tokens: usize) -> usize { + limits + .context_window + .saturating_sub(summary_reserve_tokens.min(limits.context_window)) +} + +pub fn compact_threshold_tokens(effective_window: usize, threshold_percent: u8) -> usize { + effective_window + .saturating_mul(threshold_percent as usize) + .saturating_div(100) +} + +pub fn should_compact(snapshot: PromptTokenSnapshot) -> bool { + snapshot.context_tokens >= snapshot.threshold_tokens + || snapshot.remaining_context_tokens <= snapshot.reserved_context_size +} + +pub fn estimate_request_tokens(messages: &[LlmMessage], system_prompt: Option<&str>) -> usize { + let system_tokens = system_prompt.map_or(0, estimate_text_tokens); + let raw_total = system_tokens + messages.iter().map(estimate_message_tokens).sum::(); + raw_total + .saturating_mul(REQUEST_ESTIMATE_PADDING_NUMERATOR) + .div_ceil(REQUEST_ESTIMATE_PADDING_DENOMINATOR) +} + +pub fn estimate_message_tokens(message: &LlmMessage) -> usize { + match message { + LlmMessage::User { content, origin } => { + MESSAGE_BASE_TOKENS + + estimate_text_tokens(content) + + match origin { + UserMessageOrigin::User => 0, + UserMessageOrigin::QueuedInput => 8, + UserMessageOrigin::ContinuationPrompt => 10, + UserMessageOrigin::ReactivationPrompt => 8, + UserMessageOrigin::RecentUserContextDigest => 8, + UserMessageOrigin::RecentUserContext => 8, + UserMessageOrigin::CompactSummary => 16, + } + }, + LlmMessage::Assistant { + content, + tool_calls, + reasoning, + } => { + MESSAGE_BASE_TOKENS + + estimate_text_tokens(content) + + reasoning + .as_ref() + .map_or(0, |reasoning| estimate_text_tokens(&reasoning.content)) + + tool_calls + .iter() + .map(|call| { + TOOL_CALL_BASE_TOKENS + + estimate_text_tokens(&call.id) + + estimate_text_tokens(&call.name) + + estimate_json_tokens(&call.args.to_string()) + }) + .sum::() + }, + LlmMessage::Tool { + tool_call_id, + content, + } => { + MESSAGE_BASE_TOKENS + estimate_text_tokens(tool_call_id) + estimate_text_tokens(content) + }, + } +} + +pub fn estimate_text_tokens(text: &str) -> usize { + let chars = text.chars().count(); + chars.div_ceil(4).max(1) +} + +fn estimate_json_tokens(json: &str) -> usize { + estimate_text_tokens(json) + 4 +} diff --git a/crates/context-window/src/tool_result_budget.rs b/crates/context-window/src/tool_result_budget.rs new file mode 100644 index 00000000..6a20e883 --- /dev/null +++ b/crates/context-window/src/tool_result_budget.rs @@ -0,0 +1,373 @@ +use std::{ + collections::{HashMap, HashSet}, + path::{Path, PathBuf}, +}; + +use astrcode_core::{ + AgentEventContext, LlmMessage, PersistedToolOutput, Result, StorageEvent, StorageEventPayload, + is_persisted_output, + project::project_dir_name, + tool_result_persist::{PersistedToolResult, TOOL_RESULT_PREVIEW_LIMIT, TOOL_RESULTS_DIR}, +}; +use astrcode_support::hostpaths::resolve_home_dir; + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ToolResultReplacementRecord { + pub tool_call_id: String, + pub persisted_output: PersistedToolOutput, + pub replacement: String, + pub original_bytes: u64, +} + +#[derive(Debug, Clone, Default)] +pub struct ToolResultReplacementState { + replacements: HashMap, + frozen: HashSet, +} + +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct ToolResultBudgetStats { + pub replacement_count: usize, + pub reapply_count: usize, + pub bytes_saved: usize, + pub over_budget_message_count: usize, +} + +#[derive(Debug, Clone)] +pub struct ToolResultBudgetOutcome { + pub messages: Vec, + pub events: Vec, + pub stats: ToolResultBudgetStats, +} + +pub struct ApplyToolResultBudgetRequest<'a> { + pub messages: &'a [LlmMessage], + pub session_id: &'a str, + pub working_dir: &'a Path, + pub replacement_state: &'a mut ToolResultReplacementState, + pub aggregate_budget_bytes: usize, + pub turn_id: &'a str, + pub agent: &'a AgentEventContext, +} + +impl ToolResultReplacementState { + pub fn seed(records: impl IntoIterator) -> Self { + let mut state = Self::default(); + for record in records { + state + .replacements + .insert(record.tool_call_id.clone(), record); + } + state + } + + fn replacement_for(&self, tool_call_id: &str) -> Option<&ToolResultReplacementRecord> { + self.replacements.get(tool_call_id) + } + + fn is_frozen(&self, tool_call_id: &str) -> bool { + self.frozen.contains(tool_call_id) + } + + fn freeze(&mut self, tool_call_id: String) { + self.frozen.insert(tool_call_id); + } + + fn record_replacement(&mut self, tool_call_id: String, record: ToolResultReplacementRecord) { + self.replacements.insert(tool_call_id.clone(), record); + self.frozen.remove(&tool_call_id); + } +} + +pub fn apply_tool_result_budget( + request: ApplyToolResultBudgetRequest<'_>, +) -> Result { + let mut messages = request.messages.to_vec(); + let mut events = Vec::new(); + let mut stats = ToolResultBudgetStats::default(); + let Some(batch_start) = trailing_tool_batch_start(&messages) else { + return Ok(ToolResultBudgetOutcome { + messages, + events, + stats, + }); + }; + + let mut total_bytes = 0usize; + for message in &messages[batch_start..] { + if let LlmMessage::Tool { content, .. } = message { + total_bytes = total_bytes.saturating_add(content.len()); + } + } + + for message in &mut messages[batch_start..] { + let LlmMessage::Tool { + tool_call_id, + content, + } = message + else { + continue; + }; + if let Some(record) = request.replacement_state.replacement_for(tool_call_id) { + if content != &record.replacement { + total_bytes = total_bytes + .saturating_sub(content.len()) + .saturating_add(record.replacement.len()); + *content = record.replacement.clone(); + stats.reapply_count = stats.reapply_count.saturating_add(1); + } + } + } + + if total_bytes <= request.aggregate_budget_bytes { + return Ok(ToolResultBudgetOutcome { + messages, + events, + stats, + }); + } + stats.over_budget_message_count = 1; + + let session_dir = resolve_session_dir(request.working_dir, request.session_id)?; + let mut fresh_candidates = messages[batch_start..] + .iter() + .enumerate() + .filter_map(|(offset, message)| match message { + LlmMessage::Tool { + tool_call_id, + content, + } if request + .replacement_state + .replacement_for(tool_call_id) + .is_none() + && !request.replacement_state.is_frozen(tool_call_id) + && !is_persisted_output(content) => + { + Some((batch_start + offset, tool_call_id.clone(), content.len())) + }, + _ => None, + }) + .collect::>(); + fresh_candidates.sort_by_key(|candidate| std::cmp::Reverse(candidate.2)); + + let mut replaced = HashSet::new(); + for (index, tool_call_id, original_len) in fresh_candidates { + if total_bytes <= request.aggregate_budget_bytes { + break; + } + let LlmMessage::Tool { content, .. } = &messages[index] else { + continue; + }; + let replacement = persist_tool_result(&session_dir, &tool_call_id, content); + let Some(persisted_output) = replacement.persisted.clone() else { + continue; + }; + let saved_bytes = original_len.saturating_sub(replacement.output.len()); + let record = ToolResultReplacementRecord { + tool_call_id: tool_call_id.clone(), + persisted_output: persisted_output.clone(), + replacement: replacement.output.clone(), + original_bytes: original_len as u64, + }; + request + .replacement_state + .record_replacement(tool_call_id.clone(), record.clone()); + messages[index] = LlmMessage::Tool { + tool_call_id: tool_call_id.clone(), + content: replacement.output.clone(), + }; + events.push(tool_result_reference_applied_event( + request.turn_id, + request.agent, + &tool_call_id, + &record.persisted_output, + &record.replacement, + record.original_bytes, + )); + total_bytes = total_bytes + .saturating_sub(original_len) + .saturating_add(replacement.output.len()); + stats.replacement_count = stats.replacement_count.saturating_add(1); + stats.bytes_saved = stats.bytes_saved.saturating_add(saved_bytes); + replaced.insert(tool_call_id); + } + + for message in &messages[batch_start..] { + if let LlmMessage::Tool { + tool_call_id, + content, + } = message + { + if request + .replacement_state + .replacement_for(tool_call_id) + .is_none() + && !is_persisted_output(content) + && !replaced.contains(tool_call_id) + { + request.replacement_state.freeze(tool_call_id.clone()); + } + } + } + + Ok(ToolResultBudgetOutcome { + messages, + events, + stats, + }) +} + +fn trailing_tool_batch_start(messages: &[LlmMessage]) -> Option { + let trailing_tools = messages + .iter() + .rev() + .take_while(|message| matches!(message, LlmMessage::Tool { .. })) + .count(); + if trailing_tools == 0 { + None + } else { + Some(messages.len().saturating_sub(trailing_tools)) + } +} + +fn resolve_session_dir(working_dir: &Path, session_id: &str) -> Result { + Ok(project_dir(working_dir)?.join("sessions").join(session_id)) +} + +pub fn project_dir(working_dir: &Path) -> Result { + Ok(projects_dir()?.join(project_dir_name(working_dir))) +} + +fn projects_dir() -> Result { + Ok(astrcode_dir()?.join("projects")) +} + +fn astrcode_dir() -> Result { + Ok(resolve_home_dir()?.join(".astrcode")) +} + +fn persist_tool_result( + session_dir: &Path, + tool_call_id: &str, + content: &str, +) -> PersistedToolResult { + let content_bytes = content.len(); + let results_dir = session_dir.join(TOOL_RESULTS_DIR); + + if std::fs::create_dir_all(&results_dir).is_err() { + log::warn!( + "tool-result: failed to create dir '{}', falling back to truncation", + results_dir.display() + ); + return PersistedToolResult { + output: truncate_with_notice(content), + persisted: None, + }; + } + + let safe_id: String = tool_call_id + .chars() + .filter(|ch| ch.is_alphanumeric() || *ch == '-' || *ch == '_') + .take(64) + .collect(); + let path = results_dir.join(format!("{safe_id}.txt")); + + if std::fs::write(&path, content).is_err() { + log::warn!( + "tool-result: failed to write '{}', falling back to truncation", + path.display() + ); + return PersistedToolResult { + output: truncate_with_notice(content), + persisted: None, + }; + } + + let relative_path = path + .strip_prefix(session_dir) + .unwrap_or(&path) + .to_string_lossy() + .replace('\\', "/"); + let persisted = PersistedToolOutput { + storage_kind: "toolResult".to_string(), + absolute_path: normalize_absolute_path(&path), + relative_path, + total_bytes: content_bytes as u64, + preview_text: build_preview_text(content), + preview_bytes: TOOL_RESULT_PREVIEW_LIMIT.min(content.len()) as u64, + }; + + PersistedToolResult { + output: format_persisted_output(&persisted), + persisted: Some(persisted), + } +} + +fn format_persisted_output(persisted: &PersistedToolOutput) -> String { + format!( + "\nLarge tool output was saved to a file instead of being \ + inlined.\nPath: {}\nBytes: {}\nRead the file with `readFile`.\nIf you only need a \ + section, read a smaller chunk instead of the whole file.\nStart from the first chunk \ + when you do not yet know the right section.\nSuggested first read: {{ path: {:?}, \ + charOffset: 0, maxChars: 20000 }}\n", + persisted.absolute_path, persisted.total_bytes, persisted.absolute_path + ) +} + +fn build_preview_text(content: &str) -> String { + let preview_limit = TOOL_RESULT_PREVIEW_LIMIT.min(content.len()); + let truncated_at = content.floor_char_boundary(preview_limit); + content[..truncated_at].to_string() +} + +fn normalize_absolute_path(path: &Path) -> String { + normalize_verbatim_path(path.to_path_buf()) + .to_string_lossy() + .to_string() +} + +fn normalize_verbatim_path(path: PathBuf) -> PathBuf { + #[cfg(windows)] + { + if let Some(rendered) = path.to_str() { + if let Some(stripped) = rendered.strip_prefix(r"\\?\UNC\") { + return PathBuf::from(format!(r"\\{}", stripped)); + } + if let Some(stripped) = rendered.strip_prefix(r"\\?\") { + return PathBuf::from(stripped); + } + } + } + + path +} + +fn truncate_with_notice(content: &str) -> String { + let limit = TOOL_RESULT_PREVIEW_LIMIT.min(content.len()); + let truncated_at = content.floor_char_boundary(limit); + let prefix = &content[..truncated_at]; + format!( + "{prefix}\n\n... [output truncated to {limit} bytes because persisted storage is \ + unavailable; use offset/limit parameters or rerun with a narrower scope for full content]" + ) +} + +fn tool_result_reference_applied_event( + turn_id: &str, + agent: &AgentEventContext, + tool_call_id: &str, + persisted_output: &PersistedToolOutput, + replacement: &str, + original_bytes: u64, +) -> StorageEvent { + StorageEvent { + turn_id: Some(turn_id.to_string()), + agent: agent.clone(), + payload: StorageEventPayload::ToolResultReferenceApplied { + tool_call_id: tool_call_id.to_string(), + persisted_output: persisted_output.clone(), + replacement: replacement.to_string(), + original_bytes, + }, + } +} diff --git a/crates/context-window/src/tool_results.rs b/crates/context-window/src/tool_results.rs new file mode 100644 index 00000000..b6919649 --- /dev/null +++ b/crates/context-window/src/tool_results.rs @@ -0,0 +1,16 @@ +use std::collections::HashMap; + +use astrcode_core::LlmMessage; + +pub fn tool_call_name_map(messages: &[LlmMessage]) -> HashMap { + let mut names = HashMap::new(); + for message in messages { + let LlmMessage::Assistant { tool_calls, .. } = message else { + continue; + }; + for call in tool_calls { + names.insert(call.id.clone(), call.name.clone()); + } + } + names +} diff --git a/crates/core/src/agent/collaboration.rs b/crates/core/src/agent/collaboration.rs index 05048e86..ced23a54 100644 --- a/crates/core/src/agent/collaboration.rs +++ b/crates/core/src/agent/collaboration.rs @@ -9,8 +9,9 @@ use super::{ spawn::DelegationMetadata, }; use crate::{ - AgentId, DeliveryId, ExecutionContinuation, ModeId, SessionId, SubRunId, TurnId, + AgentId, DeliveryId, ExecutionContinuation, SessionId, SubRunId, TurnId, error::{AstrError, Result}, + mode::ModeId, }; /// `send` 的稳定调用参数。 diff --git a/crates/core/src/config.rs b/crates/core/src/config.rs index a585750d..1e344615 100644 --- a/crates/core/src/config.rs +++ b/crates/core/src/config.rs @@ -7,7 +7,7 @@ use std::fmt; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::env::{ASTRCODE_MAX_TOOL_CONCURRENCY_ENV, DEEPSEEK_API_KEY_ENV, OPENAI_API_KEY_ENV}; +use crate::env::{DEEPSEEK_API_KEY_ENV, OPENAI_API_KEY_ENV}; const CURRENT_CONFIG_VERSION: &str = "1"; const PROVIDER_KIND_OPENAI: &str = "openai"; @@ -264,7 +264,7 @@ impl Default for ResolvedAgentConfig { impl Default for ResolvedRuntimeConfig { fn default() -> Self { Self { - max_tool_concurrency: max_tool_concurrency(), + max_tool_concurrency: DEFAULT_MAX_TOOL_CONCURRENCY, auto_compact_enabled: DEFAULT_AUTO_COMPACT_ENABLED, compact_threshold_percent: DEFAULT_COMPACT_THRESHOLD_PERCENT, tool_result_max_bytes: DEFAULT_TOOL_RESULT_MAX_BYTES, @@ -629,13 +629,9 @@ fn env_reference(name: &str) -> String { format!("{ENV_REFERENCE_PREFIX}{name}") } -/// 从进程环境变量/默认值获取最大安全工具并发数。 +/// 返回默认最大安全工具并发数。 pub fn max_tool_concurrency() -> usize { - std::env::var(ASTRCODE_MAX_TOOL_CONCURRENCY_ENV) - .ok() - .and_then(|s| s.parse().ok()) - .unwrap_or(DEFAULT_MAX_TOOL_CONCURRENCY) - .max(1) + DEFAULT_MAX_TOOL_CONCURRENCY } /// 从 `Option` 解析出完整的 `ResolvedAgentConfig`。 diff --git a/crates/core/src/event/domain.rs b/crates/core/src/event/domain.rs index 38cf894e..89c73f7f 100644 --- a/crates/core/src/event/domain.rs +++ b/crates/core/src/event/domain.rs @@ -8,7 +8,8 @@ use serde_json::Value; use crate::{ AgentEventContext, ChildSessionNotification, CompactAppliedMeta, CompactTrigger, PromptMetricsPayload, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, - SubRunResult, ToolExecutionResult, ToolOutputStream, + SubRunResult, + action::{ToolExecutionResult, ToolOutputStream}, }; /// 会话阶段 diff --git a/crates/core/src/event/mod.rs b/crates/core/src/event/mod.rs index 45ebbcc0..dd115906 100644 --- a/crates/core/src/event/mod.rs +++ b/crates/core/src/event/mod.rs @@ -17,7 +17,6 @@ mod domain; mod phase; -mod translate; mod types; use chrono::{DateTime, Local, Utc}; @@ -27,7 +26,6 @@ use uuid::Uuid; pub use self::{ domain::{AgentEvent, Phase}, phase::{PhaseTracker, normalize_recovered_phase, target_phase as phase_of_storage_event}, - translate::{EventTranslator, replay_records}, types::{ CompactAppliedMeta, CompactMode, CompactTrigger, PromptMetricsPayload, StorageEvent, StorageEventPayload, StoredEvent, TurnTerminalKind, diff --git a/crates/core/src/event/types.rs b/crates/core/src/event/types.rs index d5f99b27..6268ce1c 100644 --- a/crates/core/src/event/types.rs +++ b/crates/core/src/event/types.rs @@ -15,9 +15,10 @@ use serde_json::Value; use crate::{ AgentCollaborationFact, AgentEventContext, AstrError, ChildSessionNotification, ExecutionContinuation, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, - InputQueuedPayload, ModeId, PersistedToolOutput, PromptCacheDiagnostics, - ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, Result, SubRunResult, - SystemPromptLayer, ToolOutputStream, UserMessageOrigin, + InputQueuedPayload, PersistedToolOutput, ResolvedExecutionLimitsSnapshot, + ResolvedSubagentContextOverrides, Result, SubRunResult, UserMessageOrigin, + action::ToolOutputStream, mode::ModeId, policy::SystemPromptLayer, + prompt::PromptCacheDiagnostics, }; /// Prompt/缓存指标共享载荷。 diff --git a/crates/core/src/home.rs b/crates/core/src/home.rs deleted file mode 100644 index 33a60628..00000000 --- a/crates/core/src/home.rs +++ /dev/null @@ -1,39 +0,0 @@ -//! # Home 目录解析 -//! -//! 提供 Astrcode 应用主目录的统一解析入口，供整个 workspace 的所有 crate 共享使用。 -//! -//! ## 解析优先级 -//! -//! 1. `ASTRCODE_TEST_HOME` — 测试隔离环境变量，优先级最高 -//! 2. `ASTRCODE_HOME_DIR` — 生产环境覆盖变量 -//! 3. 系统默认 home 目录下的 `.astrcode` 文件夹 - -use std::path::PathBuf; - -pub use crate::env::{ASTRCODE_HOME_DIR_ENV, ASTRCODE_TEST_HOME_ENV}; -use crate::{AstrError, Result}; - -/// Resolves the home directory for Astrcode storage. -/// -/// Resolution order (unified for both test and non-test builds): -/// 1. `ASTRCODE_TEST_HOME` — test isolation (checked first so tests don't leak to real home) -/// 2. `ASTRCODE_HOME_DIR` — production override -/// 3. `dirs::home_dir()` — system default -pub fn resolve_home_dir() -> Result { - // 1. Check ASTRCODE_TEST_HOME first (test isolation) - if let Some(home) = std::env::var_os(ASTRCODE_TEST_HOME_ENV) { - if !home.is_empty() { - return Ok(PathBuf::from(home)); - } - } - - // 2. Check ASTRCODE_HOME_DIR (production override) - if let Some(home) = std::env::var_os(ASTRCODE_HOME_DIR_ENV) { - if !home.is_empty() { - return Ok(PathBuf::from(home)); - } - } - - // 3. Fall back to system home directory - dirs::home_dir().ok_or(AstrError::HomeDirectoryNotFound) -} diff --git a/crates/core/src/hook.rs b/crates/core/src/hook.rs index 83f08505..e5662e82 100644 --- a/crates/core/src/hook.rs +++ b/crates/core/src/hook.rs @@ -23,7 +23,10 @@ use std::path::PathBuf; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::{CompactTrigger, LlmMessage, ToolDefinition, ToolExecutionResult}; +use crate::{ + CompactTrigger, LlmMessage, + action::{ToolDefinition, ToolExecutionResult}, +}; /// 可被外部扩展拦截的生命周期事件。 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)] diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 3c316b83..8283a556 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -1,11 +1,14 @@ -//! Astrcode 最小共享语义层。 +//! Astrcode 共享语义层。 //! -//! `core` 只作为跨 owner 共享的值对象和稳定语义入口。session durable -//! truth、plugin descriptor、运行时执行面、projection、workflow、mode 等 -//! owner 专属模型不再作为顶层默认导出；仍保留的历史模块路径仅供 owner -//! bridge 内部复用，不应被新调用方继续视为正式入口。 +//! 承载跨 crate 共享的稳定值对象、事件数据模型和最小基础设施。 +//! 工具 trait、LLM 契约、runtime 边界、prompt 契约、治理策略分别由 +//! `*-contract` crate 持有；此处只保留事件存储、配置数据、hook 事件键、 +//! agent 协作模型等真正跨 owner 共享的语义。 +//! +//! 以下模块仍有 `#[doc(hidden)]` 标注，表示已迁移到对应 contract crate， +//! 仅作为过渡桥保留：`prompt`、`tool`。 -mod action; +pub mod action; pub mod agent; mod cancel; pub mod capability; @@ -26,18 +29,20 @@ pub mod observability; pub mod policy; pub mod ports; pub mod project; -mod prompt; +#[doc(hidden)] +pub mod prompt; pub mod registry; pub mod runtime; pub mod session; mod shell; -mod skill; +pub mod skill; pub mod store; pub mod support; #[cfg(feature = "test-support")] pub mod test_support; mod time; -mod tool; +#[doc(hidden)] +pub mod tool; pub mod tool_result_persist; pub use action::{ @@ -45,49 +50,26 @@ pub use action::{ ToolExecutionResult, ToolOutputDelta, ToolOutputStream, UserMessageOrigin, split_assistant_content, }; -#[doc(hidden)] pub use agent::{ - AgentCollaborationActionKind, AgentCollaborationFact as PreviousAgentCollaborationFact, - AgentCollaborationOutcomeKind, AgentCollaborationPolicyContext, - AgentEventContext as PreviousAgentEventContext, AgentInboxEnvelope, AgentMode, - AgentProfile as PreviousAgentProfile, AgentProfileCatalog, ArtifactRef, ChildAgentRef, - ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNode as PreviousChildSessionNode, - ChildSessionNotification as PreviousChildSessionNotification, - ChildSessionNotificationKind as PreviousChildSessionNotificationKind, ChildSessionStatusSource, - CloseAgentParams as PreviousCloseAgentParams, CloseRequestParentDeliveryPayload, - CollaborationResult as PreviousCollaborationResult, CompletedParentDeliveryPayload, + AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, + AgentCollaborationPolicyContext, AgentEventContext, AgentInboxEnvelope, AgentMode, + AgentProfile, AgentProfileCatalog, ArtifactRef, ChildAgentRef, ChildExecutionIdentity, + ChildSessionLineageKind, ChildSessionNode, ChildSessionNotification, + ChildSessionNotificationKind, ChildSessionStatusSource, CloseAgentParams, + CloseRequestParentDeliveryPayload, CollaborationResult, CompletedParentDeliveryPayload, CompletedSubRunOutcome, DelegationMetadata, FailedParentDeliveryPayload, FailedSubRunOutcome, - ForkMode as PreviousForkMode, InboxEnvelopeKind, InvocationKind as PreviousInvocationKind, - LineageSnapshot, ParentDelivery, ParentDeliveryKind, ParentDeliveryOrigin, - ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ParentExecutionRef, - ProgressParentDeliveryPayload, - ResolvedExecutionLimitsSnapshot as PreviousResolvedExecutionLimitsSnapshot, - ResolvedSubagentContextOverrides as PreviousResolvedSubagentContextOverrides, - SendAgentParams as PreviousSendAgentParams, SendToChildParams, SendToParentParams, - SpawnAgentParams as PreviousSpawnAgentParams, SubRunFailure, SubRunFailureCode, SubRunHandoff, - SubRunResult as PreviousSubRunResult, SubRunStatus, - SubRunStorageMode as PreviousSubRunStorageMode, - SubagentContextOverrides as PreviousSubagentContextOverrides, + ForkMode, InboxEnvelopeKind, InvocationKind, LineageSnapshot, ParentDelivery, + ParentDeliveryKind, ParentDeliveryOrigin, ParentDeliveryPayload, + ParentDeliveryTerminalSemantics, ParentExecutionRef, ProgressParentDeliveryPayload, + ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, SendAgentParams, + SendToChildParams, SendToParentParams, SpawnAgentParams, SubRunFailure, SubRunFailureCode, + SubRunHandoff, SubRunResult, SubRunStatus, SubRunStorageMode, SubagentContextOverrides, input_queue::{ - BatchId, CloseParams, DeliveryId as PreviousDeliveryId, - InputBatchAckedPayload as PreviousInputBatchAckedPayload, - InputBatchStartedPayload as PreviousInputBatchStartedPayload, - InputDiscardedPayload as PreviousInputDiscardedPayload, - InputQueuedPayload as PreviousInputQueuedPayload, ObserveParams as PreviousObserveParams, - ObserveSnapshot, QueuedInputEnvelope, SendParams, - }, - lifecycle::{AgentLifecycleStatus, AgentTurnOutcome as PreviousAgentTurnOutcome}, -}; -#[doc(hidden)] -pub use agent::{ - AgentCollaborationFact, AgentEventContext, AgentProfile, AgentTurnOutcome, ChildSessionNode, - ChildSessionNotification, ChildSessionNotificationKind, CloseAgentParams, CollaborationResult, - ForkMode, InvocationKind, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, - SendAgentParams, SpawnAgentParams, SubRunResult, SubRunStorageMode, SubagentContextOverrides, - input_queue::{ - DeliveryId, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, - InputQueuedPayload, ObserveParams, + BatchId, CloseParams, DeliveryId, InputBatchAckedPayload, InputBatchStartedPayload, + InputDiscardedPayload, InputQueuedPayload, ObserveParams, ObserveSnapshot, + QueuedInputEnvelope, SendParams, }, + lifecycle::{AgentLifecycleStatus, AgentTurnOutcome}, normalize_non_empty_unique_string_list, }; pub use cancel::CancelToken; @@ -99,88 +81,51 @@ pub use compact_summary::{ COMPACT_SUMMARY_CONTINUATION, COMPACT_SUMMARY_PREFIX, CompactSummaryEnvelope, format_compact_summary, parse_compact_summary_message, }; -#[doc(hidden)] pub use config::{ ActiveSelection, AgentConfig, Config, ConfigOverlay, CurrentModelSelection, ModelConfig, ModelOption, ModelSelection, OpenAiApiMode, Profile, ResolvedAgentConfig, - ResolvedRuntimeConfig, RuntimeConfig, TestConnectionResult, max_tool_concurrency, - resolve_agent_config, resolve_runtime_config, + ResolvedRuntimeConfig, RuntimeConfig, TestConnectionResult, resolve_agent_config, + resolve_runtime_config, }; pub use error::{AstrError, Result, ResultExt}; pub use event::{ - AgentEvent, CompactAppliedMeta, CompactMode, CompactTrigger, EventTranslator, Phase, - PromptMetricsPayload, StorageEvent, StorageEventPayload, StoredEvent, TurnTerminalKind, - generate_session_id, generate_turn_id, normalize_recovered_phase, phase_of_storage_event, - replay_records, + AgentEvent, CompactAppliedMeta, CompactMode, CompactTrigger, Phase, PromptMetricsPayload, + StorageEvent, StorageEventPayload, StoredEvent, TurnTerminalKind, generate_session_id, + generate_turn_id, normalize_recovered_phase, phase_of_storage_event, }; -#[doc(hidden)] pub use execution_control::ExecutionControl; -#[doc(hidden)] pub use execution_result::{ExecutionContinuation, ExecutionResultCommon}; -#[doc(hidden)] pub use execution_task::{ EXECUTION_TASK_SNAPSHOT_SCHEMA, ExecutionTaskItem, ExecutionTaskSnapshotMetadata, ExecutionTaskStatus, TaskSnapshot, }; -#[doc(hidden)] pub use hook::{ - CompactionHookContext, CompactionHookResultContext, ToolHookContext, ToolHookResultContext, + CompactionHookContext, CompactionHookResultContext, HookEvent, HookEventKey, ToolHookContext, + ToolHookResultContext, }; -pub use hook::{HookEvent, HookEventKey}; pub use ids::{AgentId, CapabilityName, SessionId, SubRunId, TurnId}; pub use local_server::{LOCAL_SERVER_READY_PREFIX, LocalServerInfo}; pub use mcp::{McpApprovalData, McpApprovalStatus}; -#[doc(hidden)] -pub use mode::{ - ActionPolicies, ActionPolicyEffect, ActionPolicyRule, BUILTIN_MODE_CODE_ID, - BUILTIN_MODE_PLAN_ID, BUILTIN_MODE_REVIEW_ID, BoundModeToolContractSnapshot, - CapabilitySelector, ChildPolicySpec, CompiledModeContracts, GovernanceModeSpec, - ModeArtifactDef, ModeExecutionPolicySpec, ModeExitGateDef, ModeId, ModePromptHooks, - PromptProgramEntry, ResolvedChildPolicy, ResolvedTurnEnvelope, SubmitBusyPolicy, - TransitionPolicySpec, -}; -#[doc(hidden)] pub use observability::{ AgentCollaborationScorecardSnapshot, ExecutionDiagnosticsSnapshot, OperationMetricsSnapshot, ReplayMetricsSnapshot, ReplayPath, RuntimeMetricsRecorder, RuntimeObservabilitySnapshot, SubRunExecutionMetricsSnapshot, }; -#[doc(hidden)] -pub use policy::{ - AllowAllPolicyEngine, ApprovalDefault, ApprovalPending, ApprovalRequest, ApprovalResolution, - CapabilityCall, ModelRequest, PolicyContext, PolicyEngine, PolicyVerdict, SystemPromptBlock, - SystemPromptLayer, -}; -#[doc(hidden)] pub use ports::{McpSettingsStore, SkillCatalog}; -pub use prompt::{ - PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, - PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, - PromptDeclarationSource, PromptLayerFingerprints, -}; -pub use registry::{CapabilityContext, CapabilityExecutionResult, CapabilityInvoker}; -#[doc(hidden)] -pub use runtime::{ - ExecutionAccepted, ExecutionOrchestrationBoundary, LiveSubRunControlBoundary, - LoopRunnerBoundary, ManagedRuntimeComponent, RuntimeHandle, SessionTruthBoundary, +pub use prompt::{PromptCacheBreakReason, PromptCacheDiagnostics}; +pub use registry::{ + CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, ExecutionOwner, ToolEventSink, }; pub use session::{DeleteProjectResult, SessionEventRecord, SessionMeta}; pub use shell::{ResolvedShell, ShellFamily}; pub use skill::{SkillSource, SkillSpec, is_valid_skill_name, normalize_skill_name}; -#[doc(hidden)] pub use store::{ EventLogWriter, SessionManager, SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StoreError, StoreResult, }; -#[doc(hidden)] pub use time::{ format_local_rfc3339, format_local_rfc3339_opt, local_rfc3339, local_rfc3339_option, }; -pub use tool::{ - DEFAULT_MAX_OUTPUT_SIZE, ExecutionOwner, Tool, ToolCapabilityMetadata, ToolContext, - ToolEventSink, ToolPromptMetadata, -}; -#[doc(hidden)] pub use tool_result_persist::{ DEFAULT_TOOL_RESULT_INLINE_LIMIT, PersistedToolOutput, PersistedToolResult, TOOL_RESULT_PREVIEW_LIMIT, TOOL_RESULTS_DIR, is_persisted_output, diff --git a/crates/core/src/mode/mod.rs b/crates/core/src/mode/mod.rs index d0bbace8..87c1e0c3 100644 --- a/crates/core/src/mode/mod.rs +++ b/crates/core/src/mode/mod.rs @@ -16,8 +16,8 @@ use serde::{Deserialize, Serialize}; use crate::{ - AstrError, CapabilityKind, ForkMode, PromptDeclaration, Result, SideEffect, - normalize_non_empty_unique_string_list, + AstrError, CapabilityKind, ForkMode, Result, SideEffect, + normalize_non_empty_unique_string_list, prompt::PromptDeclaration, }; pub const BUILTIN_MODE_CODE_ID: &str = "code"; @@ -516,11 +516,19 @@ const fn default_true() -> bool { #[cfg(test)] mod tests { use super::{ - ActionPolicies, BUILTIN_MODE_CODE_ID, BoundModeToolContractSnapshot, CapabilitySelector, - CompiledModeContracts, GovernanceModeSpec, ModeArtifactDef, ModeExitGateDef, ModeId, - ModePromptHooks, PromptProgramEntry, ResolvedTurnEnvelope, SubmitBusyPolicy, + ActionPolicies, ActionPolicyEffect, BUILTIN_MODE_CODE_ID, BoundModeToolContractSnapshot, + CapabilitySelector, CompiledModeContracts, GovernanceModeSpec, ModeArtifactDef, + ModeExitGateDef, ModeId, ModePromptHooks, PromptProgramEntry, ResolvedTurnEnvelope, + SubmitBusyPolicy, + }; + use crate::{ + CapabilityKind, SideEffect, + policy::SystemPromptLayer, + prompt::{ + PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, + PromptDeclarationSource, + }, }; - use crate::{CapabilityKind, PromptDeclaration, SideEffect, SystemPromptLayer}; #[test] fn mode_id_defaults_to_builtin_code() { @@ -622,18 +630,18 @@ mod tests { block_id: "mode.review".to_string(), title: "Review".to_string(), content: "review only".to_string(), - render_target: crate::PromptDeclarationRenderTarget::System, + render_target: PromptDeclarationRenderTarget::System, layer: SystemPromptLayer::Dynamic, - kind: crate::PromptDeclarationKind::ExtensionInstruction, + kind: PromptDeclarationKind::ExtensionInstruction, priority_hint: Some(600), always_include: true, - source: crate::PromptDeclarationSource::Builtin, + source: PromptDeclarationSource::Builtin, capability_name: None, origin: None, }], mode_contracts: CompiledModeContracts::default(), action_policies: ActionPolicies { - default_effect: crate::ActionPolicyEffect::Ask, + default_effect: ActionPolicyEffect::Ask, rules: Vec::new(), }, child_policy: Default::default(), diff --git a/crates/core/src/policy/engine.rs b/crates/core/src/policy/engine.rs index 38637823..1ef127bd 100644 --- a/crates/core/src/policy/engine.rs +++ b/crates/core/src/policy/engine.rs @@ -1,27 +1,9 @@ -//! # 策略引擎 -//! -//! 定义了策略引擎的抽象接口和类型，用于控制 Agent 的行为。 -//! -//! ## 核心职责 -//! -//! - **审批流程**: 决定某个能力调用是否需要用户审批 -//! - **内容审查**: 检查/修改 LLM 请求和工具调用 -//! - **模型/工具护栏**: 为运行时提供统一的审批与请求检查入口 -//! -//! ## 裁决流程 -//! -//! 每次能力调用都会经过 `check_capability_call`，返回三种裁决之一： -//! `Allow`（直接执行）、`Deny`（拒绝并说明原因）、`Ask`（等待用户审批）。 - -use async_trait::async_trait; use serde::{Deserialize, Serialize}; -use serde_json::Value; - -use crate::{CapabilitySpec, LlmMessage, Result, ToolDefinition}; /// 系统提示词块所属层级。 /// -/// provider 可以利用该层级决定缓存边界，从而在分层 prompt 下尽量保住稳定前缀。 +/// 该类型出现在 durable prompt metrics 中，因此保留在 `core` 的事件语义层。 +/// 治理策略、模型请求和 policy engine 契约位于 `astrcode-governance-contract`。 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)] #[serde(rename_all = "snake_case")] pub enum SystemPromptLayer { @@ -32,379 +14,3 @@ pub enum SystemPromptLayer { #[default] Unspecified, } - -/// 已渲染的系统提示词块。 -/// -/// RequestAssembler 会把 `PromptPlan` 中的 system blocks 降级为这个 provider 无关 DTO。 -/// 这样 `core` 只感知“分段后的系统提示词”，而不依赖 `adapter-prompt` 的内部类型。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct SystemPromptBlock { - pub title: String, - pub content: String, - #[serde(default, skip_serializing_if = "is_false")] - pub cache_boundary: bool, - #[serde(default, skip_serializing_if = "is_unspecified_system_prompt_layer")] - pub layer: SystemPromptLayer, -} - -impl SystemPromptBlock { - pub fn render(&self) -> String { - format!("[{}]\n{}", self.title, self.content) - } -} - -fn is_false(value: &bool) -> bool { - !*value -} - -fn is_unspecified_system_prompt_layer(layer: &SystemPromptLayer) -> bool { - matches!(layer, SystemPromptLayer::Unspecified) -} - -/// Turn 范围的模型请求，策略层可在执行前检查或重写。 -#[derive(Debug, Clone)] -pub struct ModelRequest { - /// 消息历史 - pub messages: Vec, - /// 可用工具列表 - pub tools: Vec, - /// 系统提示词 - pub system_prompt: Option, - /// 分段后的系统提示词块。 - /// - /// 默认 provider 可忽略它继续使用 `system_prompt`，支持分层缓存或稳定前缀优化的 - /// 后端则可以直接消费它。 - pub system_prompt_blocks: Vec, -} - -/// 通用能力调用提案 -/// -/// 流经策略层等待执行的通用能力调用提案。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct CapabilityCall { - /// 请求 ID - pub request_id: String, - /// 能力规范 - pub capability: CapabilitySpec, - /// 调用载荷 - pub payload: Value, - /// 元数据 - #[serde(default)] - pub metadata: Value, -} - -impl CapabilityCall { - /// 获取能力名称 - pub fn name(&self) -> &str { - self.capability.name.as_str() - } -} - -/// 策略上下文 -/// -/// 策略实现可用的共享 Turn 元数据，不暴露传输细节。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct PolicyContext { - /// 会话 ID - pub session_id: String, - /// Turn ID - pub turn_id: String, - /// 步骤索引 - pub step_index: usize, - /// 工作目录 - pub working_dir: String, - /// Profile 名称 - pub profile: String, - /// 元数据 - #[serde(default)] - pub metadata: Value, -} - -/// 审批默认值 -/// -/// 用于 UI 展示默认选项。 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "snake_case")] -pub enum ApprovalDefault { - /// 默认允许 - Allow, - /// 默认拒绝 - Deny, -} - -impl ApprovalDefault { - /// 解析为审批结果 - pub fn resolve(self) -> ApprovalResolution { - match self { - Self::Allow => ApprovalResolution::approved(), - Self::Deny => ApprovalResolution::denied("approval denied by default"), - } - } -} - -/// 审批请求 -/// -/// 策略层产生的、需要用户确认的审批载荷。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct ApprovalRequest { - /// 请求 ID - pub request_id: String, - /// 会话 ID - pub session_id: String, - /// Turn ID - pub turn_id: String, - /// 能力描述符 - pub capability: CapabilitySpec, - /// 调用载荷 - pub payload: Value, - /// 提示文本（向用户展示） - pub prompt: String, - /// 默认选项 - pub default: ApprovalDefault, - /// 元数据 - #[serde(default)] - pub metadata: Value, -} - -impl ApprovalRequest { - /// 获取能力名称 - pub fn capability_name(&self) -> &str { - &self.capability.name - } -} - -/// 审批结果 -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct ApprovalResolution { - /// 是否批准 - pub approved: bool, - /// 拒绝原因（批准时为 None） - #[serde(default, skip_serializing_if = "Option::is_none")] - pub reason: Option, -} - -impl ApprovalResolution { - /// 创建批准结果 - pub fn approved() -> Self { - Self { - approved: true, - reason: None, - } - } - - /// 创建拒绝结果 - pub fn denied(reason: impl Into) -> Self { - Self { - approved: false, - reason: Some(reason.into()), - } - } -} - -/// 等待审批的动作 -/// -/// 包装审批请求和待执行的动作。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "camelCase")] -pub struct ApprovalPending { - /// 审批请求 - pub request: ApprovalRequest, - /// 审批通过后要执行的动作 - pub action: T, -} - -/// 策略裁决 -/// -/// 策略引擎对能力调用的裁决结果。 -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] -#[serde(rename_all = "snake_case")] -pub enum PolicyVerdict { - /// 允许执行 - Allow(T), - /// 拒绝执行 - Deny { reason: String }, - /// 需要用户审批 - /// - /// Box 住审批载荷，避免 Allow/Deny 也为较大的审批上下文付出同样的栈空间成本。 - Ask(Box>), -} - -impl PolicyVerdict { - /// 创建允许裁决 - pub fn allow(value: T) -> Self { - Self::Allow(value) - } - - /// 创建拒绝裁决 - pub fn deny(reason: impl Into) -> Self { - Self::Deny { - reason: reason.into(), - } - } - - /// 创建需审批裁决 - pub fn ask(request: ApprovalRequest, action: T) -> Self { - Self::Ask(Box::new(ApprovalPending { request, action })) - } -} - -/// 策略引擎 trait。 -/// -/// 定义了策略引擎必须实现的两个核心检查点： -/// 1. `check_model_request`: 在发送 LLM 请求前，可检查/重写请求内容 -/// 2. `check_capability_call`: 在执行能力调用前，决定允许/拒绝/需审批 -#[async_trait] -pub trait PolicyEngine: Send + Sync { - /// 检查/重写模型请求。 - /// - /// 策略实现可以修改消息、工具列表或系统提示词， - /// 用于内容审查、敏感信息过滤等场景。 - async fn check_model_request( - &self, - request: ModelRequest, - ctx: &PolicyContext, - ) -> Result; - - /// 检查能力调用是否需要审批。 - /// - /// 返回 `Allow`（直接执行）、`Deny`（拒绝）或 `Ask`（等待用户审批）。 - async fn check_capability_call( - &self, - call: CapabilityCall, - ctx: &PolicyContext, - ) -> Result>; -} - -/// 允许所有操作的策略引擎。 -/// -/// 用于测试和不启用策略的场景，所有请求和调用都直接放行。 -#[derive(Debug, Default, Clone, Copy)] -pub struct AllowAllPolicyEngine; - -#[async_trait] -impl PolicyEngine for AllowAllPolicyEngine { - async fn check_model_request( - &self, - request: ModelRequest, - _ctx: &PolicyContext, - ) -> Result { - Ok(request) - } - - async fn check_capability_call( - &self, - call: CapabilityCall, - _ctx: &PolicyContext, - ) -> Result> { - Ok(PolicyVerdict::Allow(call)) - } -} - -#[cfg(test)] -mod tests { - use serde_json::{Value, json}; - - use super::{ - AllowAllPolicyEngine, ApprovalDefault, ApprovalRequest, PolicyContext, PolicyEngine, - PolicyVerdict, - }; - use crate::{ - CapabilityKind, CapabilitySpec, InvocationMode, ModelRequest, SideEffect, Stability, - }; - - fn capability(name: &str) -> CapabilitySpec { - CapabilitySpec { - name: name.into(), - kind: CapabilityKind::Tool, - description: "test capability".to_string(), - input_schema: json!({ "type": "object" }), - output_schema: json!({ "type": "object" }), - invocation_mode: InvocationMode::Unary, - concurrency_safe: false, - compact_clearable: false, - profiles: vec!["coding".to_string()], - tags: vec![], - permissions: vec![], - side_effect: SideEffect::Workspace, - stability: Stability::Stable, - metadata: Value::Null, - max_result_inline_size: None, - } - } - - fn policy_context() -> PolicyContext { - PolicyContext { - session_id: "session-1".to_string(), - turn_id: "turn-1".to_string(), - step_index: 0, - working_dir: ".".to_string(), - profile: "coding".to_string(), - metadata: Value::Null, - } - } - - #[tokio::test] - async fn allow_all_policy_preserves_requests() { - let policy = AllowAllPolicyEngine; - let request = ModelRequest { - messages: vec![], - tools: vec![], - system_prompt: Some("system".to_string()), - system_prompt_blocks: Vec::new(), - }; - let call = super::CapabilityCall { - request_id: "call-1".to_string(), - capability: capability("tool.sample"), - payload: json!({ "path": "Cargo.toml" }), - metadata: Value::Null, - }; - - let checked_request = policy - .check_model_request(request, &policy_context()) - .await - .expect("request should pass"); - assert_eq!(checked_request.system_prompt.as_deref(), Some("system")); - assert!(checked_request.messages.is_empty()); - assert!(checked_request.tools.is_empty()); - assert_eq!( - policy - .check_capability_call(call.clone(), &policy_context()) - .await - .expect("call should pass"), - PolicyVerdict::Allow(call) - ); - } - - #[test] - fn approval_default_resolves_to_expected_resolution() { - assert!(ApprovalDefault::Allow.resolve().approved); - assert_eq!( - ApprovalDefault::Deny.resolve(), - super::ApprovalResolution { - approved: false, - reason: Some("approval denied by default".to_string()), - } - ); - } - - #[test] - fn approval_request_reports_capability_name() { - let request = ApprovalRequest { - request_id: "call-1".to_string(), - session_id: "session-1".to_string(), - turn_id: "turn-1".to_string(), - capability: capability("tool.sample"), - payload: json!({}), - prompt: "Allow?".to_string(), - default: ApprovalDefault::Deny, - metadata: Value::Null, - }; - - assert_eq!(request.capability_name(), "tool.sample"); - } -} diff --git a/crates/core/src/policy/mod.rs b/crates/core/src/policy/mod.rs index 90add1c4..e74cce86 100644 --- a/crates/core/src/policy/mod.rs +++ b/crates/core/src/policy/mod.rs @@ -1,17 +1,8 @@ -//! # 策略引擎 +//! # Prompt metrics layer //! -//! 定义了策略引擎的抽象接口，用于控制 Agent 的行为。 -//! -//! ## 核心职责 -//! -//! - 审批流程：决定能力调用是否需要用户确认 -//! - 内容审查：检查/重写 LLM 请求 -//! - 模型/工具护栏：统一的审批与请求检查入口 +//! `core` 只保留 durable event 需要序列化的 prompt layer 枚举。 +//! 策略引擎与治理契约位于 `astrcode-governance-contract`。 mod engine; -pub use engine::{ - AllowAllPolicyEngine, ApprovalDefault, ApprovalPending, ApprovalRequest, ApprovalResolution, - CapabilityCall, ModelRequest, PolicyContext, PolicyEngine, PolicyVerdict, SystemPromptBlock, - SystemPromptLayer, -}; +pub use engine::SystemPromptLayer; diff --git a/crates/core/src/prompt.rs b/crates/core/src/prompt.rs index 857c62fd..e12cfc82 100644 --- a/crates/core/src/prompt.rs +++ b/crates/core/src/prompt.rs @@ -1,42 +1,6 @@ use serde::{Deserialize, Serialize}; -use crate::SystemPromptLayer; - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptLayerFingerprints { - #[serde(default, skip_serializing_if = "Option::is_none")] - pub stable: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub semi_stable: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub inherited: Option, - #[serde(default, skip_serializing_if = "Option::is_none")] - pub dynamic: Option, -} - -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "camelCase")] -pub struct PromptCacheHints { - #[serde(default)] - pub layer_fingerprints: PromptLayerFingerprints, - #[serde(default)] - pub global_cache_strategy: PromptCacheGlobalStrategy, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub unchanged_layers: Vec, - #[serde(default, skip_serializing_if = "is_false")] - pub compacted: bool, - #[serde(default, skip_serializing_if = "is_false")] - pub tool_result_rebudgeted: bool, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] -#[serde(rename_all = "snake_case")] -pub enum PromptCacheGlobalStrategy { - #[default] - SystemPrompt, - ToolBased, -} +use crate::policy::SystemPromptLayer; #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] diff --git a/crates/core/src/registry/mod.rs b/crates/core/src/registry/mod.rs index c7db27b7..2d7c08ec 100644 --- a/crates/core/src/registry/mod.rs +++ b/crates/core/src/registry/mod.rs @@ -9,4 +9,6 @@ pub mod router; -pub use router::{CapabilityContext, CapabilityExecutionResult, CapabilityInvoker}; +pub use router::{ + CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, ExecutionOwner, ToolEventSink, +}; diff --git a/crates/core/src/registry/router.rs b/crates/core/src/registry/router.rs index 0e2715cf..4d285faa 100644 --- a/crates/core/src/registry/router.rs +++ b/crates/core/src/registry/router.rs @@ -10,11 +10,66 @@ use serde_json::Value; use tokio::sync::mpsc::UnboundedSender; use crate::{ - AgentEventContext, BoundModeToolContractSnapshot, CancelToken, CapabilitySpec, - ExecutionContinuation, ExecutionOwner, ExecutionResultCommon, ModeId, Result, SessionId, - ToolEventSink, ToolExecutionResult, ToolOutputDelta, + AgentEventContext, CancelToken, CapabilitySpec, ExecutionContinuation, ExecutionResultCommon, + InvocationKind, Result, SessionId, StorageEvent, TurnId, + action::{ToolExecutionResult, ToolOutputDelta}, + mode::{BoundModeToolContractSnapshot, ModeId}, }; +/// 工具调用链路的稳定归属标识。 +/// +/// 这是能力调用上下文的一部分，保留在 `core` 是为了让通用 +/// `CapabilityInvoker` 不依赖具体 tool contract。真正的工具执行接口 +/// 位于 `astrcode-tool-contract`。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +pub struct ExecutionOwner { + /// 根执行所在的 session。 + pub root_session_id: SessionId, + /// 根执行所在的 turn。 + pub root_turn_id: TurnId, + /// 当前工具调用若属于子执行域，则记录 sub-run id。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub sub_run_id: Option, + /// 当前归属来源。 + pub invocation_kind: InvocationKind, +} + +impl ExecutionOwner { + /// 为顶层执行构造 owner。 + pub fn root( + root_session_id: impl Into, + root_turn_id: impl Into, + invocation_kind: InvocationKind, + ) -> Self { + Self { + root_session_id: root_session_id.into(), + root_turn_id: root_turn_id.into(), + sub_run_id: None, + invocation_kind, + } + } + + /// 在现有根归属上挂接当前 sub-run。 + pub fn for_sub_run(&self, sub_run_id: impl Into) -> Self { + Self { + root_session_id: self.root_session_id.clone(), + root_turn_id: self.root_turn_id.clone(), + sub_run_id: Some(sub_run_id.into()), + invocation_kind: InvocationKind::SubRun, + } + } +} + +/// 能力内部产生 turn 级事件时使用的发射接口。 +/// +/// 子 Agent / 复合能力不能直接依赖 runtime 的会话写入实现，因此这里通过 +/// 最小抽象把事件交回当前 turn 的持久化/广播链路。 +#[async_trait] +pub trait ToolEventSink: Send + Sync { + async fn emit(&self, event: StorageEvent) -> Result<()>; +} + /// 能力调用的上下文信息。 #[derive(Clone)] pub struct CapabilityContext { diff --git a/crates/core/src/runtime/traits.rs b/crates/core/src/runtime/traits.rs index 1f25272f..9e75c104 100644 --- a/crates/core/src/runtime/traits.rs +++ b/crates/core/src/runtime/traits.rs @@ -11,7 +11,7 @@ use async_trait::async_trait; use crate::{ AgentId, AgentProfile, AstrError, SessionEventRecord, SessionId, SessionMeta, SubRunResult, - SubagentContextOverrides, TurnId, agent::lineage::SubRunHandle, + SubagentContextOverrides, TurnId, agent::lineage::SubRunHandle, tool::ToolContext, }; /// 运行时主句柄。 @@ -133,7 +133,7 @@ pub trait LiveSubRunControlBoundary: Send + Sync { async fn launch_subagent( &self, params: crate::SpawnAgentParams, - ctx: &crate::ToolContext, + ctx: &ToolContext, ) -> std::result::Result; async fn list_profiles(&self) -> std::result::Result, AstrError>; diff --git a/crates/core/src/tool.rs b/crates/core/src/tool.rs index ef08f68c..62b789f0 100644 --- a/crates/core/src/tool.rs +++ b/crates/core/src/tool.rs @@ -16,10 +16,11 @@ use serde_json::{Value, json}; use tokio::sync::mpsc::UnboundedSender; use crate::{ - AgentEventContext, BoundModeToolContractSnapshot, CancelToken, CapabilityKind, CapabilitySpec, - CapabilitySpecBuildError, InvocationKind, InvocationMode, ModeId, PermissionSpec, Result, - SessionId, SideEffect, Stability, StorageEvent, ToolDefinition, ToolExecutionResult, - ToolOutputDelta, ToolOutputStream, TurnId, + AgentEventContext, CancelToken, CapabilityKind, CapabilitySpec, CapabilitySpecBuildError, + InvocationKind, InvocationMode, PermissionSpec, Result, SessionId, SideEffect, Stability, + StorageEvent, TurnId, + action::{ToolDefinition, ToolExecutionResult, ToolOutputDelta, ToolOutputStream}, + mode::{BoundModeToolContractSnapshot, ModeId}, tool_result_persist::DEFAULT_TOOL_RESULT_INLINE_LIMIT, }; @@ -678,7 +679,8 @@ pub trait Tool: Send + Sync { mod tests { use std::path::PathBuf; - use crate::{BoundModeToolContractSnapshot, CancelToken, ToolContext}; + use super::ToolContext; + use crate::{CancelToken, mode::BoundModeToolContractSnapshot}; #[test] fn tool_context_preserves_bound_mode_tool_contract_snapshot() { diff --git a/crates/core/src/tool_result_persist.rs b/crates/core/src/tool_result_persist.rs index 921313c5..09446a05 100644 --- a/crates/core/src/tool_result_persist.rs +++ b/crates/core/src/tool_result_persist.rs @@ -46,81 +46,19 @@ pub fn persisted_output_absolute_path(content: &str) -> Option { }) } -/// 解析工具结果内联阈值，支持环境变量覆盖。 +/// 解析工具结果内联阈值。 /// /// 优先级（从高到低）： -/// 1. Per-tool 环境变量 `ASTRCODE_TOOL_INLINE_LIMIT_{TOOL_NAME}`（大写） -/// 2. 描述符中的 `max_result_inline_size` -/// 3. 全局环境变量 `ASTRCODE_TOOL_RESULT_INLINE_LIMIT` -/// 4. 调用方提供的默认阈值（通常来自 runtime 配置） -/// -/// 工具名转换规则：camelCase → SCREAMING_SNAKE_CASE。 -/// 例如 `readFile` → `ASTRCODE_TOOL_INLINE_LIMIT_READ_FILE`， -/// `shell` → `ASTRCODE_TOOL_INLINE_LIMIT_SHELL`。 -pub fn resolve_inline_limit( - tool_name: &str, - descriptor_limit: Option, - configured_default: usize, -) -> usize { - let per_tool_env_key = format!( - "{}{}", - crate::env::ASTRCODE_TOOL_INLINE_LIMIT_PREFIX, - camel_to_screaming_snake(tool_name) - ); - resolve_inline_limit_impl( - std::env::var(&per_tool_env_key).ok().as_deref(), - descriptor_limit, - std::env::var(crate::env::ASTRCODE_TOOL_RESULT_INLINE_LIMIT_ENV) - .ok() - .as_deref(), - configured_default, - ) -} - -/// 纯逻辑解析，不读取环境变量。方便测试。 -fn resolve_inline_limit_impl( - per_tool_env: Option<&str>, - descriptor_limit: Option, - global_env: Option<&str>, - configured_default: usize, -) -> usize { - // 层级 1：per-tool 环境变量 - if let Some(val) = per_tool_env { - if let Ok(limit) = val.parse::() { - return limit; - } - } - - // 层级 2：描述符中的值 +/// 1. 描述符中的 `max_result_inline_size` +/// 2. 调用方注入的默认阈值（通常来自 runtime 配置） +pub fn resolve_inline_limit(descriptor_limit: Option, configured_default: usize) -> usize { if let Some(limit) = descriptor_limit { return limit; } - // 层级 3：全局环境变量 - if let Some(val) = global_env { - if let Ok(limit) = val.parse::() { - return limit; - } - } - - // 层级 4：默认值 configured_default.max(1) } -/// 将 camelCase 转换为 SCREAMING_SNAKE_CASE。 -/// -/// 例：`readFile` → `READ_FILE`，`findFiles` → `FIND_FILES`，`shell` → `SHELL`。 -fn camel_to_screaming_snake(s: &str) -> String { - let mut result = String::with_capacity(s.len() * 2); - for (i, c) in s.chars().enumerate() { - if c.is_uppercase() && i > 0 { - result.push('_'); - } - result.push(c.to_ascii_uppercase()); - } - result -} - #[cfg(test)] mod tests { use super::*; @@ -144,87 +82,21 @@ mod tests { ); } - #[test] - fn camel_to_screaming_snake_converts_correctly() { - assert_eq!(camel_to_screaming_snake("readFile"), "READ_FILE"); - assert_eq!(camel_to_screaming_snake("findFiles"), "FIND_FILES"); - assert_eq!(camel_to_screaming_snake("shell"), "SHELL"); - assert_eq!(camel_to_screaming_snake("grep"), "GREP"); - } - #[test] fn resolve_inline_limit_uses_default_when_no_override() { - // 无 env、无描述符 → 默认 32KB assert_eq!( - resolve_inline_limit_impl(None, None, None, DEFAULT_TOOL_RESULT_INLINE_LIMIT), + resolve_inline_limit(None, DEFAULT_TOOL_RESULT_INLINE_LIMIT), DEFAULT_TOOL_RESULT_INLINE_LIMIT ); - // 有描述符值 → 使用描述符值 assert_eq!( - resolve_inline_limit_impl(None, Some(30_000), None, DEFAULT_TOOL_RESULT_INLINE_LIMIT), + resolve_inline_limit(Some(30_000), DEFAULT_TOOL_RESULT_INLINE_LIMIT), 30_000 ); } - #[test] - fn resolve_inline_limit_global_env_overrides_default() { - // 无描述符值，全局 env 覆盖默认 - assert_eq!( - resolve_inline_limit_impl(None, None, Some("65536"), DEFAULT_TOOL_RESULT_INLINE_LIMIT), - 65536 - ); - - // 全局 env 优先级低于描述符值 - assert_eq!( - resolve_inline_limit_impl( - None, - Some(30_000), - Some("65536"), - DEFAULT_TOOL_RESULT_INLINE_LIMIT, - ), - 30_000 - ); - } - - #[test] - fn resolve_inline_limit_per_tool_env_has_highest_priority() { - // per-tool env > 描述符值 > 全局 env - assert_eq!( - resolve_inline_limit_impl( - Some("12345"), - Some(30_000), - Some("65536"), - DEFAULT_TOOL_RESULT_INLINE_LIMIT, - ), - 12345 - ); - - // per-tool env 为无效值 → 降级到描述符值 - assert_eq!( - resolve_inline_limit_impl( - Some("not-a-number"), - Some(30_000), - Some("65536"), - DEFAULT_TOOL_RESULT_INLINE_LIMIT, - ), - 30_000 - ); - - // per-tool env 为 None → 降级到描述符值 - assert_eq!( - resolve_inline_limit_impl( - None, - Some(20_000), - Some("65536"), - DEFAULT_TOOL_RESULT_INLINE_LIMIT, - ), - 20_000 - ); - } - #[test] fn resolve_inline_limit_uses_runtime_default_after_all_overrides_miss() { - assert_eq!(resolve_inline_limit_impl(None, None, None, 88_888), 88_888); + assert_eq!(resolve_inline_limit(None, 88_888), 88_888); } } diff --git a/crates/eval/src/trace/extractor.rs b/crates/eval/src/trace/extractor.rs index b293ed3c..f890e23f 100644 --- a/crates/eval/src/trace/extractor.rs +++ b/crates/eval/src/trace/extractor.rs @@ -798,7 +798,8 @@ mod tests { AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, AgentCollaborationPolicyContext, AgentEventContext, ChildExecutionIdentity, InvocationKind, PersistedToolOutput, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, - StorageEvent, StorageEventPayload, StoredEvent, SubRunStorageMode, ToolOutputStream, + StorageEvent, StorageEventPayload, StoredEvent, SubRunStorageMode, + action::ToolOutputStream, }; use chrono::{TimeZone, Utc}; use serde_json::json; diff --git a/crates/eval/src/trace/mod.rs b/crates/eval/src/trace/mod.rs index 61a0b15e..bf0807ad 100644 --- a/crates/eval/src/trace/mod.rs +++ b/crates/eval/src/trace/mod.rs @@ -4,7 +4,7 @@ use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationOutcomeKind, AgentEventContext, CompactAppliedMeta, CompactTrigger, ExecutionContinuation, InvocationKind, PersistedToolOutput, PromptMetricsPayload, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, - SubRunResult, SubRunStorageMode, ToolOutputStream, + SubRunResult, SubRunStorageMode, action::ToolOutputStream, }; use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; @@ -310,7 +310,7 @@ pub struct TurnTimelineEvent { #[cfg(test)] mod tests { - use astrcode_core::{AgentEventContext, PersistedToolOutput, ToolOutputStream}; + use astrcode_core::{AgentEventContext, PersistedToolOutput, action::ToolOutputStream}; use chrono::{TimeZone, Utc}; use serde_json::json; diff --git a/crates/governance-contract/Cargo.toml b/crates/governance-contract/Cargo.toml new file mode 100644 index 00000000..c7dc27c3 --- /dev/null +++ b/crates/governance-contract/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "astrcode-governance-contract" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +astrcode-prompt-contract = { path = "../prompt-contract" } +async-trait.workspace = true +serde.workspace = true +serde_json.workspace = true +tokio.workspace = true diff --git a/crates/governance-contract/src/lib.rs b/crates/governance-contract/src/lib.rs new file mode 100644 index 00000000..1516b661 --- /dev/null +++ b/crates/governance-contract/src/lib.rs @@ -0,0 +1,5 @@ +mod mode; +mod policy; + +pub use mode::*; +pub use policy::*; diff --git a/crates/governance-contract/src/mode.rs b/crates/governance-contract/src/mode.rs new file mode 100644 index 00000000..15e6ee98 --- /dev/null +++ b/crates/governance-contract/src/mode.rs @@ -0,0 +1,821 @@ +//! # 声明式治理模式系统 +//! +//! 定义运行时治理模式（Governance Mode）的完整 DSL： +//! +//! - **ModeId**: 模式唯一标识（内置 code / plan / review） +//! - **CapabilitySelector**: 能力选择器 DSL（支持 AllTools / Name / Kind / Tag / Union / +//! Intersection / Difference） +//! - **ActionPolicies**: 动作策略规则集（Allow / Deny / Ask 三种裁决效果） +//! - **GovernanceModeSpec**: 完整模式定义（能力表面 + 动作策略 + 子策略 + 执行策略 + 提示词程序 + +//! 转换策略） +//! - **ResolvedTurnEnvelope**: 当前命名沿用 envelope，但语义上是治理 compile 阶段产物 +//! +//! 模式由声明式配置文件加载，运行时通过 `GovernanceModeSpec::validate()` 校验后， +//! 由治理层先编译为 `ResolvedTurnEnvelope`，再由 application bind 成 turn 可执行治理快照。 + +use astrcode_core::{ + AstrError, CapabilityKind, ForkMode, Result, SideEffect, normalize_non_empty_unique_string_list, +}; +use astrcode_prompt_contract::PromptDeclaration; +use serde::{Deserialize, Serialize}; + +pub const BUILTIN_MODE_CODE_ID: &str = "code"; +pub const BUILTIN_MODE_PLAN_ID: &str = "plan"; +pub const BUILTIN_MODE_REVIEW_ID: &str = "review"; + +#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(transparent)] +pub struct ModeId(String); + +impl ModeId { + pub fn new(value: impl Into) -> Result { + let value = value.into(); + let trimmed = value.trim(); + if trimmed.is_empty() { + return Err(AstrError::Validation("modeId 不能为空".to_string())); + } + Ok(Self(trimmed.to_string())) + } + + pub fn code() -> Self { + Self(BUILTIN_MODE_CODE_ID.to_string()) + } + + pub fn plan() -> Self { + Self(BUILTIN_MODE_PLAN_ID.to_string()) + } + + pub fn review() -> Self { + Self(BUILTIN_MODE_REVIEW_ID.to_string()) + } + + pub fn as_str(&self) -> &str { + self.0.as_str() + } +} + +impl Default for ModeId { + fn default() -> Self { + Self::code() + } +} + +impl From<&str> for ModeId { + fn from(value: &str) -> Self { + Self(value.trim().to_string()) + } +} + +impl From for ModeId { + fn from(value: String) -> Self { + Self(value.trim().to_string()) + } +} + +impl std::fmt::Display for ModeId { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.as_str()) + } +} + +impl From for astrcode_core::mode::ModeId { + fn from(value: ModeId) -> Self { + Self::from(value.0) + } +} + +impl From for ModeId { + fn from(value: astrcode_core::mode::ModeId) -> Self { + Self::from(value.as_str()) + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum SubmitBusyPolicy { + #[default] + BranchOnBusy, + RejectOnBusy, +} + +impl From for astrcode_core::mode::SubmitBusyPolicy { + fn from(value: SubmitBusyPolicy) -> Self { + match value { + SubmitBusyPolicy::BranchOnBusy => Self::BranchOnBusy, + SubmitBusyPolicy::RejectOnBusy => Self::RejectOnBusy, + } + } +} + +impl From for SubmitBusyPolicy { + fn from(value: astrcode_core::mode::SubmitBusyPolicy) -> Self { + match value { + astrcode_core::mode::SubmitBusyPolicy::BranchOnBusy => Self::BranchOnBusy, + astrcode_core::mode::SubmitBusyPolicy::RejectOnBusy => Self::RejectOnBusy, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum CapabilitySelector { + AllTools, + Name(String), + Kind(CapabilityKind), + SideEffect(SideEffect), + Tag(String), + Union(Vec), + Intersection(Vec), + Difference { + base: Box, + subtract: Box, + }, +} + +impl CapabilitySelector { + pub fn validate(&self) -> Result<()> { + match self { + Self::AllTools => Ok(()), + Self::Name(name) => validate_non_empty_trimmed("capabilitySelector.name", name), + Self::Kind(_) | Self::SideEffect(_) => Ok(()), + Self::Tag(tag) => validate_non_empty_trimmed("capabilitySelector.tag", tag), + Self::Union(selectors) | Self::Intersection(selectors) => { + if selectors.is_empty() { + return Err(AstrError::Validation( + "capabilitySelector 组合操作不能为空".to_string(), + )); + } + for selector in selectors { + selector.validate()?; + } + Ok(()) + }, + Self::Difference { base, subtract } => { + base.validate()?; + subtract.validate()?; + Ok(()) + }, + } + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum ActionPolicyEffect { + #[default] + Allow, + Deny, + Ask, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ActionPolicyRule { + pub selector: CapabilitySelector, + pub effect: ActionPolicyEffect, +} + +impl ActionPolicyRule { + pub fn validate(&self) -> Result<()> { + self.selector.validate() + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ActionPolicies { + #[serde(default = "default_action_policy_effect")] + pub default_effect: ActionPolicyEffect, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub rules: Vec, +} + +impl ActionPolicies { + pub fn validate(&self) -> Result<()> { + for rule in &self.rules { + rule.validate()?; + } + Ok(()) + } + + pub fn requires_approval(&self) -> bool { + self.rules + .iter() + .any(|rule| matches!(rule.effect, ActionPolicyEffect::Ask)) + || matches!(self.default_effect, ActionPolicyEffect::Ask) + } +} + +fn default_action_policy_effect() -> ActionPolicyEffect { + ActionPolicyEffect::Allow +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ChildPolicySpec { + #[serde(default = "default_true")] + pub allow_delegation: bool, + #[serde(default = "default_true")] + pub allow_recursive_delegation: bool, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub default_mode_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub capability_selector: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub allowed_profile_ids: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fork_mode: Option, + #[serde(default)] + pub restricted: bool, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reuse_scope_summary: Option, +} + +impl ChildPolicySpec { + pub fn validate(&self) -> Result<()> { + if let Some(selector) = &self.capability_selector { + selector.validate()?; + } + normalize_non_empty_unique_string_list( + &self.allowed_profile_ids, + "childPolicy.allowedProfileIds", + )?; + if let Some(summary) = &self.reuse_scope_summary { + validate_non_empty_trimmed("childPolicy.reuseScopeSummary", summary)?; + } + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ModeExecutionPolicySpec { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub submit_busy_policy: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fork_mode: Option, +} + +impl ModeExecutionPolicySpec { + pub fn validate(&self) -> Result<()> { + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PromptProgramEntry { + pub block_id: String, + pub title: String, + pub content: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub priority_hint: Option, +} + +impl PromptProgramEntry { + pub fn validate(&self) -> Result<()> { + validate_non_empty_trimmed("promptProgram.blockId", &self.block_id)?; + validate_non_empty_trimmed("promptProgram.title", &self.title)?; + validate_non_empty_trimmed("promptProgram.content", &self.content)?; + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct TransitionPolicySpec { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub allowed_targets: Vec, +} + +impl TransitionPolicySpec { + pub fn validate(&self) -> Result<()> { + let values = self + .allowed_targets + .iter() + .map(|mode_id| mode_id.as_str().to_string()) + .collect::>(); + normalize_non_empty_unique_string_list(&values, "transitionPolicy.allowedTargets")?; + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ModeArtifactDef { + pub artifact_type: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub file_template: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub schema_template: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub required_headings: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub actionable_sections: Vec, +} + +impl From for astrcode_core::mode::ModeArtifactDef { + fn from(value: ModeArtifactDef) -> Self { + Self { + artifact_type: value.artifact_type, + file_template: value.file_template, + schema_template: value.schema_template, + required_headings: value.required_headings, + actionable_sections: value.actionable_sections, + } + } +} + +impl From for ModeArtifactDef { + fn from(value: astrcode_core::mode::ModeArtifactDef) -> Self { + Self { + artifact_type: value.artifact_type, + file_template: value.file_template, + schema_template: value.schema_template, + required_headings: value.required_headings, + actionable_sections: value.actionable_sections, + } + } +} + +impl ModeArtifactDef { + pub fn validate(&self) -> Result<()> { + validate_non_empty_trimmed("mode.artifact.artifactType", &self.artifact_type)?; + if let Some(template) = &self.file_template { + validate_non_empty_trimmed("mode.artifact.fileTemplate", template)?; + } + if let Some(template) = &self.schema_template { + validate_non_empty_trimmed("mode.artifact.schemaTemplate", template)?; + } + normalize_non_empty_unique_string_list( + &self.required_headings, + "mode.artifact.requiredHeadings", + )?; + normalize_non_empty_unique_string_list( + &self.actionable_sections, + "mode.artifact.actionableSections", + )?; + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ModeExitGateDef { + pub review_passes: u32, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub review_checklist: Vec, +} + +impl From for astrcode_core::mode::ModeExitGateDef { + fn from(value: ModeExitGateDef) -> Self { + Self { + review_passes: value.review_passes, + review_checklist: value.review_checklist, + } + } +} + +impl From for ModeExitGateDef { + fn from(value: astrcode_core::mode::ModeExitGateDef) -> Self { + Self { + review_passes: value.review_passes, + review_checklist: value.review_checklist, + } + } +} + +impl ModeExitGateDef { + pub fn validate(&self) -> Result<()> { + if self.review_passes == 0 { + return Err(AstrError::Validation( + "mode.exitGate.reviewPasses 必须大于 0".to_string(), + )); + } + normalize_non_empty_unique_string_list( + &self.review_checklist, + "mode.exitGate.reviewChecklist", + )?; + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ModePromptHooks { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reentry_prompt: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub initial_template: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub exit_prompt: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub facts_template: Option, +} + +impl From for astrcode_core::mode::ModePromptHooks { + fn from(value: ModePromptHooks) -> Self { + Self { + reentry_prompt: value.reentry_prompt, + initial_template: value.initial_template, + exit_prompt: value.exit_prompt, + facts_template: value.facts_template, + } + } +} + +impl From for ModePromptHooks { + fn from(value: astrcode_core::mode::ModePromptHooks) -> Self { + Self { + reentry_prompt: value.reentry_prompt, + initial_template: value.initial_template, + exit_prompt: value.exit_prompt, + facts_template: value.facts_template, + } + } +} + +impl ModePromptHooks { + pub fn validate(&self) -> Result<()> { + let mut has_any = false; + for (field, value) in [ + ( + "mode.promptHooks.reentryPrompt", + self.reentry_prompt.as_ref(), + ), + ( + "mode.promptHooks.initialTemplate", + self.initial_template.as_ref(), + ), + ("mode.promptHooks.exitPrompt", self.exit_prompt.as_ref()), + ( + "mode.promptHooks.factsTemplate", + self.facts_template.as_ref(), + ), + ] { + if let Some(value) = value { + validate_non_empty_trimmed(field, value)?; + has_any = true; + } + } + if !has_any { + return Err(AstrError::Validation( + "mode.promptHooks 至少需要一个非空模板".to_string(), + )); + } + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct CompiledModeContracts { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub artifact: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub exit_gate: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub prompt_hooks: Option, +} + +impl From for astrcode_core::mode::CompiledModeContracts { + fn from(value: CompiledModeContracts) -> Self { + Self { + artifact: value.artifact.map(Into::into), + exit_gate: value.exit_gate.map(Into::into), + prompt_hooks: value.prompt_hooks.map(Into::into), + } + } +} + +impl From for CompiledModeContracts { + fn from(value: astrcode_core::mode::CompiledModeContracts) -> Self { + Self { + artifact: value.artifact.map(Into::into), + exit_gate: value.exit_gate.map(Into::into), + prompt_hooks: value.prompt_hooks.map(Into::into), + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct BoundModeToolContractSnapshot { + pub mode_id: ModeId, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub artifact: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub exit_gate: Option, +} + +impl From for astrcode_core::mode::BoundModeToolContractSnapshot { + fn from(value: BoundModeToolContractSnapshot) -> Self { + Self { + mode_id: value.mode_id.into(), + artifact: value.artifact.map(Into::into), + exit_gate: value.exit_gate.map(Into::into), + } + } +} + +impl From for BoundModeToolContractSnapshot { + fn from(value: astrcode_core::mode::BoundModeToolContractSnapshot) -> Self { + Self { + mode_id: value.mode_id.into(), + artifact: value.artifact.map(Into::into), + exit_gate: value.exit_gate.map(Into::into), + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct GovernanceModeSpec { + pub id: ModeId, + pub name: String, + pub description: String, + pub capability_selector: CapabilitySelector, + #[serde(default)] + pub action_policies: ActionPolicies, + #[serde(default)] + pub child_policy: ChildPolicySpec, + #[serde(default)] + pub execution_policy: ModeExecutionPolicySpec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub prompt_program: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub artifact: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub exit_gate: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub prompt_hooks: Option, + #[serde(default)] + pub transition_policy: TransitionPolicySpec, +} + +impl GovernanceModeSpec { + pub fn validate(&self) -> Result<()> { + validate_non_empty_trimmed("mode.id", self.id.as_str())?; + validate_non_empty_trimmed("mode.name", &self.name)?; + validate_non_empty_trimmed("mode.description", &self.description)?; + self.capability_selector.validate()?; + self.action_policies.validate()?; + self.child_policy.validate()?; + self.execution_policy.validate()?; + if let Some(artifact) = &self.artifact { + artifact.validate()?; + } + if let Some(exit_gate) = &self.exit_gate { + exit_gate.validate()?; + } + if let Some(prompt_hooks) = &self.prompt_hooks { + prompt_hooks.validate()?; + } + self.transition_policy.validate()?; + for entry in &self.prompt_program { + entry.validate()?; + } + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct ResolvedChildPolicy { + pub mode_id: ModeId, + #[serde(default = "default_true")] + pub allow_delegation: bool, + #[serde(default = "default_true")] + pub allow_recursive_delegation: bool, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub allowed_profile_ids: Vec, + #[serde(default)] + pub restricted: bool, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fork_mode: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reuse_scope_summary: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ResolvedTurnEnvelope { + pub mode_id: ModeId, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub prompt_declarations: Vec, + #[serde(default)] + pub mode_contracts: CompiledModeContracts, + #[serde(default)] + pub action_policies: ActionPolicies, + #[serde(default)] + pub child_policy: ResolvedChildPolicy, + #[serde(default)] + pub submit_busy_policy: SubmitBusyPolicy, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fork_mode: Option, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub diagnostics: Vec, +} + +impl ResolvedTurnEnvelope { + pub fn approval_mode(&self) -> String { + if self.action_policies.requires_approval() { + "required".to_string() + } else { + "inherit".to_string() + } + } + + pub fn bound_tool_contract_snapshot(&self) -> BoundModeToolContractSnapshot { + BoundModeToolContractSnapshot { + mode_id: self.mode_id.clone(), + artifact: self.mode_contracts.artifact.clone(), + exit_gate: self.mode_contracts.exit_gate.clone(), + } + } +} + +fn validate_non_empty_trimmed(field: &str, value: impl AsRef) -> Result<()> { + if value.as_ref().trim().is_empty() { + return Err(AstrError::Validation(format!("{field} 不能为空"))); + } + Ok(()) +} + +const fn default_true() -> bool { + true +} + +#[cfg(test)] +mod tests { + use astrcode_core::{CapabilityKind, SideEffect}; + use astrcode_prompt_contract::{ + PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, + PromptDeclarationSource, SystemPromptLayer, + }; + + use super::{ + ActionPolicies, BUILTIN_MODE_CODE_ID, BoundModeToolContractSnapshot, CapabilitySelector, + CompiledModeContracts, GovernanceModeSpec, ModeArtifactDef, ModeExitGateDef, ModeId, + ModePromptHooks, PromptProgramEntry, ResolvedTurnEnvelope, SubmitBusyPolicy, + }; + + #[test] + fn mode_id_defaults_to_builtin_code() { + assert_eq!(ModeId::default().as_str(), BUILTIN_MODE_CODE_ID); + } + + #[test] + fn capability_selector_validation_rejects_empty_union() { + let error = CapabilitySelector::Union(Vec::new()) + .validate() + .expect_err("empty union should be rejected"); + assert!(error.to_string().contains("不能为空")); + } + + #[test] + fn governance_mode_spec_round_trips_and_validates() { + let spec = GovernanceModeSpec { + id: ModeId::plan(), + name: "Plan".to_string(), + description: "只读规划".to_string(), + capability_selector: CapabilitySelector::Intersection(vec![ + CapabilitySelector::Kind(CapabilityKind::Tool), + CapabilitySelector::Difference { + base: Box::new(CapabilitySelector::AllTools), + subtract: Box::new(CapabilitySelector::SideEffect(SideEffect::Workspace)), + }, + ]), + action_policies: ActionPolicies::default(), + child_policy: Default::default(), + execution_policy: Default::default(), + prompt_program: vec![PromptProgramEntry { + block_id: "mode.plan".to_string(), + title: "Plan".to_string(), + content: "plan first".to_string(), + priority_hint: Some(600), + }], + artifact: Some(ModeArtifactDef { + artifact_type: "canonical-plan".to_string(), + file_template: Some("# Plan".to_string()), + schema_template: Some("markdown-plan-v1".to_string()), + required_headings: vec!["Context".to_string(), "Implementation Steps".to_string()], + actionable_sections: vec!["Implementation Steps".to_string()], + }), + exit_gate: Some(ModeExitGateDef { + review_passes: 1, + review_checklist: vec!["验证实现步骤".to_string()], + }), + prompt_hooks: Some(ModePromptHooks { + reentry_prompt: Some("read the plan first".to_string()), + initial_template: Some("## Implementation Steps".to_string()), + exit_prompt: Some("use approved plan".to_string()), + facts_template: Some("targetPlanPath={{target_plan_path}}".to_string()), + }), + transition_policy: Default::default(), + }; + + spec.validate().expect("spec should be valid"); + let encoded = serde_json::to_string(&spec).expect("spec should serialize"); + let decoded: GovernanceModeSpec = + serde_json::from_str(&encoded).expect("spec should deserialize"); + assert_eq!(decoded.id, ModeId::plan()); + } + + #[test] + fn mode_artifact_def_rejects_blank_artifact_type() { + let error = ModeArtifactDef { + artifact_type: " ".to_string(), + ..ModeArtifactDef::default() + } + .validate() + .expect_err("blank artifact type should fail"); + assert!(error.to_string().contains("artifactType")); + } + + #[test] + fn mode_exit_gate_def_rejects_zero_review_passes() { + let error = ModeExitGateDef { + review_passes: 0, + review_checklist: vec!["检查计划".to_string()], + } + .validate() + .expect_err("zero review passes should fail"); + assert!(error.to_string().contains("reviewPasses")); + } + + #[test] + fn mode_prompt_hooks_require_at_least_one_non_empty_template() { + let error = ModePromptHooks::default() + .validate() + .expect_err("empty hooks should fail"); + assert!(error.to_string().contains("至少需要一个")); + } + + #[test] + fn resolved_turn_envelope_reports_required_approval_mode_when_rule_asks() { + let envelope = ResolvedTurnEnvelope { + mode_id: ModeId::review(), + prompt_declarations: vec![PromptDeclaration { + block_id: "mode.review".to_string(), + title: "Review".to_string(), + content: "review only".to_string(), + render_target: PromptDeclarationRenderTarget::System, + layer: SystemPromptLayer::Dynamic, + kind: PromptDeclarationKind::ExtensionInstruction, + priority_hint: Some(600), + always_include: true, + source: PromptDeclarationSource::Builtin, + capability_name: None, + origin: None, + }], + mode_contracts: CompiledModeContracts::default(), + action_policies: ActionPolicies { + default_effect: crate::ActionPolicyEffect::Ask, + rules: Vec::new(), + }, + child_policy: Default::default(), + submit_busy_policy: SubmitBusyPolicy::RejectOnBusy, + fork_mode: None, + diagnostics: Vec::new(), + }; + + assert_eq!(envelope.approval_mode(), "required"); + } + + #[test] + fn resolved_turn_envelope_projects_bound_tool_contract_snapshot() { + let envelope = ResolvedTurnEnvelope { + mode_id: ModeId::plan(), + prompt_declarations: Vec::new(), + mode_contracts: CompiledModeContracts { + artifact: Some(ModeArtifactDef { + artifact_type: "canonical-plan".to_string(), + file_template: None, + schema_template: None, + required_headings: vec!["Implementation Steps".to_string()], + actionable_sections: vec!["Implementation Steps".to_string()], + }), + exit_gate: Some(ModeExitGateDef { + review_passes: 1, + review_checklist: vec!["检查验证步骤".to_string()], + }), + prompt_hooks: None, + }, + action_policies: ActionPolicies::default(), + child_policy: Default::default(), + submit_busy_policy: SubmitBusyPolicy::BranchOnBusy, + fork_mode: None, + diagnostics: Vec::new(), + }; + + assert_eq!( + envelope.bound_tool_contract_snapshot(), + BoundModeToolContractSnapshot { + mode_id: ModeId::plan(), + artifact: envelope.mode_contracts.artifact.clone(), + exit_gate: envelope.mode_contracts.exit_gate.clone(), + } + ); + } +} diff --git a/crates/governance-contract/src/policy.rs b/crates/governance-contract/src/policy.rs new file mode 100644 index 00000000..95c96930 --- /dev/null +++ b/crates/governance-contract/src/policy.rs @@ -0,0 +1,312 @@ +//! # 策略引擎 +//! +//! 定义治理层的策略接口和请求/审批类型。 + +use astrcode_core::{CapabilitySpec, LlmMessage, Result, action::ToolDefinition}; +use astrcode_prompt_contract::SystemPromptLayer; +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +/// 已渲染的系统提示词块。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct SystemPromptBlock { + pub title: String, + pub content: String, + #[serde(default, skip_serializing_if = "is_false")] + pub cache_boundary: bool, + #[serde(default, skip_serializing_if = "is_unspecified_system_prompt_layer")] + pub layer: SystemPromptLayer, +} + +impl SystemPromptBlock { + pub fn render(&self) -> String { + format!("[{}]\n{}", self.title, self.content) + } +} + +fn is_false(value: &bool) -> bool { + !*value +} + +fn is_unspecified_system_prompt_layer(layer: &SystemPromptLayer) -> bool { + matches!(layer, SystemPromptLayer::Unspecified) +} + +/// Turn 范围的模型请求，策略层可在执行前检查或重写。 +#[derive(Debug, Clone)] +pub struct ModelRequest { + pub messages: Vec, + pub tools: Vec, + pub system_prompt: Option, + pub system_prompt_blocks: Vec, +} + +/// 通用能力调用提案。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct CapabilityCall { + pub request_id: String, + pub capability: CapabilitySpec, + pub payload: Value, + #[serde(default)] + pub metadata: Value, +} + +impl CapabilityCall { + pub fn name(&self) -> &str { + self.capability.name.as_str() + } +} + +/// 策略实现可用的共享 turn 元数据，不暴露传输细节。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PolicyContext { + pub session_id: String, + pub turn_id: String, + pub step_index: usize, + pub working_dir: String, + pub profile: String, + #[serde(default)] + pub metadata: Value, +} + +/// 审批默认值。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ApprovalDefault { + Allow, + Deny, +} + +impl ApprovalDefault { + pub fn resolve(self) -> ApprovalResolution { + match self { + Self::Allow => ApprovalResolution::approved(), + Self::Deny => ApprovalResolution::denied("approval denied by default"), + } + } +} + +/// 策略层产生的、需要用户确认的审批载荷。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ApprovalRequest { + pub request_id: String, + pub session_id: String, + pub turn_id: String, + pub capability: CapabilitySpec, + pub payload: Value, + pub prompt: String, + pub default: ApprovalDefault, + #[serde(default)] + pub metadata: Value, +} + +impl ApprovalRequest { + pub fn capability_name(&self) -> &str { + &self.capability.name + } +} + +/// 审批结果。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ApprovalResolution { + pub approved: bool, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub reason: Option, +} + +impl ApprovalResolution { + pub fn approved() -> Self { + Self { + approved: true, + reason: None, + } + } + + pub fn denied(reason: impl Into) -> Self { + Self { + approved: false, + reason: Some(reason.into()), + } + } +} + +/// 等待审批的动作。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ApprovalPending { + pub request: ApprovalRequest, + pub action: T, +} + +/// 策略引擎对能力调用的裁决结果。 +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum PolicyVerdict { + Allow(T), + Deny { reason: String }, + Ask(Box>), +} + +impl PolicyVerdict { + pub fn allow(value: T) -> Self { + Self::Allow(value) + } + + pub fn deny(reason: impl Into) -> Self { + Self::Deny { + reason: reason.into(), + } + } + + pub fn ask(request: ApprovalRequest, action: T) -> Self { + Self::Ask(Box::new(ApprovalPending { request, action })) + } +} + +/// 策略引擎 trait。 +#[async_trait] +pub trait PolicyEngine: Send + Sync { + async fn check_model_request( + &self, + request: ModelRequest, + ctx: &PolicyContext, + ) -> Result; + + async fn check_capability_call( + &self, + call: CapabilityCall, + ctx: &PolicyContext, + ) -> Result>; +} + +/// 允许所有操作的无状态策略引擎。 +#[derive(Debug, Default, Clone, Copy)] +pub struct AllowAllPolicyEngine; + +#[async_trait] +impl PolicyEngine for AllowAllPolicyEngine { + async fn check_model_request( + &self, + request: ModelRequest, + _ctx: &PolicyContext, + ) -> Result { + Ok(request) + } + + async fn check_capability_call( + &self, + call: CapabilityCall, + _ctx: &PolicyContext, + ) -> Result> { + Ok(PolicyVerdict::Allow(call)) + } +} + +#[cfg(test)] +mod tests { + use astrcode_core::{CapabilityKind, CapabilitySpec, InvocationMode, SideEffect, Stability}; + use serde_json::{Value, json}; + + use super::{ + AllowAllPolicyEngine, ApprovalDefault, ApprovalRequest, PolicyContext, PolicyEngine, + PolicyVerdict, + }; + use crate::ModelRequest; + + fn capability(name: &str) -> CapabilitySpec { + CapabilitySpec { + name: name.into(), + kind: CapabilityKind::Tool, + description: "test capability".to_string(), + input_schema: json!({ "type": "object" }), + output_schema: json!({ "type": "object" }), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: false, + profiles: vec!["coding".to_string()], + tags: vec![], + permissions: vec![], + side_effect: SideEffect::Workspace, + stability: Stability::Stable, + metadata: Value::Null, + max_result_inline_size: None, + } + } + + fn policy_context() -> PolicyContext { + PolicyContext { + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + step_index: 0, + working_dir: ".".to_string(), + profile: "coding".to_string(), + metadata: Value::Null, + } + } + + #[tokio::test] + async fn allow_all_policy_preserves_requests() { + let policy = AllowAllPolicyEngine; + let request = ModelRequest { + messages: vec![], + tools: vec![], + system_prompt: Some("system".to_string()), + system_prompt_blocks: Vec::new(), + }; + let call = super::CapabilityCall { + request_id: "call-1".to_string(), + capability: capability("tool.sample"), + payload: json!({ "path": "Cargo.toml" }), + metadata: Value::Null, + }; + + let checked_request = policy + .check_model_request(request, &policy_context()) + .await + .expect("request should pass"); + assert_eq!(checked_request.system_prompt.as_deref(), Some("system")); + assert!(checked_request.messages.is_empty()); + assert!(checked_request.tools.is_empty()); + assert_eq!( + policy + .check_capability_call(call.clone(), &policy_context()) + .await + .expect("call should pass"), + PolicyVerdict::Allow(call) + ); + } + + #[test] + fn approval_default_resolves_to_expected_resolution() { + assert!(ApprovalDefault::Allow.resolve().approved); + assert_eq!( + ApprovalDefault::Deny.resolve(), + super::ApprovalResolution { + approved: false, + reason: Some("approval denied by default".to_string()), + } + ); + } + + #[test] + fn approval_request_reports_capability_name() { + let request = ApprovalRequest { + request_id: "call-1".to_string(), + session_id: "session-1".to_string(), + turn_id: "turn-1".to_string(), + capability: capability("tool.sample"), + payload: json!({}), + prompt: "Allow?".to_string(), + default: ApprovalDefault::Deny, + metadata: Value::Null, + }; + + assert_eq!(request.capability_name(), "tool.sample"); + } +} diff --git a/crates/host-session/Cargo.toml b/crates/host-session/Cargo.toml index 6b4a320e..e15ccb7f 100644 --- a/crates/host-session/Cargo.toml +++ b/crates/host-session/Cargo.toml @@ -8,8 +8,12 @@ authors.workspace = true [dependencies] astrcode-agent-runtime = { path = "../agent-runtime" } astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } astrcode-plugin-host = { path = "../plugin-host" } +astrcode-prompt-contract = { path = "../prompt-contract" } +astrcode-runtime-contract = { path = "../runtime-contract" } astrcode-support = { path = "../support" } +astrcode-tool-contract = { path = "../tool-contract" } async-trait.workspace = true chrono.workspace = true dashmap.workspace = true diff --git a/crates/host-session/src/catalog.rs b/crates/host-session/src/catalog.rs index 48470440..2e2cadfb 100644 --- a/crates/host-session/src/catalog.rs +++ b/crates/host-session/src/catalog.rs @@ -4,16 +4,16 @@ use std::{ }; use astrcode_core::{ - AstrError, EventTranslator, ModeId, Phase, Result, SessionId, SessionMeta, - SessionTurnAcquireResult, StorageEvent, StorageEventPayload, StoredEvent, - event::generate_session_id, + AstrError, Phase, Result, SessionId, SessionMeta, SessionTurnAcquireResult, StorageEvent, + StorageEventPayload, StoredEvent, event::generate_session_id, mode::ModeId, }; use chrono::Utc; use dashmap::DashMap; use tokio::sync::broadcast; use crate::{ - AgentStateProjector, EventStore, SessionCatalogEvent, SessionState, SessionWriter, + AgentStateProjector, EventStore, EventTranslator, SessionCatalogEvent, SessionState, + SessionWriter, replay_records, state::{SESSION_BROADCAST_CAPACITY, append_and_broadcast}, turn_mutation::TurnMutationState, }; @@ -199,7 +199,7 @@ impl SessionCatalog { normalize_recovered_phase_from_events(&recovered.tail_events), writer, AgentStateProjector::from_events(&events), - astrcode_core::replay_records(&recovered.tail_events, None), + replay_records(&recovered.tail_events, None), recovered.tail_events, ) }, @@ -378,8 +378,8 @@ mod tests { }; use astrcode_core::{ - DeleteProjectResult, ModeId, SessionMeta, SessionTurnAcquireResult, SessionTurnLease, - StoredEvent, + DeleteProjectResult, SessionMeta, SessionTurnAcquireResult, SessionTurnLease, StoredEvent, + mode::ModeId, }; use async_trait::async_trait; diff --git a/crates/host-session/src/collaboration.rs b/crates/host-session/src/collaboration.rs index bb53ffa0..74a779fb 100644 --- a/crates/host-session/src/collaboration.rs +++ b/crates/host-session/src/collaboration.rs @@ -1,14 +1,15 @@ use astrcode_core::{ AgentCollaborationFact, AgentEventContext, ChildSessionNotification, CloseAgentParams, - CollaborationResult, EventTranslator, InputBatchAckedPayload, InputBatchStartedPayload, - InputDiscardedPayload, InputQueuedPayload, ObserveParams, ResolvedExecutionLimitsSnapshot, + CollaborationResult, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, + InputQueuedPayload, ObserveParams, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, Result, SendAgentParams, SpawnAgentParams, StorageEvent, - StorageEventPayload, StoredEvent, SubRunResult, ToolContext, + StorageEventPayload, StoredEvent, SubRunResult, }; +use astrcode_tool_contract::ToolContext; use async_trait::async_trait; use chrono::Utc; -use crate::{SessionCatalog, state}; +use crate::{EventTranslator, SessionCatalog, state}; /// `host-session` 对外暴露的 sub-run owner bridge。 /// diff --git a/crates/host-session/src/compaction.rs b/crates/host-session/src/compaction.rs index 2648cf33..63a8ce74 100644 --- a/crates/host-session/src/compaction.rs +++ b/crates/host-session/src/compaction.rs @@ -1,6 +1,6 @@ -use astrcode_core::{EventTranslator, Result, StorageEvent, StorageEventPayload, StoredEvent}; +use astrcode_core::{Result, StorageEvent, StorageEventPayload, StoredEvent}; -use crate::{SessionCatalog, state}; +use crate::{EventTranslator, SessionCatalog, state}; #[derive(Debug, Clone)] pub struct CompactPersistResult { diff --git a/crates/core/src/event/translate.rs b/crates/host-session/src/event_translate.rs similarity index 98% rename from crates/core/src/event/translate.rs rename to crates/host-session/src/event_translate.rs index c203a6ea..1c2ef8c3 100644 --- a/crates/core/src/event/translate.rs +++ b/crates/host-session/src/event_translate.rs @@ -17,13 +17,12 @@ use std::collections::HashMap; -use serde_json::json; - -use super::phase::PhaseTracker; -use crate::{ - AgentEvent, AgentEventContext, Phase, StorageEvent, StorageEventPayload, StoredEvent, - ToolExecutionResult, UserMessageOrigin, session::SessionEventRecord, split_assistant_content, +use astrcode_core::{ + AgentEvent, AgentEventContext, Phase, SessionEventRecord, StorageEvent, StorageEventPayload, + StoredEvent, UserMessageOrigin, action::ToolExecutionResult, event::PhaseTracker, + phase_of_storage_event, split_assistant_content, }; +use serde_json::json; /// 批量回放存储事件为会话事件记录。 /// @@ -427,7 +426,7 @@ impl EventTranslator { warn_missing_turn_id(stored.storage_seq, "turnDone"); } self.phase_tracker.force_to( - super::phase::target_phase(&stored.event), + phase_of_storage_event(&stored.event), None, AgentEventContext::default(), ); @@ -497,14 +496,14 @@ impl EventTranslator { #[cfg(test)] mod tests { + use astrcode_core::{ + AgentEvent, AgentEventContext, CompactAppliedMeta, CompactMode, CompactTrigger, + PromptMetricsPayload, StoredEvent, UserMessageOrigin, action::ToolOutputStream, + format_compact_summary, phase_of_storage_event, + }; use serde_json::json; use super::*; - use crate::{ - AgentEvent, AgentEventContext, CompactAppliedMeta, CompactMode, PromptMetricsPayload, - StoredEvent, ToolOutputStream, UserMessageOrigin, format_compact_summary, - phase_of_storage_event, - }; #[test] fn user_message_replays_before_phase_change() { @@ -722,7 +721,7 @@ mod tests { turn_id: None, agent: AgentEventContext::default(), payload: StorageEventPayload::CompactApplied { - trigger: crate::CompactTrigger::Manual, + trigger: CompactTrigger::Manual, summary: "保留最近上下文".to_string(), meta: CompactAppliedMeta { mode: CompactMode::Incremental, @@ -750,7 +749,7 @@ mod tests { &records[0].event, AgentEvent::CompactApplied { turn_id: None, - trigger: crate::CompactTrigger::Manual, + trigger: CompactTrigger::Manual, summary, meta, preserved_recent_turns, diff --git a/crates/host-session/src/lib.rs b/crates/host-session/src/lib.rs index 66e0599a..7ab28fda 100644 --- a/crates/host-session/src/lib.rs +++ b/crates/host-session/src/lib.rs @@ -11,6 +11,7 @@ pub mod compaction; pub mod composer; mod event_cache; pub mod event_log; +mod event_translate; pub mod execution_surface; pub mod fork; pub mod input_queue; @@ -37,6 +38,7 @@ pub use collaboration::{ pub use compaction::CompactPersistResult; pub use composer::{ComposerOption, ComposerOptionActionKind, ComposerOptionKind}; pub use event_log::SessionWriter; +pub use event_translate::{EventTranslator, replay_records}; pub use execution_surface::HostSessionSnapshot; pub use fork::{ForkPoint, ForkResult}; pub use input_queue::{InputKind, InputQueueProjection}; diff --git a/crates/host-session/src/ports.rs b/crates/host-session/src/ports.rs index 0a9a2961..fe34bc9f 100644 --- a/crates/host-session/src/ports.rs +++ b/crates/host-session/src/ports.rs @@ -3,11 +3,13 @@ use std::{ path::{Path, PathBuf}, }; -use astrcode_agent_runtime::provider::{PromptCacheGlobalStrategy, PromptCacheHints}; use astrcode_core::{ - CapabilitySpec, ChildSessionNode, DeleteProjectResult, PromptDeclaration, Result, SessionId, - SessionMeta, SessionTurnAcquireResult, StorageEvent, StoredEvent, SystemPromptBlock, - SystemPromptLayer, TaskSnapshot, TurnId, TurnTerminalKind, mode::ModeId, + CapabilitySpec, ChildSessionNode, DeleteProjectResult, Result, SessionId, SessionMeta, + SessionTurnAcquireResult, StorageEvent, StoredEvent, TaskSnapshot, TurnId, TurnTerminalKind, +}; +use astrcode_governance_contract::{ModeId, SystemPromptBlock}; +use astrcode_prompt_contract::{ + PromptCacheGlobalStrategy, PromptCacheHints, PromptDeclaration, SystemPromptLayer, }; use async_trait::async_trait; use chrono::{DateTime, Utc}; diff --git a/crates/host-session/src/projection.rs b/crates/host-session/src/projection.rs index da7d779e..c58a8ddd 100644 --- a/crates/host-session/src/projection.rs +++ b/crates/host-session/src/projection.rs @@ -20,10 +20,12 @@ use std::path::PathBuf; use astrcode_core::{ - InvocationKind, LlmMessage, ModeId, Phase, ReasoningContent, ToolCallRequest, - ToolExecutionResult, UserMessageOrigin, + InvocationKind, LlmMessage, Phase, ReasoningContent, ToolCallRequest, UserMessageOrigin, + action::ToolExecutionResult, event::{StorageEvent, StorageEventPayload}, - format_compact_summary, split_assistant_content, + format_compact_summary, + mode::ModeId, + split_assistant_content, }; use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; diff --git a/crates/host-session/src/projection_registry.rs b/crates/host-session/src/projection_registry.rs index 474b7660..8204e065 100644 --- a/crates/host-session/src/projection_registry.rs +++ b/crates/host-session/src/projection_registry.rs @@ -1,8 +1,8 @@ use std::collections::{HashMap, VecDeque}; use astrcode_core::{ - ChildSessionNode, ModeId, Phase, Result, SessionEventRecord, StorageEventPayload, StoredEvent, - TaskSnapshot, event::PhaseTracker, + ChildSessionNode, Phase, Result, SessionEventRecord, StorageEventPayload, StoredEvent, + TaskSnapshot, event::PhaseTracker, mode::ModeId, }; use chrono::{DateTime, Utc}; diff --git a/crates/host-session/src/query.rs b/crates/host-session/src/query.rs index 8dd7f2b6..cd112d9c 100644 --- a/crates/host-session/src/query.rs +++ b/crates/host-session/src/query.rs @@ -1,15 +1,15 @@ use std::sync::Arc; use astrcode_core::{ - AgentEvent, ChildSessionNode, CompactAppliedMeta, CompactTrigger, ModeId, Phase, Result, - SessionEventRecord, SessionId, StoredEvent, TaskSnapshot, TurnTerminalKind, + AgentEvent, ChildSessionNode, CompactAppliedMeta, CompactTrigger, Phase, Result, + SessionEventRecord, SessionId, StoredEvent, TaskSnapshot, TurnTerminalKind, mode::ModeId, }; use chrono::{DateTime, Utc}; use tokio::sync::broadcast::error::RecvError; use crate::{ InputQueueProjection, SessionCatalog, SessionSnapshot, SessionState, TurnProjectionSnapshot, - turn_projection::project_turn_projection, + replay_records, turn_projection::project_turn_projection, }; #[derive(Debug, Clone, PartialEq, Eq)] @@ -184,7 +184,7 @@ impl SessionCatalog { last_event_id: Option<&str>, ) -> Result { self.ensure_session_exists(session_id).await?; - let full = astrcode_core::replay_records(&self.event_store.replay(session_id).await?, None); + let full = replay_records(&self.event_store.replay(session_id).await?, None); let (seed_records, history) = split_records_at_cursor(full, last_event_id); Ok(SessionReadModelReplay { cursor: history.last().map(|record| record.event_id.clone()), diff --git a/crates/host-session/src/state.rs b/crates/host-session/src/state.rs index d0862eb4..8fc95818 100644 --- a/crates/host-session/src/state.rs +++ b/crates/host-session/src/state.rs @@ -1,16 +1,19 @@ use std::sync::{Arc, Mutex as StdMutex}; use astrcode_core::{ - AgentEvent, ChildSessionNode, EventTranslator, LlmMessage, ModeId, Phase, Result, - SessionEventRecord, StoredEvent, TaskSnapshot, normalize_recovered_phase, + AgentEvent, ChildSessionNode, LlmMessage, Phase, Result, SessionEventRecord, StoredEvent, + TaskSnapshot, + mode::ModeId, + normalize_recovered_phase, support::{self}, }; use chrono::Utc; use tokio::sync::broadcast; use crate::{ - AgentState, AgentStateProjector, EventStore, InputQueueProjection, SessionRecoveryCheckpoint, - TurnProjectionSnapshot, event_log::SessionWriter, projection_registry::ProjectionRegistry, + AgentState, AgentStateProjector, EventStore, EventTranslator, InputQueueProjection, + SessionRecoveryCheckpoint, TurnProjectionSnapshot, event_log::SessionWriter, + projection_registry::ProjectionRegistry, replay_records, }; pub const SESSION_BROADCAST_CAPACITY: usize = 2048; @@ -71,7 +74,7 @@ impl SessionState { })?; projection_registry.apply(stored)?; } - projection_registry.cache_records(&astrcode_core::replay_records(&tail_events, None)); + projection_registry.cache_records(&replay_records(&tail_events, None)); let (broadcaster, _) = broadcast::channel(SESSION_BROADCAST_CAPACITY); let (live_broadcaster, _) = broadcast::channel(SESSION_LIVE_BROADCAST_CAPACITY); @@ -314,13 +317,13 @@ mod tests { use astrcode_core::{ AgentEventContext, AgentLifecycleStatus, ChildSessionLineageKind, ChildSessionNotification, - ChildSessionNotificationKind, ChildSessionStatusSource, EventLogWriter, EventTranslator, - InputQueuedPayload, Phase, QueuedInputEnvelope, StorageEvent, StorageEventPayload, - StoreResult, StoredEvent, SubRunStorageMode, UserMessageOrigin, + ChildSessionNotificationKind, ChildSessionStatusSource, EventLogWriter, InputQueuedPayload, + Phase, QueuedInputEnvelope, StorageEvent, StorageEventPayload, StoreResult, StoredEvent, + SubRunStorageMode, UserMessageOrigin, }; use super::{SessionState, SessionWriter}; - use crate::{AgentStateProjector, SubRunHandle}; + use crate::{AgentStateProjector, EventTranslator, SubRunHandle}; #[derive(Default)] struct NoopEventLogWriter { diff --git a/crates/host-session/src/turn_mutation.rs b/crates/host-session/src/turn_mutation.rs index 8071b493..2f30fe57 100644 --- a/crates/host-session/src/turn_mutation.rs +++ b/crates/host-session/src/turn_mutation.rs @@ -6,16 +6,16 @@ use std::sync::{Arc, Mutex as StdMutex}; -use astrcode_agent_runtime::RuntimeTurnEvent; use astrcode_core::{ - AgentEventContext, AstrError, CancelToken, EventTranslator, ExecutionAccepted, - ExecutionControl, Result, SessionId, StorageEvent, StorageEventPayload, StoredEvent, TurnId, - TurnTerminalKind, UserMessageOrigin, generate_turn_id, + AgentEventContext, AstrError, CancelToken, ExecutionControl, Result, SessionId, StorageEvent, + StorageEventPayload, StoredEvent, TurnId, TurnTerminalKind, UserMessageOrigin, + generate_turn_id, }; +use astrcode_runtime_contract::{ExecutionAccepted, RuntimeTurnEvent}; use async_trait::async_trait; use chrono::Utc; -use crate::{SessionCatalog, SubmitTarget, state::checkpoint_if_compacted}; +use crate::{EventTranslator, SessionCatalog, SubmitTarget, state::checkpoint_if_compacted}; /// turn mutation 预处理来源。 /// @@ -710,10 +710,11 @@ mod tests { use astrcode_agent_runtime::TurnIdentity; use astrcode_core::{ - AgentId, DeleteProjectResult, ExecutionAccepted, Phase, SessionMeta, - SessionTurnAcquireResult, SessionTurnBusy, SessionTurnLease, StorageEvent, - StorageEventPayload, StoredEvent, TurnTerminalKind, + AgentId, DeleteProjectResult, Phase, SessionMeta, SessionTurnAcquireResult, + SessionTurnBusy, SessionTurnLease, StorageEvent, StorageEventPayload, StoredEvent, + TurnTerminalKind, }; + use astrcode_runtime_contract::ExecutionAccepted; use async_trait::async_trait; use chrono::Utc; diff --git a/crates/host-session/src/workflow.rs b/crates/host-session/src/workflow.rs index c30d47f5..faac0482 100644 --- a/crates/host-session/src/workflow.rs +++ b/crates/host-session/src/workflow.rs @@ -1,6 +1,6 @@ use std::collections::BTreeMap; -use astrcode_core::ModeId; +use astrcode_governance_contract::ModeId; use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; use serde_json::Value; @@ -130,7 +130,7 @@ pub struct WorkflowInstanceState { mod tests { use std::collections::BTreeMap; - use astrcode_core::ModeId; + use astrcode_governance_contract::ModeId; use serde_json::json; use super::{ diff --git a/crates/llm-contract/Cargo.toml b/crates/llm-contract/Cargo.toml new file mode 100644 index 00000000..c9fd12f5 --- /dev/null +++ b/crates/llm-contract/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "astrcode-llm-contract" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } +astrcode-prompt-contract = { path = "../prompt-contract" } +async-trait.workspace = true +serde.workspace = true diff --git a/crates/llm-contract/src/lib.rs b/crates/llm-contract/src/lib.rs new file mode 100644 index 00000000..0096186f --- /dev/null +++ b/crates/llm-contract/src/lib.rs @@ -0,0 +1,189 @@ +use std::sync::Arc; + +use astrcode_core::{ + CancelToken, LlmMessage, ReasoningContent, Result, ToolCallRequest, ToolDefinition, +}; +use astrcode_governance_contract::{ModelRequest, SystemPromptBlock}; +pub use astrcode_prompt_contract::{ + PromptCacheBreakReason, PromptCacheDiagnostics, PromptCacheGlobalStrategy, PromptCacheHints, + PromptLayerFingerprints, +}; +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; + +/// runtime owner 的 provider 能力限制。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct ModelLimits { + pub context_window: usize, + pub max_output_tokens: usize, +} + +/// 模型 token 使用统计。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct LlmUsage { + pub input_tokens: usize, + pub output_tokens: usize, + pub cache_creation_input_tokens: usize, + pub cache_read_input_tokens: usize, +} + +impl LlmUsage { + pub fn total_tokens(self) -> usize { + self.input_tokens.saturating_add(self.output_tokens) + } +} + +/// LLM 输出结束原因。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum LlmFinishReason { + #[default] + Stop, + MaxTokens, + ToolCalls, + Other(String), +} + +impl LlmFinishReason { + pub fn is_max_tokens(&self) -> bool { + matches!(self, Self::MaxTokens) + } + + pub fn from_api_value(value: &str) -> Self { + match value { + "stop" => Self::Stop, + "max_tokens" | "length" => Self::MaxTokens, + "tool_calls" => Self::ToolCalls, + other => Self::Other(other.to_string()), + } + } +} + +/// provider 流式增量事件。 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum LlmEvent { + TextDelta(String), + ThinkingDelta(String), + ThinkingSignature(String), + StreamRetryStarted { + attempt: u32, + max_attempts: u32, + reason: String, + }, + ToolCallDelta { + index: usize, + id: Option, + name: Option, + arguments_delta: String, + }, +} + +pub type LlmEventSink = Arc; + +/// 模型调用请求。 +#[derive(Debug, Clone)] +pub struct LlmRequest { + pub messages: Vec, + pub tools: Arc<[ToolDefinition]>, + pub cancel: CancelToken, + pub system_prompt: Option, + pub system_prompt_blocks: Vec, + pub prompt_cache_hints: Option, + pub max_output_tokens_override: Option, + pub skip_cache_write: bool, +} + +impl LlmRequest { + pub fn new( + messages: Vec, + tools: impl Into>, + cancel: CancelToken, + ) -> Self { + Self { + messages, + tools: tools.into(), + cancel, + system_prompt: None, + system_prompt_blocks: Vec::new(), + prompt_cache_hints: None, + max_output_tokens_override: None, + skip_cache_write: false, + } + } + + pub fn with_system(mut self, prompt: impl Into) -> Self { + self.system_prompt = Some(prompt.into()); + self + } + + pub fn with_max_output_tokens_override(mut self, max_output_tokens: usize) -> Self { + self.max_output_tokens_override = Some(max_output_tokens.max(1)); + self + } + + pub fn with_skip_cache_write(mut self, skip_cache_write: bool) -> Self { + self.skip_cache_write = skip_cache_write; + self + } + + pub fn from_model_request(request: ModelRequest, cancel: CancelToken) -> Self { + Self { + messages: request.messages, + tools: request.tools.into(), + cancel, + system_prompt: request.system_prompt, + system_prompt_blocks: request.system_prompt_blocks, + prompt_cache_hints: None, + max_output_tokens_override: None, + skip_cache_write: false, + } + } +} + +/// 模型调用输出。 +#[derive(Debug, Clone, Default)] +pub struct LlmOutput { + pub content: String, + pub tool_calls: Vec, + pub reasoning: Option, + pub usage: Option, + pub finish_reason: LlmFinishReason, + pub prompt_cache_diagnostics: Option, +} + +/// agent-runtime 消费的抽象 provider stream surface。 +#[async_trait] +pub trait LlmProvider: Send + Sync { + async fn generate(&self, request: LlmRequest, sink: Option) -> Result; + fn model_limits(&self) -> ModelLimits; + fn supports_cache_metrics(&self) -> bool { + false + } +} + +#[cfg(test)] +mod tests { + use super::{LlmFinishReason, LlmUsage}; + + #[test] + fn usage_total_saturates() { + let usage = LlmUsage { + input_tokens: usize::MAX, + output_tokens: 1, + cache_creation_input_tokens: 0, + cache_read_input_tokens: 0, + }; + + assert_eq!(usage.total_tokens(), usize::MAX); + } + + #[test] + fn finish_reason_accepts_openai_family_values() { + assert!(LlmFinishReason::from_api_value("length").is_max_tokens()); + assert_eq!( + LlmFinishReason::from_api_value("tool_calls"), + LlmFinishReason::ToolCalls + ); + } +} diff --git a/crates/plugin-host/Cargo.toml b/crates/plugin-host/Cargo.toml index f9e827f3..9f92d799 100644 --- a/crates/plugin-host/Cargo.toml +++ b/crates/plugin-host/Cargo.toml @@ -7,8 +7,8 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } astrcode-protocol = { path = "../protocol" } -astrcode-support = { path = "../support" } log.workspace = true async-trait.workspace = true serde.workspace = true diff --git a/crates/plugin-host/src/descriptor.rs b/crates/plugin-host/src/descriptor.rs index 6ab5db7d..23952c20 100644 --- a/crates/plugin-host/src/descriptor.rs +++ b/crates/plugin-host/src/descriptor.rs @@ -1,6 +1,7 @@ use std::collections::BTreeSet; -use astrcode_core::{AstrError, CapabilitySpec, GovernanceModeSpec, Result}; +use astrcode_core::{AstrError, CapabilitySpec, Result}; +use astrcode_governance_contract::GovernanceModeSpec; #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] pub enum PluginSourceKind { diff --git a/crates/plugin-host/src/host_dispatch.rs b/crates/plugin-host/src/host_dispatch.rs index fc6e9afe..804cf66d 100644 --- a/crates/plugin-host/src/host_dispatch.rs +++ b/crates/plugin-host/src/host_dispatch.rs @@ -31,6 +31,7 @@ pub struct PluginRuntimeHandleSnapshot { pub struct PluginCapabilityBinding { pub plugin_id: String, pub display_name: String, + pub source_ref: String, pub backend_kind: PluginBackendKind, pub capability: CapabilityWireDescriptor, pub runtime_handle: Option, diff --git a/crates/plugin-host/src/host_reload.rs b/crates/plugin-host/src/host_reload.rs index 06248ae1..62b22b01 100644 --- a/crates/plugin-host/src/host_reload.rs +++ b/crates/plugin-host/src/host_reload.rs @@ -375,6 +375,7 @@ impl PluginHostReload { .map(|tool| PluginCapabilityBinding { plugin_id: descriptor.plugin_id.clone(), display_name: descriptor.display_name.clone(), + source_ref: descriptor.source_ref.clone(), backend_kind: descriptor.source_kind.to_backend_kind(), capability: tool.clone(), runtime_handle: self.runtime_handle_snapshot(&descriptor.plugin_id), @@ -389,6 +390,7 @@ impl PluginHostReload { descriptor.tools.iter().map(|tool| PluginCapabilityBinding { plugin_id: descriptor.plugin_id.clone(), display_name: descriptor.display_name.clone(), + source_ref: descriptor.source_ref.clone(), backend_kind: descriptor.source_kind.to_backend_kind(), capability: tool.clone(), runtime_handle: self.runtime_handle_snapshot(&descriptor.plugin_id), diff --git a/crates/plugin-host/src/host_tests.rs b/crates/plugin-host/src/host_tests.rs index 4a52db08..6d0e1559 100644 --- a/crates/plugin-host/src/host_tests.rs +++ b/crates/plugin-host/src/host_tests.rs @@ -6,9 +6,9 @@ use std::{ }; use astrcode_core::{ - AgentEventContext, AstrError, BoundModeToolContractSnapshot, CancelToken, CapabilityContext, - CapabilityExecutionResult, ExecutionOwner, InvocationKind, InvocationMode, ModeId, Result, - SessionId, TurnId, + AgentEventContext, AstrError, CancelToken, CapabilityContext, CapabilityExecutionResult, + ExecutionOwner, InvocationKind, InvocationMode, Result, SessionId, TurnId, + mode::{BoundModeToolContractSnapshot, ModeId}, }; use astrcode_protocol::plugin::{ CapabilityWireDescriptor, ErrorPayload, EventMessage, EventPhase, InitializeResultData, @@ -2624,6 +2624,7 @@ fn http_dispatch_outcome_executes_via_http_dispatcher() { let binding = PluginCapabilityBinding { plugin_id: "http-plugin".to_string(), display_name: "HTTP Plugin".to_string(), + source_ref: "https://plugins.example.com/http-plugin".to_string(), backend_kind: PluginBackendKind::Http, capability: CapabilityWireDescriptor::builder( "tool.fetch", diff --git a/crates/plugin-host/src/modes.rs b/crates/plugin-host/src/modes.rs index 594387ff..0413c5d9 100644 --- a/crates/plugin-host/src/modes.rs +++ b/crates/plugin-host/src/modes.rs @@ -1,4 +1,4 @@ -use astrcode_core::GovernanceModeSpec; +use astrcode_governance_contract::GovernanceModeSpec; use crate::PluginDescriptor; diff --git a/crates/plugin-host/src/snapshot.rs b/crates/plugin-host/src/snapshot.rs index d31b6e0e..27d998d8 100644 --- a/crates/plugin-host/src/snapshot.rs +++ b/crates/plugin-host/src/snapshot.rs @@ -1,4 +1,5 @@ -use astrcode_core::{CapabilitySpec, GovernanceModeSpec}; +use astrcode_core::CapabilitySpec; +use astrcode_governance_contract::GovernanceModeSpec; use crate::descriptor::{ CommandDescriptor, HookDescriptor, PluginDescriptor, PromptDescriptor, ProviderDescriptor, diff --git a/crates/prompt-contract/Cargo.toml b/crates/prompt-contract/Cargo.toml new file mode 100644 index 00000000..43c70922 --- /dev/null +++ b/crates/prompt-contract/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "astrcode-prompt-contract" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +serde.workspace = true diff --git a/crates/prompt-contract/src/lib.rs b/crates/prompt-contract/src/lib.rs new file mode 100644 index 00000000..8a942c68 --- /dev/null +++ b/crates/prompt-contract/src/lib.rs @@ -0,0 +1,134 @@ +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum SystemPromptLayer { + Stable, + SemiStable, + Inherited, + Dynamic, + #[default] + Unspecified, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptLayerFingerprints { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub stable: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub semi_stable: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub inherited: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub dynamic: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptCacheHints { + #[serde(default)] + pub layer_fingerprints: PromptLayerFingerprints, + #[serde(default)] + pub global_cache_strategy: PromptCacheGlobalStrategy, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub unchanged_layers: Vec, + #[serde(default, skip_serializing_if = "is_false")] + pub compacted: bool, + #[serde(default, skip_serializing_if = "is_false")] + pub tool_result_rebudgeted: bool, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptCacheGlobalStrategy { + #[default] + SystemPrompt, + ToolBased, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum PromptCacheBreakReason { + SystemPromptChanged, + ToolSchemasChanged, + ModelChanged, + GlobalCacheStrategyChanged, + CompactedPrompt, + ToolResultRebudgeted, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptCacheDiagnostics { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub reasons: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub previous_cache_read_input_tokens: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub current_cache_read_input_tokens: Option, + #[serde(default, skip_serializing_if = "is_false")] + pub expected_drop: bool, + #[serde(default, skip_serializing_if = "is_false")] + pub cache_break_detected: bool, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationSource { + Builtin, + #[default] + Plugin, + Mcp, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationKind { + ToolGuide, + #[default] + ExtensionInstruction, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum PromptDeclarationRenderTarget { + #[default] + System, + PrependUser, + PrependAssistant, + AppendUser, + AppendAssistant, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "camelCase")] +pub struct PromptDeclaration { + pub block_id: String, + pub title: String, + pub content: String, + #[serde(default)] + pub render_target: PromptDeclarationRenderTarget, + #[serde(default, skip_serializing_if = "is_unspecified_prompt_layer")] + pub layer: SystemPromptLayer, + #[serde(default)] + pub kind: PromptDeclarationKind, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub priority_hint: Option, + #[serde(default)] + pub always_include: bool, + #[serde(default)] + pub source: PromptDeclarationSource, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub capability_name: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub origin: Option, +} + +fn is_unspecified_prompt_layer(layer: &SystemPromptLayer) -> bool { + matches!(layer, SystemPromptLayer::Unspecified) +} + +fn is_false(value: &bool) -> bool { + !*value +} diff --git a/crates/protocol/Cargo.toml b/crates/protocol/Cargo.toml index f7d78f7f..860303bd 100644 --- a/crates/protocol/Cargo.toml +++ b/crates/protocol/Cargo.toml @@ -7,6 +7,7 @@ authors.workspace = true [dependencies] astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } serde.workspace = true serde_json.workspace = true thiserror.workspace = true diff --git a/crates/protocol/src/plugin/handshake.rs b/crates/protocol/src/plugin/handshake.rs index 934a4009..9ef9f1a1 100644 --- a/crates/protocol/src/plugin/handshake.rs +++ b/crates/protocol/src/plugin/handshake.rs @@ -10,7 +10,7 @@ //! //! 握手完成后，双方进入正常的调用/事件流阶段。 -use astrcode_core::GovernanceModeSpec; +use astrcode_governance_contract::GovernanceModeSpec; use serde::{Deserialize, Serialize}; use serde_json::Value; diff --git a/crates/protocol/src/plugin/tests.rs b/crates/protocol/src/plugin/tests.rs index 22f23535..014f1e47 100644 --- a/crates/protocol/src/plugin/tests.rs +++ b/crates/protocol/src/plugin/tests.rs @@ -3,7 +3,7 @@ //! 验证各类消息（初始化、调用、事件、结果等）的序列化/反序列化 //! 是否正确，确保 JSON 格式与协议版本兼容。 -use astrcode_core::{ +use astrcode_governance_contract::{ ActionPolicies, CapabilitySelector, ChildPolicySpec, GovernanceModeSpec, ModeArtifactDef, ModeExecutionPolicySpec, ModeExitGateDef, ModeId, ModePromptHooks, TransitionPolicySpec, }; diff --git a/crates/runtime-contract/Cargo.toml b/crates/runtime-contract/Cargo.toml new file mode 100644 index 00000000..30f42d16 --- /dev/null +++ b/crates/runtime-contract/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "astrcode-runtime-contract" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +astrcode-llm-contract = { path = "../llm-contract" } +astrcode-tool-contract = { path = "../tool-contract" } +async-trait.workspace = true +chrono.workspace = true + diff --git a/crates/runtime-contract/src/lib.rs b/crates/runtime-contract/src/lib.rs new file mode 100644 index 00000000..0ab4adc9 --- /dev/null +++ b/crates/runtime-contract/src/lib.rs @@ -0,0 +1,5 @@ +mod traits; +mod turn; + +pub use traits::*; +pub use turn::*; diff --git a/crates/runtime-contract/src/traits.rs b/crates/runtime-contract/src/traits.rs new file mode 100644 index 00000000..0b56ce86 --- /dev/null +++ b/crates/runtime-contract/src/traits.rs @@ -0,0 +1,140 @@ +//! # 运行时接口 +//! +//! 定义了运行时组件的抽象接口，用于管理 LLM 连接和生命周期。 +//! +//! ## 核心接口 +//! +//! - [`RuntimeHandle`][]: 运行时主句柄，提供名称、类型和关闭接口 +//! - [`ManagedRuntimeComponent`][]: 可被运行时协调器管理的子组件 + +use astrcode_core::{ + AgentId, AgentProfile, AstrError, SessionEventRecord, SessionId, SessionMeta, SpawnAgentParams, + SubRunResult, SubagentContextOverrides, TurnId, agent::lineage::SubRunHandle, +}; +use astrcode_tool_contract::ToolContext; +use async_trait::async_trait; + +/// 运行时主句柄。 +/// +/// 代表一个具体的 LLM 运行时实现（如 OpenAI 兼容 API 客户端）。 +/// 生命周期由组合根的运行时协调设施统一管理。 +#[async_trait] +pub trait RuntimeHandle: Send + Sync { + /// 运行时实例的名称（用于日志和错误信息）。 + fn runtime_name(&self) -> &'static str; + + /// 运行时的类型标识（如 "openai"）。 + fn runtime_kind(&self) -> &'static str; + + /// 优雅关闭运行时，释放所有连接和资源。 + async fn shutdown(&self, timeout_secs: u64) -> std::result::Result<(), AstrError>; +} + +/// 可被运行时协调器管理的子组件。 +/// +/// 用于管理除主运行时之外的其他需要生命周期管理的组件 +/// （如 SSE 广播器、后台任务等）。 +#[async_trait] +pub trait ManagedRuntimeComponent: Send + Sync { + /// 组件名称（用于日志和错误信息）。 + fn component_name(&self) -> String; + + /// 优雅关闭组件，释放资源。 + async fn shutdown_component(&self) -> std::result::Result<(), AstrError>; +} + +/// 统一执行回执。 +/// +/// 替代之前的 `PromptAccepted` / `RootExecutionAccepted` / runtime 重复 receipt。 +/// 内部 contract 不再分裂，HTTP 路由可按需做 DTO 投影。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ExecutionAccepted { + pub session_id: SessionId, + pub turn_id: TurnId, + /// 仅 root execute 等有独立 agent 时存在。 + pub agent_id: Option, + /// 仅 prompt submit 分支场景存在。 + pub branched_from_session_id: Option, +} + +/// 会话边界：负责 durable truth 与会话目录语义。 +#[async_trait] +pub trait SessionTruthBoundary: Send + Sync { + async fn create_session( + &self, + working_dir: &std::path::Path, + ) -> std::result::Result; + + async fn list_sessions(&self) -> std::result::Result, AstrError>; + + async fn load_history( + &self, + session_id: &SessionId, + ) -> std::result::Result, AstrError>; +} + +/// 执行边界：负责 submit/interrupt/root-execute。 +/// +/// `launch_subagent` 已迁入 [`LiveSubRunControlBoundary`]， +/// 因为它依赖 live child ownership、tool context 和 active control tree， +/// 而不是纯 root orchestration。 +#[async_trait] +pub trait ExecutionOrchestrationBoundary: Send + Sync { + async fn submit_prompt( + &self, + session_id: &SessionId, + text: String, + ) -> std::result::Result; + + async fn interrupt_session(&self, session_id: &SessionId) + -> std::result::Result<(), AstrError>; + + async fn execute_root_agent( + &self, + agent_id: AgentId, + task: String, + context: Option, + context_overrides: Option, + working_dir: std::path::PathBuf, + ) -> std::result::Result; +} + +/// 主循环边界：负责单次 turn 的模型/工具循环。 +#[async_trait] +pub trait LoopRunnerBoundary: Send + Sync { + async fn run_session_turn( + &self, + session_id: &SessionId, + turn_id: &TurnId, + ) -> std::result::Result<(), AstrError>; +} + +/// live 子执行控制平面边界。 +/// +/// 包含 subrun 句柄查询、取消、agent 启动和 profile 枚举。 +#[async_trait] +pub trait LiveSubRunControlBoundary: Send + Sync { + async fn get_subrun_handle( + &self, + session_id: &SessionId, + sub_run_id: &str, + ) -> std::result::Result, AstrError>; + + async fn cancel_subrun( + &self, + session_id: &SessionId, + sub_run_id: &str, + ) -> std::result::Result<(), AstrError>; + + /// 启动子 agent 执行。 + /// + /// 从 `ExecutionOrchestrationBoundary` 迁入，因为该操作依赖 + /// live child ownership、tool context 和 active control tree。 + async fn launch_subagent( + &self, + params: SpawnAgentParams, + ctx: &ToolContext, + ) -> std::result::Result; + + async fn list_profiles(&self) -> std::result::Result, AstrError>; +} diff --git a/crates/runtime-contract/src/turn.rs b/crates/runtime-contract/src/turn.rs new file mode 100644 index 00000000..bb08113c --- /dev/null +++ b/crates/runtime-contract/src/turn.rs @@ -0,0 +1,165 @@ +use astrcode_core::{AstrError, HookEventKey, ReasoningContent, StorageEvent, TurnTerminalKind}; +use astrcode_llm_contract::LlmEvent; + +/// runtime 事件发射回调。 +/// +/// `agent-runtime` 只通过这个回调把 turn 生命周期事件交还给宿主，不持有 +/// EventStore、SessionState 或 plugin registry。 +pub trait RuntimeEventSink: Send + Sync { + fn emit_event(&self, event: RuntimeTurnEvent); +} + +impl RuntimeEventSink for F +where + F: Fn(RuntimeTurnEvent) + Send + Sync, +{ + fn emit_event(&self, event: RuntimeTurnEvent) { + self(event); + } +} + +/// 内部 loop 的“继续下一轮”原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum TurnLoopTransition { + ToolCycleCompleted, + ReactiveCompactRecovered, + OutputContinuationRequested, +} + +/// turn 停止的细粒度原因。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum TurnStopCause { + Completed, + Cancelled, + Error, +} + +impl TurnStopCause { + pub fn terminal_kind(self, error_message: Option<&str>) -> TurnTerminalKind { + match self { + Self::Completed => TurnTerminalKind::Completed, + Self::Cancelled => TurnTerminalKind::Cancelled, + Self::Error => TurnTerminalKind::Error { + message: error_message.unwrap_or("turn failed").to_string(), + }, + } + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct TurnIdentity { + pub session_id: String, + pub turn_id: String, + pub agent_id: String, +} + +impl TurnIdentity { + pub fn new(session_id: String, turn_id: String, agent_id: String) -> Self { + Self { + session_id, + turn_id, + agent_id, + } + } +} + +/// 单步执行中产生的错误，保留可重试/致命区分。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct StepError { + pub message: String, + pub kind: StepErrorKind, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum StepErrorKind { + Fatal, + Retryable, +} + +impl StepError { + pub fn fatal(message: impl Into) -> Self { + Self { + message: message.into(), + kind: StepErrorKind::Fatal, + } + } + + pub fn retryable(message: impl Into) -> Self { + Self { + message: message.into(), + kind: StepErrorKind::Retryable, + } + } +} + +impl From<&AstrError> for StepError { + fn from(error: &AstrError) -> Self { + Self { + message: error.to_string(), + kind: if error.is_retryable() { + StepErrorKind::Retryable + } else { + StepErrorKind::Fatal + }, + } + } +} + +#[derive(Debug, Clone)] +pub enum RuntimeTurnEvent { + TurnStarted { + identity: TurnIdentity, + }, + ProviderStream { + identity: TurnIdentity, + event: LlmEvent, + }, + AssistantFinal { + identity: TurnIdentity, + content: String, + reasoning: Option, + tool_call_count: usize, + }, + ToolUseRequested { + identity: TurnIdentity, + tool_call_count: usize, + }, + ToolCallStarted { + identity: TurnIdentity, + tool_call_id: String, + tool_name: String, + }, + ToolResultReady { + identity: TurnIdentity, + tool_call_id: String, + tool_name: String, + ok: bool, + }, + HookDispatched { + identity: TurnIdentity, + event: HookEventKey, + effect_count: usize, + }, + HookPromptAugmented { + identity: TurnIdentity, + event: HookEventKey, + content: String, + }, + StorageEvent { + event: Box, + }, + StepContinued { + identity: TurnIdentity, + step_index: usize, + transition: TurnLoopTransition, + }, + TurnCompleted { + identity: TurnIdentity, + stop_cause: TurnStopCause, + terminal_kind: TurnTerminalKind, + }, + TurnErrored { + identity: TurnIdentity, + message: String, + }, +} diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml index c81750d8..63860a92 100644 --- a/crates/server/Cargo.toml +++ b/crates/server/Cargo.toml @@ -14,11 +14,17 @@ astrcode-adapter-skills = { path = "../adapter-skills" } astrcode-adapter-storage = { path = "../adapter-storage" } astrcode-adapter-tools = { path = "../adapter-tools" } astrcode-agent-runtime = { path = "../agent-runtime" } +astrcode-context-window = { path = "../context-window" } astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } astrcode-host-session = { path = "../host-session" } +astrcode-llm-contract = { path = "../llm-contract" } astrcode-plugin-host = { path = "../plugin-host" } +astrcode-prompt-contract = { path = "../prompt-contract" } astrcode-protocol = { path = "../protocol" } +astrcode-runtime-contract = { path = "../runtime-contract" } astrcode-support = { path = "../support" } +astrcode-tool-contract = { path = "../tool-contract" } async-stream.workspace = true anyhow.workspace = true async-trait.workspace = true @@ -31,6 +37,7 @@ log.workspace = true env_logger.workspace = true notify.workspace = true rand.workspace = true +reqwest.workspace = true serde.workspace = true serde_json.workspace = true thiserror.workspace = true @@ -42,5 +49,4 @@ uuid.workspace = true [dev-dependencies] astrcode-core = { path = "../core", features = ["test-support"] } astrcode-adapter-storage = { path = "../adapter-storage" } -reqwest.workspace = true tempfile.workspace = true diff --git a/crates/server/src/agent/context.rs b/crates/server/src/agent/context.rs index b1c16f38..ac72d792 100644 --- a/crates/server/src/agent/context.rs +++ b/crates/server/src/agent/context.rs @@ -9,9 +9,10 @@ use std::path::Path; use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationFact, AgentCollaborationOutcomeKind, AgentCollaborationPolicyContext, AgentEventContext, ChildExecutionIdentity, InvocationKind, - ModeId, ResolvedExecutionLimitsSnapshot, Result, ToolContext, + ResolvedExecutionLimitsSnapshot, Result, mode::ModeId, }; use astrcode_host_session::SubRunHandle; +use astrcode_tool_contract::ToolContext; use super::{ AgentOrchestrationError, AgentOrchestrationService, IMPLICIT_ROOT_PROFILE_ID, diff --git a/crates/server/src/agent/mod.rs b/crates/server/src/agent/mod.rs index 7094f328..ae26c39b 100644 --- a/crates/server/src/agent/mod.rs +++ b/crates/server/src/agent/mod.rs @@ -31,9 +31,10 @@ use astrcode_core::{ DelegationMetadata, ObserveParams, ParentDelivery, ParentDeliveryOrigin, ParentDeliveryPayload, ParentDeliveryTerminalSemantics, ProgressParentDeliveryPayload, QueuedInputEnvelope, ResolvedExecutionLimitsSnapshot, Result, RuntimeMetricsRecorder, SendAgentParams, - SpawnAgentParams, SubRunHandoff, SubRunResult, ToolContext, + SpawnAgentParams, SubRunHandoff, SubRunResult, }; use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor, SubRunHandle}; +use astrcode_tool_contract::ToolContext; use async_trait::async_trait; pub(crate) use context::{ CollaborationFactRecord, ToolCollaborationContext, ToolCollaborationContextInput, @@ -465,7 +466,7 @@ impl SubAgentExecutor for AgentOrchestrationService { parent_agent_id: parent_agent_id.clone(), parent_turn_id: parent_turn_id.clone(), working_dir: ctx.working_dir().display().to_string(), - mode_id: collaboration.mode_id().clone(), + mode_id: collaboration.mode_id().clone().into(), profile, description: spawn_description.clone(), task: params.prompt, @@ -599,9 +600,9 @@ mod tests { CancelToken, ChildAgentRef, ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNotification, ChildSessionNotificationKind, ParentExecutionRef, ResolvedExecutionLimitsSnapshot, SessionId, SpawnAgentParams, StorageEventPayload, - ToolContext, }; use astrcode_host_session::SubAgentExecutor; + use astrcode_tool_contract::ToolContext; use super::{ IMPLICIT_ROOT_PROFILE_ID, build_delegation_metadata, child_delivery_input_queue_envelope, diff --git a/crates/server/src/agent/observe.rs b/crates/server/src/agent/observe.rs index 9e8f33fe..86c739c7 100644 --- a/crates/server/src/agent/observe.rs +++ b/crates/server/src/agent/observe.rs @@ -8,6 +8,7 @@ use astrcode_core::{ CollaborationResult, ObserveParams, ObserveSnapshot, }; use astrcode_host_session::SubRunHandle; +use astrcode_tool_contract::ToolContext; use super::{AgentOrchestrationService, ObserveSnapshotSignature}; @@ -20,7 +21,7 @@ impl AgentOrchestrationService { pub async fn observe_child( &self, params: ObserveParams, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, ) -> Result { let collaboration = self.tool_collaboration_context(ctx).await?; params @@ -211,9 +212,10 @@ mod tests { use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationOutcomeKind, CancelToken, ObserveParams, - SessionId, StorageEventPayload, ToolContext, + SessionId, StorageEventPayload, }; use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; + use astrcode_tool_contract::ToolContext; use tokio::time::sleep; use super::format_observe_summary; diff --git a/crates/server/src/agent/routing.rs b/crates/server/src/agent/routing.rs index 755bc9b4..9e37fd79 100644 --- a/crates/server/src/agent/routing.rs +++ b/crates/server/src/agent/routing.rs @@ -12,6 +12,7 @@ use astrcode_core::{ SendToChildParams, SendToParentParams, }; use astrcode_host_session::SubRunHandle; +use astrcode_tool_contract::ToolContext; use collaboration_flow::parent_delivery_label; use super::{ @@ -26,7 +27,7 @@ impl AgentOrchestrationService { /// 验证调用者是否为目标子 agent 的直接父级。 pub(super) fn verify_caller_owns_child( &self, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, child_handle: &SubRunHandle, ) -> Result<(), super::AgentOrchestrationError> { let caller_agent_id = ctx.agent_context().agent_id.as_deref(); @@ -49,7 +50,7 @@ impl AgentOrchestrationService { &self, agent_id: &str, action: AgentCollaborationActionKind, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, collaboration: &super::ToolCollaborationContext, ) -> Result { let child = match self.kernel.get_handle(agent_id).await { @@ -113,7 +114,7 @@ impl AgentOrchestrationService { pub async fn route_send( &self, params: SendAgentParams, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, ) -> Result { params .validate() @@ -129,7 +130,7 @@ impl AgentOrchestrationService { async fn send_to_child( &self, params: SendToChildParams, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, ) -> Result { let collaboration = self.tool_collaboration_context(ctx).await?; @@ -183,7 +184,7 @@ impl AgentOrchestrationService { async fn send_to_parent( &self, params: SendToParentParams, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, ) -> Result { let fallback_collaboration = self.tool_collaboration_context(ctx).await?; let Some(child_agent_id) = ctx.agent_context().agent_id.as_deref() else { @@ -414,7 +415,7 @@ impl AgentOrchestrationService { async fn upstream_collaboration_context( &self, child: &SubRunHandle, - ctx: &astrcode_core::ToolContext, + ctx: &ToolContext, ) -> Result { let parent_turn_id = match ctx.agent_context().parent_turn_id.clone() { Some(id) => id, diff --git a/crates/server/src/agent/routing/child_send.rs b/crates/server/src/agent/routing/child_send.rs index c6c3586a..03deac99 100644 --- a/crates/server/src/agent/routing/child_send.rs +++ b/crates/server/src/agent/routing/child_send.rs @@ -33,7 +33,7 @@ impl AgentOrchestrationService { &self, child: &SubRunHandle, params: &SendToChildParams, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, collaboration: &ToolCollaborationContext, lifecycle: Option, ) -> Result, AgentOrchestrationError> { @@ -134,7 +134,7 @@ impl AgentOrchestrationService { session_id: child_session_id.to_string(), turn_id: resumed_turn_id.clone(), working_dir, - mode_id: collaboration.mode_id().clone(), + mode_id: collaboration.mode_id().clone().into(), runtime: runtime.clone(), resolved_limits: reused_handle.resolved_limits.clone(), delegation: Some(resume_delegation.clone()), @@ -221,7 +221,7 @@ impl AgentOrchestrationService { &self, child: &SubRunHandle, params: &SendToChildParams, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, collaboration: &ToolCollaborationContext, ) -> Result { let delivery_id = format!( diff --git a/crates/server/src/agent/routing/parent_delivery.rs b/crates/server/src/agent/routing/parent_delivery.rs index 8c58c2e6..42a38efd 100644 --- a/crates/server/src/agent/routing/parent_delivery.rs +++ b/crates/server/src/agent/routing/parent_delivery.rs @@ -5,7 +5,7 @@ impl AgentOrchestrationService { &self, child: &SubRunHandle, payload: &ParentDeliveryPayload, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, source_turn_id: &str, ) -> ChildSessionNotification { let status = self @@ -39,7 +39,7 @@ impl AgentOrchestrationService { &self, child: &SubRunHandle, envelope: &AgentInboxEnvelope, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, ) -> astrcode_core::Result<()> { let target_session_id = child .child_session_id @@ -97,7 +97,7 @@ impl AgentOrchestrationService { pub(in crate::agent) async fn append_durable_input_queue_discard_batch( &self, handles: &[SubRunHandle], - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, ) -> astrcode_core::Result<()> { for handle in handles { self.append_durable_input_queue_discard(handle, ctx).await?; @@ -108,7 +108,7 @@ impl AgentOrchestrationService { async fn append_durable_input_queue_discard( &self, handle: &SubRunHandle, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, ) -> astrcode_core::Result<()> { let target_session_id = handle .child_session_id diff --git a/crates/server/src/agent/routing/tests.rs b/crates/server/src/agent/routing/tests.rs index efade784..547c5c48 100644 --- a/crates/server/src/agent/routing/tests.rs +++ b/crates/server/src/agent/routing/tests.rs @@ -4,9 +4,9 @@ use astrcode_core::{ AgentCollaborationActionKind, AgentCollaborationOutcomeKind, CancelToken, CloseAgentParams, CompletedParentDeliveryPayload, ObserveParams, ParentDeliveryPayload, SendAgentParams, SendToChildParams, SendToParentParams, SessionId, SpawnAgentParams, StorageEventPayload, - ToolContext, }; use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; +use astrcode_tool_contract::ToolContext; use tokio::time::sleep; use super::super::{root_execution_event_context, subrun_event_context}; diff --git a/crates/server/src/agent/routing_collaboration_flow.rs b/crates/server/src/agent/routing_collaboration_flow.rs index 045f8a36..bfa83ca3 100644 --- a/crates/server/src/agent/routing_collaboration_flow.rs +++ b/crates/server/src/agent/routing_collaboration_flow.rs @@ -17,7 +17,7 @@ impl AgentOrchestrationService { pub(in crate::agent) async fn close_child( &self, params: CloseAgentParams, - ctx: &astrcode_core::ToolContext, + ctx: &astrcode_tool_contract::ToolContext, ) -> Result { let collaboration = self.tool_collaboration_context(ctx).await?; params diff --git a/crates/server/src/agent/test_support.rs b/crates/server/src/agent/test_support.rs index 178b7c03..94b360f4 100644 --- a/crates/server/src/agent/test_support.rs +++ b/crates/server/src/agent/test_support.rs @@ -9,7 +9,6 @@ use std::{ sync::{Arc, Mutex}, }; -use astrcode_agent_runtime::{LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits}; use astrcode_core::{ AgentLifecycleStatus, AgentMode, AgentProfile, AstrError, Config, ConfigOverlay, DeleteProjectResult, Phase, Result, SessionId, SessionMeta, SessionTurnAcquireResult, @@ -19,6 +18,9 @@ use astrcode_core::{ use astrcode_host_session::{ EventStore, SessionCatalog, SubRunHandle, catalog::display_name_from_working_dir, }; +use astrcode_llm_contract::{ + LlmEventSink, LlmFinishReason, LlmOutput, LlmProvider, LlmRequest, ModelLimits, +}; use async_trait::async_trait; use chrono::Utc; use serde_json::Value; @@ -413,7 +415,7 @@ impl LlmProvider for TestLlmProvider { async fn generate( &self, _request: LlmRequest, - _sink: Option, + _sink: Option, ) -> Result { match &self.behavior { TestLlmBehavior::Succeed { content } => Ok(LlmOutput { diff --git a/crates/server/src/agent_runtime_bridge.rs b/crates/server/src/agent_runtime_bridge.rs index 9c26c843..340842b3 100644 --- a/crates/server/src/agent_runtime_bridge.rs +++ b/crates/server/src/agent_runtime_bridge.rs @@ -5,7 +5,7 @@ use std::{path::Path, sync::Arc}; -use astrcode_core::ModeId; +use astrcode_governance_contract::ModeId; use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; use crate::{ diff --git a/crates/server/src/bootstrap/capabilities.rs b/crates/server/src/bootstrap/capabilities.rs index febbc654..febf4fbc 100644 --- a/crates/server/src/bootstrap/capabilities.rs +++ b/crates/server/src/bootstrap/capabilities.rs @@ -35,8 +35,9 @@ use astrcode_adapter_tools::{ use astrcode_core::{CapabilitySpec, SkillCatalog, SkillSpec}; use astrcode_host_session::{CollaborationExecutor, SubAgentExecutor}; use astrcode_plugin_host::{ResourceCatalog, build_skill_catalog_base}; +use astrcode_tool_contract::Tool; -use super::deps::core::{CapabilityInvoker, Result, Tool}; +use super::deps::core::{CapabilityInvoker, Result}; use crate::{ session_runtime_owner_bridge::ServerCapabilitySurfacePort, tool_capability_invoker::ToolCapabilityInvoker, @@ -246,6 +247,7 @@ mod tests { use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; use astrcode_plugin_host::ResourceCatalog; + use astrcode_tool_contract::{Tool, ToolContext, ToolDefinition, ToolExecutionResult}; use async_trait::async_trait; use serde_json::{Value, json}; @@ -258,8 +260,7 @@ mod tests { capabilities::sync_external_tool_search_index, deps::core::{ AstrError, CapabilityInvoker, CapabilityKind, CapabilitySpec, - CapabilitySpecBuildError, Result, Tool, ToolContext, ToolDefinition, - ToolExecutionResult, + CapabilitySpecBuildError, Result, }, }, session_runtime_owner_bridge::ServerCapabilitySurfacePort, diff --git a/crates/server/src/bootstrap/governance.rs b/crates/server/src/bootstrap/governance.rs index 5ae71492..bc123fcb 100644 --- a/crates/server/src/bootstrap/governance.rs +++ b/crates/server/src/bootstrap/governance.rs @@ -19,14 +19,12 @@ use astrcode_plugin_host::{ PluginEntry, ProviderContributionCatalog, ResourceCatalog, build_skill_catalog_base, builtin_openai_provider_descriptor, }; +use astrcode_runtime_contract::{ManagedRuntimeComponent, RuntimeHandle}; use async_trait::async_trait; use super::{ - capabilities::CapabilitySurfaceSync, - deps::core::{AstrError, ManagedRuntimeComponent, RuntimeHandle}, - mcp::load_declared_configs, - plugins::bootstrap_plugins_with_skill_root, - runtime_coordinator::RuntimeCoordinator, + capabilities::CapabilitySurfaceSync, deps::core::AstrError, mcp::load_declared_configs, + plugins::bootstrap_plugins_with_skill_root, runtime_coordinator::RuntimeCoordinator, }; use crate::{ AppGovernance, ApplicationError, GovernanceSnapshot, RuntimeGovernancePort, @@ -444,6 +442,7 @@ mod tests { }; use astrcode_plugin_host::PluginRegistry; + use astrcode_tool_contract::{Tool, ToolContext, ToolDefinition, ToolExecutionResult}; use async_trait::async_trait; use serde_json::{Value, json}; @@ -451,7 +450,7 @@ mod tests { use crate::{ bootstrap::deps::core::{ AstrError, CapabilityInvoker, CapabilityKind, CapabilitySpec, CapabilitySpecBuildError, - Result, Tool, ToolContext, ToolDefinition, ToolExecutionResult, + Result, }, tool_capability_invoker::ToolCapabilityInvoker, }; diff --git a/crates/server/src/bootstrap/plugins.rs b/crates/server/src/bootstrap/plugins.rs index c60ea2a9..b8de24a4 100644 --- a/crates/server/src/bootstrap/plugins.rs +++ b/crates/server/src/bootstrap/plugins.rs @@ -19,9 +19,9 @@ use std::{ use astrcode_adapter_skills::collect_asset_files; use astrcode_core::{ AstrError, CapabilityContext, CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, - GovernanceModeSpec, InvocationMode, ManagedRuntimeComponent, Result, SkillSource, SkillSpec, - is_valid_skill_name, + InvocationMode, Result, SkillSource, SkillSpec, is_valid_skill_name, }; +use astrcode_governance_contract::GovernanceModeSpec; use astrcode_plugin_host::{ PluginDescriptor, PluginLoader, PluginManifest, PluginRegistry, PluginSourceKind, PluginType, ResourceCatalog, @@ -30,10 +30,12 @@ use astrcode_plugin_host::{ resources_discover, }; use astrcode_protocol::plugin::{EventPhase, InvocationContext, SkillDescriptor, WorkspaceRef}; +use astrcode_runtime_contract::ManagedRuntimeComponent; #[cfg(test)] use astrcode_support::hostpaths::resolve_home_dir; use async_trait::async_trait; use log::warn; +use reqwest::Client; use serde_json::{Value, json}; use tokio::sync::Mutex; @@ -115,7 +117,18 @@ pub(crate) async fn bootstrap_plugins_with_skill_root( log::info!("loading plugin '{name}'..."); registry.record_discovered(manifest.clone()); - match bootstrap_external_plugin_runtime(descriptor, init_message.clone()).await { + let bootstrap_result = match descriptor.source_kind { + PluginSourceKind::Process | PluginSourceKind::Command => { + bootstrap_external_plugin_runtime(descriptor, init_message.clone()).await + }, + PluginSourceKind::Http => bootstrap_http_plugin_runtime(descriptor).await, + PluginSourceKind::Builtin => Err(AstrError::Validation(format!( + "plugin '{}' 不是 external plugin source，无法走 plugin-host 装配路径", + descriptor.plugin_id + ))), + }; + + match bootstrap_result { Ok(initialized) => { let (skills, mut warnings) = materialize_plugin_skills( plugin_skill_root.as_path(), @@ -188,6 +201,13 @@ struct HostedExternalPluginRuntime { handle: Mutex, } +struct HostedHttpPluginRuntime { + plugin_id: String, + display_name: String, + endpoint: String, + client: Client, +} + impl HostedExternalPluginRuntime { fn new(plugin_id: String, display_name: String, handle: ExternalPluginRuntimeHandle) -> Self { Self { @@ -254,6 +274,88 @@ impl HostedExternalPluginRuntime { } } +impl HostedHttpPluginRuntime { + fn new(plugin_id: String, display_name: String, endpoint: String) -> Self { + Self { + plugin_id, + display_name, + endpoint, + client: Client::new(), + } + } + + async fn invoke( + &self, + capability_name: &str, + payload: Value, + ctx: &CapabilityContext, + invocation_mode: InvocationMode, + ) -> Result { + if matches!(invocation_mode, InvocationMode::Streaming) { + return Err(AstrError::Validation(format!( + "plugin '{}' 的 HTTP backend 暂不支持流式 capability '{}'", + self.plugin_id, capability_name + ))); + } + + let started_at = Instant::now(); + let invocation = to_invocation_context(ctx, capability_name); + let request = astrcode_protocol::plugin::InvokeMessage { + id: invocation.request_id.clone(), + capability: capability_name.to_string(), + input: payload, + context: invocation, + stream: false, + }; + let response = self + .client + .post(&self.endpoint) + .json(&request) + .send() + .await + .map_err(|error| { + AstrError::http_with_source( + format!( + "failed to invoke HTTP plugin '{}' at '{}'", + self.plugin_id, self.endpoint + ), + is_retryable_http_error(&error), + error, + ) + })? + .error_for_status() + .map_err(|error| { + AstrError::http_with_source( + format!( + "HTTP plugin '{}' returned an error status from '{}'", + self.plugin_id, self.endpoint + ), + is_retryable_http_error(&error), + error, + ) + })?; + let result = response + .json::() + .await + .map_err(|error| { + AstrError::http_with_source( + format!( + "failed to decode HTTP plugin response for '{}' from '{}'", + self.plugin_id, self.endpoint + ), + is_retryable_http_error(&error), + error, + ) + })?; + + Ok(capability_execution_from_result_message( + capability_name.to_string(), + result, + started_at, + )) + } +} + #[async_trait] impl ManagedRuntimeComponent for HostedExternalPluginRuntime { fn component_name(&self) -> String { @@ -266,6 +368,17 @@ impl ManagedRuntimeComponent for HostedExternalPluginRuntime { } } +#[async_trait] +impl ManagedRuntimeComponent for HostedHttpPluginRuntime { + fn component_name(&self) -> String { + format!("plugin-http '{}' ({})", self.plugin_id, self.display_name) + } + + async fn shutdown_component(&self) -> Result<()> { + Ok(()) + } +} + #[derive(Clone)] struct HostedPluginCapabilityInvoker { runtime: Arc, @@ -273,6 +386,13 @@ struct HostedPluginCapabilityInvoker { remote_name: String, } +#[derive(Clone)] +struct HostedHttpPluginCapabilityInvoker { + runtime: Arc, + capability_spec: CapabilitySpec, + remote_name: String, +} + #[async_trait] impl CapabilityInvoker for HostedPluginCapabilityInvoker { fn capability_spec(&self) -> CapabilitySpec { @@ -295,6 +415,28 @@ impl CapabilityInvoker for HostedPluginCapabilityInvoker { } } +#[async_trait] +impl CapabilityInvoker for HostedHttpPluginCapabilityInvoker { + fn capability_spec(&self) -> CapabilitySpec { + self.capability_spec.clone() + } + + async fn invoke( + &self, + payload: Value, + ctx: &CapabilityContext, + ) -> Result { + self.runtime + .invoke( + self.remote_name.as_str(), + payload, + ctx, + self.capability_spec.invocation_mode, + ) + .await + } +} + async fn bootstrap_external_plugin_runtime( descriptor: &PluginDescriptor, init_message: astrcode_protocol::plugin::InitializeMessage, @@ -350,6 +492,50 @@ async fn bootstrap_external_plugin_runtime( }) } +async fn bootstrap_http_plugin_runtime( + descriptor: &PluginDescriptor, +) -> Result { + if descriptor.source_ref.trim().is_empty() { + return Err(AstrError::Validation(format!( + "plugin '{}' 缺少 HTTP endpoint，无法走 HTTP 宿主路径", + descriptor.plugin_id + ))); + } + + let runtime = Arc::new(HostedHttpPluginRuntime::new( + descriptor.plugin_id.clone(), + descriptor.display_name.clone(), + descriptor.source_ref.clone(), + )); + let invokers = descriptor + .tools + .iter() + .cloned() + .map(|capability| { + capability.validate().map_err(|error| { + AstrError::Validation(format!( + "invalid HTTP plugin capability '{}': {}", + capability.name, error + )) + })?; + Ok(Arc::new(HostedHttpPluginCapabilityInvoker { + runtime: Arc::clone(&runtime), + remote_name: capability.name.to_string(), + capability_spec: capability, + }) as Arc) + }) + .collect::>>()?; + + Ok(BootstrappedPluginRuntime { + runtime: runtime as Arc, + invokers, + capabilities: descriptor.tools.clone(), + declared_skills: Vec::new(), + modes: descriptor.modes.clone(), + warnings: Vec::new(), + }) +} + fn create_plugin_capability_invoker( runtime: Arc, capability: CapabilitySpec, @@ -524,6 +710,39 @@ fn finish_stream_invocation( )) } +fn capability_execution_from_result_message( + capability_name: String, + result: astrcode_protocol::plugin::ResultMessage, + started_at: Instant, +) -> CapabilityExecutionResult { + let (success, error) = if result.success { + (true, None) + } else { + let message = result + .error + .map(|value| value.message) + .unwrap_or_else(|| "plugin invocation failed".to_string()); + (false, Some(message)) + }; + + CapabilityExecutionResult::from_common( + capability_name, + success, + result.output, + None, + astrcode_core::ExecutionResultCommon { + error, + metadata: Some(result.metadata), + duration_ms: started_at.elapsed().as_millis() as u64, + truncated: false, + }, + ) +} + +fn is_retryable_http_error(error: &reqwest::Error) -> bool { + error.is_timeout() || error.is_connect() || error.is_body() +} + fn to_invocation_context(ctx: &CapabilityContext, capability_name: &str) -> InvocationContext { let working_dir = ctx.working_dir.to_string_lossy().into_owned(); let request_id = ctx.request_id.clone().unwrap_or_else(|| { @@ -754,9 +973,12 @@ fn write_asset_if_changed(path: &Path, content: &str) -> std::io::Result<()> { #[cfg(test)] mod tests { - use astrcode_core::{CapabilitySelector, ModeId, SkillSource}; + use astrcode_core::SkillSource; + use astrcode_governance_contract::{CapabilitySelector, ModeId}; use astrcode_plugin_host::{PluginHealth, PluginState}; use astrcode_protocol::plugin::{SkillAssetDescriptor, SkillDescriptor}; + use axum::{Json, Router, routing::post}; + use tokio::net::TcpListener; use super::*; @@ -1013,6 +1235,96 @@ args = ["{script_path}"] assert_eq!(entry.health, PluginHealth::Healthy); } + #[tokio::test] + async fn http_plugin_bootstrap_materializes_invoker_and_executes_unary_calls() { + async fn invoke( + Json(request): Json, + ) -> Json { + Json(astrcode_protocol::plugin::ResultMessage { + id: request.id, + kind: Some("tool_result".to_string()), + success: true, + output: serde_json::json!({ + "echoed": request.input, + "capability": request.capability, + }), + error: None, + metadata: serde_json::json!({ "transport": "http" }), + }) + } + + let listener = TcpListener::bind("127.0.0.1:0") + .await + .expect("listener should bind"); + let address = listener + .local_addr() + .expect("listener should expose address"); + tokio::spawn(async move { + axum::serve(listener, Router::new().route("/invoke", post(invoke))) + .await + .expect("server should run"); + }); + + let mut descriptor = PluginDescriptor::builtin("remote-fetch", "Remote Fetch"); + descriptor.source_kind = PluginSourceKind::Http; + descriptor.source_ref = format!("http://{address}/invoke"); + descriptor.tools.push(CapabilitySpec { + name: "tool.fetch".into(), + kind: astrcode_core::CapabilityKind::Tool, + description: "fetch remote data".to_string(), + input_schema: serde_json::json!({ "type": "object" }), + output_schema: serde_json::json!({ "type": "object" }), + invocation_mode: InvocationMode::Unary, + concurrency_safe: false, + compact_clearable: false, + profiles: vec!["coding".to_string()], + tags: Vec::new(), + permissions: Vec::new(), + side_effect: astrcode_core::SideEffect::External, + stability: astrcode_core::Stability::Stable, + metadata: serde_json::Value::Null, + max_result_inline_size: None, + }); + + let bootstrapped = bootstrap_http_plugin_runtime(&descriptor) + .await + .expect("http plugin should bootstrap"); + + assert_eq!(bootstrapped.invokers.len(), 1); + let result = bootstrapped.invokers[0] + .invoke( + serde_json::json!({ "url": "https://example.com" }), + &CapabilityContext { + request_id: Some("req-http-1".to_string()), + trace_id: None, + session_id: astrcode_core::SessionId::from("session-http"), + working_dir: PathBuf::from("."), + cancel: astrcode_core::CancelToken::new(), + turn_id: None, + agent: astrcode_core::AgentEventContext::root_execution("agent-1", "coding"), + current_mode_id: ModeId::from("coding").into(), + bound_mode_tool_contract: None, + execution_owner: None, + profile: "coding".to_string(), + profile_context: serde_json::Value::Null, + metadata: serde_json::Value::Null, + tool_output_sender: None, + event_sink: None, + }, + ) + .await + .expect("http plugin invoke should succeed"); + + assert!(result.success); + assert_eq!( + result.output, + serde_json::json!({ + "echoed": { "url": "https://example.com" }, + "capability": "tool.fetch", + }) + ); + } + #[test] fn plugin_declared_skills_materialize_into_skill_specs() { let temp_home = tempfile::tempdir().expect("temp home should be created"); diff --git a/crates/server/src/bootstrap/providers.rs b/crates/server/src/bootstrap/providers.rs index f64c7e94..e63c4acf 100644 --- a/crates/server/src/bootstrap/providers.rs +++ b/crates/server/src/bootstrap/providers.rs @@ -11,12 +11,12 @@ use std::{ use astrcode_adapter_agents::AgentProfileLoader; use astrcode_adapter_llm::{ - LlmClientConfig, ModelLimits, + LlmClientConfig, openai::{OpenAiProvider, OpenAiProviderCapabilities}, }; use astrcode_adapter_storage::config_store::FileConfigStore; -use astrcode_agent_runtime::{LlmEventSink, LlmOutput, LlmProvider, LlmRequest}; use astrcode_core::config::{OpenAiApiMode, OpenAiProfileCapabilities}; +use astrcode_llm_contract::{LlmEventSink, LlmOutput, LlmProvider, LlmRequest, ModelLimits}; use astrcode_plugin_host::{OPENAI_API_KIND, ProviderContributionCatalog}; use super::deps::core::{ diff --git a/crates/server/src/bootstrap/runtime.rs b/crates/server/src/bootstrap/runtime.rs index 876594f0..84e4df3c 100644 --- a/crates/server/src/bootstrap/runtime.rs +++ b/crates/server/src/bootstrap/runtime.rs @@ -12,6 +12,7 @@ use std::{ use astrcode_adapter_storage::session::FileSystemSessionRepository; use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; use astrcode_core::SkillCatalog; +use astrcode_governance_contract::GovernanceModeSpec; use astrcode_host_session::{EventStore, SessionCatalog, SubAgentExecutor}; use astrcode_plugin_host::{ CommandDescriptor, PluginActiveSnapshot, PluginDescriptor, PluginRegistry, @@ -369,8 +370,8 @@ pub async fn bootstrap_server_runtime_with_options( fn build_server_plugin_contribution_descriptors( core_tool_invokers: &[Arc], mcp_invokers: &[Arc], - builtin_modes: Vec, - plugin_modes: Vec, + builtin_modes: Vec, + plugin_modes: Vec, mut external_descriptors: Vec, ) -> Vec { let mut descriptors = vec![ @@ -423,8 +424,8 @@ struct ServerPluginHostReload { snapshot: PluginActiveSnapshot, resources: ResourceCatalog, provider_catalog: ProviderContributionCatalog, - builtin_modes: Vec, - plugin_modes: Vec, + builtin_modes: Vec, + plugin_modes: Vec, } fn reload_server_plugin_host_snapshot( @@ -449,10 +450,7 @@ fn reload_server_plugin_host_snapshot( }) } -fn descriptor_modes( - descriptors: &[PluginDescriptor], - plugin_id: &str, -) -> Vec { +fn descriptor_modes(descriptors: &[PluginDescriptor], plugin_id: &str) -> Vec { descriptors .iter() .find(|descriptor| descriptor.plugin_id == plugin_id) diff --git a/crates/server/src/bootstrap/runtime_coordinator.rs b/crates/server/src/bootstrap/runtime_coordinator.rs index bfe9c93a..d9719226 100644 --- a/crates/server/src/bootstrap/runtime_coordinator.rs +++ b/crates/server/src/bootstrap/runtime_coordinator.rs @@ -5,10 +5,9 @@ use std::sync::{Arc, RwLock}; use astrcode_plugin_host::{PluginEntry, PluginRegistry}; +use astrcode_runtime_contract::{ManagedRuntimeComponent, RuntimeHandle}; -use super::deps::core::{ - AstrError, CapabilitySpec, ManagedRuntimeComponent, Result, RuntimeHandle, support, -}; +use super::deps::core::{AstrError, CapabilitySpec, Result, support}; /// 运行时协调器。 /// @@ -142,13 +141,13 @@ mod tests { use std::sync::{Arc, Mutex}; use astrcode_plugin_host::{PluginEntry, PluginHealth, PluginRegistry, PluginState}; + use astrcode_runtime_contract::{ManagedRuntimeComponent, RuntimeHandle}; use async_trait::async_trait; use serde_json::json; use super::RuntimeCoordinator; use crate::bootstrap::deps::core::{ - AstrError, CapabilityKind, CapabilitySpec, InvocationMode, ManagedRuntimeComponent, Result, - RuntimeHandle, SideEffect, Stability, + AstrError, CapabilityKind, CapabilitySpec, InvocationMode, Result, SideEffect, Stability, }; struct FakeRuntimeHandle { diff --git a/crates/server/src/capability_router.rs b/crates/server/src/capability_router.rs index 85ecdfd1..cd77f8d5 100644 --- a/crates/server/src/capability_router.rs +++ b/crates/server/src/capability_router.rs @@ -11,9 +11,9 @@ use std::{ }; use astrcode_core::{ - AstrError, CapabilityInvoker, CapabilitySpec, Result, ToolCallRequest, ToolContext, - ToolExecutionResult, support, + AstrError, CapabilityInvoker, CapabilitySpec, Result, ToolCallRequest, support, }; +use astrcode_tool_contract::{ToolContext, ToolExecutionResult}; fn validate_capability_spec(capability_spec: &CapabilitySpec) -> Result<()> { capability_spec.validate().map_err(|error| { diff --git a/crates/server/src/conversation_read_model.rs b/crates/server/src/conversation_read_model.rs index 4724c52d..db0d57dd 100644 --- a/crates/server/src/conversation_read_model.rs +++ b/crates/server/src/conversation_read_model.rs @@ -9,8 +9,8 @@ use std::collections::{HashMap, HashSet}; use astrcode_core::{ AgentEvent, ChildAgentRef, ChildSessionNotification, ChildSessionNotificationKind, CompactAppliedMeta, CompactTrigger, Phase, PromptMetricsPayload, SessionEventRecord, - ToolExecutionResult, ToolOutputStream, }; +use astrcode_tool_contract::{ToolExecutionResult, ToolOutputStream}; use serde_json::Value; use tokio::sync::broadcast; diff --git a/crates/server/src/conversation_read_model/facts.rs b/crates/server/src/conversation_read_model/facts.rs index 31c3e749..48442053 100644 --- a/crates/server/src/conversation_read_model/facts.rs +++ b/crates/server/src/conversation_read_model/facts.rs @@ -2,8 +2,9 @@ use astrcode_core::{ ChildAgentRef, CompactAppliedMeta, CompactTrigger, Phase, PromptCacheDiagnostics, - SystemPromptLayer, ToolOutputStream, + policy::SystemPromptLayer, }; +use astrcode_tool_contract::ToolOutputStream; use serde_json::Value; #[derive(Debug, Clone, Copy, PartialEq, Eq)] diff --git a/crates/server/src/conversation_read_model/plan_projection.rs b/crates/server/src/conversation_read_model/plan_projection.rs index 2f961870..17c49495 100644 --- a/crates/server/src/conversation_read_model/plan_projection.rs +++ b/crates/server/src/conversation_read_model/plan_projection.rs @@ -1,3 +1,4 @@ +use astrcode_tool_contract::ToolExecutionResult; use serde_json::Value; use super::*; diff --git a/crates/server/src/execution/subagent.rs b/crates/server/src/execution/subagent.rs index 425baa3f..353c38bc 100644 --- a/crates/server/src/execution/subagent.rs +++ b/crates/server/src/execution/subagent.rs @@ -6,10 +6,11 @@ use std::sync::Arc; use astrcode_core::{ - AgentLifecycleStatus, AgentMode, AgentProfile, ExecutionAccepted, ModeId, - ResolvedRuntimeConfig, RuntimeMetricsRecorder, + AgentLifecycleStatus, AgentMode, AgentProfile, ResolvedRuntimeConfig, RuntimeMetricsRecorder, }; +use astrcode_governance_contract::ModeId; use astrcode_host_session::SubRunHandle; +use astrcode_runtime_contract::ExecutionAccepted; use crate::{ AgentKernelPort, AgentSessionPort, diff --git a/crates/server/src/governance_surface/assembler.rs b/crates/server/src/governance_surface/assembler.rs index b946fc95..279f4a7b 100644 --- a/crates/server/src/governance_surface/assembler.rs +++ b/crates/server/src/governance_surface/assembler.rs @@ -13,6 +13,8 @@ use astrcode_core::{ ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, ResolvedSubagentContextOverrides, }; +use astrcode_governance_contract::ModeId; +use astrcode_prompt_contract::PromptDeclaration; use super::{ BuildSurfaceInput, FreshChildGovernanceInput, GovernanceBusyPolicy, ResolvedGovernanceSurface, @@ -52,8 +54,8 @@ impl GovernanceSurfaceAssembler { fn compile_mode_surface( &self, - mode_id: &astrcode_core::ModeId, - extra_prompt_declarations: Vec, + mode_id: &ModeId, + extra_prompt_declarations: Vec, ) -> Result { let spec = self.mode_catalog.get(mode_id).ok_or_else(|| { ApplicationError::InvalidArgument(format!("unknown mode '{}'", mode_id)) @@ -63,7 +65,7 @@ impl GovernanceSurfaceAssembler { fn compile_child_mode_surface( &self, - mode_id: &astrcode_core::ModeId, + mode_id: &ModeId, ) -> Result { let spec = self.mode_catalog.get(mode_id).ok_or_else(|| { ApplicationError::InvalidArgument(format!("unknown mode '{}'", mode_id)) @@ -87,7 +89,8 @@ impl GovernanceSurfaceAssembler { injected_messages, leading_prompt_declaration, } = input; - let mut prompt_declarations = compiled.envelope.prompt_declarations.clone(); + let mut prompt_declarations: Vec = + compiled.envelope.prompt_declarations.clone(); if let Some(leading) = leading_prompt_declaration { prompt_declarations.insert(0, leading); } diff --git a/crates/server/src/governance_surface/mod.rs b/crates/server/src/governance_surface/mod.rs index b5506cd4..d4075184 100644 --- a/crates/server/src/governance_surface/mod.rs +++ b/crates/server/src/governance_surface/mod.rs @@ -20,11 +20,14 @@ mod tests; pub use assembler::GovernanceSurfaceAssembler; use astrcode_core::{ - AgentCollaborationPolicyContext, BoundModeToolContractSnapshot, CapabilityCall, LlmMessage, - ModeId, PolicyContext, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, - ResolvedSubagentContextOverrides, + AgentCollaborationPolicyContext, LlmMessage, ResolvedExecutionLimitsSnapshot, + ResolvedRuntimeConfig, ResolvedSubagentContextOverrides, +}; +use astrcode_governance_contract::{ + ApprovalPending, BoundModeToolContractSnapshot, CapabilityCall, ModeId, PolicyContext, }; use astrcode_host_session::PromptGovernanceContext; +use astrcode_prompt_contract::PromptDeclaration; pub(crate) use inherited::resolve_inherited_parent_messages; #[cfg(test)] pub(crate) use inherited::{build_inherited_messages, select_inherited_recent_tail}; @@ -55,7 +58,7 @@ pub enum GovernanceBusyPolicy { /// 在实际执行前需要用户确认。 #[derive(Clone, PartialEq, Default)] pub struct GovernanceApprovalPipeline { - pub pending: Option>, + pub pending: Option>, } /// bind 完成的治理面，一次性消费的 turn 级上下文快照。 @@ -66,7 +69,7 @@ pub struct GovernanceApprovalPipeline { pub struct ResolvedGovernanceSurface { pub mode_id: ModeId, pub runtime: ResolvedRuntimeConfig, - pub prompt_declarations: Vec, + pub prompt_declarations: Vec, pub bound_mode_tool_contract: BoundModeToolContractSnapshot, pub resolved_limits: ResolvedExecutionLimitsSnapshot, pub resolved_overrides: Option, @@ -140,7 +143,7 @@ struct BuildSurfaceInput { requested_busy_policy: GovernanceBusyPolicy, resolved_overrides: Option, injected_messages: Vec, - leading_prompt_declaration: Option, + leading_prompt_declaration: Option, } #[derive(Debug, Clone)] @@ -152,7 +155,7 @@ pub struct SessionGovernanceInput { pub mode_id: ModeId, pub runtime: ResolvedRuntimeConfig, pub control: Option, - pub extra_prompt_declarations: Vec, + pub extra_prompt_declarations: Vec, pub busy_policy: GovernanceBusyPolicy, } diff --git a/crates/server/src/governance_surface/policy.rs b/crates/server/src/governance_surface/policy.rs index 689648e8..ffdf8392 100644 --- a/crates/server/src/governance_surface/policy.rs +++ b/crates/server/src/governance_surface/policy.rs @@ -5,9 +5,10 @@ //! - 构建审批管线（`default_approval_pipeline`），当 mode 要求审批时安装占位骨架 #![allow(dead_code)] -use astrcode_core::{ - AgentCollaborationPolicyContext, ApprovalPending, ApprovalRequest, CapabilityCall, ModeId, - PolicyContext, ResolvedRuntimeConfig, ResolvedTurnEnvelope, +use astrcode_core::{AgentCollaborationPolicyContext, ResolvedRuntimeConfig}; +use astrcode_governance_contract::{ + ApprovalDefault, ApprovalPending, ApprovalRequest, CapabilityCall, ModeId, PolicyContext, + ResolvedTurnEnvelope, SubmitBusyPolicy, }; use serde_json::{Value, json}; @@ -146,7 +147,7 @@ pub(super) fn default_approval_pipeline( }), prompt: "Governance approval skeleton is installed but disabled by default." .to_string(), - default: astrcode_core::ApprovalDefault::Allow, + default: ApprovalDefault::Allow, metadata: json!({ "disabled": true, "governanceRevision": GOVERNANCE_POLICY_REVISION, @@ -175,11 +176,11 @@ pub(super) fn default_approval_pipeline( /// 解析 busy policy：mode 级别 RejectOnBusy 强制覆盖，否则使用请求方指定的策略。 pub(super) fn resolve_busy_policy( - submit_busy_policy: astrcode_core::SubmitBusyPolicy, + submit_busy_policy: SubmitBusyPolicy, requested_busy_policy: GovernanceBusyPolicy, ) -> GovernanceBusyPolicy { match submit_busy_policy { - astrcode_core::SubmitBusyPolicy::BranchOnBusy => requested_busy_policy, - astrcode_core::SubmitBusyPolicy::RejectOnBusy => GovernanceBusyPolicy::RejectOnBusy, + SubmitBusyPolicy::BranchOnBusy => requested_busy_policy, + SubmitBusyPolicy::RejectOnBusy => GovernanceBusyPolicy::RejectOnBusy, } } diff --git a/crates/server/src/governance_surface/prompt.rs b/crates/server/src/governance_surface/prompt.rs index a8771c93..28dbb4b1 100644 --- a/crates/server/src/governance_surface/prompt.rs +++ b/crates/server/src/governance_surface/prompt.rs @@ -6,9 +6,10 @@ //! - `build_resumed_child_contract`：继续委派的增量指令 prompt //! - `collaboration_prompt_declarations`：四工具协作指导 prompt -use astrcode_core::{ +use astrcode_core::ResolvedExecutionLimitsSnapshot; +use astrcode_prompt_contract::{ PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, - PromptDeclarationSource, ResolvedExecutionLimitsSnapshot, SystemPromptLayer, + PromptDeclarationSource, SystemPromptLayer, }; pub fn build_delegation_metadata( diff --git a/crates/server/src/governance_surface/tests.rs b/crates/server/src/governance_surface/tests.rs index b2700c60..52d1164c 100644 --- a/crates/server/src/governance_surface/tests.rs +++ b/crates/server/src/governance_surface/tests.rs @@ -7,9 +7,10 @@ //! - 各种 capability selector（all / subset / none / union / difference）的编译结果 use astrcode_core::{ - ApprovalDefault, BoundModeToolContractSnapshot, CapabilityKind, CapabilitySpec, LlmMessage, - ModeId, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, UserMessageOrigin, + CapabilityKind, CapabilitySpec, LlmMessage, ResolvedExecutionLimitsSnapshot, + ResolvedRuntimeConfig, UserMessageOrigin, }; +use astrcode_governance_contract::{ApprovalDefault, BoundModeToolContractSnapshot, ModeId}; use serde_json::{Value, json}; use super::{ @@ -63,7 +64,7 @@ async fn surface_policy_pipeline_defaults_to_allow_all() { resolved_limits: ResolvedExecutionLimitsSnapshot, resolved_overrides: None, injected_messages: Vec::new(), - policy_context: astrcode_core::PolicyContext { + policy_context: astrcode_governance_contract::PolicyContext { session_id: "session-1".to_string(), turn_id: "turn-1".to_string(), step_index: 0, @@ -73,8 +74,8 @@ async fn surface_policy_pipeline_defaults_to_allow_all() { }, collaboration_policy: collaboration_policy_context(&ResolvedRuntimeConfig::default()), approval: GovernanceApprovalPipeline { - pending: Some(astrcode_core::ApprovalPending { - request: astrcode_core::ApprovalRequest { + pending: Some(astrcode_governance_contract::ApprovalPending { + request: astrcode_governance_contract::ApprovalRequest { request_id: "approval".to_string(), session_id: "session-1".to_string(), turn_id: "turn-1".to_string(), @@ -88,7 +89,7 @@ async fn surface_policy_pipeline_defaults_to_allow_all() { default: ApprovalDefault::Allow, metadata: json!({}), }, - action: astrcode_core::CapabilityCall { + action: astrcode_governance_contract::CapabilityCall { request_id: "approval-call".to_string(), capability: CapabilitySpec::builder("placeholder", CapabilityKind::Tool) .description("placeholder") diff --git a/crates/server/src/http/routes/conversation.rs b/crates/server/src/http/routes/conversation.rs index 205695b1..d6be255c 100644 --- a/crates/server/src/http/routes/conversation.rs +++ b/crates/server/src/http/routes/conversation.rs @@ -1122,9 +1122,10 @@ mod tests { use astrcode_core::{ AgentEventContext, AgentLifecycleStatus, ChildExecutionIdentity, ChildSessionLineageKind, ChildSessionNode, ChildSessionStatusSource, ExecutionTaskStatus, ParentExecutionRef, Phase, - SessionEventRecord, ToolExecutionResult, ToolOutputStream, + SessionEventRecord, }; use astrcode_protocol::http::conversation::v1::ConversationStreamEnvelopeDto; + use astrcode_tool_contract::{ToolExecutionResult, ToolOutputStream}; use serde_json::{Value, json}; use tokio::sync::broadcast; diff --git a/crates/server/src/http/routes/sessions/mutation.rs b/crates/server/src/http/routes/sessions/mutation.rs index a036e130..664526dc 100644 --- a/crates/server/src/http/routes/sessions/mutation.rs +++ b/crates/server/src/http/routes/sessions/mutation.rs @@ -1,6 +1,7 @@ use std::{fs, path::Path as FsPath}; use astrcode_core::{ExecutionControl, SessionId}; +use astrcode_governance_contract::ModeId; use astrcode_host_session::{ CompactSessionMutationInput, ForkPoint, InterruptSessionMutationInput, TurnMutationPreparation, }; @@ -256,12 +257,11 @@ pub(crate) async fn switch_mode( .session_mode_state(&session_id) .await .map_err(ApiError::from)?; + let current_mode_id = ModeId::from(current_mode.current_mode_id.clone()); + let target_mode_id = ModeId::from(request.mode_id.clone()); state .mode_catalog - .validate_transition( - ¤t_mode.current_mode_id, - &request.mode_id.clone().into(), - ) + .validate_transition(¤t_mode_id, &target_mode_id) .map_err(ApiError::from)?; let mode = state .session_catalog diff --git a/crates/server/src/mode/catalog.rs b/crates/server/src/mode/catalog.rs index dbf6345c..a068a1f9 100644 --- a/crates/server/src/mode/catalog.rs +++ b/crates/server/src/mode/catalog.rs @@ -17,10 +17,11 @@ use std::{ sync::{Arc, RwLock}, }; -use astrcode_core::{ +use astrcode_core::Result; +use astrcode_governance_contract::{ ActionPolicies, ActionPolicyEffect, ActionPolicyRule, CapabilitySelector, ChildPolicySpec, GovernanceModeSpec, ModeArtifactDef, ModeExecutionPolicySpec, ModeExitGateDef, ModeId, - ModePromptHooks, PromptProgramEntry, Result, SubmitBusyPolicy, TransitionPolicySpec, + ModePromptHooks, PromptProgramEntry, SubmitBusyPolicy, TransitionPolicySpec, }; use super::builtin_prompts::{ @@ -345,7 +346,8 @@ fn builtin_mode_specs() -> Vec { #[cfg(test)] mod tests { - use astrcode_core::{CapabilitySelector, GovernanceModeSpec, ModeId, Result}; + use astrcode_core::Result; + use astrcode_governance_contract::{CapabilitySelector, GovernanceModeSpec, ModeId}; use super::{ModeCatalog, builtin_mode_catalog, builtin_mode_specs}; diff --git a/crates/server/src/mode/compiler.rs b/crates/server/src/mode/compiler.rs index 434567a7..26d8a599 100644 --- a/crates/server/src/mode/compiler.rs +++ b/crates/server/src/mode/compiler.rs @@ -8,10 +8,14 @@ use std::collections::BTreeSet; -use astrcode_core::{ - CapabilitySelector, CapabilitySpec, CompiledModeContracts, GovernanceModeSpec, +use astrcode_core::{CapabilitySpec, Result}; +use astrcode_governance_contract::{ + CapabilitySelector, CompiledModeContracts, GovernanceModeSpec, ResolvedChildPolicy, + ResolvedTurnEnvelope, SubmitBusyPolicy, +}; +use astrcode_prompt_contract::{ PromptDeclaration, PromptDeclarationKind, PromptDeclarationRenderTarget, - PromptDeclarationSource, ResolvedTurnEnvelope, Result, SystemPromptLayer, + PromptDeclarationSource, SystemPromptLayer, }; #[derive(Clone)] @@ -38,7 +42,7 @@ pub fn compile_mode_envelope( prompt_declarations: prompt_declarations.clone(), mode_contracts: compiled_mode_contracts(spec), action_policies: spec.action_policies.clone(), - child_policy: astrcode_core::ResolvedChildPolicy { + child_policy: ResolvedChildPolicy { mode_id: spec .child_policy .default_mode_id @@ -58,7 +62,7 @@ pub fn compile_mode_envelope( submit_busy_policy: spec .execution_policy .submit_busy_policy - .unwrap_or(astrcode_core::SubmitBusyPolicy::BranchOnBusy), + .unwrap_or(SubmitBusyPolicy::BranchOnBusy), fork_mode: spec.execution_policy.fork_mode.clone(), diagnostics: Vec::new(), }; @@ -75,7 +79,7 @@ pub fn compile_mode_envelope_for_child(spec: &GovernanceModeSpec) -> Result Result astrcode_core::Result; async fn session_child_nodes( &self, diff --git a/crates/server/src/ports/session_bridge.rs b/crates/server/src/ports/session_bridge.rs index 97f704fb..e6fdc0fc 100644 --- a/crates/server/src/ports/session_bridge.rs +++ b/crates/server/src/ports/session_bridge.rs @@ -4,15 +4,18 @@ use std::{ }; use astrcode_core::{ - AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, ExecutionAccepted, + AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, InputQueuedPayload, InvocationKind, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, ResolvedSubagentContextOverrides, SessionEventRecord, SessionId, SessionMeta, - StorageEventPayload, StoredEvent, SubRunResult, SubRunStorageMode, TurnId, replay_records, + StorageEventPayload, StoredEvent, SubRunResult, SubRunStorageMode, TurnId, }; +use astrcode_governance_contract::ModeId; use astrcode_host_session::{ ForkPoint, InputQueueProjection, ProjectedTurnOutcome, SessionCatalog, SubRunHandle, + replay_records, }; +use astrcode_runtime_contract::ExecutionAccepted; use async_trait::async_trait; use tokio::sync::broadcast; @@ -255,8 +258,8 @@ impl AppSessionPort for ServerSessionBridge { async fn switch_mode( &self, session_id: &str, - from: astrcode_core::ModeId, - to: astrcode_core::ModeId, + from: ModeId, + to: ModeId, ) -> astrcode_core::Result { self.session_runtime.switch_mode(session_id, from, to).await } diff --git a/crates/server/src/ports/session_submission.rs b/crates/server/src/ports/session_submission.rs index 135e9153..ec507ae2 100644 --- a/crates/server/src/ports/session_submission.rs +++ b/crates/server/src/ports/session_submission.rs @@ -4,11 +4,14 @@ //! 但不应该直接依赖 session-runtime 的具体提交结构。 use astrcode_core::{ - AgentEventContext, BoundModeToolContractSnapshot, CapabilityCall, LlmMessage, ModeId, - PolicyContext, PromptDeclaration, ResolvedExecutionLimitsSnapshot, + AgentEventContext, LlmMessage, ResolvedExecutionLimitsSnapshot, ResolvedSubagentContextOverrides, }; +use astrcode_governance_contract::{ + ApprovalPending, BoundModeToolContractSnapshot, CapabilityCall, ModeId, PolicyContext, +}; use astrcode_host_session::PromptGovernanceContext; +use astrcode_prompt_contract::PromptDeclaration; /// 应用层提交给 session 端口的稳定载荷。 #[allow(dead_code)] @@ -24,6 +27,6 @@ pub struct AppAgentPromptSubmission { pub source_tool_call_id: Option, pub policy_context: Option, pub governance_revision: Option, - pub approval: Option>, + pub approval: Option>, pub prompt_governance: Option, } diff --git a/crates/server/src/runtime_owner_bridge.rs b/crates/server/src/runtime_owner_bridge.rs index ab94d5c5..73b8a538 100644 --- a/crates/server/src/runtime_owner_bridge.rs +++ b/crates/server/src/runtime_owner_bridge.rs @@ -6,9 +6,10 @@ use std::sync::Arc; use astrcode_core::{ - AgentCollaborationFact, AgentTurnOutcome, GovernanceModeSpec, Result, RuntimeMetricsRecorder, + AgentCollaborationFact, AgentTurnOutcome, Result, RuntimeMetricsRecorder, RuntimeObservabilitySnapshot, SubRunStorageMode, }; +use astrcode_governance_contract::GovernanceModeSpec; use crate::{ ObservabilitySnapshotProvider, RuntimeObservabilityCollector, TaskRegistry, diff --git a/crates/server/src/session_runtime_owner_bridge.rs b/crates/server/src/session_runtime_owner_bridge.rs index 19b75460..5f42f0d0 100644 --- a/crates/server/src/session_runtime_owner_bridge.rs +++ b/crates/server/src/session_runtime_owner_bridge.rs @@ -4,13 +4,13 @@ use std::{ sync::{Arc, Mutex}, }; -use astrcode_agent_runtime::LlmProvider; #[cfg(test)] use astrcode_core::{AgentLifecycleStatus, AgentProfile}; use astrcode_core::{CapabilityInvoker, Result}; use astrcode_host_session::SessionCatalog; #[cfg(test)] use astrcode_host_session::SubRunHandle; +use astrcode_llm_contract::LlmProvider; #[cfg(test)] use crate::agent_control_bridge::ServerLiveSubRunStatus; diff --git a/crates/server/src/session_runtime_owner_bridge_impl.rs b/crates/server/src/session_runtime_owner_bridge_impl.rs index 70b43d57..6df205ed 100644 --- a/crates/server/src/session_runtime_owner_bridge_impl.rs +++ b/crates/server/src/session_runtime_owner_bridge_impl.rs @@ -4,10 +4,12 @@ use std::sync::atomic::{AtomicU64, Ordering}; #[cfg(test)] use astrcode_core::{ - AgentLifecycleStatus, AgentProfile, EventTranslator, SessionId, SessionTurnAcquireResult, - SessionTurnLease, StorageEvent, StoredEvent, + AgentLifecycleStatus, AgentProfile, SessionId, SessionTurnAcquireResult, SessionTurnLease, + StorageEvent, StoredEvent, }; use astrcode_core::{CapabilityInvoker, Result}; +#[cfg(test)] +use astrcode_host_session::EventTranslator; use astrcode_host_session::SessionCatalog; #[cfg(test)] diff --git a/crates/server/src/session_runtime_port.rs b/crates/server/src/session_runtime_port.rs index 14a55c68..797877e4 100644 --- a/crates/server/src/session_runtime_port.rs +++ b/crates/server/src/session_runtime_port.rs @@ -1,9 +1,11 @@ use astrcode_core::{ AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, ChildSessionNotification, - DelegationMetadata, ExecutionAccepted, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, - StoredEvent, TurnId, + DelegationMetadata, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, StoredEvent, + TurnId, }; +use astrcode_governance_contract::ModeId; use astrcode_host_session::SubRunHandle; +use astrcode_runtime_contract::ExecutionAccepted; use async_trait::async_trait; use crate::{ @@ -38,8 +40,8 @@ pub(crate) trait SessionRuntimePort: Send + Sync { async fn switch_mode( &self, session_id: &str, - from: astrcode_core::ModeId, - to: astrcode_core::ModeId, + from: ModeId, + to: ModeId, ) -> astrcode_core::Result; async fn submit_prompt_for_agent_with_submission( &self, diff --git a/crates/server/src/session_runtime_port_adapter.rs b/crates/server/src/session_runtime_port_adapter.rs index 7ac64229..c3a865ec 100644 --- a/crates/server/src/session_runtime_port_adapter.rs +++ b/crates/server/src/session_runtime_port_adapter.rs @@ -4,23 +4,28 @@ use std::{ }; use astrcode_agent_runtime::{ - AgentRuntime, AgentRuntimeExecutionSurface, LlmEvent, LlmProvider, RuntimeEventSink, - RuntimeTurnEvent, ToolDispatchRequest, ToolDispatcher, ToolResultReplacementRecord, TurnInput, - TurnOutput, TurnStopCause, + AgentRuntime, AgentRuntimeExecutionSurface, ToolDispatchRequest, ToolDispatcher, TurnInput, + TurnOutput, }; +use astrcode_context_window::tool_result_budget::ToolResultReplacementRecord; use astrcode_core::{ - AgentEvent, AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, AstrError, - BoundModeToolContractSnapshot, CancelToken, ChildSessionNotification, CompletedSubRunOutcome, - DelegationMetadata, EventTranslator, ExecutionAccepted, ExecutionControl, FailedSubRunOutcome, - LlmMessage, ModeId, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, SessionId, - StorageEvent, StorageEventPayload, StoredEvent, SubRunFailure, SubRunFailureCode, - SubRunHandoff, SubRunResult, ToolEventSink, ToolExecutionResult, TurnId, UserMessageOrigin, + AgentEvent, AgentInboxEnvelope, AgentLifecycleStatus, AgentTurnOutcome, AstrError, CancelToken, + ChildSessionNotification, CompletedSubRunOutcome, DelegationMetadata, ExecutionControl, + FailedSubRunOutcome, LlmMessage, ResolvedExecutionLimitsSnapshot, ResolvedRuntimeConfig, + SessionId, StorageEvent, StorageEventPayload, StoredEvent, SubRunFailure, SubRunFailureCode, + SubRunHandoff, SubRunResult, TurnId, UserMessageOrigin, }; +use astrcode_governance_contract::{BoundModeToolContractSnapshot, ModeId}; use astrcode_host_session::{ - CompactSessionMutationInput, InputQueueProjection, InterruptSessionMutationInput, - SessionCatalog, SubRunFinishStats, SubmitPromptMutationInput, SubmitTurnBusyPolicy, - TurnMutationPreparation, + CompactSessionMutationInput, EventTranslator, InputQueueProjection, + InterruptSessionMutationInput, SessionCatalog, SubRunFinishStats, SubmitPromptMutationInput, + SubmitTurnBusyPolicy, TurnMutationPreparation, }; +use astrcode_llm_contract::{LlmEvent, LlmProvider}; +use astrcode_runtime_contract::{ + ExecutionAccepted, RuntimeEventSink, RuntimeTurnEvent, TurnStopCause, +}; +use astrcode_tool_contract::{ToolContext, ToolEventSink, ToolExecutionResult}; use async_trait::async_trait; use chrono::Utc; @@ -155,8 +160,8 @@ impl ToolDispatcher for RouterToolDispatcher { async fn dispatch_tool( &self, request: ToolDispatchRequest, - ) -> astrcode_core::Result { - let mut tool_ctx = astrcode_core::ToolContext::new( + ) -> astrcode_core::Result { + let mut tool_ctx = ToolContext::new( request.session_id.clone().into(), self.working_dir.clone(), self.cancel.clone(), @@ -481,8 +486,8 @@ impl SessionRuntimePort for SessionRuntimeCompatPort { turn_id: None, agent: astrcode_core::AgentEventContext::default(), payload: astrcode_core::StorageEventPayload::ModeChanged { - from, - to, + from: from.into(), + to: to.into(), timestamp: Utc::now(), }, }, @@ -807,17 +812,22 @@ struct RuntimeToolEventSink { impl ToolEventSink for RuntimeToolEventSink { async fn emit(&self, event: StorageEvent) -> astrcode_core::Result<()> { if let StorageEventPayload::ModeChanged { from, to, .. } = &event.payload { - self.mode_catalog.validate_transition(from, to)?; + let from_mode_id = ModeId::from(from.clone()); + let to_mode_id = ModeId::from(to.clone()); + self.mode_catalog + .validate_transition(&from_mode_id, &to_mode_id)?; let current_mode_id = self.mode_tool_state.current_mode_id(); - if ¤t_mode_id != from { + if current_mode_id != from_mode_id { return Err(AstrError::Validation(format!( "mode transition from '{}' does not match current runtime mode '{}'", from, current_mode_id ))); } - let bound_mode_tool_contract = self.mode_catalog.bound_tool_contract_snapshot(to)?; + let bound_mode_tool_contract = self + .mode_catalog + .bound_tool_contract_snapshot(&to_mode_id)?; self.mode_tool_state - .replace(to.clone(), Some(bound_mode_tool_contract)); + .replace(to_mode_id, Some(bound_mode_tool_contract)); } self.runtime_event_sink .emit_event(RuntimeTurnEvent::StorageEvent { @@ -1292,9 +1302,11 @@ mod tests { }; use astrcode_agent_runtime::{RuntimeEventSink, ToolDispatchRequest, ToolDispatcher}; use astrcode_core::{ - AgentEvent, AgentEventContext, CancelToken, CapabilityInvoker, ModeId, StorageEvent, - StorageEventPayload, ToolCallRequest, ToolOutputStream, + AgentEvent, AgentEventContext, CancelToken, CapabilityInvoker, StorageEvent, + StorageEventPayload, ToolCallRequest, mode::ModeId as StoredModeId, }; + use astrcode_governance_contract::ModeId; + use astrcode_tool_contract::ToolOutputStream; use super::{ RouterToolDispatcher, RuntimeModeToolState, RuntimeToolEventSink, RuntimeTurnEvent, @@ -1396,7 +1408,7 @@ mod tests { if matches!( &event.payload, StorageEventPayload::ModeChanged { from, to, .. } - if *from == ModeId::code() && *to == ModeId::plan() + if *from == StoredModeId::code() && *to == StoredModeId::plan() ) )); } @@ -1460,7 +1472,7 @@ mod tests { if matches!( &event.payload, StorageEventPayload::ModeChanged { from, to, .. } - if *from == ModeId::code() && *to == ModeId::plan() + if *from == StoredModeId::code() && *to == StoredModeId::plan() ) )); @@ -1627,7 +1639,7 @@ mod tests { if matches!( &event.payload, StorageEventPayload::ModeChanged { from, to, .. } - if *from == ModeId::plan() && *to == ModeId::code() + if *from == StoredModeId::plan() && *to == StoredModeId::code() ) )); @@ -1662,7 +1674,7 @@ mod tests { if matches!( &event.payload, StorageEventPayload::ModeChanged { from, to, .. } - if *from == ModeId::code() && *to == ModeId::plan() + if *from == StoredModeId::code() && *to == StoredModeId::plan() ) )); } diff --git a/crates/server/src/tests/agent_routes_tests.rs b/crates/server/src/tests/agent_routes_tests.rs index 7b3f68e1..b32653f1 100644 --- a/crates/server/src/tests/agent_routes_tests.rs +++ b/crates/server/src/tests/agent_routes_tests.rs @@ -4,7 +4,8 @@ use std::{ time::{Duration, Instant}, }; -use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams, ToolContext}; +use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams}; +use astrcode_tool_contract::ToolContext; use axum::{ body::{Body, to_bytes}, http::{Request, StatusCode}, diff --git a/crates/server/src/tests/session_contract_tests.rs b/crates/server/src/tests/session_contract_tests.rs index 620218c5..eed123e9 100644 --- a/crates/server/src/tests/session_contract_tests.rs +++ b/crates/server/src/tests/session_contract_tests.rs @@ -1,4 +1,5 @@ -use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams, ToolContext}; +use astrcode_core::{AgentEventContext, CancelToken, SpawnAgentParams}; +use astrcode_tool_contract::ToolContext; use axum::{ body::{Body, to_bytes}, http::{Request, Response, StatusCode}, diff --git a/crates/server/src/tests/test_support.rs b/crates/server/src/tests/test_support.rs index ef29ccdc..28292bbd 100644 --- a/crates/server/src/tests/test_support.rs +++ b/crates/server/src/tests/test_support.rs @@ -7,12 +7,15 @@ use std::{ use astrcode_core::{ AgentCollaborationFact, AgentEventContext, AgentLifecycleStatus, AstrError, - DeleteProjectResult, ExecutionAccepted, InputBatchAckedPayload, InputBatchStartedPayload, - InputDiscardedPayload, InputQueuedPayload, LlmMessage, ModeId, PromptDeclaration, - ResolvedRuntimeConfig, SessionId, SessionMeta, SkillCatalog, StorageEvent, StorageEventPayload, - StoredEvent, TaskSnapshot, TurnId, TurnTerminalKind, UserMessageOrigin, + DeleteProjectResult, InputBatchAckedPayload, InputBatchStartedPayload, InputDiscardedPayload, + InputQueuedPayload, LlmMessage, ResolvedRuntimeConfig, SessionId, SessionMeta, SkillCatalog, + StorageEvent, StorageEventPayload, StoredEvent, TaskSnapshot, TurnId, TurnTerminalKind, + UserMessageOrigin, mode::ModeId as StoredModeId, }; +use astrcode_governance_contract::ModeId; use astrcode_host_session::{SessionCatalogEvent, SessionControlStateSnapshot, SessionModeState}; +use astrcode_prompt_contract::PromptDeclaration; +use astrcode_runtime_contract::ExecutionAccepted; use async_trait::async_trait; use tokio::sync::broadcast; @@ -320,7 +323,7 @@ impl AppSessionPort for StubSessionPort { manual_compact_pending: false, compacting: false, last_compact_meta: None, - current_mode_id: ModeId::code(), + current_mode_id: StoredModeId::code(), last_mode_changed_at: None, })) } @@ -347,7 +350,7 @@ impl AppSessionPort for StubSessionPort { .expect("mode state lock should work") .clone() .unwrap_or(SessionModeState { - current_mode_id: ModeId::code(), + current_mode_id: StoredModeId::code(), last_mode_changed_at: None, })) } @@ -375,7 +378,7 @@ impl AppSessionPort for StubSessionPort { to: to.clone(), }); *self.mode_state.lock().expect("mode state lock should work") = Some(SessionModeState { - current_mode_id: to.clone(), + current_mode_id: to.clone().into(), last_mode_changed_at: None, }); Ok(StoredEvent { @@ -384,8 +387,8 @@ impl AppSessionPort for StubSessionPort { turn_id: None, agent: AgentEventContext::default(), payload: StorageEventPayload::ModeChanged { - from, - to, + from: from.into(), + to: to.into(), timestamp: chrono::Utc::now(), }, }, diff --git a/crates/server/src/tool_capability_invoker.rs b/crates/server/src/tool_capability_invoker.rs index 3825e7bf..abe18ed2 100644 --- a/crates/server/src/tool_capability_invoker.rs +++ b/crates/server/src/tool_capability_invoker.rs @@ -5,9 +5,13 @@ use std::sync::Arc; use astrcode_core::{ - AgentEventContext, AstrError, BoundModeToolContractSnapshot, CancelToken, CapabilityContext, - CapabilityExecutionResult, CapabilityInvoker, CapabilitySpec, ExecutionOwner, Result, - SessionId, Tool, ToolContext, ToolEventSink, ToolOutputDelta, + AgentEventContext, AstrError, CancelToken, CapabilityContext, CapabilityExecutionResult, + CapabilityInvoker, CapabilitySpec, ExecutionOwner as CoreExecutionOwner, Result, SessionId, + ToolEventSink as CoreToolEventSink, mode::BoundModeToolContractSnapshot, +}; +use astrcode_tool_contract::{ + ExecutionOwner as ContractExecutionOwner, Tool, ToolContext, + ToolEventSink as ContractToolEventSink, ToolOutputDelta, }; use async_trait::async_trait; use serde_json::Value; @@ -95,11 +99,33 @@ struct ToolBridgeContext { turn_id: Option, request_id: Option, agent: AgentEventContext, - current_mode_id: astrcode_core::ModeId, + current_mode_id: astrcode_core::mode::ModeId, bound_mode_tool_contract: Option, - execution_owner: Option, + execution_owner: Option, tool_output_sender: Option>, - event_sink: Option>, + event_sink: Option>, +} + +struct CoreToolEventSinkAdapter { + inner: Arc, +} + +#[async_trait] +impl CoreToolEventSink for CoreToolEventSinkAdapter { + async fn emit(&self, event: astrcode_core::StorageEvent) -> Result<()> { + self.inner.emit(event).await + } +} + +struct ContractToolEventSinkAdapter { + inner: Arc, +} + +#[async_trait] +impl ContractToolEventSink for ContractToolEventSinkAdapter { + async fn emit(&self, event: astrcode_core::StorageEvent) -> Result<()> { + self.inner.emit(event).await + } } impl ToolBridgeContext { @@ -111,11 +137,13 @@ impl ToolBridgeContext { turn_id: ctx.turn_id().map(ToString::to_string), request_id: None, agent: ctx.agent_context().clone(), - current_mode_id: ctx.current_mode_id().clone(), - bound_mode_tool_contract: ctx.bound_mode_tool_contract().cloned(), - execution_owner: ctx.execution_owner().cloned(), + current_mode_id: ctx.current_mode_id().clone().into(), + bound_mode_tool_contract: ctx.bound_mode_tool_contract().cloned().map(Into::into), + execution_owner: ctx.execution_owner().cloned().map(contract_owner_to_core), tool_output_sender: ctx.tool_output_sender(), - event_sink: ctx.event_sink(), + event_sink: ctx.event_sink().map(|sink| { + Arc::new(CoreToolEventSinkAdapter { inner: sink }) as Arc + }), } } @@ -164,23 +192,42 @@ impl ToolBridgeContext { tool_ctx = tool_ctx.with_tool_call_id(tool_call_id); } tool_ctx = tool_ctx.with_agent_context(self.agent); - tool_ctx = tool_ctx.with_current_mode_id(self.current_mode_id); + tool_ctx = tool_ctx.with_current_mode_id(self.current_mode_id.into()); if let Some(snapshot) = self.bound_mode_tool_contract { - tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot); + tool_ctx = tool_ctx.with_bound_mode_tool_contract(snapshot.into()); } if let Some(sender) = self.tool_output_sender { tool_ctx = tool_ctx.with_tool_output_sender(sender); } if let Some(event_sink) = self.event_sink { - tool_ctx = tool_ctx.with_event_sink(event_sink); + tool_ctx = tool_ctx + .with_event_sink(Arc::new(ContractToolEventSinkAdapter { inner: event_sink })); } if let Some(owner) = self.execution_owner { - tool_ctx = tool_ctx.with_execution_owner(owner); + tool_ctx = tool_ctx.with_execution_owner(core_owner_to_contract(owner)); } tool_ctx } } +fn contract_owner_to_core(owner: ContractExecutionOwner) -> CoreExecutionOwner { + CoreExecutionOwner { + root_session_id: owner.root_session_id, + root_turn_id: owner.root_turn_id, + sub_run_id: owner.sub_run_id, + invocation_kind: owner.invocation_kind, + } +} + +fn core_owner_to_contract(owner: CoreExecutionOwner) -> ContractExecutionOwner { + ContractExecutionOwner { + root_session_id: owner.root_session_id, + root_turn_id: owner.root_turn_id, + sub_run_id: owner.sub_run_id, + invocation_kind: owner.invocation_kind, + } +} + pub(crate) fn tool_context_from_capability_context(ctx: &CapabilityContext) -> ToolContext { ToolBridgeContext::from_capability_context(ctx).into_tool_context() } diff --git a/crates/tool-contract/Cargo.toml b/crates/tool-contract/Cargo.toml new file mode 100644 index 00000000..a55709f2 --- /dev/null +++ b/crates/tool-contract/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "astrcode-tool-contract" +version = "0.1.0" +edition.workspace = true +license-file.workspace = true +authors.workspace = true + +[dependencies] +astrcode-core = { path = "../core" } +astrcode-governance-contract = { path = "../governance-contract" } +async-trait.workspace = true +serde.workspace = true +serde_json.workspace = true +tokio.workspace = true + diff --git a/crates/tool-contract/src/lib.rs b/crates/tool-contract/src/lib.rs new file mode 100644 index 00000000..c7e70cdf --- /dev/null +++ b/crates/tool-contract/src/lib.rs @@ -0,0 +1,707 @@ +//! # Tool Trait 与执行上下文 +//! +//! 定义了工具（Tool）系统的核心抽象。Tool 是 LLM Agent 调用外部能力的统一接口。 +//! +//! ## 核心概念 +//! +//! - **Tool**: 可被 Agent 调用的能力单元（如文件读写、Shell 执行、代码搜索） +//! - **ToolContext**: 工具执行时的上下文信息（会话 ID、工作目录、取消令牌） +//! - **ToolCapabilityMetadata**: 工具的能力元数据（用于策略引擎的权限判断） + +use std::{fmt, path::PathBuf, sync::Arc}; + +use astrcode_core::{ + AgentEventContext, CancelToken, CapabilityKind, CapabilitySpec, CapabilitySpecBuildError, + InvocationKind, InvocationMode, PermissionSpec, Result, SessionId, SideEffect, Stability, + StorageEvent, TurnId, tool_result_persist::DEFAULT_TOOL_RESULT_INLINE_LIMIT, +}; +pub use astrcode_core::{ToolDefinition, ToolExecutionResult, ToolOutputDelta, ToolOutputStream}; +use astrcode_governance_contract::{BoundModeToolContractSnapshot, ModeId}; +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; +use serde_json::{Value, json}; +use tokio::sync::mpsc::UnboundedSender; + +/// 工具执行的默认最大输出大小（1 MB） +/// +/// 超过此大小的输出会被截断，防止大文件导致内存溢出或网络传输问题。 +pub const DEFAULT_MAX_OUTPUT_SIZE: usize = 1024 * 1024; + +/// 工具调用链路的稳定归属标识。 +/// +/// 该结构只服务 runtime 内部的控制面演进，用于把“根执行归属”和 +/// “当前 sub-run 归属”显式挂到工具上下文里，避免后续长任务注册继续 +/// 依赖 `parent_turn_id` 这类脆弱字符串推断。 +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +pub struct ExecutionOwner { + /// 根执行所在的 session。 + pub root_session_id: SessionId, + /// 根执行所在的 turn。 + pub root_turn_id: TurnId, + /// 当前工具调用若属于子执行域，则记录 sub-run id。 + #[serde(default, skip_serializing_if = "Option::is_none")] + pub sub_run_id: Option, + /// 当前归属来源。 + pub invocation_kind: InvocationKind, +} + +impl ExecutionOwner { + /// 为顶层执行构造 owner。 + pub fn root( + root_session_id: impl Into, + root_turn_id: impl Into, + invocation_kind: InvocationKind, + ) -> Self { + Self { + root_session_id: root_session_id.into(), + root_turn_id: root_turn_id.into(), + sub_run_id: None, + invocation_kind, + } + } + + /// 在现有根归属上挂接当前 sub-run。 + pub fn for_sub_run(&self, sub_run_id: impl Into) -> Self { + Self { + root_session_id: self.root_session_id.clone(), + root_turn_id: self.root_turn_id.clone(), + sub_run_id: Some(sub_run_id.into()), + invocation_kind: InvocationKind::SubRun, + } + } +} + +/// Tool 内部产生 turn 级事件时使用的发射接口。 +/// +/// 子 Agent / 复合工具不能直接依赖 runtime 的会话写入实现， +/// 因此这里通过一个最小抽象把事件重新交回当前 turn 的持久化/广播链路。 +#[async_trait] +pub trait ToolEventSink: Send + Sync { + async fn emit(&self, event: StorageEvent) -> Result<()>; +} + +/// Execution context provided to tools during invocation. +/// +/// `ToolContext` carries session metadata, working directory, cancellation support, +/// and output size limits that tools should respect when producing results. +pub struct ToolContext { + /// Unique session identifier. + session_id: SessionId, + /// Working directory that tools must operate within. + working_dir: PathBuf, + /// Cancellation token for cooperative cancellation. + cancel: CancelToken, + /// 当前工具调用所属 turn。 + /// + /// 普通工具通常不需要感知 turn_id，但像 spawn 这类复合工具 + /// 需要把子事件重新挂回父 turn。 + turn_id: Option, + /// 当前工具调用 ID。 + /// + /// spawn 等复合工具会把这个值落到 durable lifecycle 事件， + /// 保证重放后仍然能还原触发链路。 + tool_call_id: Option, + /// 当前工具调用所属 Agent 元数据。 + /// + /// 子 Agent 工具会基于父 Agent 上下文继续派生自己的 agent_id / + /// parent_turn_id / agent_profile。 + /// + /// 使用 Arc 避免 ToolContext 在高频 clone 时反复复制整块 AgentEventContext。 + agent: Arc, + /// 工具执行开始时当前会话的治理 mode。 + current_mode_id: ModeId, + /// 当前 turn 绑定后的 mode tool contract 快照。 + bound_mode_tool_contract: Option, + /// Maximum output size in bytes. Defaults to 1MB. + max_output_size: usize, + /// Optional override for session-scoped persisted tool artifacts. + /// + /// Production runtime usually leaves this unset so storage falls back to the + /// project bucket under `~/.astrcode/projects/...`. Tests can point it at a + /// temp dir to avoid leaking files into the real home directory. + session_storage_root: Option, + /// Optional streaming channel for long-running tools. + /// + /// Tools emit best-effort deltas through this sender so runtime can persist and fan them out + /// in-order without coupling individual tools to storage or transport details. + tool_output_sender: Option>, + /// 工具级 turn 事件发射器。 + /// + /// 只有像 spawn 这类会在工具内部再触发 turn/tool 事件的复合工具才会使用。 + event_sink: Option>, + /// 工具调用链路归属。 + /// + /// 当前只作为只读上下文向下游传播，为后续根级任务控制平面预留稳定 owner。 + execution_owner: Option, + /// 当前工具的结果内联阈值（字节）。 + /// + /// 由工具调度时从 `CapabilitySpec::max_result_inline_size` 解析填入， + /// 未设置时使用 `DEFAULT_TOOL_RESULT_INLINE_LIMIT`。 + /// 工具执行侧用此值决定是否将结果持久化到磁盘。 + resolved_inline_limit: usize, +} + +impl ToolContext { + /// Creates a new `ToolContext` with the given session id, working directory, and cancel token. + /// + /// The `max_output_size` is initialized to [`DEFAULT_MAX_OUTPUT_SIZE`]. + pub fn new(session_id: SessionId, working_dir: PathBuf, cancel: CancelToken) -> Self { + Self { + session_id, + working_dir, + cancel, + turn_id: None, + tool_call_id: None, + agent: Arc::new(AgentEventContext::default()), + current_mode_id: ModeId::default(), + bound_mode_tool_contract: None, + max_output_size: DEFAULT_MAX_OUTPUT_SIZE, + session_storage_root: None, + tool_output_sender: None, + event_sink: None, + execution_owner: None, + resolved_inline_limit: DEFAULT_TOOL_RESULT_INLINE_LIMIT, + } + } + + /// Sets the maximum output size in bytes. + pub fn with_max_output_size(mut self, max_output_size: usize) -> Self { + self.max_output_size = max_output_size; + self + } + + /// Overrides the root directory used for session-scoped persisted tool artifacts. + pub fn with_session_storage_root(mut self, session_storage_root: PathBuf) -> Self { + self.session_storage_root = Some(session_storage_root); + self + } + + /// Attaches a sender used for best-effort tool output streaming. + /// + /// Runtime injects this when it wants a tool to publish incremental stdout/stderr updates + /// before the final `ToolExecutionResult` is available. + pub fn with_tool_output_sender( + mut self, + tool_output_sender: UnboundedSender, + ) -> Self { + self.tool_output_sender = Some(tool_output_sender); + self + } + + /// 为工具上下文注入当前 turn_id。 + pub fn with_turn_id(mut self, turn_id: impl Into) -> Self { + self.turn_id = Some(turn_id.into()); + self + } + + /// 为工具上下文注入当前 tool_call_id。 + pub fn with_tool_call_id(mut self, tool_call_id: impl Into) -> Self { + self.tool_call_id = Some(tool_call_id.into()); + self + } + + /// 为工具上下文注入当前 Agent 元数据。 + pub fn with_agent_context(mut self, agent: AgentEventContext) -> Self { + self.agent = Arc::new(agent); + self + } + + /// 为工具上下文注入当前治理 mode。 + pub fn with_current_mode_id(mut self, current_mode_id: ModeId) -> Self { + self.current_mode_id = current_mode_id; + self + } + + /// 为工具上下文注入当前 turn 绑定后的 mode contract 快照。 + pub fn with_bound_mode_tool_contract( + mut self, + bound_mode_tool_contract: BoundModeToolContractSnapshot, + ) -> Self { + self.bound_mode_tool_contract = Some(bound_mode_tool_contract); + self + } + + /// 为工具上下文注入 turn 事件发射器。 + pub fn with_event_sink(mut self, event_sink: Arc) -> Self { + self.event_sink = Some(event_sink); + self + } + + /// 为工具上下文注入执行 owner。 + pub fn with_execution_owner(mut self, execution_owner: ExecutionOwner) -> Self { + self.execution_owner = Some(execution_owner); + self + } + + /// 设置当前工具的结果内联阈值。 + /// + /// 由工具调度时从 `CapabilitySpec::max_result_inline_size` 解析填入。 + pub fn with_resolved_inline_limit(mut self, limit: usize) -> Self { + self.resolved_inline_limit = limit; + self + } + + /// Returns the session identifier. + pub fn session_id(&self) -> &str { + &self.session_id + } + + /// Returns the working directory path. + pub fn working_dir(&self) -> &std::path::Path { + &self.working_dir + } + + /// Returns a reference to the cancellation token. + pub fn cancel(&self) -> &CancelToken { + &self.cancel + } + + /// 返回当前 turn_id（若有）。 + pub fn turn_id(&self) -> Option<&str> { + self.turn_id.as_deref() + } + + /// 返回当前 tool_call_id（若有）。 + pub fn tool_call_id(&self) -> Option<&str> { + self.tool_call_id.as_deref() + } + + /// 返回当前 Agent 元数据。 + pub fn agent_context(&self) -> &AgentEventContext { + self.agent.as_ref() + } + + /// 返回工具执行开始时当前会话的治理 mode。 + pub fn current_mode_id(&self) -> &ModeId { + &self.current_mode_id + } + + pub fn bound_mode_tool_contract(&self) -> Option<&BoundModeToolContractSnapshot> { + self.bound_mode_tool_contract.as_ref() + } + + /// Returns the maximum output size in bytes. + pub fn max_output_size(&self) -> usize { + self.max_output_size + } + + pub fn session_storage_root(&self) -> Option<&std::path::Path> { + self.session_storage_root.as_deref() + } + + pub fn tool_output_sender(&self) -> Option> { + self.tool_output_sender.clone() + } + + pub fn event_sink(&self) -> Option> { + self.event_sink.clone() + } + + /// 返回当前执行 owner。 + pub fn execution_owner(&self) -> Option<&ExecutionOwner> { + self.execution_owner.as_ref() + } + + /// 返回当前工具的结果内联阈值（字节）。 + pub fn resolved_inline_limit(&self) -> usize { + self.resolved_inline_limit + } + + /// Emits a tool delta to the runtime if streaming is enabled. + /// + /// This is intentionally best-effort: losing a live UI update must not fail the tool itself, + /// because the final persisted `ToolExecutionResult` is still the source of truth. + pub fn emit_tool_delta(&self, delta: ToolOutputDelta) -> bool { + self.tool_output_sender + .as_ref() + .is_some_and(|sender| sender.send(delta).is_ok()) + } + + pub fn emit_stdout( + &self, + tool_call_id: impl Into, + tool_name: impl Into, + delta: impl Into, + ) -> bool { + self.emit_tool_delta(ToolOutputDelta { + tool_call_id: tool_call_id.into(), + tool_name: tool_name.into(), + stream: ToolOutputStream::Stdout, + delta: delta.into(), + }) + } + + pub fn emit_stderr( + &self, + tool_call_id: impl Into, + tool_name: impl Into, + delta: impl Into, + ) -> bool { + self.emit_tool_delta(ToolOutputDelta { + tool_call_id: tool_call_id.into(), + tool_name: tool_name.into(), + stream: ToolOutputStream::Stderr, + delta: delta.into(), + }) + } +} + +impl Clone for ToolContext { + fn clone(&self) -> Self { + Self { + session_id: self.session_id.clone(), + working_dir: self.working_dir.clone(), + cancel: self.cancel.clone(), + turn_id: self.turn_id.clone(), + tool_call_id: self.tool_call_id.clone(), + agent: self.agent.clone(), + current_mode_id: self.current_mode_id.clone(), + bound_mode_tool_contract: self.bound_mode_tool_contract.clone(), + max_output_size: self.max_output_size, + session_storage_root: self.session_storage_root.clone(), + tool_output_sender: self.tool_output_sender.clone(), + event_sink: self.event_sink.clone(), + execution_owner: self.execution_owner.clone(), + resolved_inline_limit: self.resolved_inline_limit, + } + } +} + +impl fmt::Debug for ToolContext { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("ToolContext") + .field("session_id", &self.session_id) + .field("working_dir", &self.working_dir) + .field("cancel", &self.cancel) + .field("turn_id", &self.turn_id) + .field("agent", self.agent.as_ref()) + .field("current_mode_id", &self.current_mode_id) + .field("bound_mode_tool_contract", &self.bound_mode_tool_contract) + .field("max_output_size", &self.max_output_size) + .field("session_storage_root", &self.session_storage_root) + .field( + "tool_output_sender", + &self.tool_output_sender.as_ref().map(|_| ""), + ) + .field( + "event_sink", + &self.event_sink.as_ref().map(|_| ""), + ) + .field("execution_owner", &self.execution_owner) + .field("resolved_inline_limit", &self.resolved_inline_limit) + .finish() + } +} + +/// Metadata describing the capability profiles, permissions, and stability of a tool. +/// +/// This struct is used by tools to declare their operational characteristics, which +/// the policy engine and capability router use to make access control decisions. +#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Default)] +#[serde(rename_all = "camelCase")] +pub struct ToolPromptMetadata { + pub summary: String, + pub guide: String, + #[serde(default)] + pub caveats: Vec, + #[serde(default)] + pub examples: Vec, + #[serde(default)] + pub prompt_tags: Vec, + #[serde(default)] + pub always_include: bool, +} + +impl ToolPromptMetadata { + pub fn new(summary: impl Into, guide: impl Into) -> Self { + Self { + summary: summary.into(), + guide: guide.into(), + caveats: Vec::new(), + examples: Vec::new(), + prompt_tags: Vec::new(), + always_include: false, + } + } + + pub fn caveat(mut self, caveat: impl Into) -> Self { + self.caveats.push(caveat.into()); + self + } + + pub fn example(mut self, example: impl Into) -> Self { + self.examples.push(example.into()); + self + } + + pub fn prompt_tag(mut self, prompt_tag: impl Into) -> Self { + self.prompt_tags.push(prompt_tag.into()); + self + } + + pub fn always_include(mut self, always_include: bool) -> Self { + self.always_include = always_include; + self + } +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ToolCapabilityMetadata { + /// Capability profiles that this tool belongs to (e.g., "coding", "analysis"). + pub profiles: Vec, + /// Descriptive tags for categorization and discovery. + pub tags: Vec, + /// Permission hints indicating what resources or actions this tool may access. + pub permissions: Vec, + /// 调用模式，替代旧的 `streaming: bool`。 + pub invocation_mode: InvocationMode, + /// The level of side effects this tool may produce. + pub side_effect: SideEffect, + /// Whether the runtime may execute multiple calls to this capability in parallel. + pub concurrency_safe: bool, + /// Whether old tool results may be compacted out of request context to save tokens. + pub compact_clearable: bool, + /// Stability level indicating API maturity. + pub stability: Stability, + /// Prompt guidance that should be projected into the layered prompt system. + pub prompt: Option, + /// 工具结果内联阈值（字节）。 + /// 超过此大小的结果在执行时持久化到磁盘。 + /// None 时使用系统默认阈值（DEFAULT_TOOL_RESULT_INLINE_LIMIT = 32KB）。 + pub max_result_inline_size: Option, +} + +impl Default for ToolCapabilityMetadata { + fn default() -> Self { + Self::builtin() + } +} + +impl ToolCapabilityMetadata { + /// Creates a new metadata instance with default builtin values. + /// + /// The defaults are: profile "coding", tag "builtin", no permissions, + /// side effect level `Workspace`, and stability `Stable`. + pub fn builtin() -> Self { + Self { + profiles: vec!["coding".to_string()], + tags: vec!["builtin".to_string()], + permissions: Vec::new(), + invocation_mode: InvocationMode::Unary, + side_effect: SideEffect::Workspace, + concurrency_safe: false, + compact_clearable: false, + stability: Stability::Stable, + prompt: None, + max_result_inline_size: None, + } + } + + /// Adds a single capability profile. + pub fn profile(mut self, profile: impl Into) -> Self { + self.profiles.push(profile.into()); + self + } + + /// Adds multiple capability profiles. + pub fn profiles(mut self, profiles: I) -> Self + where + I: IntoIterator, + S: Into, + { + self.profiles.extend(profiles.into_iter().map(Into::into)); + self + } + + /// Adds a single descriptive tag. + pub fn tag(mut self, tag: impl Into) -> Self { + self.tags.push(tag.into()); + self + } + + /// Adds multiple descriptive tags. + pub fn tags(mut self, tags: I) -> Self + where + I: IntoIterator, + S: Into, + { + self.tags.extend(tags.into_iter().map(Into::into)); + self + } + + /// Adds a permission hint without a rationale. + pub fn permission(mut self, name: impl Into) -> Self { + self.permissions.push(PermissionSpec { + name: name.into(), + rationale: None, + }); + self + } + + /// Adds a permission hint with an explanatory rationale. + pub fn permission_with_rationale( + mut self, + name: impl Into, + rationale: impl Into, + ) -> Self { + self.permissions.push(PermissionSpec { + name: name.into(), + rationale: Some(rationale.into()), + }); + self + } + + /// 设置调用模式（Unary / Streaming）。 + pub fn invocation_mode(mut self, invocation_mode: InvocationMode) -> Self { + self.invocation_mode = invocation_mode; + self + } + + /// Sets the side effect level for this tool. + pub fn side_effect(mut self, side_effect: SideEffect) -> Self { + self.side_effect = side_effect; + self + } + + /// Marks whether the tool is safe to run concurrently with other safe tools. + pub fn concurrency_safe(mut self, concurrency_safe: bool) -> Self { + self.concurrency_safe = concurrency_safe; + self + } + + /// Marks whether historical results from this tool may be cleared from model context. + pub fn compact_clearable(mut self, compact_clearable: bool) -> Self { + self.compact_clearable = compact_clearable; + self + } + + /// Sets the stability level for this tool. + pub fn stability(mut self, stability: Stability) -> Self { + self.stability = stability; + self + } + + /// Attaches prompt guidance to this tool descriptor. + pub fn prompt(mut self, prompt: ToolPromptMetadata) -> Self { + self.prompt = Some(prompt); + self + } + + /// Sets the maximum inline size for tool results (bytes). + pub fn max_result_inline_size(mut self, size: usize) -> Self { + self.max_result_inline_size = Some(size); + self + } + + /// Builds a [`CapabilitySpec`] from this metadata and the tool definition. + pub fn build_spec( + self, + definition: ToolDefinition, + ) -> std::result::Result { + let mut metadata = serde_json::Map::new(); + if let Some(prompt) = self.prompt { + metadata.insert( + "prompt".to_string(), + serde_json::to_value(prompt) + // 提示词元数据必须作为 descriptor 的一部分向上游显式报错， + // 不能在库层 panic 吞掉调用方的构建上下文。 + .map_err(|_| CapabilitySpecBuildError::InvalidSchema("metadata"))?, + ); + } + + let builder = CapabilitySpec::builder(definition.name, CapabilityKind::Tool) + .description(definition.description) + .schema(definition.parameters, json!({ "type": "string" })) + .invocation_mode(self.invocation_mode) + .profiles(self.profiles) + .tags(self.tags) + .permissions(self.permissions) + .side_effect(self.side_effect) + .concurrency_safe(self.concurrency_safe) + .compact_clearable(self.compact_clearable) + .stability(self.stability) + .metadata(Value::Object(metadata)); + let builder = match self.max_result_inline_size { + Some(size) => builder.max_result_inline_size(size), + None => builder, + }; + builder.build() + } +} + +/// Trait that all tools must implement. +/// +/// A `Tool` provides a named operation that can be invoked by the agent loop. +/// Implementors must be `Send + Sync` to support concurrent execution. +#[async_trait] +pub trait Tool: Send + Sync { + /// Returns the tool's definition including name, description, and parameter schema. + fn definition(&self) -> ToolDefinition; + + /// Returns capability metadata for policy and routing decisions. + /// + /// The default implementation returns builtin defaults. Override this method + /// to customize the tool's operational characteristics. + fn capability_metadata(&self) -> ToolCapabilityMetadata { + ToolCapabilityMetadata::builtin() + } + + /// Returns a full capability spec for this tool. + /// + /// The default implementation builds a spec from `definition()` and + /// `capability_metadata()`. Override this method for advanced tools that + /// need complete control over the capability spec. + fn capability_spec(&self) -> std::result::Result { + self.capability_metadata().build_spec(self.definition()) + } + + /// Executes the tool with the given arguments and context. + /// + /// # Arguments + /// * `tool_call_id` - Unique identifier for this tool call. + /// * `input` - JSON arguments parsed from the agent's tool call request. + /// * `ctx` - Execution context providing session info, working directory, and cancellation. + /// + /// # Returns + /// `Ok(ToolExecutionResult)` on success, or `Err` for system-level failures. + async fn execute( + &self, + tool_call_id: String, + input: Value, + ctx: &ToolContext, + ) -> Result; +} + +#[cfg(test)] +mod tests { + use std::path::PathBuf; + + use crate::{BoundModeToolContractSnapshot, CancelToken, ToolContext}; + + #[test] + fn tool_context_preserves_bound_mode_tool_contract_snapshot() { + let ctx = ToolContext::new( + "session-1".into(), + PathBuf::from("/repo"), + CancelToken::new(), + ) + .with_bound_mode_tool_contract(BoundModeToolContractSnapshot { + mode_id: "plan".into(), + artifact: None, + exit_gate: None, + }); + + assert_eq!( + ctx.bound_mode_tool_contract() + .map(|snapshot| snapshot.mode_id.as_str()), + Some("plan") + ); + assert_eq!( + ctx.clone() + .bound_mode_tool_contract() + .map(|snapshot| snapshot.mode_id.as_str()), + Some("plan") + ); + } +} diff --git a/scripts/check-crate-boundaries.mjs b/scripts/check-crate-boundaries.mjs index 99162506..ff57a7d0 100644 --- a/scripts/check-crate-boundaries.mjs +++ b/scripts/check-crate-boundaries.mjs @@ -50,75 +50,103 @@ function buildRules() { }, { id: 'R002', - description: 'protocol 必须保持纯 DTO，仅允许依赖 core', + description: 'protocol 必须保持纯 DTO，仅允许依赖 core 与对外传输所需的 contract crate', source: 'astrcode-protocol', - allowedExact: new Set(['astrcode-core']), + allowedExact: new Set(['astrcode-core', 'astrcode-governance-contract']), }, { id: 'R003', - description: 'kernel 是迁移源，只允许依赖 core 与新 owner 边界', - source: 'astrcode-kernel', + description: 'prompt-contract 只承载 prompt 契约，仅允许依赖 core', + source: 'astrcode-prompt-contract', + allowedExact: new Set(['astrcode-core']), + }, + { + id: 'R004', + description: 'governance-contract 只承载治理契约，仅允许依赖 core、prompt-contract', + source: 'astrcode-governance-contract', + allowedExact: new Set(['astrcode-core', 'astrcode-prompt-contract']), + }, + { + id: 'R005', + description: 'tool-contract 只承载工具契约，仅允许依赖 core、governance-contract', + source: 'astrcode-tool-contract', + allowedExact: new Set(['astrcode-core', 'astrcode-governance-contract']), + }, + { + id: 'R006', + description: 'support 仅允许依赖 core', + source: 'astrcode-support', + allowedExact: new Set(['astrcode-core']), + }, + { + id: 'R007', + description: 'llm-contract 只承载 LLM 契约，仅允许依赖 core、governance-contract、prompt-contract', + source: 'astrcode-llm-contract', allowedExact: new Set([ 'astrcode-core', - 'astrcode-agent-runtime', - 'astrcode-host-session', - 'astrcode-plugin-host', + 'astrcode-governance-contract', + 'astrcode-prompt-contract', ]), }, { - id: 'R004', - description: 'session-runtime 是迁移源，只允许依赖 core、support、kernel 与新 owner 边界', - source: 'astrcode-session-runtime', + id: 'R008', + description: 'runtime-contract 只承载 runtime 边界，仅允许依赖 core、llm-contract、tool-contract', + source: 'astrcode-runtime-contract', allowedExact: new Set([ 'astrcode-core', - 'astrcode-support', - 'astrcode-kernel', - 'astrcode-agent-runtime', - 'astrcode-host-session', - 'astrcode-plugin-host', + 'astrcode-llm-contract', + 'astrcode-tool-contract', ]), }, { - id: 'R005', - description: 'application 是迁移源，只允许依赖 core、support、旧迁移源与新 owner 边界', - source: 'astrcode-application', + id: 'R009', + description: 'context-window 只负责上下文窗口，允许依赖 core、llm-contract、runtime-contract、tool-contract、support', + source: 'astrcode-context-window', allowedExact: new Set([ 'astrcode-core', + 'astrcode-llm-contract', + 'astrcode-runtime-contract', + 'astrcode-tool-contract', 'astrcode-support', - 'astrcode-kernel', - 'astrcode-session-runtime', - 'astrcode-agent-runtime', - 'astrcode-host-session', - 'astrcode-plugin-host', ]), }, { - id: 'R006', - description: 'support 仅允许依赖 core', - source: 'astrcode-support', - allowedExact: new Set(['astrcode-core']), - }, - { - id: 'R007', - description: 'agent-runtime 是最小执行内核，只允许依赖 core', + id: 'R010', + description: 'agent-runtime 是最小执行内核，仅允许依赖 core、context-window、llm-contract、runtime-contract、tool-contract', source: 'astrcode-agent-runtime', - allowedExact: new Set(['astrcode-core']), + allowedExact: new Set([ + 'astrcode-core', + 'astrcode-context-window', + 'astrcode-llm-contract', + 'astrcode-prompt-contract', + 'astrcode-runtime-contract', + 'astrcode-tool-contract', + ]), }, { - id: 'R008', - description: 'plugin-host 只承载统一插件宿主，只允许依赖 core、protocol、support', + id: 'R011', + description: 'plugin-host 只承载统一插件宿主，只允许依赖 core、protocol、governance-contract、support', source: 'astrcode-plugin-host', - allowedExact: new Set(['astrcode-core', 'astrcode-protocol', 'astrcode-support']), + allowedExact: new Set([ + 'astrcode-core', + 'astrcode-governance-contract', + 'astrcode-protocol', + 'astrcode-support', + ]), }, { - id: 'R009', - description: 'host-session 只承载 session owner 逻辑，只允许依赖 core、support、agent-runtime、plugin-host', + id: 'R012', + description: 'host-session 只承载 session owner 逻辑，只允许依赖 core、support、agent-runtime、plugin-host、governance-contract、prompt-contract、runtime-contract、tool-contract', source: 'astrcode-host-session', allowedExact: new Set([ 'astrcode-core', 'astrcode-support', 'astrcode-agent-runtime', 'astrcode-plugin-host', + 'astrcode-governance-contract', + 'astrcode-prompt-contract', + 'astrcode-runtime-contract', + 'astrcode-tool-contract', ]), }, ]; @@ -152,15 +180,32 @@ function main() { const findings = []; for (const rule of rules) { - if (!packageNames.has(rule.source)) { - continue; - } const violations = checkRule(rule, edges, packageNames); if (violations.length > 0) { findings.push({ rule, violations: violations.sort() }); } } + for (const source of packageNames) { + if (!source.startsWith('astrcode-adapter-')) { + continue; + } + const deps = [...(edges.get(source) ?? [])].filter((name) => isWorkspaceInternal(name, packageNames)); + const violations = deps.filter((target) => + target.startsWith('astrcode-adapter-') && target !== 'astrcode-adapter-storage', + ); + if (violations.length > 0) { + findings.push({ + rule: { + id: 'R013', + description: 'adapter-* 之间禁止横向依赖', + source, + }, + violations: violations.sort(), + }); + } + } + if (findings.length === 0) { console.log('crate boundary check passed.'); return; diff --git a/src-tauri/src/desktop_frontend_mode.rs b/src-tauri/src/desktop_frontend_mode.rs index 326277b6..6e87f590 100644 --- a/src-tauri/src/desktop_frontend_mode.rs +++ b/src-tauri/src/desktop_frontend_mode.rs @@ -1,3 +1,5 @@ +#![cfg_attr(not(test), allow(dead_code))] + #[allow(dead_code)] pub const FRONTEND_MODE_ENV: &str = "ASTRCODE_DESKTOP_FRONTEND_MODE"; pub const TAURI_CLI_VERBOSITY_ENV: &str = "TAURI_CLI_VERBOSITY"; From 52385e980cb22bdc59663b2e236f889e39450dc9 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Fri, 24 Apr 2026 22:21:55 +0800 Subject: [PATCH 06/10] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20?= =?UTF-8?q?=E6=B8=85=E7=90=86=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A=EF=BC=8C?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=E4=B8=8D=E5=BF=85=E8=A6=81=E7=9A=84=20`#[doc?= =?UTF-8?q?(hidden)]`=20=E6=A0=87=E6=B3=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- crates/core/src/lib.rs | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 8283a556..67aec9ab 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -1,12 +1,9 @@ //! Astrcode 共享语义层。 //! //! 承载跨 crate 共享的稳定值对象、事件数据模型和最小基础设施。 -//! 工具 trait、LLM 契约、runtime 边界、prompt 契约、治理策略分别由 -//! `*-contract` crate 持有；此处只保留事件存储、配置数据、hook 事件键、 -//! agent 协作模型等真正跨 owner 共享的语义。 -//! -//! 以下模块仍有 `#[doc(hidden)]` 标注，表示已迁移到对应 contract crate， -//! 仅作为过渡桥保留：`prompt`、`tool`。 +//! 工具 trait、LLM 契约、runtime 边界、治理策略分别由 `*-contract` crate 持有； +//! TODO:prompt cache 诊断类型因被 durable storage 事件引用，暂留于此直到 +//! storage 事件迁移到独立薄类型。 pub mod action; pub mod agent; @@ -29,7 +26,6 @@ pub mod observability; pub mod policy; pub mod ports; pub mod project; -#[doc(hidden)] pub mod prompt; pub mod registry; pub mod runtime; @@ -41,7 +37,6 @@ pub mod support; #[cfg(feature = "test-support")] pub mod test_support; mod time; -#[doc(hidden)] pub mod tool; pub mod tool_result_persist; From 4988155284d1f74d32fe7fa2c2607f3d353574f0 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Sat, 25 Apr 2026 00:15:03 +0800 Subject: [PATCH 07/10] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(tools):=20?= =?UTF-8?q?=E7=B2=BE=E7=AE=80=E5=B7=A5=E5=85=B7=E8=A1=A8=E9=9D=A2=EF=BC=8C?= =?UTF-8?q?=E4=BC=98=E5=8C=96=20KV=20=E7=BC=93=E5=AD=98=E7=A8=B3=E5=AE=9A?= =?UTF-8?q?=E6=80=A7=E4=B8=8E=E6=8F=90=E7=A4=BA=E8=AF=8D=E6=95=88=E7=8E=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除 listDir 工具（由 shell ls/dir 替代），简化 editFile（移除批量 edits 数组）， 简化 shell（移除 shell override 参数），增强 grep（新增 literal 模式、参数别名归一化、 默认输出改为 files_with_matches），增强 readFile（charOffset 分页支持持久化结果）。 capability_prompt 不再为 plan 工具生成详细指南块，仅保留摘要行， enterPlanMode 摘要引导 LLM 在复杂任务时主动使用。 tool-summary 块增加工具选择导航，移除逐工具 caveat 拼接。 OpenAI provider 新增 builtin_tool_rank 确定序排列工具 schema， 避免跨 turn 工具顺序抖动导致 KV 缓存失效。 --- README.md | 3 +- .../src/builtin_agents/explore.md | 4 +- .../src/builtin_agents/reviewer.md | 139 +----- crates/adapter-llm/src/openai.rs | 67 ++- .../src/contributors/capability_prompt.rs | 90 ++-- .../src/contributors/workflow_examples.rs | 5 +- .../adapter-skills/src/builtin_skills/mod.rs | 2 +- .../src/builtin_tools/apply_patch.rs | 23 +- .../src/builtin_tools/edit_file.rs | 327 +++---------- .../src/builtin_tools/enter_plan_mode.rs | 8 +- .../src/builtin_tools/exit_plan_mode.rs | 13 +- .../src/builtin_tools/find_files.rs | 46 +- .../adapter-tools/src/builtin_tools/grep.rs | 315 ++++++++++-- .../src/builtin_tools/list_dir.rs | 462 ------------------ crates/adapter-tools/src/builtin_tools/mod.rs | 2 - .../src/builtin_tools/read_file.rs | 245 +++++++--- .../adapter-tools/src/builtin_tools/shell.rs | 146 +++--- .../src/builtin_tools/upsert_session_plan.rs | 11 +- .../src/builtin_tools/write_file.rs | 14 +- crates/adapter-tools/src/lib.rs | 2 +- crates/eval/tests/core_end_to_end.rs | 19 +- crates/server/src/bootstrap/capabilities.rs | 9 +- .../advanced/empty-dir-safe-response.yaml | 3 +- .../advanced/listdir-read-edit-status.yaml | 5 +- tool_demo_example.md | 4 +- 25 files changed, 754 insertions(+), 1210 deletions(-) delete mode 100644 crates/adapter-tools/src/builtin_tools/list_dir.rs diff --git a/README.md b/README.md index 6883eab7..10fc139a 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,9 @@ | `writeFile` | 写入或创建文件，并返回结构化 diff metadata | | `editFile` | 精确替换文件内容（唯一匹配验证），并返回结构化 diff metadata | | `apply_patch` | 应用 unified diff 格式的多文件批量变更 | -| `listDir` | 列出目录内容 | | `findFiles` | Glob 模式文件搜索 | | `grep` | 正则表达式内容搜索 | -| `shell` | 执行 Shell 命令，stdout/stderr 以流式事件增量展示 | +| `shell` | 查看目录或执行 Shell 命令，stdout/stderr 以流式事件增量展示 | | `tool_search` | 搜索可用工具 | | `spawn` | 创建子 Agent | | `send` | 向 Agent 发送消息 | diff --git a/crates/adapter-agents/src/builtin_agents/explore.md b/crates/adapter-agents/src/builtin_agents/explore.md index ffb22cf6..71fd0e9e 100644 --- a/crates/adapter-agents/src/builtin_agents/explore.md +++ b/crates/adapter-agents/src/builtin_agents/explore.md @@ -1,7 +1,7 @@ --- name: explore description: 快速检索和阅读代码。 -tools: ["readFile", "listDir", "findFiles", "grep"] +tools: ["readFile", "findFiles", "grep", "shell"] --- You are an exploration agent specialized in rapid codebase analysis and answering questions efficiently. @@ -31,4 +31,4 @@ Report findings directly as a message. Include: - Analogous existing features that serve as implementation templates - Clear answers to what was asked, not comprehensive overviews -Remember: Your goal is searching efficiently through MAXIMUM PARALLELISM to report concise and clear answers. \ No newline at end of file +Remember: Your goal is searching efficiently through MAXIMUM PARALLELISM to report concise and clear answers. diff --git a/crates/adapter-agents/src/builtin_agents/reviewer.md b/crates/adapter-agents/src/builtin_agents/reviewer.md index 4d09cd44..1ffd4bcf 100644 --- a/crates/adapter-agents/src/builtin_agents/reviewer.md +++ b/crates/adapter-agents/src/builtin_agents/reviewer.md @@ -1,6 +1,6 @@ --- name: "reviewer" -description: "Use this agent when code review is needed—after meaningful code changes, before commit/PR, or when explicitly asked. Performs focused multi-perspective review across security, correctness, tests, and architecture. Use proactively after significant changes; prefer real issues over noisy advice.\\n\\nExamples:\\n\\n\\nContext: User has just written a new API endpoint with database operations.\\nuser: \"I just added a new user registration endpoint\"\\nassistant: \"I've implemented the registration endpoint. Now let me use the code-review agent to check for security, correctness, and test coverage before you commit.\"\\n\\nSince significant code was written involving database operations and user input, use the code-review agent to perform a thorough multi-perspective review.\\n\\n\\n\\n\\nContext: User has made changes to multiple files and is preparing to commit.\\nuser: \"I'm ready to commit these changes to the authentication module\"\\nassistant: \"Before you commit, let me launch the code-review agent to review the authentication changes for security vulnerabilities and consistency issues.\"\\n\\nSince the user is about to commit changes to a security-critical module, proactively use the code-review agent to catch issues before they enter the codebase.\\n\\n\\n\\n\\nContext: User explicitly requests a review.\\nuser: \"Can you review my latest changes?\"\\nassistant: \"I'll use the code-review agent to perform a comprehensive review of your recent changes.\"\\n\\nSince the user explicitly asked for a code review, use the code-review agent to analyze the changes.\\n\\n\\n\\n\\nContext: User has refactored a core module affecting multiple components.\\nuser: \"I refactored the data layer to use a new query builder\"\\nassistant: \"The data layer refactor is complete. Let me use the code-review agent to verify the changes haven't introduced issues and that the architecture remains consistent.\"\\n\\nSince a core module was refactored affecting multiple components, use the code-review agent to check for cross-layer inconsistencies and test coverage gaps.\\n\\n" +description: "Code review agent for security, correctness, tests, and architecture. Trigger: after significant code changes, before commit/PR, or when user asks for review. Prefer real issues over noise.\\n\\nExamples:\\n\\n\\nuser: \\\"I just added a new user registration endpoint\\\"\\nassistant: \\\"Let me use the code-review agent to check for security, correctness, and test coverage before you commit.\\\"\\nSignificant code involving DB and user input — trigger review.\\n\\n\\n\\nuser: \\\"Can you review my latest changes?\\\"\\nassistant: \\\"I'll use the code-review agent for a comprehensive review.\\\"\\nUser explicitly requested review — trigger.\\n\\n\\n\\nuser: \\\"I'm ready to commit these changes\\\"\\nassistant: \\\"Before committing, let me run the code-review agent on these changes.\\\"\\nUser about to commit — proactively trigger review.\\n" --- You are an expert code reviewer with deep expertise in software security, code quality, testing practices, and system architecture. You have extensive experience across multiple programming languages and frameworks. Your reputation is built on surfacing genuine, actionable issues—not generating filler advice that wastes developers' time. @@ -193,139 +193,4 @@ After completing the review, inform the user: 3. Whether the code is clear to merge 4. Location of the detailed report -Remember: Quality over quantity. One real security vulnerability is worth more than twenty style suggestions. Your job is to protect the codebase, not to appear busy. - -# Persistent Agent Memory - -You have a persistent, file-based memory system at `C:\Users\18794\.claude\agent-memory\code-review\`. This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence). - -You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you. - -If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry. - -## Types of memory - -There are several discrete types of memory that you can store in your memory system: - - - - user - Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together. - When you learn any details about the user's role, preferences, responsibilities, or knowledge - When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have. - - user: I'm a data scientist investigating what logging we have in place - assistant: [saves user memory: user is a data scientist, currently focused on observability/logging] - - user: I've been writing Go for ten years but this is my first time touching the React side of this repo - assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues] - - - - feedback - Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious. - Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Include *why* so you can judge edge cases later. - Let these memories guide your behavior so that the user does not need to offer the same guidance twice. - Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule. - - user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed - assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration] - - user: stop summarizing what you just did at the end of every response, I can read the diff - assistant: [saves feedback memory: this user wants terse responses with no trailing summaries] - - user: yeah the single bundled PR was the right call here, splitting this one would've just been churn - assistant: [saves feedback memory: for refactors in this area, user prefers one bundled PR over many small ones. Confirmed after I chose this approach — a validated judgment call, not a correction] - - - - project - Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory. - When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes. - Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions. - Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing. - - user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch - assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date] - - user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements - assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics] - - - - reference - Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory. - When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel. - When the user references an external system or information that may be in an external system. - - user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs - assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"] - - user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone - assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code] - - - - -## What NOT to save in memory - -- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state. -- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative. -- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context. -- Anything already documented in CLAUDE.md files. -- Ephemeral task details: in-progress work, temporary state, current conversation context. - -These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping. - -## How to save memories - -Saving a memory is a two-step process: - -**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format: - -```markdown ---- -name: {{memory name}} -description: {{one-line description — used to decide relevance in future conversations, so be specific}} -type: {{user, feedback, project, reference}} ---- - -{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}} -``` - -**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — each entry should be one line, under ~150 characters: `- [Title](file.md) — one-line hook`. It has no frontmatter. Never write memory content directly into `MEMORY.md`. - -- `MEMORY.md` is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise -- Keep the name, description, and type fields in memory files up-to-date with the content -- Organize memory semantically by topic, not chronologically -- Update or remove memories that turn out to be wrong or outdated -- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one. - -## When to access memories -- When memories seem relevant, or the user references prior-conversation work. -- You MUST access memory when the user explicitly asks you to check, recall, or remember. -- If the user says to *ignore* or *not use* memory: proceed as if MEMORY.md were empty. Do not apply remembered facts, cite, compare against, or mention memory content. -- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory rather than acting on it. - -## Before recommending from memory - -A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it: - -- If the memory names a file path: check the file exists. -- If the memory names a function or flag: grep for it. -- If the user is about to act on your recommendation (not just asking about history), verify first. - -"The memory says X exists" is not the same as "X exists now." - -A memory that summarizes repo state (activity logs, architecture snapshots) is frozen in time. If the user asks about *recent* or *current* state, prefer `git log` or reading the code over recalling the snapshot. - -## Memory and other forms of persistence -Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation. -- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory. -- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations. - -- Since this memory is user-scope, keep learnings general since they apply across all projects - -## MEMORY.md - -Your MEMORY.md is currently empty. When you save new memories, they will appear here. +Remember: Quality over quantity. One real security vulnerability is worth more than twenty style suggestions. Your job is to protect the codebase, not to appear busy. \ No newline at end of file diff --git a/crates/adapter-llm/src/openai.rs b/crates/adapter-llm/src/openai.rs index 69231029..d136b88c 100644 --- a/crates/adapter-llm/src/openai.rs +++ b/crates/adapter-llm/src/openai.rs @@ -659,13 +659,42 @@ fn build_prompt_cache_key( fn order_tools_for_cache(tools: &[ToolDefinition]) -> Vec<&ToolDefinition> { let mut ordered: Vec<&ToolDefinition> = tools.iter().collect(); ordered.sort_by(|left, right| { - let left_key = (left.name.starts_with("mcp__"), left.name.as_str()); - let right_key = (right.name.starts_with("mcp__"), right.name.as_str()); + let left_key = ( + builtin_tool_rank(left.name.as_str()).unwrap_or(u8::MAX), + left.name.as_str(), + ); + let right_key = ( + builtin_tool_rank(right.name.as_str()).unwrap_or(u8::MAX), + right.name.as_str(), + ); left_key.cmp(&right_key) }); ordered } +fn builtin_tool_rank(name: &str) -> Option { + match name { + "readFile" => Some(0), + "findFiles" => Some(1), + "grep" => Some(2), + "shell" => Some(3), + "editFile" => Some(4), + "writeFile" => Some(5), + "apply_patch" => Some(6), + "enterPlanMode" => Some(7), + "exitPlanMode" => Some(8), + "upsertSessionPlan" => Some(9), + "taskWrite" => Some(10), + "tool_search" => Some(11), + "Skill" => Some(12), + "spawn" => Some(13), + "send" => Some(14), + "observe" => Some(15), + "close" => Some(16), + _ => None, + } +} + #[async_trait] impl LlmProvider for OpenAiProvider { fn supports_cache_metrics(&self) -> bool { @@ -1598,25 +1627,35 @@ mod tests { }]; let first_tools = vec![ ToolDefinition { - name: "mcp__search".to_string(), - description: "Search".to_string(), + name: "zzz_plugin_search".to_string(), + description: "Plugin Search".to_string(), parameters: json!({"type":"object"}), }, ToolDefinition { - name: "read_file".to_string(), + name: "readFile".to_string(), description: "Read".to_string(), parameters: json!({"type":"object"}), }, + ToolDefinition { + name: "mcp__search".to_string(), + description: "MCP Search".to_string(), + parameters: json!({"type":"object"}), + }, ]; let second_tools = vec![ ToolDefinition { - name: "read_file".to_string(), - description: "Read".to_string(), + name: "mcp__search".to_string(), + description: "MCP Search".to_string(), parameters: json!({"type":"object"}), }, ToolDefinition { - name: "mcp__search".to_string(), - description: "Search".to_string(), + name: "zzz_plugin_search".to_string(), + description: "Plugin Search".to_string(), + parameters: json!({"type":"object"}), + }, + ToolDefinition { + name: "readFile".to_string(), + description: "Read".to_string(), parameters: json!({"type":"object"}), }, ]; @@ -1655,8 +1694,14 @@ mod tests { .map(|tool| tool.function.name.as_str()) .collect(); - assert_eq!(first_names, vec!["read_file", "mcp__search"]); - assert_eq!(second_names, vec!["read_file", "mcp__search"]); + assert_eq!( + first_names, + vec!["readFile", "mcp__search", "zzz_plugin_search"] + ); + assert_eq!( + second_names, + vec!["readFile", "mcp__search", "zzz_plugin_search"] + ); assert_eq!(first.prompt_cache_key, second.prompt_cache_key); } diff --git a/crates/adapter-prompt/src/contributors/capability_prompt.rs b/crates/adapter-prompt/src/contributors/capability_prompt.rs index e3763e52..c7c46c09 100644 --- a/crates/adapter-prompt/src/contributors/capability_prompt.rs +++ b/crates/adapter-prompt/src/contributors/capability_prompt.rs @@ -6,7 +6,7 @@ //! # 设计原则 //! //! - 外部 MCP / plugin 工具仅保留粗略摘要，不展开详细指南 -//! - 非外部工具保持详细指南可见，不再因为工具总数被整体折叠 +//! - 内置工具默认进入稳定摘要，只有工具发现和协作类工具展开详细指南 //! - 只负责工具指南；外部 `PromptDeclaration` 由独立 contributor 承接 use astrcode_core::CapabilitySpec; @@ -24,7 +24,7 @@ impl PromptContributor for CapabilityPromptContributor { } fn cache_version(&self) -> u64 { - 6 + 7 } fn cache_fingerprint(&self, ctx: &PromptContext) -> String { @@ -129,11 +129,10 @@ fn is_external_tool(spec: &CapabilitySpec) -> bool { fn tool_summary_rank(name: &str) -> u8 { match name { "readFile" => 0, - "listDir" => 1, - "findFiles" => 2, - "grep" => 3, + "findFiles" => 1, + "grep" => 2, + "shell" => 3, "tool_search" => 4, - "shell" => 5, "Skill" => 6, "apply_patch" => 90, "editFile" => 91, @@ -143,9 +142,8 @@ fn tool_summary_rank(name: &str) -> u8 { } fn should_render_detailed_tool_guide(guide: &ToolGuideEntry) -> bool { - guide.prompt.always_include - || is_agent_collaboration_tool(guide) - || !is_external_tool(&guide.spec) + is_agent_collaboration_tool(guide) + || matches!(guide.spec.name.as_str(), "tool_search" | "Skill") } fn is_agent_collaboration_tool(guide: &ToolGuideEntry) -> bool { @@ -164,7 +162,10 @@ fn build_tool_summary_block( "Use the narrowest tool that can answer the request. Prefer read-only inspection before \ mutation. All paths must stay inside the working directory. When a tool returns a \ persisted-result reference for large output, keep the reference in context and inspect \ - it with `readFile` chunks instead of asking the tool to inline the whole result again.", + it with `readFile` chunks instead of asking the tool to inline the whole result again. \ + Use `findFiles` for file names and paths, `grep` for content search, `shell` for \ + directory inspection or commands, `readFile` for known files, and \ + `editFile`/`writeFile`/`apply_patch` for file changes.", ); if !tool_guides.is_empty() { @@ -173,15 +174,9 @@ fn build_tool_summary_block( .iter() .filter(|guide| !is_agent_collaboration_tool(guide)) { - let caveat = guide - .prompt - .caveats - .first() - .map(|caveat| format!(" Caveat: {caveat}")) - .unwrap_or_default(); content.push_str(&format!( - "\n- `{}`: {}{}", - guide.spec.name, guide.prompt.summary, caveat + "\n- `{}`: {}", + guide.spec.name, guide.prompt.summary )); } @@ -196,15 +191,9 @@ fn build_tool_summary_block( calls.", ); for guide in collaboration_guides { - let caveat = guide - .prompt - .caveats - .first() - .map(|caveat| format!(" Caveat: {caveat}")) - .unwrap_or_default(); content.push_str(&format!( - "\n- `{}`: {}{}", - guide.spec.name, guide.prompt.summary, caveat + "\n- `{}`: {}", + guide.spec.name, guide.prompt.summary )); } } @@ -365,7 +354,7 @@ mod tests { } #[tokio::test] - async fn contributes_tool_summary_and_detailed_guides() { + async fn contributes_tool_summary_without_default_core_guides() { let contribution = CapabilityPromptContributor.contribute(&context()).await; assert!( @@ -375,15 +364,15 @@ mod tests { .any(|block| block.id == "tool-summary" && block.kind == BlockKind::ToolGuide) ); assert!( - contribution + !contribution .blocks .iter() - .any(|block| block.id == "tool-guide-grep" && block.kind == BlockKind::ToolGuide) + .any(|block| block.id == "tool-guide-grep") ); } #[tokio::test] - async fn large_tool_surfaces_keep_internal_tool_guides_visible() { + async fn large_tool_surfaces_keep_core_tools_in_summary_only() { let _guard = TestEnvGuard::new(); let mut ctx = context(); ctx.capability_specs = vec![ @@ -398,7 +387,7 @@ mod tests { for name in ["alpha", "beta", "gamma", "delta", "epsilon"] { assert!( - contribution + !contribution .blocks .iter() .any(|block| block.id == format!("tool-guide-{name}")) @@ -406,6 +395,45 @@ mod tests { } } + #[tokio::test] + async fn only_discovery_and_collaboration_tools_get_detailed_guides() { + let _guard = TestEnvGuard::new(); + let mut ctx = context(); + ctx.capability_specs = vec![ + tool_spec("readFile", false), + tool_spec("tool_search", false), + tool_spec("upsertSessionPlan", false), + tool_spec("Skill", false), + ]; + + let contribution = CapabilityPromptContributor.contribute(&ctx).await; + + assert!( + !contribution + .blocks + .iter() + .any(|block| block.id == "tool-guide-readFile") + ); + assert!( + !contribution + .blocks + .iter() + .any(|block| block.id == "tool-guide-upsertSessionPlan") + ); + assert!( + contribution + .blocks + .iter() + .any(|block| block.id == "tool-guide-tool_search") + ); + assert!( + contribution + .blocks + .iter() + .any(|block| block.id == "tool-guide-Skill") + ); + } + #[tokio::test] async fn tool_summary_places_builtin_before_external_and_adds_workflow() { let _guard = TestEnvGuard::new(); diff --git a/crates/adapter-prompt/src/contributors/workflow_examples.rs b/crates/adapter-prompt/src/contributors/workflow_examples.rs index ab21673e..94b7173f 100644 --- a/crates/adapter-prompt/src/contributors/workflow_examples.rs +++ b/crates/adapter-prompt/src/contributors/workflow_examples.rs @@ -27,7 +27,8 @@ impl PromptContributor for WorkflowExamplesContributor { "Few Shot User", "Before changing code, inspect the relevant files and gather context first. If \ you only know a filename pattern or glob, use `findFiles`. Use `grep` only when \ - you have both a content pattern and a search path.", + you have both a content pattern and a search path. Use `shell` for directory \ + inspection commands.", RenderTarget::PrependUser, ) .with_condition(BlockCondition::FirstStepOnly) @@ -39,7 +40,7 @@ impl PromptContributor for WorkflowExamplesContributor { "I will inspect the relevant files and gather context before making changes. I \ will use `findFiles` to discover candidate paths, then use `grep` with both \ `pattern` and `path` when I need content search inside those files or \ - directories.", + directories. I will use `shell` for directory inspection when needed.", RenderTarget::PrependAssistant, ) .with_condition(BlockCondition::FirstStepOnly) diff --git a/crates/adapter-skills/src/builtin_skills/mod.rs b/crates/adapter-skills/src/builtin_skills/mod.rs index 5a726c1e..9d7113b1 100644 --- a/crates/adapter-skills/src/builtin_skills/mod.rs +++ b/crates/adapter-skills/src/builtin_skills/mod.rs @@ -87,7 +87,7 @@ fn bundled_skill_allowed_tools(skill_id: &str) -> &'static [&'static str] { match skill_id { // The skill contract stays Claude-compatible in markdown, while runtime // records the actual tool boundary here for the Skill capability output. - "git-commit" => &["shell", "readFile", "grep", "findFiles", "listDir"], + "git-commit" => &["shell", "readFile", "grep", "findFiles"], _ => &[], } } diff --git a/crates/adapter-tools/src/builtin_tools/apply_patch.rs b/crates/adapter-tools/src/builtin_tools/apply_patch.rs index c681564c..4ab4d747 100644 --- a/crates/adapter-tools/src/builtin_tools/apply_patch.rs +++ b/crates/adapter-tools/src/builtin_tools/apply_patch.rs @@ -735,29 +735,14 @@ impl Tool for ApplyPatchTool { .prompt( ToolPromptMetadata::new( "Apply a unified diff patch across one or more files.", - "Use `apply_patch` for coordinated multi-file changes using standard unified \ - diff format (like `git diff` output). Prefer this over `editFile` when you \ - need to change multiple regions, touch multiple files, or create/delete \ - files.", + "Use `apply_patch` for coordinated multi-file changes, multiple hunks, or \ + file creation/deletion using unified diff format.", ) .caveat( - "Hunk context lines must match the current file exactly — provide at least 3 \ - unchanged context lines around each change for reliable matching. If a hunk \ - fails, `readFile` the target region and adjust.", + "Hunk context must match exactly. If a hunk fails, `readFile` the target \ + region and adjust.", ) .caveat("Use '--- /dev/null' to create new files, '+++ /dev/null' to delete.") - .example( - "Replace in one file: { patch: \"--- a/src/lib.rs\\n+++ b/src/lib.rs\\n@@ \ - -1,3 +1,3 @@\\n fn x()\\n- old()\\n+ new()\\n\" }", - ) - .example( - "Create a file: { patch: \"--- /dev/null\\n+++ b/src/new.rs\\n@@ -0,0 +1,2 \ - @@\\n+pub fn new_file() {}\\n\" }", - ) - .example( - "Delete a file: { patch: \"--- a/src/old.rs\\n+++ /dev/null\\n@@ -1,2 +0,0 \ - @@\\n-old line 1\\n-old line 2\\n\" }", - ) .prompt_tag("filesystem") .always_include(true), ) diff --git a/crates/adapter-tools/src/builtin_tools/edit_file.rs b/crates/adapter-tools/src/builtin_tools/edit_file.rs index ab919600..e1df5da4 100644 --- a/crates/adapter-tools/src/builtin_tools/edit_file.rs +++ b/crates/adapter-tools/src/builtin_tools/edit_file.rs @@ -8,11 +8,6 @@ //! - 支持重叠匹配检测（如在 `"ababa"` 中搜索 `"aba"` 会找到两个位置） //! - 编辑前/后均检查取消标记，避免长文件操作无法中断 //! -//! ## 批量编辑 -//! -//! 支持通过 `edits` 数组一次执行多个替换操作，按顺序应用。 -//! 每个 edit 必须满足唯一匹配要求。 -//! //! ## 与 writeFile 的区别 //! //! `writeFile` 用于完全覆盖，`editFile` 用于窄范围修改。 @@ -54,30 +49,17 @@ const MAX_EDIT_FILE_SIZE: u64 = 1024 * 1024 * 1024; // 1 GiB #[derive(Default)] pub struct EditFileTool; -/// 单个编辑操作。 -#[derive(Debug, Deserialize, Clone)] -#[serde(rename_all = "camelCase")] -struct EditOperation { - old_text: String, - new_text: String, -} - #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] struct EditFileArgs { path: PathBuf, - /// 旧字符串（单个编辑时使用）。 - #[serde(default)] - old_str: Option, - /// 新字符串（单个编辑时使用）。 - #[serde(default)] - new_str: Option, + /// 旧字符串。 + old_str: String, + /// 新字符串。 + new_str: String, /// 设为 true 时替换所有匹配（而非要求唯一匹配），0 次匹配仍报错。 #[serde(default)] replace_all: bool, - /// 批量编辑：多个 oldText/newText 对，按顺序应用。 - #[serde(default)] - edits: Option>, } /// 将智能引号规范化为 ASCII 引号。 @@ -161,21 +143,9 @@ impl Tool for EditFileTool { "type": "boolean", "description": "If true, replaces all occurrences. If false (default), \ requires an exact single match." - }, - "edits": { - "type": "array", - "description": "Batch edits: array of {oldText, newText} pairs, applied in order", - "items": { - "type": "object", - "properties": { - "oldText": { "type": "string" }, - "newText": { "type": "string" } - }, - "required": ["oldText", "newText"] - } } }, - "required": ["path"], + "required": ["path", "oldStr", "newStr"], "additionalProperties": false }), } @@ -188,27 +158,13 @@ impl Tool for EditFileTool { .side_effect(SideEffect::Local) .prompt( ToolPromptMetadata::new( - "Apply a narrow, safety-checked string replacement inside an existing file.", - "Use `editFile` when you know the exact old text and want a minimal change. \ - It rejects ambiguous replacements, which makes it safer than rewriting a \ - whole file for small edits. Prefer `apply_patch` instead when you need \ - multi-file edits, multiple distant changes, or file creation/deletion. If \ - the file was changed after the last `readFile`, `editFile` will stop and ask \ - for a fresh reread first.", + "Apply a narrow exact string replacement inside an existing file.", + "Use `editFile` for small edits when you know the exact old text. Prefer \ + `apply_patch` for multi-file changes, distant hunks, or create/delete work.", ) .caveat( "`oldStr` must match exactly once — including whitespace, newlines, trailing \ - spaces, tabs, and line endings (`\\r\\n` vs `\\n`). If rejected, `readFile` \ - the region first.", - ) - .caveat( - "When this session has already observed the file, `editFile` also checks that \ - the file has not changed on disk since that observation. If it did, call \ - `readFile` again before editing.", - ) - .example( - "Change one function body: { path: \"src/lib.rs\", oldStr: \"fn a() { old \ - }\", newStr: \"fn a() { new }\" }", + spaces, tabs, and line endings. If rejected, `readFile` the region first.", ) .prompt_tag("filesystem") .always_include(true), @@ -226,54 +182,13 @@ impl Tool for EditFileTool { let args: EditFileArgs = serde_json::from_value(args) .map_err(|e| AstrError::parse("invalid args for editFile", e))?; - // 验证参数：要么提供 oldStr/newStr，要么提供 edits - let edits = match (&args.old_str, &args.new_str, &args.edits) { - (Some(old_str), Some(new_str), None) => { - if old_str.is_empty() { - return Err(AstrError::Validation("oldStr cannot be empty".to_string())); - } - vec![EditOperation { - old_text: old_str.clone(), - new_text: new_str.clone(), - }] - }, - (None, None, Some(edits)) => { - if edits.is_empty() { - return Err(AstrError::Validation( - "edits array cannot be empty".to_string(), - )); - } - for (i, edit) in edits.iter().enumerate() { - if edit.old_text.is_empty() { - return Err(AstrError::Validation(format!( - "edits[{}].oldText cannot be empty", - i - ))); - } - } - edits.clone() - }, - (Some(_), Some(_), Some(_)) => { - return Err(AstrError::Validation( - "cannot specify both oldStr/newStr and edits - use one or the other" - .to_string(), - )); - }, - _ => { - return Err(AstrError::Validation( - "must specify either oldStr/newStr or edits array".to_string(), - )); - }, - }; + if args.old_str.is_empty() { + return Err(AstrError::Validation("oldStr cannot be empty".to_string())); + } // 引号规范化：将智能引号转换为 ASCII 引号 - let edits: Vec = edits - .into_iter() - .map(|edit| EditOperation { - old_text: normalize_quotes(&edit.old_text), - new_text: normalize_quotes(&edit.new_text), - }) - .collect(); + let old_text = normalize_quotes(&args.old_str); + let new_text = normalize_quotes(&args.new_str); let started_at = Instant::now(); let path = resolve_path(ctx, &args.path)?; @@ -362,61 +277,48 @@ impl Tool for EditFileTool { let original_content = read_utf8_file(&path).await?; check_cancel(ctx.cancel())?; - let mut content = original_content.clone(); - let mut total_edits = 0usize; - - for edit in &edits { - check_cancel(ctx.cancel())?; - - content = if args.replace_all { - // replace_all 模式：替换所有出现 - if !content.contains(&edit.old_text) { + let content = if args.replace_all { + if !original_content.contains(&old_text) { + return make_edit_error_result( + &tool_call_id, + &format!("oldStr '{old_text}' not found in file"), + &path, + started_at, + ); + } + original_content.replace(&old_text, &new_text) + } else { + let match_start = match find_unique_occurrence(&original_content, &old_text) { + Some(Ok(pos)) => pos, + Some(Err(_)) => { return make_edit_error_result( &tool_call_id, - &format!("oldText '{}' not found in file", edit.old_text), + &format!( + "oldStr '{old_text}' appears multiple times, must be unique to edit \ + safely" + ), &path, started_at, ); - } - total_edits += content.matches(&edit.old_text).count(); - content.replace(&edit.old_text, &edit.new_text) - } else { - // 唯一匹配模式：必须恰好出现一次 - let match_start = match find_unique_occurrence(&content, &edit.old_text) { - Some(Ok(pos)) => pos, - Some(Err(_)) => { - return make_edit_error_result( - &tool_call_id, - &format!( - "oldText '{}' appears multiple times, must be unique to edit \ - safely", - edit.old_text - ), - &path, - started_at, - ); - }, - None => { - return make_edit_error_result( - &tool_call_id, - &format!("oldText '{}' not found in file", edit.old_text), - &path, - started_at, - ); - }, - }; - - let match_end = match_start + edit.old_text.len(); - let mut replaced = String::with_capacity( - content.len() - edit.old_text.len() + edit.new_text.len(), - ); - replaced.push_str(&content[..match_start]); - replaced.push_str(&edit.new_text); - replaced.push_str(&content[match_end..]); - total_edits += 1; - replaced + }, + None => { + return make_edit_error_result( + &tool_call_id, + &format!("oldStr '{old_text}' not found in file"), + &path, + started_at, + ); + }, }; - } + + let match_end = match_start + old_text.len(); + let mut replaced = + String::with_capacity(original_content.len() - old_text.len() + new_text.len()); + replaced.push_str(&original_content[..match_start]); + replaced.push_str(&new_text); + replaced.push_str(&original_content[match_end..]); + replaced + }; let report = build_text_change_report(&path, "updated", Some(&original_content), &content); check_cancel(ctx.cancel())?; @@ -424,39 +326,23 @@ impl Tool for EditFileTool { // 编辑成功后刷新观察快照，允许同一 session 在未发生外部改动时继续连续 edit。 let observation = remember_file_observation(ctx, &path)?; - let metadata = if edits.len() > 1 { - json!({ - "path": path.to_string_lossy(), - "editsApplied": edits.len(), - "totalReplacements": total_edits, - "contentFingerprint": observation.content_fingerprint, - "modifiedUnixNanos": observation.modified_unix_nanos, - "diff": report.metadata.get("diff").cloned().unwrap_or(json!(null)), - }) - } else { - let mut metadata = report.metadata; - if let Some(object) = metadata.as_object_mut() { - object.insert( - "contentFingerprint".to_string(), - json!(observation.content_fingerprint), - ); - object.insert( - "modifiedUnixNanos".to_string(), - json!(observation.modified_unix_nanos), - ); - } - metadata - }; + let mut metadata = report.metadata; + if let Some(object) = metadata.as_object_mut() { + object.insert( + "contentFingerprint".to_string(), + json!(observation.content_fingerprint), + ); + object.insert( + "modifiedUnixNanos".to_string(), + json!(observation.modified_unix_nanos), + ); + } Ok(ToolExecutionResult { tool_call_id, tool_name: "editFile".to_string(), ok: true, - output: if edits.len() > 1 { - format!("{} ({} edits applied)", report.summary, edits.len()) - } else { - report.summary - }, + output: report.summary, error: None, metadata: Some(metadata), continuation: None, @@ -876,40 +762,6 @@ mod tests { assert_eq!(content, "delta beta omega"); } - #[tokio::test] - async fn edit_file_batch_edits_applied_in_order() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - let file = temp.path().join("code.rs"); - tokio::fs::write(&file, "fn old_name() { old_body }") - .await - .expect("seed write should work"); - let tool = EditFileTool; - - let result = tool - .execute( - "tc-edit-batch".to_string(), - json!({ - "path": file.to_string_lossy(), - "edits": [ - {"oldText": "old_name", "newText": "new_name"}, - {"oldText": "old_body", "newText": "new_body"} - ] - }), - &test_tool_context_for(temp.path()), - ) - .await - .expect("editFile should execute"); - - assert!(result.ok); - let content = tokio::fs::read_to_string(&file) - .await - .expect("file should be readable"); - assert_eq!(content, "fn new_name() { new_body }"); - // 验证 metadata 包含编辑数量 - let meta = result.metadata.expect("metadata should exist"); - assert_eq!(meta["editsApplied"], json!(2)); - } - #[tokio::test] async fn edit_file_allows_relative_path_outside_working_dir() { let parent = tempfile::tempdir().expect("tempdir should be created"); @@ -943,30 +795,6 @@ mod tests { assert_eq!(content, "omega beta"); } - #[tokio::test] - async fn edit_file_batch_edits_rejects_empty_array() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - let file = temp.path().join("hello.txt"); - tokio::fs::write(&file, "hello") - .await - .expect("seed write should work"); - let tool = EditFileTool; - - let result = tool - .execute( - "tc-edit-empty-batch".to_string(), - json!({ - "path": file.to_string_lossy(), - "edits": [] - }), - &test_tool_context_for(temp.path()), - ) - .await; - - assert!(result.is_err()); - assert!(result.unwrap_err().to_string().contains("cannot be empty")); - } - #[tokio::test] async fn edit_file_rejects_canonical_session_plan_targets() { let temp = tempfile::tempdir().expect("tempdir should be created"); @@ -1005,35 +833,4 @@ mod tests { .contains("upsertSessionPlan") ); } - - #[tokio::test] - async fn edit_file_cannot_mix_single_and_batch() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - let file = temp.path().join("hello.txt"); - tokio::fs::write(&file, "hello") - .await - .expect("seed write should work"); - let tool = EditFileTool; - - let result = tool - .execute( - "tc-edit-mixed".to_string(), - json!({ - "path": file.to_string_lossy(), - "oldStr": "hello", - "newStr": "world", - "edits": [{"oldText": "a", "newText": "b"}] - }), - &test_tool_context_for(temp.path()), - ) - .await; - - assert!(result.is_err()); - assert!( - result - .unwrap_err() - .to_string() - .contains("cannot specify both") - ); - } } diff --git a/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs b/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs index 9e229c4f..814ef180 100644 --- a/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs +++ b/crates/adapter-tools/src/builtin_tools/enter_plan_mode.rs @@ -54,13 +54,19 @@ impl Tool for EnterPlanModeTool { .side_effect(SideEffect::Local) .prompt( ToolPromptMetadata::new( - "Switch the current session into plan mode.", + "Enter plan mode for complex or ambiguous tasks. Proactively use when a task \ + spans multiple files, involves significant refactoring, requires analysis \ + before code changes, or when the user asks for a structured plan.", "Use `enterPlanMode` when the task needs an explicit planning phase before \ execution, or when the user directly asks for a plan. After entering, \ inspect the relevant code and tests, keep updating the session plan artifact \ until it is executable, then use `exitPlanMode` to present the finalized \ plan.", ) + .caveat( + "Plan mode restricts you to read-only operations — no file writes, shell \ + commands, or agent delegation. Exit plan mode to resume execution.", + ) .example( "{ reason: \"Need to inspect the codebase and propose a safe refactor plan\" }", ) diff --git a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs index 8bd3173d..038d5af5 100644 --- a/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs +++ b/crates/adapter-tools/src/builtin_tools/exit_plan_mode.rs @@ -57,21 +57,20 @@ impl Tool for ExitPlanModeTool { .side_effect(SideEffect::Local) .prompt( ToolPromptMetadata::new( - "Present the current session plan to the user and leave plan mode.", + "Exit plan mode after the plan is complete and executable. Requires the plan \ + artifact to cover all required sections with concrete actionable items.", "Only use `exitPlanMode` after you have inspected the code, persisted the \ current canonical plan artifact, and refined it until it is executable. If \ the plan is still vague, missing risks, or lacking verification steps, keep \ updating `upsertSessionPlan` instead of exiting.", ) .caveat( - "`exitPlanMode` first checks whether the current plan is executable, then \ - enforces one internal final-review checkpoint before it actually exits. Keep \ - that review out of the plan artifact itself unless the user explicitly asks \ - for it.", + "Enforces a two-gate check: plan readiness (all sections filled, actionable \ + items present) then a final-review checkpoint. Call again after the review \ + to complete the exit.", ) .example("{}") - .prompt_tag("plan") - .always_include(true), + .prompt_tag("plan"), ) } diff --git a/crates/adapter-tools/src/builtin_tools/find_files.rs b/crates/adapter-tools/src/builtin_tools/find_files.rs index 8531089e..e8c68782 100644 --- a/crates/adapter-tools/src/builtin_tools/find_files.rs +++ b/crates/adapter-tools/src/builtin_tools/find_files.rs @@ -7,7 +7,7 @@ //! - 使用 `ignore` crate（ripgrep 同源）进行 .gitignore 感知的文件遍历 //! - 支持 glob 模式匹配，包括 `**` 递归 //! - 路径沙箱检查：glob 模式不能逃逸工作目录 -//! - 默认最多返回 200 条结果，按修改时间排序（最新优先） +//! - 默认最多返回 500 条结果，按修改时间排序（最新优先） //! - 返回结构化 JSON 数组，便于前端渲染 use std::{ @@ -61,16 +61,16 @@ impl Tool for FindFilesTool { fn definition(&self) -> ToolDefinition { ToolDefinition { name: "findFiles".to_string(), - description: "Find files matching a glob pattern. Respects .gitignore by default. Use \ - ** for recursive search. Prefer this over `grep` when you only know \ - file names or globs." + description: "Find candidate file paths matching a glob pattern. This is a Glob-style \ + file path search, not a content search. Respects .gitignore by default \ + and supports ** for recursive search." .to_string(), parameters: json!({ "type": "object", "properties": { "pattern": { "type": "string", - "description": "Glob pattern to match files, e.g. '*.rs', '**/*.ts', '*.{json,toml}'" + "description": "Glob pattern to match file paths, e.g. '*.rs', '**/*.ts', '*.{json,toml}'. Does not search file contents." }, "root": { "type": "string", @@ -79,7 +79,7 @@ impl Tool for FindFilesTool { "maxResults": { "type": "integer", "minimum": 1, - "description": "Maximum number of results to return (default 200)" + "description": "Maximum number of results to return (default 500)" }, "respectGitignore": { "type": "boolean", @@ -105,25 +105,15 @@ impl Tool for FindFilesTool { .compact_clearable(true) .prompt( ToolPromptMetadata::new( - "Find candidate files by glob when you know the filename pattern but not the \ - exact path.", - "Find files by glob pattern under a known search root. Use this before `grep` \ - when you only know a filename, extension, or glob. Supported common glob \ - forms include `**/*.rs` (recursive), `*.toml` (current dir), and \ - `*.{json,toml}` (alternation). When using `root`, the glob pattern is \ - relative to that root. Results are sorted by modification time.", + "Find candidate file paths by Glob-style pattern. Does not search file \ + contents.", + "Use `findFiles` when you know a file name, extension, or path glob but not \ + the exact path. Results are sorted by modification time, newest first. Use \ + `grep` after this when the next step is content search.", ) .caveat( - "Pattern must stay relative to the search root. Truncated at 200 results — \ - narrow with `root` or a more specific glob.", - ) - .example( - "Find all Cargo.toml: { pattern: \"**/Cargo.toml\" }. Limit to ./crates/: { \ - pattern: \"**/*.rs\", root: \"crates\" }", - ) - .example( - "If the next step is content search, first `findFiles { pattern: \"**/*.rs\", \ - root: \"crates\" }`, then call `grep` with both `pattern` and `path`.", + "Pattern matches paths only and is relative to `root` when provided. Narrow \ + with `root` or a more specific glob if results are truncated.", ) .prompt_tag("search") .always_include(true), @@ -633,12 +623,8 @@ mod tests { .prompt .expect("findFiles should expose prompt metadata"); - assert!(prompt.guide.contains("before `grep`")); - assert!( - prompt - .examples - .iter() - .any(|example| example.contains("then call `grep`")) - ); + assert!(prompt.summary.contains("Glob-style")); + assert!(prompt.summary.contains("Does not search file contents")); + assert!(prompt.guide.contains("Use `grep` after this")); } } diff --git a/crates/adapter-tools/src/builtin_tools/grep.rs b/crates/adapter-tools/src/builtin_tools/grep.rs index c9b4ba6f..b7a1ae4d 100644 --- a/crates/adapter-tools/src/builtin_tools/grep.rs +++ b/crates/adapter-tools/src/builtin_tools/grep.rs @@ -29,7 +29,7 @@ use async_trait::async_trait; use log::warn; use regex::RegexBuilder; use serde::{Deserialize, Serialize}; -use serde_json::json; +use serde_json::{Value, json}; use crate::builtin_tools::fs_common::{ check_cancel, maybe_persist_large_tool_result, merge_persisted_tool_output_metadata, @@ -56,6 +56,9 @@ pub struct GrepTool; struct GrepArgs { /// Rust 正则表达式模式，必填。 pattern: String, + /// 按字面量搜索 pattern，等价于 ripgrep 的 -F。 + #[serde(default)] + literal: bool, /// 搜索路径，可选。未提供时使用当前工作目录。 #[serde(default)] path: Option, @@ -92,10 +95,10 @@ struct GrepArgs { #[derive(Debug, Default, Deserialize, Clone, Copy, PartialEq, Eq)] #[serde(rename_all = "snake_case")] enum GrepOutputMode { - /// 返回匹配行内容（默认）。 - #[default] + /// 返回匹配行内容。 Content, - /// 仅返回包含匹配的文件路径列表。 + /// 仅返回包含匹配的文件路径列表（默认）。 + #[default] FilesWithMatches, /// 返回每个文件的匹配计数。 Count, @@ -132,21 +135,104 @@ struct GrepFileCount { count: usize, } +fn normalize_grep_args(mut args: Value) -> Value { + let Some(object) = args.as_object_mut() else { + return args; + }; + + move_alias(object, "output_mode", "outputMode"); + move_alias(object, "type", "fileType"); + move_alias(object, "file_type", "fileType"); + move_alias(object, "head_limit", "maxMatches"); + move_alias(object, "max_matches", "maxMatches"); + move_alias(object, "-A", "afterContext"); + move_alias(object, "-B", "beforeContext"); + move_alias(object, "-i", "caseInsensitive"); + move_alias(object, "case_insensitive", "caseInsensitive"); + move_alias(object, "before_context", "beforeContext"); + move_alias(object, "after_context", "afterContext"); + + if let Some(context) = object.remove("-C").or_else(|| object.remove("context")) { + object + .entry("beforeContext".to_string()) + .or_insert_with(|| context.clone()); + object.entry("afterContext".to_string()).or_insert(context); + } + + normalize_bool_field(object, "literal"); + normalize_bool_field(object, "recursive"); + normalize_bool_field(object, "caseInsensitive"); + normalize_usize_field(object, "maxMatches"); + normalize_usize_field(object, "offset"); + normalize_usize_field(object, "beforeContext"); + normalize_usize_field(object, "afterContext"); + + args +} + +fn move_alias(object: &mut serde_json::Map, from: &str, to: &str) { + if object.contains_key(to) { + object.remove(from); + return; + } + if let Some(value) = object.remove(from) { + object.insert(to.to_string(), value); + } +} + +fn normalize_bool_field(object: &mut serde_json::Map, key: &str) { + let Some(value) = object.get_mut(key) else { + return; + }; + let Some(text) = value.as_str() else { + return; + }; + match text.trim().to_ascii_lowercase().as_str() { + "true" | "1" | "yes" | "on" => *value = Value::Bool(true), + "false" | "0" | "no" | "off" => *value = Value::Bool(false), + _ => {}, + } +} + +fn normalize_usize_field(object: &mut serde_json::Map, key: &str) { + let Some(value) = object.get_mut(key) else { + return; + }; + if value.as_u64() == Some(0) && key == "maxMatches" { + *value = json!(DEFAULT_MAX_MATCHES); + return; + } + let Some(text) = value.as_str() else { + return; + }; + let Ok(parsed) = text.trim().parse::() else { + return; + }; + if key == "maxMatches" && parsed == 0 { + *value = json!(DEFAULT_MAX_MATCHES); + } else { + *value = json!(parsed); + } +} + #[async_trait] impl Tool for GrepTool { fn definition(&self) -> ToolDefinition { ToolDefinition { name: "grep".to_string(), - description: "Search for a regex pattern in files, returning matching lines with file \ - path and line number. `path` defaults to the current working directory \ - when omitted." + description: "Search file contents with regex or literal text. Defaults to returning \ + matching file paths; request content mode for matching lines." .to_string(), parameters: json!({ "type": "object", "properties": { "pattern": { "type": "string", - "description": "Rust regex pattern to search for inside file contents" + "description": "Pattern to search for inside file contents. Interpreted as regex unless `literal` is true." + }, + "literal": { + "type": "boolean", + "description": "Treat `pattern` as exact text instead of regex, equivalent to ripgrep -F. Use this for punctuation-heavy code such as brackets, parentheses, quotes, or operators." }, "path": { "type": "string", @@ -188,7 +274,7 @@ impl Tool for GrepTool { "outputMode": { "type": "string", "enum": ["content", "files_with_matches", "count"], - "description": "Output mode (default: content)" + "description": "Output mode (default: files_with_matches). Use content when you need matching lines." } }, "required": ["pattern"], @@ -206,33 +292,17 @@ impl Tool for GrepTool { .compact_clearable(true) .prompt( ToolPromptMetadata::new( - "Search file contents by regex when you already know the search root. Always \ - provide both `pattern` and `path`.", - "Use `grep` only for content search inside a known file or directory. Always \ - provide both `pattern` and `path`. `glob` and `fileType` only narrow which \ - files are searched inside that path; they never replace `path`. Directory \ - paths recurse by default; set `recursive: false` only when you intentionally \ - want the current directory level only. If you only know a filename pattern \ - or need to discover candidate paths first, use `findFiles`.", - ) - .caveat( - "Pattern uses Rust regex syntax. Narrow scope with `glob`/`fileType`. If \ - `truncated`, use `offset` to paginate. For quick file discovery, prefer \ - `outputMode: \"files_with_matches\"` or use `findFiles` first.", + "Search file contents. Defaults to `files_with_matches`; use `outputMode: \ + \"content\"` for matching lines.", + "Use `grep` for content search inside a known file or directory. Use \ + `outputMode: \"content\"` when matching lines are needed. `glob` and \ + `fileType` only narrow files inside `path`; they do not replace `path`. Use \ + `literal: true` for exact punctuation-heavy text. Use regex when you need \ + regex behavior. If you only know a file path glob, use `findFiles` first.", ) .caveat( - "Each result's `match_text` is the first regex match fragment on that line \ - (or first capture group if the pattern contains groups). The full line is in \ - the `line` field.", - ) - .example( - "Find usages in Rust files: { pattern: \"fn foo\\\\(\", path: \"src\", glob: \ - \"**/*.rs\", outputMode: \"files_with_matches\" }", - ) - .example( - "If you only know the glob first, do not call `grep` yet: first `findFiles { \ - pattern: \"**/*.rs\", root: \"crates\" }`, then `grep { pattern: \ - \"AgentLoop\", path: \"crates\", glob: \"**/*.rs\" }`.", + "Pattern uses Rust regex syntax unless `literal: true`. If regex parsing \ + fails and you meant exact text, retry with `literal: true`.", ) .prompt_tag("search") .always_include(true), @@ -248,19 +318,24 @@ impl Tool for GrepTool { ) -> Result { check_cancel(ctx.cancel())?; - let args: GrepArgs = serde_json::from_value(args) + let args: GrepArgs = serde_json::from_value(normalize_grep_args(args)) .map_err(|e| AstrError::parse(explain_grep_args_error(&e), e))?; let path = match &args.path { Some(p) => resolve_path(ctx, p)?, None => ctx.working_dir().to_path_buf(), }; let started_at = Instant::now(); - let regex = RegexBuilder::new(&args.pattern) + let pattern = if args.literal { + regex::escape(&args.pattern) + } else { + args.pattern.clone() + }; + let regex = RegexBuilder::new(&pattern) .case_insensitive(args.case_insensitive) .build() .map_err(|error| AstrError::ToolError { name: "grep".to_string(), - reason: format!("invalid regex: {}", error), + reason: explain_regex_error(&error), })?; let recursive = args.recursive.unwrap_or(path.is_dir()); @@ -313,6 +388,7 @@ impl Tool for GrepTool { let is_persisted = final_output.persisted.is_some(); let mut metadata = serde_json::Map::new(); metadata.insert("pattern".to_string(), json!(args.pattern)); + metadata.insert("literal".to_string(), json!(args.literal)); metadata.insert("returned".to_string(), json!(result.matched_files.len())); metadata.insert("has_more".to_string(), json!(result.has_more)); metadata.insert( @@ -351,6 +427,7 @@ impl Tool for GrepTool { let is_persisted = final_output.persisted.is_some(); let mut metadata = serde_json::Map::new(); metadata.insert("pattern".to_string(), json!(args.pattern)); + metadata.insert("literal".to_string(), json!(args.literal)); metadata.insert("total_files".to_string(), json!(result.counts.len())); metadata.insert("truncated".to_string(), json!(is_persisted)); metadata.insert("skipped_files".to_string(), json!(result.skipped_files)); @@ -662,6 +739,7 @@ fn build_content_result( let is_persisted = final_output.persisted.is_some(); let mut metadata = serde_json::Map::new(); metadata.insert("pattern".to_string(), json!(args.pattern)); + metadata.insert("literal".to_string(), json!(args.literal)); metadata.insert("returned".to_string(), json!(matches.len())); metadata.insert("has_more".to_string(), json!(has_more)); metadata.insert("truncated".to_string(), json!(has_more || is_persisted)); @@ -698,6 +776,13 @@ fn grep_empty_message(offset: usize, is_empty: bool) -> Option<&'static str> { } } +fn explain_regex_error(error: ®ex::Error) -> String { + format!( + "invalid regex: {error}. If you meant to search exact text, retry with `literal: true`. \ + Use regex only for alternation, wildcards, anchors, or captures." + ) +} + /// 收集候选文件列表。 /// /// 使用 `ignore` crate（ripgrep 同源）进行 .gitignore 感知的文件遍历， @@ -932,7 +1017,8 @@ mod tests { "tc-grep-found".to_string(), json!({ "pattern": "pub fn", - "path": file.to_string_lossy() + "path": file.to_string_lossy(), + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -971,7 +1057,8 @@ mod tests { "tc-grep-recursive-default".to_string(), json!({ "pattern": "nested", - "path": temp.path().to_string_lossy() + "path": temp.path().to_string_lossy(), + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1006,7 +1093,8 @@ mod tests { json!({ "pattern": "nested", "path": temp.path().to_string_lossy(), - "recursive": false + "recursive": false, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1032,7 +1120,8 @@ mod tests { "tc-grep-empty".to_string(), json!({ "pattern": "pub fn", - "path": file.to_string_lossy() + "path": file.to_string_lossy(), + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1069,7 +1158,8 @@ mod tests { json!({ "pattern": "pub fn", "path": file.to_string_lossy(), - "maxMatches": 2 + "maxMatches": 2, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1091,7 +1181,8 @@ mod tests { "pattern": "pub fn", "path": file.to_string_lossy(), "maxMatches": 10, - "offset": 2 + "offset": 2, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1129,6 +1220,39 @@ mod tests { let msg = format!("{err}"); assert!(msg.contains("invalid regex")); + assert!(msg.contains("literal: true")); + } + + #[tokio::test] + async fn grep_literal_mode_searches_punctuation_heavy_text() { + let temp = tempfile::tempdir().expect("tempdir should be created"); + let file = temp.path().join("lib.rs"); + tokio::fs::write(&file, "#[cfg(test)]\nmod tests {}\n") + .await + .expect("seed write should work"); + let tool = GrepTool; + + let result = tool + .execute( + "tc-grep-literal".to_string(), + json!({ + "pattern": "#[cfg(test)]", + "literal": true, + "path": file.to_string_lossy(), + "outputMode": "content" + }), + &test_tool_context_for(temp.path()), + ) + .await + .expect("grep should search exact text"); + + let matches: Vec = + serde_json::from_str(&result.output).expect("output should be valid json"); + assert_eq!(matches.len(), 1); + assert_eq!(matches[0].line_no, 1); + assert_eq!(matches[0].match_text, Some("#[cfg(test)]".to_string())); + let meta = result.metadata.expect("metadata should exist"); + assert_eq!(meta["literal"], json!(true)); } #[tokio::test] @@ -1167,7 +1291,8 @@ mod tests { json!({ "pattern": "pub fn", "path": file.to_string_lossy(), - "offset": 5 + "offset": 5, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1219,6 +1344,36 @@ mod tests { assert!(files[0].ends_with("a.rs")); } + #[tokio::test] + async fn grep_defaults_to_files_with_matches_for_exploration() { + let temp = tempfile::tempdir().expect("tempdir should be created"); + let file = temp.path().join("main.rs"); + tokio::fs::write(&file, "fn main() {}\n") + .await + .expect("seed write should work"); + let tool = GrepTool; + + let result = tool + .execute( + "tc-grep-default-files".to_string(), + json!({ + "pattern": "main", + "path": temp.path().to_string_lossy() + }), + &test_tool_context_for(temp.path()), + ) + .await + .expect("grep should succeed"); + + assert!(result.ok); + let files: Vec = + serde_json::from_str(&result.output).expect("output should be valid json"); + assert_eq!(files.len(), 1); + assert!(files[0].ends_with("main.rs")); + let metadata = result.metadata.expect("metadata should exist"); + assert_eq!(metadata["output_mode"], json!("files_with_matches")); + } + #[tokio::test] async fn grep_count_mode_returns_match_counts() { let temp = tempfile::tempdir().expect("tempdir should be created"); @@ -1248,6 +1403,44 @@ mod tests { assert_eq!(counts[0].count, 2); } + #[tokio::test] + async fn grep_accepts_ripgrep_style_aliases_and_string_scalars() { + let temp = tempfile::tempdir().expect("tempdir should be created"); + let file = temp.path().join("lib.rs"); + tokio::fs::write(&file, "before\nTARGET\nmatch target\n") + .await + .expect("seed write should work"); + let tool = GrepTool; + + let result = tool + .execute( + "tc-grep-aliases".to_string(), + json!({ + "pattern": "target", + "path": temp.path().to_string_lossy(), + "output_mode": "content", + "-i": "true", + "-B": "1", + "head_limit": "1" + }), + &test_tool_context_for(temp.path()), + ) + .await + .expect("grep should accept aliases"); + + let matches: Vec = + serde_json::from_str(&result.output).expect("output should be valid json"); + assert_eq!(matches.len(), 1); + assert_eq!( + matches[0] + .before + .as_ref() + .expect("before context should exist")[0], + "before" + ); + assert!(result.truncated); + } + #[tokio::test] async fn grep_glob_filter_excludes_non_matching_files() { let temp = tempfile::tempdir().expect("tempdir should be created"); @@ -1267,7 +1460,8 @@ mod tests { json!({ "pattern": "main", "path": temp.path().to_string_lossy(), - "glob": "*.rs" + "glob": "*.rs", + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1287,9 +1481,17 @@ mod tests { .prompt .expect("grep should expose prompt metadata"); - assert!(prompt.summary.contains("provide both `pattern` and `path`")); + assert!(prompt.summary.contains("Defaults to")); + assert!(prompt.guide.contains("`outputMode: \"content\"`")); assert!(prompt.guide.contains("glob")); assert!(prompt.guide.contains("findFiles")); + assert!(prompt.guide.contains("literal: true")); + assert!( + prompt + .caveats + .iter() + .any(|caveat| caveat.contains("literal: true")) + ); } #[tokio::test] @@ -1311,7 +1513,8 @@ mod tests { json!({ "pattern": "hello", "path": temp.path().to_string_lossy(), - "fileType": "rust" + "fileType": "rust", + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1340,7 +1543,8 @@ mod tests { "pattern": "TARGET", "path": file.to_string_lossy(), "beforeContext": 2, - "afterContext": 2 + "afterContext": 2, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1412,7 +1616,8 @@ mod tests { json!({ "pattern": "x", "path": file.to_string_lossy(), - "maxMatches": 1 + "maxMatches": 1, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1454,7 +1659,8 @@ mod tests { json!({ "pattern": "TARGET", "path": temp.path().to_string_lossy(), - "recursive": true + "recursive": true, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1496,7 +1702,8 @@ mod tests { json!({ "pattern": "TARGET", "path": temp.path().to_string_lossy(), - "recursive": true + "recursive": true, + "outputMode": "content" }), &test_tool_context_for(temp.path()), ) @@ -1535,7 +1742,8 @@ mod tests { "tc-grep-outside".to_string(), json!({ "pattern": "needle", - "path": "../outside.txt" + "path": "../outside.txt", + "outputMode": "content" }), &test_tool_context_for(&workspace), ) @@ -1569,7 +1777,8 @@ mod tests { json!({ "pattern": "target_", "path": file.to_string_lossy(), - "maxMatches": 700 + "maxMatches": 700, + "outputMode": "content" }), &ctx, ) diff --git a/crates/adapter-tools/src/builtin_tools/list_dir.rs b/crates/adapter-tools/src/builtin_tools/list_dir.rs deleted file mode 100644 index e6ccca31..00000000 --- a/crates/adapter-tools/src/builtin_tools/list_dir.rs +++ /dev/null @@ -1,462 +0,0 @@ -//! # ListDir 工具 -//! -//! 实现 `listDir` 工具，用于浅层列出目录内容。 -//! -//! ## 设计要点 -//! -//! - 仅返回一层目录/文件条目，不递归 -//! - 每个条目返回 `name`、`type`（file/directory/symlink）、`sizeBytes`、`modified`、 -//! `extension`（仅文件） -//! - 默认最多 200 条，超出标记 `truncated` -//! - 未指定路径时使用上下文工作目录 -//! - 支持排序：按名称（默认）或按修改时间（最新优先） - -use std::{fs, path::PathBuf, time::Instant}; - -use astrcode_core::{AstrError, Result, SideEffect}; -use astrcode_tool_contract::{ - Tool, ToolCapabilityMetadata, ToolContext, ToolDefinition, ToolExecutionResult, - ToolPromptMetadata, -}; -use async_trait::async_trait; -use chrono::{DateTime, Utc}; -use serde::Deserialize; -use serde_json::json; - -use crate::builtin_tools::fs_common::{check_cancel, resolve_path}; - -/// ListDir 工具实现。 -/// -/// 列出指定目录的直接子条目（不递归），返回名称和类型信息。 -#[derive(Default)] -pub struct ListDirTool; - -#[derive(Debug, Deserialize)] -#[serde(rename_all = "camelCase")] -struct ListDirArgs { - #[serde(default)] - path: Option, - #[serde(default)] - max_entries: Option, - /// 排序方式：name（默认）或 modified - #[serde(default)] - sort_by: Option, -} - -#[derive(Debug, Deserialize, Clone, Copy, Default)] -#[serde(rename_all = "lowercase")] -enum SortBy { - #[default] - Name, - Modified, - Size, -} - -/// 目录条目信息。 -#[derive(Debug, Clone)] -struct DirEntry { - name: String, - /// 条目类型：file / directory / symlink - entry_type: String, - size_bytes: u64, - modified: Option, - /// 仅文件有扩展名，目录和符号链接不返回此字段 - extension: Option, -} - -#[async_trait] -impl Tool for ListDirTool { - fn definition(&self) -> ToolDefinition { - ToolDefinition { - name: "listDir".to_string(), - description: concat!( - "List immediate directory entries with metadata ", - "(name, type, sizeBytes, modified time, extension). ", - "The `type` field is one of: file, directory, symlink. ", - "The `extension` field is only present for files. ", - "`sizeBytes` is the file size in bytes." - ) - .to_string(), - parameters: json!({ - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Absolute or relative directory path. Defaults to the current working directory if omitted." - }, - "maxEntries": { - "type": "integer", - "minimum": 1, - "description": "Maximum entries to return (default 200)." - }, - "sortBy": { - "type": "string", - "enum": ["name", "modified", "size"], - "description": "Sort order: 'name' (alphabetical, default), 'modified' (newest first), or 'size' (largest first)." - } - }, - "additionalProperties": false - }), - } - } - - fn capability_metadata(&self) -> ToolCapabilityMetadata { - ToolCapabilityMetadata::builtin() - .tags(["filesystem", "read"]) - .permission("filesystem.read") - .side_effect(SideEffect::None) - .concurrency_safe(true) - .compact_clearable(true) - .prompt( - ToolPromptMetadata::new( - "List the immediate contents of a directory before drilling into specific \ - files.", - "List directory entries as structured metadata \ - (name/type/sizeBytes/modified). The `type` field is \"file\", \"directory\", \ - or \"symlink\". The `extension` field only appears for files. Returns one \ - level only — use `path` to drill deeper. Directory `sizeBytes` is always 0 \ - on Windows; only file sizes are meaningful.", - ) - .caveat( - "Truncated at maxEntries (default 200). If result count equals maxEntries, \ - the output may be truncated — use a more specific `path` or `findFiles`.", - ) - .example("List root: { }. List src/: { path: \"src\", sortBy: \"modified\" }") - .prompt_tag("filesystem"), - ) - } - - async fn execute( - &self, - tool_call_id: String, - args: serde_json::Value, - ctx: &ToolContext, - ) -> Result { - check_cancel(ctx.cancel())?; - - let args: ListDirArgs = serde_json::from_value(args) - .map_err(|e| AstrError::parse("invalid args for listDir", e))?; - let started_at = Instant::now(); - let path = match args.path { - Some(path) => resolve_path(ctx, &path)?, - None => ctx.working_dir().to_path_buf(), - }; - let max_entries = args.max_entries.unwrap_or(200); - let sort_by = args.sort_by.unwrap_or_default(); - - let mut entries: Vec = Vec::new(); - let mut truncated = false; - let read_dir = fs::read_dir(&path).map_err(|e| { - AstrError::io(format!("failed reading directory '{}'", path.display()), e) - })?; - - for entry in read_dir { - check_cancel(ctx.cancel())?; - if entries.len() >= max_entries { - truncated = true; - break; - } - let entry = entry?; - let file_type = entry.file_type()?; - let metadata = fs::metadata(entry.path()).ok(); - - let entry_type = if file_type.is_dir() { - "directory" - } else if file_type.is_file() { - "file" - } else { - "symlink" - }; - - let extension = if file_type.is_file() { - entry - .path() - .extension() - .and_then(|e| e.to_str()) - .map(|s| s.to_string()) - } else { - None - }; - - entries.push(DirEntry { - name: entry.file_name().to_string_lossy().to_string(), - entry_type: entry_type.to_string(), - size_bytes: metadata.as_ref().map(|m| m.len()).unwrap_or(0), - modified: metadata.and_then(|m| m.modified().ok()), - extension, - }); - } - - // 排序 - match sort_by { - SortBy::Name => { - // 目录优先，然后按名称排序 - entries.sort_by( - |a, b| match (a.entry_type.as_str(), b.entry_type.as_str()) { - ("directory", "file" | "symlink") => std::cmp::Ordering::Less, - ("file" | "symlink", "directory") => std::cmp::Ordering::Greater, - _ => a.name.to_lowercase().cmp(&b.name.to_lowercase()), - }, - ); - }, - SortBy::Modified => { - // 按修改时间降序（最新优先），目录优先 - entries.sort_by( - |a, b| match (a.entry_type.as_str(), b.entry_type.as_str()) { - ("directory", "file" | "symlink") => std::cmp::Ordering::Less, - ("file" | "symlink", "directory") => std::cmp::Ordering::Greater, - _ => { - let a_time = a.modified.unwrap_or(std::time::SystemTime::UNIX_EPOCH); - let b_time = b.modified.unwrap_or(std::time::SystemTime::UNIX_EPOCH); - b_time.cmp(&a_time) - }, - }, - ); - }, - SortBy::Size => { - // 按文件大小降序（最大优先），目录优先 - entries.sort_by( - |a, b| match (a.entry_type.as_str(), b.entry_type.as_str()) { - ("directory", "file" | "symlink") => std::cmp::Ordering::Less, - ("file" | "symlink", "directory") => std::cmp::Ordering::Greater, - _ => b.size_bytes.cmp(&a.size_bytes), - }, - ); - }, - } - - // 转换为 JSON - let json_entries: Vec = entries - .iter() - .map(|e| { - let mut obj = json!({ - "name": e.name, - "type": e.entry_type, - "sizeBytes": e.size_bytes, - "modified": e.modified.map(|t| { - // 这里返回真实 RFC3339 UTC 时间，便于排序和跨端展示保持一致。 - DateTime::::from(t).to_rfc3339() - }), - }); - // 仅文件返回 extension，目录/符号链接不返回以避免 AI 误解 null 含义 - if let Some(ext) = &e.extension { - obj.as_object_mut() - .expect("obj is constructed above as object") - .insert("extension".to_string(), json!(ext)); - } - obj - }) - .collect(); - - let output = serde_json::to_string(&json_entries) - .map_err(|e| AstrError::parse("failed to serialize listDir output", e))?; - let empty_message = json_entries - .is_empty() - .then_some("Directory is empty.".to_string()); - - Ok(ToolExecutionResult { - tool_call_id, - tool_name: "listDir".to_string(), - ok: true, - output, - error: None, - metadata: Some(json!({ - "path": path.to_string_lossy(), - "count": json_entries.len(), - "truncated": truncated, - "message": empty_message, - "sortBy": match sort_by { - SortBy::Name => "name", - SortBy::Modified => "modified", - SortBy::Size => "size", - }, - })), - continuation: None, - duration_ms: started_at.elapsed().as_millis() as u64, - truncated, - }) - } -} - -#[cfg(test)] -mod tests { - use chrono::DateTime; - - use super::*; - use crate::test_support::test_tool_context_for; - - #[tokio::test] - async fn list_dir_tool_lists_entries_with_metadata() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - tokio::fs::write(temp.path().join("a.txt"), "hello world") - .await - .expect("write should work"); - - let tool = ListDirTool; - let result = tool - .execute( - "tc-list-meta".to_string(), - json!({"path": temp.path().to_string_lossy()}), - &test_tool_context_for(temp.path()), - ) - .await - .expect("listDir should succeed"); - - assert!(result.ok); - let entries: Vec = - serde_json::from_str(&result.output).expect("output should be valid json"); - assert_eq!(entries.len(), 1); - assert_eq!(entries[0]["name"], "a.txt"); - assert_eq!(entries[0]["type"], "file"); - assert_eq!(entries[0]["sizeBytes"], 11); // "hello world" 的字节数 - assert_eq!(entries[0]["extension"], "txt"); - let modified = entries[0]["modified"] - .as_str() - .expect("modified timestamp should exist"); - assert!( - DateTime::parse_from_rfc3339(modified).is_ok(), - "modified should be RFC3339" - ); - } - - #[tokio::test] - async fn list_dir_tool_honors_max_entries() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - tokio::fs::write(temp.path().join("a.txt"), "x") - .await - .expect("write should work"); - tokio::fs::write(temp.path().join("b.txt"), "x") - .await - .expect("write should work"); - - let tool = ListDirTool; - let result = tool - .execute( - "tc-list-max".to_string(), - json!({"path": temp.path().to_string_lossy(), "maxEntries": 1}), - &test_tool_context_for(temp.path()), - ) - .await - .expect("listDir should succeed"); - - let entries: Vec = - serde_json::from_str(&result.output).expect("output should be valid json"); - assert_eq!(entries.len(), 1); - assert!(result.truncated); - } - - #[tokio::test] - async fn list_dir_tool_sorts_by_modified_time() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - let file1 = temp.path().join("old.txt"); - let file2 = temp.path().join("new.txt"); - - tokio::fs::write(&file1, "old") - .await - .expect("write should work"); - tokio::time::sleep(tokio::time::Duration::from_millis(10)).await; - tokio::fs::write(&file2, "new") - .await - .expect("write should work"); - - let tool = ListDirTool; - let result = tool - .execute( - "tc-list-sort".to_string(), - json!({ - "path": temp.path().to_string_lossy(), - "sortBy": "modified" - }), - &test_tool_context_for(temp.path()), - ) - .await - .expect("listDir should succeed"); - - let entries: Vec = - serde_json::from_str(&result.output).expect("output should be valid json"); - // 新文件应排在前面 - assert_eq!(entries[0]["name"], "new.txt"); - assert_eq!(entries[1]["name"], "old.txt"); - } - - #[tokio::test] - async fn list_dir_tool_directories_first() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - tokio::fs::create_dir(temp.path().join("zdir")) - .await - .expect("mkdir should work"); - tokio::fs::write(temp.path().join("afile.txt"), "x") - .await - .expect("write should work"); - - let tool = ListDirTool; - let result = tool - .execute( - "tc-list-dirs-first".to_string(), - json!({"path": temp.path().to_string_lossy()}), - &test_tool_context_for(temp.path()), - ) - .await - .expect("listDir should succeed"); - - let entries: Vec = - serde_json::from_str(&result.output).expect("output should be valid json"); - // 目录应排在前面，即使名称字母顺序更靠后 - assert_eq!(entries[0]["name"], "zdir"); - assert_eq!(entries[0]["type"], "directory"); - assert_eq!(entries[1]["name"], "afile.txt"); - } - - #[tokio::test] - async fn list_dir_tool_returns_json_for_empty_directory() { - let temp = tempfile::tempdir().expect("tempdir should be created"); - let tool = ListDirTool; - - let result = tool - .execute( - "tc-list-empty".to_string(), - json!({"path": temp.path().to_string_lossy()}), - &test_tool_context_for(temp.path()), - ) - .await - .expect("listDir should succeed"); - - let entries: Vec = - serde_json::from_str(&result.output).expect("output should remain valid json"); - assert!(entries.is_empty()); - let metadata = result.metadata.expect("metadata should exist"); - assert_eq!(metadata["message"], json!("Directory is empty.")); - } - - #[tokio::test] - async fn list_dir_allows_relative_path_outside_working_dir() { - let parent = tempfile::tempdir().expect("tempdir should be created"); - let workspace = parent.path().join("workspace"); - let outside = parent.path().join("outside"); - tokio::fs::create_dir_all(&workspace) - .await - .expect("workspace should be created"); - tokio::fs::create_dir_all(&outside) - .await - .expect("outside dir should be created"); - tokio::fs::write(outside.join("note.txt"), "hello") - .await - .expect("outside file should be created"); - let tool = ListDirTool; - - let result = tool - .execute( - "tc-list-outside".to_string(), - json!({"path": "../outside"}), - &test_tool_context_for(&workspace), - ) - .await - .expect("listDir should succeed"); - - assert!(result.ok); - let entries: Vec = - serde_json::from_str(&result.output).expect("output should be valid json"); - assert_eq!(entries.len(), 1); - assert_eq!(entries[0]["name"], "note.txt"); - } -} diff --git a/crates/adapter-tools/src/builtin_tools/mod.rs b/crates/adapter-tools/src/builtin_tools/mod.rs index ceee852e..006cc864 100644 --- a/crates/adapter-tools/src/builtin_tools/mod.rs +++ b/crates/adapter-tools/src/builtin_tools/mod.rs @@ -21,8 +21,6 @@ pub mod find_files; pub mod fs_common; /// 内容搜索工具：正则匹配 pub mod grep; -/// 目录列表工具：浅层条目枚举 -pub mod list_dir; /// mode 切换共享辅助 pub mod mode_transition; /// 文件读取工具：UTF-8 文本读取 diff --git a/crates/adapter-tools/src/builtin_tools/read_file.rs b/crates/adapter-tools/src/builtin_tools/read_file.rs index d455e0d6..f6939c53 100644 --- a/crates/adapter-tools/src/builtin_tools/read_file.rs +++ b/crates/adapter-tools/src/builtin_tools/read_file.rs @@ -13,7 +13,7 @@ use std::{ fs, - io::{BufRead, BufReader, Read as _}, + io::{BufRead, BufReader, ErrorKind, Read as _}, path::{Path, PathBuf}, time::Instant, }; @@ -98,9 +98,6 @@ struct ReadFileArgs { /// 最多返回的行数，与 offset 配合使用。 #[serde(default)] limit: Option, - /// 是否在每行前显示行号（默认 true），对 LLM 定位代码效率更高。 - #[serde(default = "default_true")] - line_numbers: bool, } /// 根据文件扩展名获取图片的 MIME 类型。 @@ -180,10 +177,6 @@ fn read_image_file( Ok((base64_data, mime_type.to_string(), file_size)) } -fn default_true() -> bool { - true -} - /// 检测文件是否为二进制文件。 /// /// 读取文件前 `BINARY_DETECT_SAMPLE_SIZE` 字节，检测是否包含 NUL 字节。 @@ -244,10 +237,6 @@ impl Tool for ReadFileTool { "minimum": 1, "description": "Maximum number of lines to read from the offset." }, - "lineNumbers": { - "type": "boolean", - "description": "Prepend line numbers to each line (default true)" - } }, "required": ["path"], "additionalProperties": false @@ -264,23 +253,16 @@ impl Tool for ReadFileTool { .compact_clearable(true) .prompt( ToolPromptMetadata::new( - "Read file contents — supports text, images (base64), persisted tool-result \ - chunks, and targeted line-range reads.", - "Use after `grep`/`findFiles` gives you a path. For normal source files, use \ - `offset` (**0-based** line) + `limit` to read a specific range; set \ - `lineNumbers: false` to skip line-number prefixes. For persisted large tool \ - results, prefer chunked reads with `charOffset` + `maxChars` instead of \ - trying to inline the whole file again.", + "Read known files. Use `offset`/`limit` for line ranges and `charOffset` for \ + persisted tool-result chunks.", + "`readFile` reads files, not directories. Use it after `findFiles`, `grep`, \ + or user-provided paths identify a file. Use `offset` + `limit` for normal \ + source files and `charOffset` + `maxChars` for persisted large tool \ + results.", ) .caveat( - "If output is truncated, continue from the next chunk. For normal files, use \ - `offset` + `limit`; for persisted tool results, use `charOffset` + \ - `maxChars`. Do not retry by requesting the whole large result again.", - ) - .example("Read lines 50–100: { path: \"src/main.rs\", offset: 50, limit: 50 }") - .example( - "Read the first chunk of a persisted tool result: { path: \ - \"C:/.../tool-results/call-1.txt\", charOffset: 0, maxChars: 20000 }", + "If output is truncated, continue from the next range or chunk instead of \ + rereading the whole file.", ) .prompt_tag("filesystem") .always_include(true), @@ -329,6 +311,63 @@ impl Tool for ReadFileTool { let path = target.path; let is_persisted_tool_result = target.persisted_relative_path.is_some(); + if !is_persisted_tool_result { + match fs::metadata(&path) { + Ok(metadata) if metadata.is_dir() => { + let command = directory_inspection_command(&path); + return Ok(ToolExecutionResult { + tool_call_id, + tool_name: "readFile".to_string(), + ok: false, + output: String::new(), + error: Some(format!( + "path is a directory, not a file: '{}'. Use `shell` to inspect it, \ + for example: {command}", + path.display() + )), + metadata: Some(json!({ + "path": path.to_string_lossy(), + "directory": true, + "suggestedTool": "shell", + "suggestedCommand": command, + })), + continuation: None, + duration_ms: started_at.elapsed().as_millis() as u64, + truncated: false, + }); + }, + Ok(_) => {}, + Err(error) if error.kind() == ErrorKind::NotFound => { + let mut message = format!("file does not exist: '{}'.", path.display()); + let similar_file = find_same_stem_file(&path); + if let Some(suggestion) = &similar_file { + message.push_str(&format!(" Did you mean {}?", suggestion.display())); + } + return Ok(ToolExecutionResult { + tool_call_id, + tool_name: "readFile".to_string(), + ok: false, + output: String::new(), + error: Some(message), + metadata: Some(json!({ + "path": path.to_string_lossy(), + "notFound": true, + "suggestedPath": similar_file.map(|path| path.to_string_lossy().to_string()), + })), + continuation: None, + duration_ms: started_at.elapsed().as_millis() as u64, + truncated: false, + }); + }, + Err(error) => { + return Err(AstrError::io( + format!("failed reading metadata for '{}'", path.display()), + error, + )); + }, + } + } + // 图片文件处理：返回 base64 编码 if is_image_file(&path) { return match read_image_file(&path, ctx.max_output_size()) { @@ -468,14 +507,13 @@ impl Tool for ReadFileTool { args.offset.unwrap_or(0), args.limit, max_chars, - args.line_numbers, ctx.cancel(), )?; total_line_count = Some(counted_total_lines); (text, truncated) } else { let (text, _returned_lines, truncated) = - read_file_full(reader, max_chars, args.line_numbers, ctx.cancel())?; + read_file_full(reader, max_chars, ctx.cancel())?; (text, truncated) }; @@ -549,6 +587,38 @@ fn total_utf8_bytes(text: &str) -> usize { text.len() } +fn directory_inspection_command(path: &Path) -> String { + let path = path.to_string_lossy().replace('"', "\\\""); + if cfg!(windows) { + format!("Get-ChildItem -Force -LiteralPath \"{path}\"") + } else { + format!("ls -la \"{path}\"") + } +} + +fn find_same_stem_file(path: &Path) -> Option { + let parent = path.parent()?; + let requested_stem = path.file_stem()?; + let requested_name = path.file_name()?; + let entries = fs::read_dir(parent).ok()?; + + for entry in entries.flatten() { + let candidate_path = entry.path(); + if !candidate_path.is_file() { + continue; + } + let candidate_name = candidate_path.file_name()?; + if candidate_name == requested_name { + continue; + } + if candidate_path.file_stem() == Some(requested_stem) { + return Some(candidate_path); + } + } + + None +} + fn read_persisted_tool_result_chunk( text: &str, char_offset: usize, @@ -591,7 +661,6 @@ fn format_line(number: usize, content: &str, width: usize) -> String { fn read_file_full( reader: BufReader, max_chars: usize, - line_numbers: bool, cancel: &astrcode_core::CancelToken, ) -> Result<(String, usize, bool)> { let mut output = String::new(); @@ -603,16 +672,12 @@ fn read_file_full( let line = line_result.map_err(|e| AstrError::io("failed reading file line", e))?; line_no += 1; - let formatted = if line_numbers { - // 缓存行号宽度，避免每行都重新计算（避免频繁字符串分配） - let width = line_number_width(line_no); - if width > cached_width { - cached_width = width; - } - format_line(line_no, &line, cached_width) - } else { - line.clone() - }; + // 缓存行号宽度，避免每行都重新计算（避免频繁字符串分配） + let width = line_number_width(line_no); + if width > cached_width { + cached_width = width; + } + let formatted = format_line(line_no, &line, cached_width); let remaining = max_chars.saturating_sub(output.chars().count()); // 已超出字符预算，后续内容全部截断 @@ -657,7 +722,6 @@ fn read_lines_range( offset: usize, limit: Option, max_chars: usize, - line_numbers: bool, cancel: &astrcode_core::CancelToken, ) -> Result<(String, usize, bool)> { let mut output = String::new(); @@ -685,12 +749,7 @@ fn read_lines_range( } // line_count 是 1-based 行号（用于显示） - let formatted = if line_numbers { - // 按当前行号动态计算宽度，避免额外的全文件预扫描。 - format_line(line_count, &line, line_number_width(line_count)) - } else { - line - }; + let formatted = format_line(line_count, &line, line_number_width(line_count)); let remaining = max_chars.saturating_sub(output.chars().count()); if remaining == 0 { @@ -703,7 +762,7 @@ fn read_lines_range( } let take = remaining.min(formatted.chars().count()); - if take == 0 && line_numbers { + if take == 0 { // 行号本身就超出预算 // 同样继续扫描到 EOF，保证 total_lines 准确。 truncated = true; @@ -743,18 +802,79 @@ mod tests { let result = tool .execute( "tc3".to_string(), - json!({ "path": file.to_string_lossy(), "maxChars": 3, "lineNumbers": false }), + json!({ "path": file.to_string_lossy(), "maxChars": 6 }), &test_tool_context_for(temp.path()), ) .await .expect("readFile should succeed"); - assert_eq!(result.output, "abc"); + assert_eq!(result.output, " 1\ta"); let metadata = result.metadata.expect("metadata should exist"); assert_eq!(metadata["bytes"], json!(6)); assert_eq!(metadata["truncated"], json!(true)); } + #[tokio::test] + async fn read_file_directory_returns_shell_recovery_hint() { + let temp = tempfile::tempdir().expect("tempdir should be created"); + let directory = temp.path().join("src"); + tokio::fs::create_dir(&directory) + .await + .expect("directory should be created"); + let tool = ReadFileTool; + + let result = tool + .execute( + "tc-read-dir".to_string(), + json!({ "path": directory.to_string_lossy() }), + &test_tool_context_for(temp.path()), + ) + .await + .expect("readFile should return a recoverable tool result"); + + assert!(!result.ok); + let error = result.error.expect("error should be present"); + assert!(error.contains("path is a directory")); + assert!(error.contains("shell")); + let metadata = result.metadata.expect("metadata should exist"); + assert_eq!(metadata["directory"], json!(true)); + assert_eq!(metadata["suggestedTool"], json!("shell")); + } + + #[tokio::test] + async fn read_file_missing_file_suggests_same_stem_different_extension() { + let temp = tempfile::tempdir().expect("tempdir should be created"); + let actual = temp.path().join("TaskOutputTool.tsx"); + tokio::fs::write(&actual, "export const x = 1;\n") + .await + .expect("write should work"); + let requested = temp.path().join("TaskOutputTool.ts"); + let tool = ReadFileTool; + + let result = tool + .execute( + "tc-read-missing-suggestion".to_string(), + json!({ "path": requested.to_string_lossy() }), + &test_tool_context_for(temp.path()), + ) + .await + .expect("readFile should return a recoverable tool result"); + + assert!(!result.ok); + let error = result.error.expect("error should be present"); + assert!(error.contains("file does not exist")); + assert!(error.contains("Did you mean")); + assert!(error.contains("TaskOutputTool.tsx")); + let metadata = result.metadata.expect("metadata should exist"); + assert_eq!(metadata["notFound"], json!(true)); + assert!( + metadata["suggestedPath"] + .as_str() + .expect("suggested path should be present") + .ends_with("TaskOutputTool.tsx") + ); + } + #[tokio::test] async fn read_file_tool_truncates_at_utf8_char_boundary() { let temp = tempfile::tempdir().expect("tempdir should be created"); @@ -766,13 +886,13 @@ mod tests { let result = tool .execute( "tc4".to_string(), - json!({ "path": file.to_string_lossy(), "maxChars": 1, "lineNumbers": false }), + json!({ "path": file.to_string_lossy(), "maxChars": 6 }), &test_tool_context_for(temp.path()), ) .await .expect("readFile should succeed"); - assert_eq!(result.output, "你"); + assert_eq!(result.output, " 1\t你"); assert!(result.truncated); } @@ -820,8 +940,7 @@ mod tests { "path": file.to_string_lossy(), "offset": 1, "limit": 10, - "maxChars": 6, - "lineNumbers": false + "maxChars": 6 }), &test_tool_context_for(temp.path()), ) @@ -834,7 +953,7 @@ mod tests { } #[tokio::test] - async fn read_file_line_numbers_disabled() { + async fn read_file_always_returns_line_numbers() { let temp = tempfile::tempdir().expect("tempdir should be created"); let file = temp.path().join("sample.txt"); tokio::fs::write(&file, "line0\nline1\nline2\n") @@ -846,16 +965,14 @@ mod tests { .execute( "tc-no-lnum".to_string(), json!({ - "path": file.to_string_lossy(), - "lineNumbers": false + "path": file.to_string_lossy() }), &test_tool_context_for(temp.path()), ) .await .expect("readFile should succeed"); - // 关闭行号后输出应为纯文本 - assert_eq!(result.output, "line0\nline1\nline2"); + assert_eq!(result.output, " 1\tline0\n 2\tline1\n 3\tline2"); } #[tokio::test] @@ -1028,8 +1145,7 @@ mod tests { .execute( "tc-svg-text".to_string(), json!({ - "path": file.to_string_lossy(), - "lineNumbers": false + "path": file.to_string_lossy() }), &test_tool_context_for(temp.path()), ) @@ -1037,7 +1153,7 @@ mod tests { .expect("readFile should succeed"); assert!(result.ok); - assert_eq!(result.output, ""); + assert_eq!(result.output, " 1\t"); let metadata = result.metadata.expect("metadata should exist"); assert_eq!(metadata["bytes"], json!(19)); assert!(metadata.get("fileType").is_none()); @@ -1060,8 +1176,7 @@ mod tests { .execute( "tc-read-outside".to_string(), json!({ - "path": "../outside.txt", - "lineNumbers": false + "path": "../outside.txt" }), &test_tool_context_for(&workspace), ) @@ -1069,7 +1184,7 @@ mod tests { .expect("readFile should succeed"); assert!(result.ok); - assert_eq!(result.output, "outside"); + assert_eq!(result.output, " 1\toutside"); let metadata = result.metadata.expect("metadata should exist"); assert_eq!( metadata["path"], diff --git a/crates/adapter-tools/src/builtin_tools/shell.rs b/crates/adapter-tools/src/builtin_tools/shell.rs index 8535e12a..dd8fc00d 100644 --- a/crates/adapter-tools/src/builtin_tools/shell.rs +++ b/crates/adapter-tools/src/builtin_tools/shell.rs @@ -58,17 +58,14 @@ pub struct ShellTool; /// Shell 工具的反序列化参数。 /// -/// `command` 是必填项；`cwd` 和 `shell` 可选， -/// 未指定时分别使用上下文工作目录和当前环境推导出的默认 shell。 +/// `command` 是必填项；`cwd` 可选，未指定时使用上下文工作目录。 +/// shell 始终由运行时根据当前环境解析，避免模型误选 shell family。 #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] struct ShellArgs { command: String, #[serde(default)] cwd: Option, - /// 覆盖默认 shell。 - #[serde(default)] - shell: Option, /// 超时参数（秒），默认 120，上限 300。 #[serde(default)] timeout: Option, @@ -352,19 +349,14 @@ impl Tool for ShellTool { ToolDefinition { name: "shell".to_string(), description: format!( - "Execute a non-interactive shell command once with the current default shell \ - ({default_shell}). `shell` may override it for supported shell families; return \ - stdout/stderr/exitCode." + "Run a non-interactive shell command with the default shell ({default_shell}). \ + Use for directory inspection and commands without a dedicated tool." ), parameters: json!({ "type": "object", "properties": { "command": { "type": "string" }, "cwd": { "type": "string" }, - "shell": { - "type": "string", - "description": "Optional shell override. Supported families: pwsh/powershell, cmd, wsl, sh/bash/zsh." - }, "timeout": { "type": "integer", "minimum": 1, @@ -387,32 +379,23 @@ impl Tool for ShellTool { .prompt( ToolPromptMetadata::new( format!( - "Run a one-shot shell command with the current default shell \ - (`{default_shell}`) when file tools or search tools are not precise \ - enough." + "Run one-shot shell commands with `{default_shell}`. Use for directory \ + inspection, build/test/git/system commands, and operations without a \ + dedicated tool." ), format!( - "Use `shell` for non-interactive commands that are easier to express as a \ - single command line than as a dedicated file tool. This session defaults \ - to `{default_shell}` and resolves that default by preferring the current \ - environment's shell before falling back to platform-safe options. The \ - optional `shell` override only supports known shell families \ - (PowerShell, cmd, WSL bash, sh/bash/zsh) so runtime can pass the command \ - with the correct flags. Prefer `shell` for build/test/git/system \ - inspection commands. Prefer dedicated tools instead of `shell` for file \ - reading (`readFile`), code search (`grep`/`findFiles`), and structured \ - file edits (`editFile`/`apply_patch`). Keep commands scoped to the \ - intended host paths, explain risky commands before running them, and \ - prefer read-only inspection before mutation." + "Use `shell` for non-interactive commands with the default shell \ + `{default_shell}`. Use `ls`, `dir`, or `Get-ChildItem` to inspect \ + directories. Prefer `readFile` for files, `findFiles` for path globs, \ + `grep` for content search, and `editFile`/`writeFile`/`apply_patch` for \ + file changes. Keep commands scoped and prefer read-only inspection \ + before mutation." ), ) .caveat( - "Non-interactive single shot — no stdin, no interactive prompts. Use `cwd` to \ - set the working directory instead of `cd &&`. On timeout the process is \ - killed; only output produced so far is returned. If quoting issues, set \ - `shell` explicitly to pwsh/cmd/wsl/sh.", + "Single shot only: no stdin and no interactive prompts. Use `cwd` instead of \ + `cd &&`; set `shell` explicitly only for quoting or shell-family issues.", ) - .example("Run cargo test: { command: \"cargo test --lib\", timeout: 300 }") .prompt_tag("shell"), ) .max_result_inline_size(30_000) @@ -433,7 +416,7 @@ impl Tool for ShellTool { )); } - let spec = command_spec(args.shell.as_deref(), &args.command)?; + let spec = command_spec(&args.command)?; let started_at = Instant::now(); let command_text = args.command.clone(); let shell_display = spec.display_shell.clone(); @@ -642,9 +625,9 @@ impl Tool for ShellTool { /// 根据平台和用户偏好构建 shell 命令规范。 /// /// 默认策略优先继承当前环境中的 shell 线索，再回退到平台可用的 -/// bash/PowerShell/WSL 兜底链。用户显式传入 `shell` 时始终优先。 -fn command_spec(shell: Option<&str>, command: &str) -> Result { - let resolved_shell = resolve_shell(shell)?; +/// bash/PowerShell/WSL 兜底链。 +fn command_spec(command: &str) -> Result { + let resolved_shell = resolve_shell(None)?; Ok(command_spec_for_family(resolved_shell, command)) } @@ -724,6 +707,27 @@ mod tests { deltas } + fn default_shell_family_for_tests() -> ShellFamily { + let spec = command_spec("echo ok").expect("default shell should resolve"); + detect_shell_family(&spec.program).expect("default shell family should be known") + } + + fn large_output_command_for_default_shell() -> String { + match default_shell_family_for_tests() { + ShellFamily::Cmd => "for /l %i in (1,1,10000) do @ "[Console]::Write(('x' * 10000))".to_string(), + ShellFamily::Posix | ShellFamily::Wsl => "yes x | head -c 10000".to_string(), + } + } + + fn pwd_command_for_default_shell() -> String { + match default_shell_family_for_tests() { + ShellFamily::Cmd => "cd".to_string(), + ShellFamily::PowerShell => "(Get-Location).Path".to_string(), + ShellFamily::Posix | ShellFamily::Wsl => "pwd".to_string(), + } + } + #[test] fn stream_capture_truncates_oversized_chunk_with_notice() { let mut capture = StreamCapture::new(ToolOutputStream::Stdout, 5); @@ -827,11 +831,7 @@ mod tests { #[tokio::test] async fn shell_tool_runs_non_interactive_command() { let tool = ShellTool; - let args = if cfg!(windows) { - json!({"command": "echo ok", "shell": "cmd"}) - } else { - json!({"command": "echo ok", "shell": "sh"}) - }; + let args = json!({"command": "echo ok"}); let result = tool .execute( @@ -846,6 +846,20 @@ mod tests { assert!(result.output.contains("ok")); } + #[test] + fn shell_prompt_describes_directory_inspection_entrypoint() { + let prompt = ShellTool + .capability_metadata() + .prompt + .expect("shell should expose prompt metadata"); + + assert!(prompt.guide.contains("inspect directories")); + assert!(prompt.guide.contains("Get-ChildItem")); + assert!(prompt.guide.contains("readFile")); + assert!(prompt.guide.contains("findFiles")); + assert!(prompt.guide.contains("grep")); + } + #[tokio::test] async fn shell_persists_large_output_and_read_file_can_open_it() { let temp = tempfile::tempdir().expect("tempdir should be created"); @@ -853,17 +867,9 @@ mod tests { .with_resolved_inline_limit(4 * 1024) .with_max_output_size(20 * 1024); let tool = ShellTool; - let args = if cfg!(windows) { - json!({ - "command": "[Console]::Write(('x' * 10000))", - "shell": "pwsh" - }) - } else { - json!({ - "command": "yes x | head -c 10000", - "shell": "sh" - }) - }; + let args = json!({ + "command": large_output_command_for_default_shell() + }); let result = tool .execute("tc-shell-persisted".to_string(), args, &shell_ctx) @@ -911,19 +917,10 @@ mod tests { .await .expect("outside dir should be created"); let tool = ShellTool; - let args = if cfg!(windows) { - json!({ - "command": "(Get-Location).Path", - "shell": "pwsh", - "cwd": outside.to_string_lossy() - }) - } else { - json!({ - "command": "pwd", - "shell": "sh", - "cwd": outside.to_string_lossy() - }) - }; + let args = json!({ + "command": pwd_command_for_default_shell(), + "cwd": outside.to_string_lossy() + }); let result = tool .execute( @@ -997,20 +994,9 @@ mod tests { } #[test] - fn command_spec_rejects_unknown_shell_override() { - let err = command_spec(Some("fish"), "echo ok").expect_err("unsupported shell should fail"); - assert!(matches!(err, AstrError::Validation(_))); - } - - #[test] - fn command_spec_uses_stable_display_labels() { - let cmd_spec = command_spec(Some("cmd"), "echo ok").expect("cmd should resolve"); - assert_eq!(cmd_spec.display_shell, "cmd"); - - let pwsh_spec = command_spec(Some("pwsh"), "echo ok").expect("pwsh should resolve"); - assert_eq!(pwsh_spec.display_shell, "pwsh"); - - let wsl_spec = command_spec(Some("wsl.exe"), "echo ok").expect("wsl should resolve"); - assert_eq!(wsl_spec.display_shell, "wsl-bash"); + fn command_spec_uses_runtime_default_shell() { + let spec = command_spec("echo ok").expect("default shell should resolve"); + assert!(!spec.program.is_empty()); + assert_eq!(spec.display_shell, default_shell_for_prompt()); } } diff --git a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs index 20a9b991..98f7112a 100644 --- a/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs +++ b/crates/adapter-tools/src/builtin_tools/upsert_session_plan.rs @@ -76,22 +76,21 @@ impl Tool for UpsertSessionPlanTool { .side_effect(SideEffect::Local) .prompt( ToolPromptMetadata::new( - "Create or update the canonical session plan artifact.", + "Create or update the session plan artifact — the single source of truth for \ + the current task plan.", "Use `upsertSessionPlan` when plan mode needs to persist the canonical \ session plan markdown and its `state.json`. This tool is the only supported \ writer for `sessions//plan/**`.", ) .caveat( - "A session has exactly one canonical plan. Revise that plan for the same \ - task; if the task changes, overwrite the current canonical plan instead of \ - creating another one.", + "One plan per session. Overwrite the existing plan when the task evolves \ + rather than creating a new one.", ) .example( "{ title: \"Cleanup crates\", content: \"# Plan: Cleanup crates\\n...\", \ status: \"draft\" }", ) - .prompt_tag("plan") - .always_include(true), + .prompt_tag("plan"), ) } diff --git a/crates/adapter-tools/src/builtin_tools/write_file.rs b/crates/adapter-tools/src/builtin_tools/write_file.rs index ee3c7865..6f720f32 100644 --- a/crates/adapter-tools/src/builtin_tools/write_file.rs +++ b/crates/adapter-tools/src/builtin_tools/write_file.rs @@ -78,21 +78,11 @@ impl Tool for WriteFileTool { ToolPromptMetadata::new( "Create or fully replace a text file when the whole target content is known.", "Use `writeFile` for file creation, regeneration, or full rewrites. Prefer \ - `editFile` when you only need to replace a small unique region, because that \ - keeps the change narrower and easier to validate.", + `editFile` or `apply_patch` for narrow edits to existing files.", ) .caveat( "Overwrites the entire file. `createDirs` defaults to false — parent \ - directories must exist or set it to true. Relative paths resolve from the \ - current working directory; absolute host paths are allowed.", - ) - .caveat( - "For small edits to existing files, prefer `editFile` or `apply_patch` to \ - avoid accidentally dropping unrelated content.", - ) - .example( - "Create a new file: { path: \"src/utils.rs\", content: \"pub fn foo() {}\", \ - createDirs: true }", + directories must exist or set it to true.", ) .prompt_tag("filesystem") .always_include(true), diff --git a/crates/adapter-tools/src/lib.rs b/crates/adapter-tools/src/lib.rs index 328ff3d6..abbce751 100644 --- a/crates/adapter-tools/src/lib.rs +++ b/crates/adapter-tools/src/lib.rs @@ -2,7 +2,7 @@ //! //! 本库实现 Astrcode 编码代理（agent）的本地工具集： //! - **core builtin tools**（`builtin_tools`）：readFile、writeFile、editFile、apply_patch、 -//! listDir、findFiles、grep、shell、tool_search、Skill +//! findFiles、grep、shell、tool_search、Skill //! - **agent tools**（`agent_tools`）：spawn、send、observe、close //! //! 所有工具均实现 `astrcode_tool_contract::Tool` trait。 diff --git a/crates/eval/tests/core_end_to_end.rs b/crates/eval/tests/core_end_to_end.rs index 9a662f28..4cf498dd 100644 --- a/crates/eval/tests/core_end_to_end.rs +++ b/crates/eval/tests/core_end_to_end.rs @@ -65,10 +65,6 @@ enum MockStep { pattern: &'static str, output: &'static str, }, - ListDir { - path: &'static str, - output: &'static str, - }, FindFiles { query: &'static str, output: &'static str, @@ -399,9 +395,11 @@ fn scenario_for(task_id: &str) -> Option { ), "listdir-read-edit-status" => scenario( vec![ - MockStep::ListDir { - path: "docs", + MockStep::Shell { + command: "ls docs", output: "docs/todo.md\n", + success: true, + error: None, }, MockStep::Read { path: "docs/todo.md", @@ -720,9 +718,11 @@ fn scenario_for(task_id: &str) -> Option { "大文件里标记的关键值是 retention_window=96。", ), "empty-dir-safe-response" => scenario( - vec![MockStep::ListDir { - path: "empty", + vec![MockStep::Shell { + command: "ls empty", output: "", + success: true, + error: None, }], "empty 目录当前没有文件。", ), @@ -843,7 +843,6 @@ impl MockStep { MockStep::ApplyPatch { .. } => "ApplyPatch", MockStep::Grep { .. } => "Grep", MockStep::Glob { .. } => "Glob", - MockStep::ListDir { .. } => "ListDir", MockStep::FindFiles { .. } => "FindFiles", MockStep::Shell { .. } => "Shell", MockStep::ToolSearch { .. } => "ToolSearch", @@ -869,7 +868,6 @@ impl MockStep { serde_json::json!({ "path": path, "pattern": pattern }) }, MockStep::Glob { pattern, .. } => serde_json::json!({ "pattern": pattern }), - MockStep::ListDir { path, .. } => serde_json::json!({ "path": path }), MockStep::FindFiles { query, .. } => serde_json::json!({ "query": query }), MockStep::Shell { command, .. } => serde_json::json!({ "command": command }), MockStep::ToolSearch { query, .. } => serde_json::json!({ "query": query }), @@ -907,7 +905,6 @@ impl MockStep { }, MockStep::Grep { output, .. } | MockStep::Glob { output, .. } - | MockStep::ListDir { output, .. } | MockStep::FindFiles { output, .. } | MockStep::ToolSearch { output, .. } | MockStep::Skill { output, .. } diff --git a/crates/server/src/bootstrap/capabilities.rs b/crates/server/src/bootstrap/capabilities.rs index febf4fbc..31888ec5 100644 --- a/crates/server/src/bootstrap/capabilities.rs +++ b/crates/server/src/bootstrap/capabilities.rs @@ -22,7 +22,6 @@ use astrcode_adapter_tools::{ exit_plan_mode::ExitPlanModeTool, find_files::FindFilesTool, grep::GrepTool, - list_dir::ListDirTool, read_file::ReadFileTool, shell::ShellTool, skill_tool::SkillTool, @@ -57,7 +56,6 @@ pub(crate) fn build_core_tool_invokers( Arc::new(WriteFileTool), Arc::new(EditFileTool), Arc::new(ApplyPatchTool), - Arc::new(ListDirTool), Arc::new(FindFilesTool), Arc::new(GrepTool), Arc::new(ShellTool), @@ -446,7 +444,7 @@ mod tests { } #[test] - fn build_core_tool_invokers_registers_task_write() { + fn build_core_tool_invokers_registers_expected_tool_surface() { let temp = tempfile::tempdir().expect("tempdir should exist"); let tool_search_index = Arc::new(ToolSearchIndex::new()); let skill_catalog = @@ -460,5 +458,10 @@ mod tests { .collect::>(); assert!(names.iter().any(|name| name == "taskWrite")); + assert!(!names.iter().any(|name| name == "listDir")); + assert!(names.iter().any(|name| name == "readFile")); + assert!(names.iter().any(|name| name == "findFiles")); + assert!(names.iter().any(|name| name == "grep")); + assert!(names.iter().any(|name| name == "shell")); } } diff --git a/eval-tasks/advanced/empty-dir-safe-response.yaml b/eval-tasks/advanced/empty-dir-safe-response.yaml index 99d2ecc2..e604b4f1 100644 --- a/eval-tasks/advanced/empty-dir-safe-response.yaml +++ b/eval-tasks/advanced/empty-dir-safe-response.yaml @@ -6,9 +6,8 @@ workspace: setup: ../fixtures/empty-dir-safe-response expected_outcome: tool_pattern: - - ListDir + - Shell max_tool_calls: 1 max_turns: 1 output_contains: - 没有文件 - diff --git a/eval-tasks/advanced/listdir-read-edit-status.yaml b/eval-tasks/advanced/listdir-read-edit-status.yaml index 37cc34f9..4c1fa617 100644 --- a/eval-tasks/advanced/listdir-read-edit-status.yaml +++ b/eval-tasks/advanced/listdir-read-edit-status.yaml @@ -1,12 +1,12 @@ task_id: listdir-read-edit-status -description: 通过 ListDir 和 Read 获取上下文后更新状态文件。 +description: 通过 Shell 查看目录并用 Read 获取上下文后更新状态文件。 prompt: | 先列出 docs 目录，再读 docs/todo.md，然后把 status.md 改成 ready-for-review。 workspace: setup: ../fixtures/listdir-read-edit-status expected_outcome: tool_pattern: - - ListDir + - Shell - Read - Edit max_tool_calls: 3 @@ -14,4 +14,3 @@ expected_outcome: file_changes: - path: status.md exact: "status: ready-for-review\n" - diff --git a/tool_demo_example.md b/tool_demo_example.md index 8b441658..359ddb7c 100644 --- a/tool_demo_example.md +++ b/tool_demo_example.md @@ -4,7 +4,7 @@ ## 工具列表 -1. **listDir** - ✅ 已使用：列出根目录内容 +1. **shell** - ✅ 已使用：查看根目录内容 2. **findFiles** - ✅ 已使用：查找所有 Rust 文件 3. **readFile** - ✅ 已使用：读取 core/src/lib.rs 前 30 行 4. **writeFile** - ✅ 已使用：创建当前文件 @@ -20,4 +20,4 @@ ### 下一步操作 所有文件操作工具已演示完毕！✨ -总结：每个工具都有其特定用途，选择正确的工具可以提高效率。 \ No newline at end of file +总结：每个工具都有其特定用途，选择正确的工具可以提高效率。 From 22266ec9083e2c23989d246e50a72d6c907d6b37 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Sat, 25 Apr 2026 00:28:41 +0800 Subject: [PATCH 08/10] =?UTF-8?q?=F0=9F=94=A7=20fix(ci):=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E5=9B=9E=E5=BD=92=E8=84=9A=E6=9C=AC=E4=B8=8E=20crate?= =?UTF-8?q?=20=E4=BE=9D=E8=B5=96=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit regressions.mjs 引用了重构后已删除的 astrcode-session-runtime 和 astrcode-plugin crate，改为锚定 agent-runtime 和 adapter-prompt 中 的等价测试。重新生成 crates-dependency-graph.md。 --- docs/architecture/crates-dependency-graph.md | 119 ++++++++++++++----- scripts/regressions.mjs | 38 ++---- 2 files changed, 98 insertions(+), 59 deletions(-) diff --git a/docs/architecture/crates-dependency-graph.md b/docs/architecture/crates-dependency-graph.md index 1d5f8c4f..d91c7fce 100644 --- a/docs/architecture/crates-dependency-graph.md +++ b/docs/architecture/crates-dependency-graph.md @@ -9,28 +9,73 @@ ```mermaid graph TD astrcode-adapter-agents[astrcode-adapter-agents] --> astrcode-core[astrcode-core] + astrcode-adapter-agents[astrcode-adapter-agents] --> astrcode-support[astrcode-support] astrcode-adapter-llm[astrcode-adapter-llm] --> astrcode-core[astrcode-core] - astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-adapter-prompt[astrcode-adapter-prompt] + astrcode-adapter-llm[astrcode-adapter-llm] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-adapter-llm[astrcode-adapter-llm] --> astrcode-llm-contract[astrcode-llm-contract] + astrcode-adapter-llm[astrcode-adapter-llm] --> astrcode-prompt-contract[astrcode-prompt-contract] astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-core[astrcode-core] + astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-plugin-host[astrcode-plugin-host] + astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-runtime-contract[astrcode-runtime-contract] + astrcode-adapter-mcp[astrcode-adapter-mcp] --> astrcode-support[astrcode-support] astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-core[astrcode-core] + astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-host-session[astrcode-host-session] + astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-support[astrcode-support] + astrcode-adapter-prompt[astrcode-adapter-prompt] --> astrcode-tool-contract[astrcode-tool-contract] astrcode-adapter-skills[astrcode-adapter-skills] --> astrcode-core[astrcode-core] + astrcode-adapter-skills[astrcode-adapter-skills] --> astrcode-support[astrcode-support] astrcode-adapter-storage[astrcode-adapter-storage] --> astrcode-core[astrcode-core] + astrcode-adapter-storage[astrcode-adapter-storage] --> astrcode-host-session[astrcode-host-session] + astrcode-adapter-storage[astrcode-adapter-storage] --> astrcode-support[astrcode-support] astrcode-adapter-tools[astrcode-adapter-tools] --> astrcode-core[astrcode-core] - astrcode-application[astrcode-application] --> astrcode-core[astrcode-core] - astrcode-application[astrcode-application] --> astrcode-kernel[astrcode-kernel] - astrcode-application[astrcode-application] --> astrcode-session-runtime[astrcode-session-runtime] + astrcode-adapter-tools[astrcode-adapter-tools] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-adapter-tools[astrcode-adapter-tools] --> astrcode-host-session[astrcode-host-session] + astrcode-adapter-tools[astrcode-adapter-tools] --> astrcode-support[astrcode-support] + astrcode-adapter-tools[astrcode-adapter-tools] --> astrcode-tool-contract[astrcode-tool-contract] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-context-window[astrcode-context-window] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-core[astrcode-core] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-llm-contract[astrcode-llm-contract] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-runtime-contract[astrcode-runtime-contract] + astrcode-agent-runtime[astrcode-agent-runtime] --> astrcode-tool-contract[astrcode-tool-contract] astrcode-cli[astrcode-cli] --> astrcode-client[astrcode-client] astrcode-cli[astrcode-cli] --> astrcode-core[astrcode-core] + astrcode-cli[astrcode-cli] --> astrcode-support[astrcode-support] astrcode-client[astrcode-client] --> astrcode-protocol[astrcode-protocol] + astrcode-context-window[astrcode-context-window] --> astrcode-core[astrcode-core] + astrcode-context-window[astrcode-context-window] --> astrcode-llm-contract[astrcode-llm-contract] + astrcode-context-window[astrcode-context-window] --> astrcode-runtime-contract[astrcode-runtime-contract] + astrcode-context-window[astrcode-context-window] --> astrcode-support[astrcode-support] + astrcode-context-window[astrcode-context-window] --> astrcode-tool-contract[astrcode-tool-contract] astrcode-core[astrcode-core] astrcode-eval[astrcode-eval] --> astrcode-core[astrcode-core] astrcode-eval[astrcode-eval] --> astrcode-protocol[astrcode-protocol] - astrcode-kernel[astrcode-kernel] --> astrcode-core[astrcode-core] - astrcode-plugin[astrcode-plugin] --> astrcode-core[astrcode-core] - astrcode-plugin[astrcode-plugin] --> astrcode-protocol[astrcode-protocol] + astrcode-eval[astrcode-eval] --> astrcode-support[astrcode-support] + astrcode-governance-contract[astrcode-governance-contract] --> astrcode-core[astrcode-core] + astrcode-governance-contract[astrcode-governance-contract] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-host-session[astrcode-host-session] --> astrcode-agent-runtime[astrcode-agent-runtime] + astrcode-host-session[astrcode-host-session] --> astrcode-core[astrcode-core] + astrcode-host-session[astrcode-host-session] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-host-session[astrcode-host-session] --> astrcode-plugin-host[astrcode-plugin-host] + astrcode-host-session[astrcode-host-session] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-host-session[astrcode-host-session] --> astrcode-runtime-contract[astrcode-runtime-contract] + astrcode-host-session[astrcode-host-session] --> astrcode-support[astrcode-support] + astrcode-host-session[astrcode-host-session] --> astrcode-tool-contract[astrcode-tool-contract] + astrcode-llm-contract[astrcode-llm-contract] --> astrcode-core[astrcode-core] + astrcode-llm-contract[astrcode-llm-contract] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-llm-contract[astrcode-llm-contract] --> astrcode-prompt-contract[astrcode-prompt-contract] + astrcode-plugin-host[astrcode-plugin-host] --> astrcode-core[astrcode-core] + astrcode-plugin-host[astrcode-plugin-host] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-plugin-host[astrcode-plugin-host] --> astrcode-protocol[astrcode-protocol] + astrcode-prompt-contract[astrcode-prompt-contract] --> astrcode-core[astrcode-core] astrcode-protocol[astrcode-protocol] --> astrcode-core[astrcode-core] - astrcode-sdk[astrcode-sdk] --> astrcode-core[astrcode-core] - astrcode-sdk[astrcode-sdk] --> astrcode-protocol[astrcode-protocol] + astrcode-protocol[astrcode-protocol] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-runtime-contract[astrcode-runtime-contract] --> astrcode-core[astrcode-core] + astrcode-runtime-contract[astrcode-runtime-contract] --> astrcode-llm-contract[astrcode-llm-contract] + astrcode-runtime-contract[astrcode-runtime-contract] --> astrcode-tool-contract[astrcode-tool-contract] astrcode-server[astrcode-server] --> astrcode-adapter-agents[astrcode-adapter-agents] astrcode-server[astrcode-server] --> astrcode-adapter-llm[astrcode-adapter-llm] astrcode-server[astrcode-server] --> astrcode-adapter-mcp[astrcode-adapter-mcp] @@ -38,35 +83,47 @@ graph TD astrcode-server[astrcode-server] --> astrcode-adapter-skills[astrcode-adapter-skills] astrcode-server[astrcode-server] --> astrcode-adapter-storage[astrcode-adapter-storage] astrcode-server[astrcode-server] --> astrcode-adapter-tools[astrcode-adapter-tools] - astrcode-server[astrcode-server] --> astrcode-application[astrcode-application] + astrcode-server[astrcode-server] --> astrcode-agent-runtime[astrcode-agent-runtime] + astrcode-server[astrcode-server] --> astrcode-context-window[astrcode-context-window] astrcode-server[astrcode-server] --> astrcode-core[astrcode-core] - astrcode-server[astrcode-server] --> astrcode-kernel[astrcode-kernel] - astrcode-server[astrcode-server] --> astrcode-plugin[astrcode-plugin] + astrcode-server[astrcode-server] --> astrcode-governance-contract[astrcode-governance-contract] + astrcode-server[astrcode-server] --> astrcode-host-session[astrcode-host-session] + astrcode-server[astrcode-server] --> astrcode-llm-contract[astrcode-llm-contract] + astrcode-server[astrcode-server] --> astrcode-plugin-host[astrcode-plugin-host] + astrcode-server[astrcode-server] --> astrcode-prompt-contract[astrcode-prompt-contract] astrcode-server[astrcode-server] --> astrcode-protocol[astrcode-protocol] - astrcode-server[astrcode-server] --> astrcode-session-runtime[astrcode-session-runtime] - astrcode-session-runtime[astrcode-session-runtime] --> astrcode-core[astrcode-core] - astrcode-session-runtime[astrcode-session-runtime] --> astrcode-kernel[astrcode-kernel] + astrcode-server[astrcode-server] --> astrcode-runtime-contract[astrcode-runtime-contract] + astrcode-server[astrcode-server] --> astrcode-support[astrcode-support] + astrcode-server[astrcode-server] --> astrcode-tool-contract[astrcode-tool-contract] + astrcode-support[astrcode-support] --> astrcode-core[astrcode-core] + astrcode-tool-contract[astrcode-tool-contract] --> astrcode-core[astrcode-core] + astrcode-tool-contract[astrcode-tool-contract] --> astrcode-governance-contract[astrcode-governance-contract] ``` ## Crate 依赖表 | Crate | Path | Internal Deps Count | Internal Deps | |---|---|---:|---| -| astrcode-adapter-agents | crates/adapter-agents | 1 | astrcode-core | -| astrcode-adapter-llm | crates/adapter-llm | 1 | astrcode-core | -| astrcode-adapter-mcp | crates/adapter-mcp | 2 | astrcode-adapter-prompt, astrcode-core | -| astrcode-adapter-prompt | crates/adapter-prompt | 1 | astrcode-core | -| astrcode-adapter-skills | crates/adapter-skills | 1 | astrcode-core | -| astrcode-adapter-storage | crates/adapter-storage | 1 | astrcode-core | -| astrcode-adapter-tools | crates/adapter-tools | 1 | astrcode-core | -| astrcode-application | crates/application | 3 | astrcode-core, astrcode-kernel, astrcode-session-runtime | -| astrcode-cli | crates/cli | 2 | astrcode-client, astrcode-core | +| astrcode-adapter-agents | crates/adapter-agents | 2 | astrcode-core, astrcode-support | +| astrcode-adapter-llm | crates/adapter-llm | 4 | astrcode-core, astrcode-governance-contract, astrcode-llm-contract, astrcode-prompt-contract | +| astrcode-adapter-mcp | crates/adapter-mcp | 5 | astrcode-core, astrcode-plugin-host, astrcode-prompt-contract, astrcode-runtime-contract, astrcode-support | +| astrcode-adapter-prompt | crates/adapter-prompt | 6 | astrcode-core, astrcode-governance-contract, astrcode-host-session, astrcode-prompt-contract, astrcode-support, astrcode-tool-contract | +| astrcode-adapter-skills | crates/adapter-skills | 2 | astrcode-core, astrcode-support | +| astrcode-adapter-storage | crates/adapter-storage | 3 | astrcode-core, astrcode-host-session, astrcode-support | +| astrcode-adapter-tools | crates/adapter-tools | 5 | astrcode-core, astrcode-governance-contract, astrcode-host-session, astrcode-support, astrcode-tool-contract | +| astrcode-agent-runtime | crates/agent-runtime | 6 | astrcode-context-window, astrcode-core, astrcode-llm-contract, astrcode-prompt-contract, astrcode-runtime-contract, astrcode-tool-contract | +| astrcode-cli | crates/cli | 3 | astrcode-client, astrcode-core, astrcode-support | | astrcode-client | crates/client | 1 | astrcode-protocol | +| astrcode-context-window | crates/context-window | 5 | astrcode-core, astrcode-llm-contract, astrcode-runtime-contract, astrcode-support, astrcode-tool-contract | | astrcode-core | crates/core | 0 | - | -| astrcode-eval | crates/eval | 2 | astrcode-core, astrcode-protocol | -| astrcode-kernel | crates/kernel | 1 | astrcode-core | -| astrcode-plugin | crates/plugin | 2 | astrcode-core, astrcode-protocol | -| astrcode-protocol | crates/protocol | 1 | astrcode-core | -| astrcode-sdk | crates/sdk | 2 | astrcode-core, astrcode-protocol | -| astrcode-server | crates/server | 13 | astrcode-adapter-agents, astrcode-adapter-llm, astrcode-adapter-mcp, astrcode-adapter-prompt, astrcode-adapter-skills, astrcode-adapter-storage, astrcode-adapter-tools, astrcode-application, astrcode-core, astrcode-kernel, astrcode-plugin, astrcode-protocol, astrcode-session-runtime | -| astrcode-session-runtime | crates/session-runtime | 2 | astrcode-core, astrcode-kernel | +| astrcode-eval | crates/eval | 3 | astrcode-core, astrcode-protocol, astrcode-support | +| astrcode-governance-contract | crates/governance-contract | 2 | astrcode-core, astrcode-prompt-contract | +| astrcode-host-session | crates/host-session | 8 | astrcode-agent-runtime, astrcode-core, astrcode-governance-contract, astrcode-plugin-host, astrcode-prompt-contract, astrcode-runtime-contract, astrcode-support, astrcode-tool-contract | +| astrcode-llm-contract | crates/llm-contract | 3 | astrcode-core, astrcode-governance-contract, astrcode-prompt-contract | +| astrcode-plugin-host | crates/plugin-host | 3 | astrcode-core, astrcode-governance-contract, astrcode-protocol | +| astrcode-prompt-contract | crates/prompt-contract | 1 | astrcode-core | +| astrcode-protocol | crates/protocol | 2 | astrcode-core, astrcode-governance-contract | +| astrcode-runtime-contract | crates/runtime-contract | 3 | astrcode-core, astrcode-llm-contract, astrcode-tool-contract | +| astrcode-server | crates/server | 19 | astrcode-adapter-agents, astrcode-adapter-llm, astrcode-adapter-mcp, astrcode-adapter-prompt, astrcode-adapter-skills, astrcode-adapter-storage, astrcode-adapter-tools, astrcode-agent-runtime, astrcode-context-window, astrcode-core, astrcode-governance-contract, astrcode-host-session, astrcode-llm-contract, astrcode-plugin-host, astrcode-prompt-contract, astrcode-protocol, astrcode-runtime-contract, astrcode-support, astrcode-tool-contract | +| astrcode-support | crates/support | 1 | astrcode-core | +| astrcode-tool-contract | crates/tool-contract | 2 | astrcode-core, astrcode-governance-contract | diff --git a/scripts/regressions.mjs b/scripts/regressions.mjs index c33a4544..f4317b9b 100644 --- a/scripts/regressions.mjs +++ b/scripts/regressions.mjs @@ -1,56 +1,38 @@ import { repoRoot, runWithInheritedOutput } from './hook-utils.mjs'; -// 阶段 0 基线回归套件：覆盖当前架构下的三条关键链路。 -// Why: 旧脚本仍引用已删除的 astrcode-runtime / astrcode-runtime-prompt， -// 会在 CI 中直接失败；这里改为锚定现存 crate 的等价回归测试。 +// 阶段 0 基线回归套件：覆盖当前架构下的关键链路。 const checks = [ { - name: 'session step execution regression', - command: 'cargo', - args: [ - 'test', - '-p', - 'astrcode-session-runtime', - '--lib', - 'turn::runner::step::tests::run_single_step_returns_cancelled_when_tool_cycle_interrupts', - ], - }, - { - name: 'tool cycle live/durable regression', + name: 'prompt build cache regression', command: 'cargo', args: [ 'test', '-p', - 'astrcode-session-runtime', + 'astrcode-adapter-prompt', '--lib', - 'turn::tool_cycle::tests::invoke_single_tool_emits_structured_and_live_events_immediately', + 'layered_builder::tests::inherited_cache_reuses_compact_summary_without_reusing_recent_tail', ], }, { - name: 'plugin capability regression', - command: 'cargo', - args: ['test', '-p', 'astrcode-plugin', '--test', 'v4_stdio_e2e'], - }, - { - name: 'prompt metrics regression', + name: 'agent loop basic lifecycle regression', command: 'cargo', args: [ 'test', '-p', - 'astrcode-session-runtime', + 'astrcode-agent-runtime', '--lib', - 'turn::request::tests::assemble_prompt_request_emits_prompt_metrics_for_final_prompt', + 'r#loop::tests::execute_empty_turn_emits_basic_lifecycle', ], }, { - name: 'prompt build cache regression', + name: 'tool dispatch round-trip regression', command: 'cargo', args: [ 'test', '-p', - 'astrcode-adapter-prompt', + 'astrcode-agent-runtime', '--lib', - 'layered_builder::tests::inherited_cache_reuses_compact_summary_without_reusing_recent_tail', + 'r#loop::tests::tool_dispatch_results_continue_back_to_provider', ], }, ]; From 65195a50461808ddb3ed85a8ddad5e75760855e2 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Sat, 25 Apr 2026 00:41:50 +0800 Subject: [PATCH 09/10] =?UTF-8?q?=F0=9F=94=A7=20fix(ci):=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=20deny.toml=20tokio=20wrappers=EF=BC=8C=E6=94=BE?= =?UTF-8?q?=E5=AE=BD=20eval=20runner=20=E8=B6=85=E6=97=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit deny.toml 的 tokio wrappers 列表包含已删除的 crate（application、 kernel、plugin、session-runtime），缺少新 crate（tool-contract、 agent-runtime、host-session、governance-contract 等）。 eval runner 测试超时从 3s 调整为 10s 以适应 CI 慢环境。 --- crates/eval/src/runner/mod.rs | 2 +- deny.toml | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/crates/eval/src/runner/mod.rs b/crates/eval/src/runner/mod.rs index d800cfe9..e8ca0c04 100644 --- a/crates/eval/src/runner/mod.rs +++ b/crates/eval/src/runner/mod.rs @@ -601,7 +601,7 @@ expected_outcome: concurrency: 2, keep_workspace: false, output: None, - timeout: Duration::from_secs(3), + timeout: Duration::from_secs(10), poll_interval: Duration::from_millis(20), auth_token: None, }) diff --git a/deny.toml b/deny.toml index 124781c5..9515724d 100644 --- a/deny.toml +++ b/deny.toml @@ -32,18 +32,20 @@ multiple-versions = "allow" deny = [ { name = "tokio", wrappers = [ - "astrcode-application", "astrcode-cli", "astrcode-client", "astrcode-core", "astrcode-eval", - "astrcode-kernel", - "astrcode-example-plugin", - "astrcode-plugin", "astrcode-adapter-llm", "astrcode-adapter-mcp", + "astrcode-adapter-prompt", "astrcode-adapter-storage", - "astrcode-session-runtime", + "astrcode-agent-runtime", + "astrcode-context-window", + "astrcode-governance-contract", + "astrcode-host-session", + "astrcode-plugin-host", + "astrcode-tool-contract", "astrcode-server", "axum", "hyper", From 9742eb05bb28f2bcbab8434bd2850cb0db76e018 Mon Sep 17 00:00:00 2001 From: whatevertogo Date: Sat, 25 Apr 2026 00:54:50 +0800 Subject: [PATCH 10/10] =?UTF-8?q?=F0=9F=94=A7=20fix(ci):=20mock=20server?= =?UTF-8?q?=20readFile=20=E7=BC=BA=E5=A4=B1=E6=96=87=E4=BB=B6=E6=97=B6?= =?UTF-8?q?=E8=BF=94=E5=9B=9E=E5=8D=A0=E4=BD=8D=E6=96=87=E6=9C=AC=E8=80=8C?= =?UTF-8?q?=E9=9D=9E=20panic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit core_end_to_end 测试的 mock server 在 fixture 文件不存在时 panic， CI 环境下偶发失败。改为返回占位文本让测试继续执行，由最终 report 断言统一判定通过/失败。 --- crates/eval/tests/core_end_to_end.rs | 3 ++- crates/server/src/agent_runtime_bridge.rs | 2 ++ crates/server/src/bootstrap/runtime.rs | 14 +++++++++++--- crates/server/src/main.rs | 16 +++++++++++----- crates/server/src/ports/app_session.rs | 14 +++----------- crates/server/src/ports/session_bridge.rs | 23 +---------------------- crates/server/src/session_runtime_port.rs | 1 - crates/server/src/session_use_cases.rs | 11 ----------- crates/server/src/tests/test_support.rs | 9 --------- 9 files changed, 30 insertions(+), 63 deletions(-) delete mode 100644 crates/server/src/session_use_cases.rs diff --git a/crates/eval/tests/core_end_to_end.rs b/crates/eval/tests/core_end_to_end.rs index 4cf498dd..89312207 100644 --- a/crates/eval/tests/core_end_to_end.rs +++ b/crates/eval/tests/core_end_to_end.rs @@ -935,7 +935,8 @@ impl MockStep { } fn read_workspace_file(working_dir: &Path, relative_path: &str) -> String { - fs::read_to_string(working_dir.join(relative_path)).expect("workspace file should read") + fs::read_to_string(working_dir.join(relative_path)) + .unwrap_or_else(|_| format!("[mock: file not found: {relative_path}]")) } fn write_workspace_file(working_dir: &Path, relative_path: &str, content: &str) { diff --git a/crates/server/src/agent_runtime_bridge.rs b/crates/server/src/agent_runtime_bridge.rs index 340842b3..3195f519 100644 --- a/crates/server/src/agent_runtime_bridge.rs +++ b/crates/server/src/agent_runtime_bridge.rs @@ -24,6 +24,7 @@ use crate::{ pub(crate) struct ServerAgentRuntimeBundle { pub agent_api: Arc, + #[cfg(test)] pub agent_control: Arc, pub subagent_executor: Arc, pub collaboration_executor: Arc, @@ -85,6 +86,7 @@ pub(crate) fn build_server_agent_runtime_bundle( ServerAgentRuntimeBundle { agent_api, + #[cfg(test)] agent_control, subagent_executor, collaboration_executor, diff --git a/crates/server/src/bootstrap/runtime.rs b/crates/server/src/bootstrap/runtime.rs index 84e4df3c..dcc654f8 100644 --- a/crates/server/src/bootstrap/runtime.rs +++ b/crates/server/src/bootstrap/runtime.rs @@ -13,7 +13,9 @@ use astrcode_adapter_storage::session::FileSystemSessionRepository; use astrcode_adapter_tools::builtin_tools::tool_search::ToolSearchIndex; use astrcode_core::SkillCatalog; use astrcode_governance_contract::GovernanceModeSpec; -use astrcode_host_session::{EventStore, SessionCatalog, SubAgentExecutor}; +#[cfg(test)] +use astrcode_host_session::SubAgentExecutor; +use astrcode_host_session::{EventStore, SessionCatalog}; use astrcode_plugin_host::{ CommandDescriptor, PluginActiveSnapshot, PluginDescriptor, PluginRegistry, ProviderContributionCatalog, ResourceCatalog, builtin_collaboration_tools_descriptor, @@ -42,13 +44,13 @@ use super::{ runtime_coordinator::RuntimeCoordinator, watch::{bootstrap_profile_watch_runtime, build_watch_service}, }; +#[cfg(test)] +use crate::{agent_control_bridge::ServerAgentControlPort, profile_service::ServerProfileService}; use crate::{ - agent_control_bridge::ServerAgentControlPort, config_service_bridge::ServerConfigService, governance_service::ServerGovernanceService, mcp_service::ServerMcpService, mode_catalog_service::ServerModeCatalog, - profile_service::ServerProfileService, runtime_owner_bridge::{ ServerRuntimeObservability, ServerTaskRegistry, builtin_server_mode_specs, }, @@ -64,10 +66,13 @@ const EXTERNAL_PLUGIN_MODES_PLUGIN_ID: &str = "external-plugin-modes"; /// 服务器运行时：组合根输出。 pub struct ServerRuntime { pub agent_api: Arc, + #[cfg(test)] pub agent_control: Arc, pub config: Arc, pub session_catalog: Arc, + #[cfg(test)] pub profiles: Arc, + #[cfg(test)] pub subagent_executor: Arc, pub mcp_service: Arc, pub skill_catalog: Arc, @@ -347,10 +352,13 @@ pub async fn bootstrap_server_runtime_with_options( Ok(ServerRuntime { agent_api: agent_runtime.agent_api, + #[cfg(test)] agent_control: agent_runtime.agent_control, config: config_service, session_catalog, + #[cfg(test)] profiles, + #[cfg(test)] subagent_executor: agent_runtime.subagent_executor, mcp_service, skill_catalog: skill_catalog_bridge, diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index 6d0ff1f2..4429ddaf 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -101,8 +101,6 @@ mod session_identity; mod session_runtime_owner_bridge; #[path = "session_runtime_port.rs"] mod session_runtime_port; -#[path = "session_use_cases.rs"] -mod session_use_cases; #[path = "http/terminal_projection.rs"] mod terminal_projection; #[cfg(test)] @@ -120,7 +118,9 @@ use std::{net::SocketAddr, path::PathBuf, sync::Arc}; pub(crate) use agent::AgentOrchestrationService; use anyhow::{Result as AnyhowResult, anyhow}; use astrcode_core::{AstrError, SkillCatalog}; -use astrcode_host_session::{SessionCatalog, SubAgentExecutor}; +use astrcode_host_session::SessionCatalog; +#[cfg(test)] +use astrcode_host_session::SubAgentExecutor; use astrcode_plugin_host::ResourceCatalog; use axum::{ Json, Router, @@ -153,6 +153,8 @@ pub(crate) use ports::{ use serde::Serialize; use tokio::io::{AsyncRead, AsyncReadExt}; +#[cfg(test)] +use crate::profile_service::ServerProfileService; use crate::{ agent_api::ServerAgentApi, application_error_bridge::ServerRouteError, @@ -165,7 +167,6 @@ use crate::{ governance_service::ServerGovernanceService, mcp_service::ServerMcpService, mode_catalog_service::ServerModeCatalog, - profile_service::ServerProfileService, routes::build_api_router, }; @@ -181,19 +182,21 @@ pub(crate) const AUTH_HEADER_NAME: &str = "x-astrcode-token"; /// 包含运行时入口、server 侧 owner bridge、治理模型、认证管理器和前端构建产物。 /// 所有字段均为 `Arc` 或可 `Clone` 类型，支持多线程共享。 #[derive(Clone)] -#[allow(dead_code)] pub(crate) struct AppState { /// server-owned agent route bridge；agent routes 不再经由 `application::agent` 用例入口。 agent_api: Arc, /// server-owned agent control bridge；测试和路由不直接暴露底层 kernel。 + #[cfg(test)] agent_control: Arc, /// server-owned 配置服务桥接；配置/模型 API 不再经由 App 访问配置。 config: Arc, /// server-owned 会话目录桥接；catalog API 不再经由 App 访问 session catalog。 session_catalog: Arc, /// server-owned profile resolver；watch/profile 测试不再经由 `App::profiles()`. + #[cfg(test)] profiles: Arc, /// subagent 启动桥接；测试直接消费 host-session 合同。 + #[cfg(test)] subagent_executor: Arc, /// server-owned MCP service；MCP API 不再经由 App facade。 mcp_service: Arc, @@ -377,10 +380,13 @@ async fn main() -> AnyhowResult<()> { let state = AppState { agent_api: Arc::clone(&runtime.agent_api), + #[cfg(test)] agent_control: Arc::clone(&runtime.agent_control), config: Arc::clone(&runtime.config), session_catalog: Arc::clone(&runtime.session_catalog), + #[cfg(test)] profiles: Arc::clone(&runtime.profiles), + #[cfg(test)] subagent_executor: Arc::clone(&runtime.subagent_executor), mcp_service: Arc::clone(&runtime.mcp_service), skill_catalog: Arc::clone(&runtime.skill_catalog), diff --git a/crates/server/src/ports/app_session.rs b/crates/server/src/ports/app_session.rs index f1ffd22f..06985e1e 100644 --- a/crates/server/src/ports/app_session.rs +++ b/crates/server/src/ports/app_session.rs @@ -15,12 +15,9 @@ use async_trait::async_trait; use tokio::sync::broadcast; use super::{AppAgentPromptSubmission, DurableSubRunStatusSummary}; -use crate::{ - conversation_read_model::{ - ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionReplay, - SessionTranscriptSnapshot, - }, - session_use_cases::SessionForkSelector, +use crate::conversation_read_model::{ + ConversationSnapshotFacts, ConversationStreamReplayFacts, SessionReplay, + SessionTranscriptSnapshot, }; /// `App` 依赖的 session 稳定端口。 @@ -33,11 +30,6 @@ pub trait AppSessionPort: Send + Sync { async fn list_session_metas(&self) -> astrcode_core::Result>; async fn create_session(&self, working_dir: String) -> astrcode_core::Result; - async fn fork_session( - &self, - session_id: &str, - selector: SessionForkSelector, - ) -> astrcode_core::Result; async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()>; async fn delete_project(&self, working_dir: &str) -> astrcode_core::Result; diff --git a/crates/server/src/ports/session_bridge.rs b/crates/server/src/ports/session_bridge.rs index e6fdc0fc..3a8fca50 100644 --- a/crates/server/src/ports/session_bridge.rs +++ b/crates/server/src/ports/session_bridge.rs @@ -12,8 +12,7 @@ use astrcode_core::{ }; use astrcode_governance_contract::ModeId; use astrcode_host_session::{ - ForkPoint, InputQueueProjection, ProjectedTurnOutcome, SessionCatalog, SubRunHandle, - replay_records, + InputQueueProjection, ProjectedTurnOutcome, SessionCatalog, SubRunHandle, replay_records, }; use astrcode_runtime_contract::ExecutionAccepted; use async_trait::async_trait; @@ -31,7 +30,6 @@ use crate::{ }, session_identity::normalize_external_session_id, session_runtime_port::SessionRuntimePort, - session_use_cases::SessionForkSelector, }; pub(crate) fn build_server_session_bridge( @@ -54,7 +52,6 @@ impl ServerSessionBridge { SessionId::from(normalize_external_session_id(session_id)) } - #[allow(dead_code)] async fn replay_history( &self, session_id: &SessionId, @@ -69,7 +66,6 @@ impl ServerSessionBridge { Ok(replay_records(&stored, last_event_id)) } - #[allow(dead_code)] async fn session_phase( &self, session_id: &SessionId, @@ -142,23 +138,6 @@ impl AppSessionPort for ServerSessionBridge { self.session_catalog.create_session(working_dir).await } - async fn fork_session( - &self, - session_id: &str, - selector: SessionForkSelector, - ) -> astrcode_core::Result { - let fork_point = match selector { - SessionForkSelector::Latest => ForkPoint::Latest, - SessionForkSelector::TurnEnd { turn_id } => ForkPoint::TurnEnd(turn_id), - SessionForkSelector::StorageSeq { storage_seq } => ForkPoint::StorageSeq(storage_seq), - }; - let result = self - .session_catalog - .fork_session(&Self::session_id(session_id), fork_point) - .await?; - self.session_meta(result.new_session_id.as_str()).await - } - async fn delete_session(&self, session_id: &str) -> astrcode_core::Result<()> { self.session_catalog .delete_session(&Self::session_id(session_id)) diff --git a/crates/server/src/session_runtime_port.rs b/crates/server/src/session_runtime_port.rs index 797877e4..e54b38cc 100644 --- a/crates/server/src/session_runtime_port.rs +++ b/crates/server/src/session_runtime_port.rs @@ -20,7 +20,6 @@ use crate::{ #[path = "session_runtime_port_adapter.rs"] pub(crate) mod adapter; -#[allow(dead_code)] #[async_trait] pub(crate) trait SessionRuntimePort: Send + Sync { async fn submit_prompt_for_agent( diff --git a/crates/server/src/session_use_cases.rs b/crates/server/src/session_use_cases.rs deleted file mode 100644 index 0a4e3f5f..00000000 --- a/crates/server/src/session_use_cases.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! server 私有的 session fork 选择枚举。 -//! -//! 只保留 `ports::app_session` 需要的最小类型定义。 - -#[allow(dead_code)] -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum SessionForkSelector { - Latest, - TurnEnd { turn_id: String }, - StorageSeq { storage_seq: u64 }, -} diff --git a/crates/server/src/tests/test_support.rs b/crates/server/src/tests/test_support.rs index 28292bbd..6f747487 100644 --- a/crates/server/src/tests/test_support.rs +++ b/crates/server/src/tests/test_support.rs @@ -33,7 +33,6 @@ use crate::{ AppSessionPort, DurableSubRunStatusSummary, SessionObserveSnapshot, SessionTurnTerminalState, }, - session_use_cases::SessionForkSelector, watch_service::{WatchEvent, WatchPort, WatchService, WatchSource}, }; @@ -236,14 +235,6 @@ impl AppSessionPort for StubSessionPort { unimplemented_for_test("server test stub") } - async fn fork_session( - &self, - _session_id: &str, - _selector: SessionForkSelector, - ) -> astrcode_core::Result { - unimplemented_for_test("server test stub") - } - async fn delete_session(&self, _session_id: &str) -> astrcode_core::Result<()> { unimplemented_for_test("server test stub") }