Skip to content

runtime-module-boundaries.md

Latest commit

 

History

History
225 lines (191 loc) · 21.1 KB

runtime-module-boundaries.md

File metadata and controls

225 lines (191 loc) · 21.1 KB
Raw

Runtime Module Boundaries

更新时间：2026-03-20

目标

明确全局 runtime 平台能力与 MCP 子域能力边界，避免配置与诊断入口继续耦合在单个 MCP runtime 包。

模块职责

  • runtime/config
    • 统一配置加载（YAML + env + default）
    • 配置校验与 fail-fast 启动
    • 热更新与原子快照切换
    • MCP profile 解析（作为配置字段的一部分）
  • runtime/diagnostics
    • 统一诊断数据模型与有界存储
    • call/run/reload/skill 记录与查询
    • 配置脱敏输出辅助
  • orchestration/composer
    • library-first 组合入口，统一装配 runner + workflow + teams + a2a + scheduler
    • 负责组合层接缝与调度桥接，不吸收 provider 协议逻辑或 transport 内部细节
    • 组合路径摘要仅通过标准事件注入（run.finished additive 字段），不直接写 diagnostics store
    • recovery 编排（load/validate/reconcile/resume）仅由 composer 收口；恢复快照与重放结果必须经标准事件进入 RuntimeRecorder 单写路径
  • orchestration/invoke
    • 统一同步远程调用抽象（submit + wait + normalize）
    • 负责 A2A 终态收敛、context 优先取消/超时语义、错误分层与 retryable 提示归一
    • 仅提供 orchestration 复用能力，不持有调度状态，也不直接写 diagnostics store
  • orchestration/teams
    • Teams 协作编排基线（serial|parallel|vote）
    • Mixed local/remote worker 执行目标（target=local|remote）与统一任务生命周期
    • 角色与任务生命周期语义（leader|worker|coordinator + pending/running/succeeded/failed/skipped/canceled）
    • 通过标准事件发射 Teams timeline/摘要元数据（含 team.dispatch_remote/team.collect_remote，不直接写 diagnostics store）
  • orchestration/workflow
    • Workflow DSL 基线（step/depends_on/condition/retry/timeout）解析与静态 DAG 校验
    • A2A remote step（kind=a2a）在现有 adapter 下执行，复用 workflow retry/timeout/checkpoint 语义
    • 确定性调度、重试/超时、checkpoint/resume 执行语义
    • 通过标准事件发射 Workflow timeline/摘要元数据（含 workflow.dispatch_a2a，不直接写 diagnostics store）
  • a2a
    • A2A 最小互联能力（submit/status/result）与任务生命周期语义
    • Agent Card 能力发现与确定性路由输入（静态注册 + capability 匹配）
    • A2A delivery 模式协商与降级（callback|sse）以及版本协商（strict_major + min_supported_minor）仅在 a2a/* 实现，不下沉到 MCP 传输层
    • 保留并透传组合编排关联字段（workflow_id/team_id/step_id/task_id/agent_id/peer_id）
    • 通过标准事件发射 A2A timeline/摘要元数据（不直接写 diagnostics store）
  • adapter/manifest
    • 外部 adapter manifest 合同解析、字段校验与兼容范围判定（manifest template contract）
    • 激活边界 fail-fast（missing/invalid/compat-mismatch/required-missing）
    • 输出 deterministic 合同错误分类，供 conformance 与 gate 回归复用
  • adapter/capability
    • requested vs declared capability 协商（capability negotiation contract）
    • 策略收敛：fail_fast|best_effort 与 override 语义
    • reason taxonomy 收敛：adapter.capability.* 命名空间
  • model/catalog
    • library-owned immutable provider/model descriptor catalog and redacted credential-evidence admission evaluation
    • reuses adapter/capability; does not perform provider discovery, network probes, credential storage, or diagnostics writes
    • freezes normalized catalog generation and admission facts for a Run or Stream before provider execution
    • owns the bounded model_catalog_routing_admission.v1 normalization/audit and the explicitly opt-in pure candidate resolver; resolver inputs are host-supplied and never become a global mutable router
  • model/openai / model/anthropic / model/gemini
    • 各自拥有 provider-native tool call/result、thinking、usage、Unicode/empty content 与 stream edge 到 canonical contract 的转换。
    • model/toolcontract.InterpretRequest 只提供无 SDK 依赖的 canonical request facts；官方 SDK request builder、system/user/assistant 映射和 native tool-result/function-response part 必须留在对应 provider 包内。
    • Generate、Stream 与 CountTokens 复用相同 canonical facts；SDK 不可表达的 token-count 字段只能记录为明确 capability exception，不得退化成文本信封。
    • capability/request-shape fallback 只能发生在 model step 调用前；首个语义 stream event 是不可跨越的 provider-switch fence。
    • core/runner 只消费 canonical values 并拥有 step、terminal 与 Run/Stream parity；禁止抽取新的共享 wire protocol 或把 Provider SDK 引入 context/*。
  • context/budgetprojection
    • 只拥有 budget_projection.v1 有界只读派生投影契约与离线预算利用 benchmark。
    • 只依赖标准库：不 import runtime/*、orchestration/*、model/*、observability/*，因此不会形成 context → runtime 反向依赖，也不构成第二本预算账本。
    • 预算事实仍由 runtime/config（ReAct iteration/tool-call limit、budget_admission.v1 的 cost/latency 决策）、orchestration/scheduler（ParentRemainingBudget）与 core/runner（React Plan Notebook）各自拥有；投影不写回、不参与终态判定。
  • extension
    • transport-neutral descriptor、source precedence、digest provenance 与 capability/admission 合同
    • external authoring conformance 仅消费 extension/adapter/policy/sandbox 的 source-owned 投影；不执行不受信任源码、不拥有第二套生命周期或终态状态机
    • bounded Hook/tool execution、turn snapshot/save-point、activation generation/reload/rollback
    • 不直接写 diagnostics；生命周期事件必须经 observability/event.RuntimeRecorder
  • adapter/scaffold
    • 外部 adapter 脚手架生成与模板收口
    • 生成 manifest/conformance/negotiation baseline 测试骨架
    • 通过 drift gate 维持模板与主线契约一致
  • orchestration/scheduler
    • 分布式 subagent 调度基线（enqueue/claim/heartbeat/lease_expire/requeue/complete/fail）
    • QoS 治理能力（scheduler.qos.mode + fairness 窗口 + retry backoff + DLQ）仅在该模块内实现
    • 维护 task/attempt/lease 状态机与 terminal commit 幂等语义（task_id+attempt_id）
    • parent-child guardrail（max_depth|max_active_children|child_timeout_budget）fail-fast 拒绝
    • 通过标准事件发射 Scheduler/Subagent timeline（scheduler.* / subagent.*，不直接写 diagnostics store）
  • orchestration/snapshot
    • 统一 state/session snapshot manifest 合同（schema/version/segment/digest）
    • 导入策略固定为 strict|compatible + compat_window，冲突场景 fail-fast
    • operation 级幂等导入语义（duplicate import -> no-op）只在合同层实现
    • 不直接写 diagnostics store；观测仍经标准事件单写路径收口
  • mcp/profile
    • MCP profile 常量与策略解析（仅 MCP 语义）
  • mcp/retry
    • MCP 重试控制（retryable 分类 + backoff）
  • mcp/diag
    • MCP 调用摘要字段模型与本地有界缓存
  • mcp/internal/reliability
    • MCP 内部共享重试/超时/backoff 执行骨架（internal-only）
  • mcp/internal/observability
    • MCP 内部共享事件发射与诊断映射桥接（internal-only）
  • mcp/http / mcp/stdio
    • 传输实现
    • 消费 runtime/config.Manager 配置与诊断 API
  • core/runner / tool/local / skill/loader
    • 消费全局 runtime 配置快照
    • 产出标准运行时事件（不直接写诊断存储）
    • tool/local 负责工具调用实际执行；工具生命周期合同仅对其既有 lookup/validation/policy/sandbox/middleware/retry/panic/finalize 边界做 transport-neutral 投影，不拥有第二套 Tool 状态机或 hosted executor
    • dynamic action resume 只保存 opaque action reference、checkpoint metadata 和 idempotency facts；PendingAction 业务正文、授权、确认策略与 executor 仍由 Application/adapter 拥有。该路径与 Realtime resume、retry、follow-up promotion 分离。
  • tool/schemaaudit
    • 只接收宿主已经准入的 bounded provider-neutral tool snapshot，负责 schema canonical facts、pressure、synthetic quality 与有限策略的离线比较。
    • 不调用 tool/local、MCP、Provider SDK/tokenizer，不访问网络/文件/时钟/credential，不修改 registry、allowlist、sandbox、Skill、ModelRequest 或运行时配置；raw schema 只允许在内存 canonicalization 阶段出现。
    • Eval corpus/Badcase 只作为 optional advisory；replay 与 Run/Stream parity 只比较有界 normalized facts，不能形成第二 admission、selector、router 或 terminal 状态机。
  • observability/event
    • 事件日志与分发
    • RuntimeRecorder 作为诊断唯一写入入口，将事件映射为统一诊断记录

依赖方向

允许方向（简化）：

runtime/* -> (no dependency on mcp/http or mcp/stdio)

mcp/*, core/*, tool/*, skill/*, observability/*, orchestration/*, adapter/* -> runtime/*

禁止方向：

  • runtime/config 或 runtime/diagnostics 反向依赖 mcp/http / mcp/stdio
  • 非 mcp/* 包依赖 mcp/internal/*
  • Teams 编排直接写 runtime/diagnostics 存储（必须经 observability/event.RuntimeRecorder 单写入口）
  • Workflow 编排直接写 runtime/diagnostics 存储（必须经 observability/event.RuntimeRecorder 单写入口）
  • A2A 模块直接写 runtime/diagnostics 存储（必须经 observability/event.RuntimeRecorder 单写入口）
  • Adapter 契约模块直接写 runtime/diagnostics 存储（必须经标准事件/门禁链路收口）
  • Extension 不得绕过 runtime/config readiness/policy、sandbox/allowlist 或 RuntimeRecorder 单写入口
  • External authoring conformance 只能离线验证既有 owner；fixture/replay 不得访问网络、写入运行时诊断或修改 workspace/source state
  • Scheduler 模块直接写 runtime/diagnostics 存储（必须经 observability/event.RuntimeRecorder 单写入口）
  • Composer 模块直接写 runtime/diagnostics 存储（必须经 observability/event.RuntimeRecorder 单写入口）
  • 将 peer 协作语义下沉到 mcp/*（A2A/MCP 职责重叠）
  • 在 adapter/* 之外重复实现 manifest/capability 合同解析，造成错误分类与回放语义漂移
  • model/catalog 或 runtime/* 进行远程 model discovery、background refresh、credential storage，或持久化 credential material
  • provider/model admission 绕过 adapter/capability、runtime/config readiness aggregation，或 RuntimeRecorder 单写入口

CI 通过 scripts/check-runtime-boundaries.sh 做静态检查。 治理型评审可结合 docs/modular-e2e-review-matrix.md 执行“模块 + 主干链路”双视角核验。

R4 多代理共享契约前置门禁（阻断级）：

  • Linux/macOS: bash scripts/check-multi-agent-shared-contract.sh
  • Windows: pwsh -File scripts/check-multi-agent-shared-contract.ps1
  • required-check 候选: multi-agent-shared-contract-gate
  • Scheduler/Subagent 收口要求：reason 必须为 scheduler.*|subagent.*，且 scheduler 管理路径需携带 task_id / attempt_id 关联字段。
  • Scheduler QoS 收口要求：scheduler.qos_claim|scheduler.fairness_yield|scheduler.retry_backoff|scheduler.dead_letter 必须经 timeline 事件进入 RuntimeRecorder 单写路径。
  • Composer 收口要求：orchestration/composer 仅做 orchestration glue；scheduler fallback 与子任务摘要信号必须以事件方式进入 RuntimeRecorder 单写路径。
  • Recovery 收口要求：orchestration/composer 负责恢复状态机与冲突终止语义（fail_fast）；恢复 reason（recovery.restore|recovery.replay|recovery.conflict）与 run 摘要字段必须走事件单写入口。
  • 明确禁止：orchestration/scheduler 直接写 runtime/diagnostics（必须经 observability/event.RuntimeRecorder 单写入口）。

Owner 建议

  • runtime/config：平台基础设施 owner
  • runtime/diagnostics：可观测性 owner
  • mcp/profile、mcp/retry、mcp/diag：MCP owner
  • skill/loader：Skill owner

扩展约束

Agent Runtime Protocol 投影边界

core/types 中的 Agent Runtime Protocol 对象（Session/Run/Step/Event/Artifact/Checkpoint）只提供面向嵌入宿主的稳定引用和关联字段，不拥有第二套执行状态、存储或传输实现。映射必须单向保留 source module：

  • core/runner 负责 Run/Stream、模型/工具步骤与终止语义；
  • orchestration/workflow、teams、scheduler 分别负责 DAG、协作和 attempt/lease 状态；
  • a2a 负责 peer Task、Agent Card、delivery/version 协商；
  • core/types realtime 与 core/runner 负责 realtime event、cursor、seq、dedup、interrupt/resume；
  • orchestration/snapshot 负责 checkpoint manifest、schema、digest、restore policy 和 import idempotency；
  • checkpoint history/workspace provenance 仅由 core/types 与 orchestration/snapshot 做 reference-only projection；snapshot 仍是唯一事实源，workspace/sandbox 仍拥有副作用与 policy，禁止新增第二套 store、workspace filesystem 或 control plane；
  • observability/event.RuntimeRecorder 继续是 diagnostics 唯一写入入口，protocol 映射只能复用标准事件路径。
  • Durable runtime event-stream binding 仅由 core/types/core/runner 做 transport-neutral source projection；Realtime 保持 cursor/history/sequence/dedup/interrupt-resume 所有权。禁止在 binding 层新增 listener、connection manager、hosted Event/Session service、external event store、global queue 或 control plane。
  • Embedded host coordinator (host) 仅维护 connection-scoped bounded correlation、pending 收口与 serialized delivery；命令 admission、source control、terminal recovery、event subscription、steering/follow-up admission 和 diagnostics 事实分别委托既有 owner。host/jsonl 只负责 strict LF framing，cmd/host-jsonl 保持 stdout protocol-only、stderr diagnostics。Host facts 必须经注入的 types.EventHandler 进入 RuntimeRecorder，不得直接写 runtime/diagnostics。只有 source 返回的 durable Realtime projection 同时声明 drop_with_record 与 source outcome 时，delta 才可按有界队列压力丢弃并记录；direct Runner callback、非 delta 事件或无标准 EventSink 时一律 non-droppable。Steering 只在 core/runner 的既有 safe point 应用，follow-up 只通过既有 Run/Stream admission path 晋升；Host 不拥有输入队列、Session history、terminal state 或 Realtime cursor。不引入新 runtime 配置、hosted listener、global queue 或平行生命周期状态机。
  • Event-stream terminal recovery 仅组合 source-owned binding、terminal outcome 与 retained facts 投影；observer disconnect/stop 不得改变 Run lifecycle 或触发 retry/resume。terminal conflict 必须经既有 arbiter 记录，禁止新增第二套 terminal state machine、binding queue、history store 或恢复 worker。
  • ProtocolDescriptor、bounded Session context 与 same-Session admission outcome 是 opt-in、side-effect-free projection；Runner、Composer/Workflow、Teams、Scheduler、A2A、Realtime 继续拥有授权、队列、锁、分支、取消与持久化事实。
  • capability negotiation 复用 adapter 的 required/optional、fail_fast|best_effort 与 reason taxonomy；descriptor 的 action availability 不等于 authorization。

该投影不得引入 hosted REST/SSE 网关、session/artifact store、Redis Stream 或其他平台控制面依赖；也不得把 A2A、MCP、Realtime、Snapshot 的 source-of-truth 语义改写为平行协议。

  • 新增全局配置字段时，必须同步：
    • runtime/config schema + validation
    • docs/runtime-config-diagnostics.md 字段索引
  • 新增诊断记录类型时，必须同步：
    • runtime/diagnostics record 定义
    • 文档中的字段与语义说明

全局限制（职责分工重点）

  • Context Assembler 与 Model Provider 的职责必须分离：
    • context/assembler 只做策略编排与触发时机控制（例如 CA3 压力分区、阈值判定、计数调用节流）。
    • model/* 负责 provider 协议细节与官方 SDK 调用（包括 token count、能力探测、流式映射）。
  • 禁止在 context/* 中直接引入 provider 官方 SDK（OpenAI/Anthropic/Gemini），避免跨层耦合与升级扩散。
  • context/handoff 只定义有界交接 DTO、验证和恢复投影，不拥有或复制 Session History、Checkpoint、Snapshot、Artifact 正文。
  • 任何新增 provider 级能力（例如 token count、模型元数据查询）应先落在 model/<provider>，再由上层通过接口复用。
  • Provider/model catalog is host-injected bounded metadata, not a provider SDK client. Provider protocol and token-accounting details remain in model/<provider>; context/* remains forbidden from importing provider SDKs.

Session history and replay boundary

Action capability evidence audit boundary

tool/diagnosticsreplay/action_capability_audit.go is a read-only, offline consumer of host-admitted bounded Action capability snapshots. Action Gate/parameter rules own authorization and approval; tool/local lifecycle owners retain dispatch, retry, attempt and finalization facts; Policy/Sandbox own security decisions; action timeline owns sequencing; and observability/event.RuntimeRecorder remains the only diagnostics writer. The audit owns neither execution, retry, compensation, terminal state nor persistent Action state.

The action_capability_audit.v1 fixture uses reference-only identity, version/digest, scope, attempt/correlation, stage/status and bounded summary fields. It excludes Tool/MCP/Provider invocation, network, registry, filesystem, credentials, clocks, payload bodies, reasoning, complete command output and unbounded responses. It introduces no runtime configuration, hosted execution/session store, global queue, dynamic registry/download path, direct diagnostic writer or second terminal state machine. Rollback removes the offline audit adapter, fixture and gate only; existing Run/Stream and source-owner semantics remain unchanged.

Capability asset provenance and release rollback audit boundary

tool/diagnosticsreplay/capability_asset_provenance.go is a bounded, read-only, offline consumer of host-owned Skill, extension, adapter, memory, context, and evaluation metadata. It normalizes stable identity, version/digest, owner, scope, dependency, consumer, withdrawal-impact, and replacement-compatibility references; it does not activate, withdraw, publish, or roll back assets. Existing owner modules remain authoritative for lifecycle and policy decisions.

The capability_asset_provenance.v1 projection excludes raw prompt/transcript/reasoning, credentials, workspace content, provider SDK calls, network access, dynamic registries, marketplace resolution, hosted persistence, and direct RuntimeRecorder writes. Replay and Run/Stream parity compare only bounded normalized facts. Rollback removes the projection adapter, fixtures, replay entry point, documentation, and gates without persistence migration or runtime behavior changes.

Session message history remains source-owned by the embedding host/session adapter. core/types provides bounded reference validation; orchestration/snapshot validates history/checkpoint context before source-owned restore; tool/diagnosticsreplay performs offline read-only normalization. No runtime package introduces a session database, hosted gateway, provider SDK dependency, artifact content service, or second state fact source.

Durable task/attempt workspace and completion boundary

orchestration/scheduler remains the owner of task, attempt, lease, retry/rollover, stale-attempt, and terminal-commit state. WorkspaceProvenance is an additive, nullable, reference-only association; scheduler validates correlation but never resolves or mutates workspace contents. orchestration/mailbox owns durable completion delivery, while core/runner owns completion-reference admission and application at its existing runtime-input safe point. No completion queue or parallel terminal/coordination FSM is permitted.

orchestration/snapshot and orchestration/composer perform pre-mutation association/integrity reconciliation under existing strict|compatible and compat_window rules. Replay (tool/diagnosticsreplay) is offline and side-effect free. New references/classifications are bounded and privacy-preserving: workspace paths/content, Git metadata, completion bodies, reasoning, credentials, and unbounded payloads are excluded from snapshots, diagnostics, and OTel. Diagnostics continue through observability/event.RuntimeRecorder only.

This boundary introduces no runtime configuration keys or hot-update semantics; existing scheduler/mailbox/recovery/snapshot/runtime-input settings keep env > file > default. Rollback removes additive references, fixtures, and gates without migration; legacy scheduler, mailbox, snapshot, and Run/Stream behavior remains valid. Git/worktree managers, workspace stores, hosted artifact services, runtime Git/shell execution, automatic merge/push, and parallel task/session state machines remain explicit non-goals.