ordin 0.1.0__tar.gz

ordin-0.1.0/.env.example

@@ -0,0 +1,7 @@
+LLM_API_BASE=https://your-vllm-host.example/v1
+LLM_API_KEY=replace-with-a-test-key
+LLM_MODEL=/models/Qwen3.5-9B
+LLM_TOOL_CALL_PARSER=hermes
+
+# Optional: required only by PostgreSQL integration tests.
+# TEST_DATABASE_URL=postgresql://user:password@localhost:5432/arbor_test

ordin-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.ty/
+dist/
+build/
+*.egg-info/
+.env

ordin-0.1.0/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+- 不要保留向后兼容性。应直接移除过时的路径，而不是增加兼容层、回退逻辑或迁移机制。
+- 选择能够完整满足当前需求的最简单实现。避免引入推测性的抽象、配置和间接层。
+- 以分层方式逐步扩展系统。先实现一个能够端到端工作的最小版本，再在已经可用的产品基础上逐步增加新能力。绝不要为了尚未完成的复杂性而牺牲一个已经能正常工作的产品。
+- 保持组件模块化，并清晰分离各自的职责，高内聚，低耦合，合理抽象复用，组合优于继承，形成可维护和可拓展架构。
+- 当成熟且维护良好的库能够降低整体复杂度或提高可靠性时，优先使用这些库。除非有明确理由，否则不要重复实现常见功能。
+- 在自行实现功能或添加新依赖之前，优先充分利用项目中已有的依赖。不要在未检查相关文档和类型定义之前，就假设某个库不具备所需能力。
+- 从长期角度做架构决策。不要接受只能暂时使用、之后注定需要被替换的权宜方案。
+
+## 文档结构与同步要求
+
+- `README.md` 只维护项目定位、安装、最小示例和文档入口。
+- `docs/architecture/` 是当前架构合同；`docs/modules/` 说明公开模块；`docs/guides/` 和
+  `examples/` 提供可运行用法；`docs/reference/` 保存生成参考；`docs/adr/` 保存长期架构决策。
+- 已完成的实施计划不得作为当前文档长期保留。长期有效的决策应写入 ADR，实施过程由 Git、
+  Issue 或 PR 保存。
+- `docs/reference/code-tree.md` 与 `docs/reference/public-api.md` 由 `scripts/docs.py` 生成，禁止
+  手工编辑。文件树必须覆盖仓库中实际跟踪的源码、测试、Notebook、文档、示例和项目配置，且
+  排除缓存、虚拟环境、构建产物和临时文件。
+- 架构图和调用流程时序图统一使用 Mermaid，并使用代码中的真实包、类型、方法、状态和事件名。
+- 模块文档必须说明职责、非职责、公开入口、核心模型、真实调用路径、最小示例、失败语义、事件、
+  对应源码和对应测试。
+- Markdown 中的 Python 示例必须能够编译；关键端到端示例必须放在 `examples/` 并由测试执行。
+
+每次开发任务开始时必须判断文档影响。发生以下任一变化时，必须在同一任务中更新文档：
+
+- 新增、删除、移动或重命名模块和文件；
+- 修改公开 API、构造参数、返回类型或异常语义；
+- 修改 Runtime、Supervisor、Planner、Agent、Runner 或 Aggregator 的调用流程；
+- 修改 Mission、Task、ExecutionPlan、AgentInstance、Context 或持久化模型；
+- 新增或修改 RuntimeEvent、LLM operation、Tool、Skill、配置项、Artifact 或恢复语义；
+- 新增关键扩展点或用户可见行为。
+
+如果代码变化不需要更新文档，最终结果必须明确说明原因，不得默认省略。
+
+## 开发任务完成前的必需校验
+
+- 每次开发任务完成前，必须依次执行以下命令：
+
+  ```bash
+  uv run python scripts/docs.py --check
+  uv run pytest tests/test_docs.py
+  uv run ruff format .
+  uv run ruff check .
+  uv run ty check
+  uv run pytest
+  ```
+
+- 只有生成文档无漂移、文档测试、格式化、静态检查、类型检查和完整测试全部通过后，才能将任务
+  标记为完成。
+- 如果检查因环境限制或与本次任务无关的既有问题无法通过，必须在最终结果中明确列出未通过的命令、错误原因和影响范围，不得省略或声称全部通过。

ordin-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: ordin
+Version: 0.1.0
+Summary: Platform-independent runtime for centrally orchestrated agent execution
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: openai>=2.53.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: pyyaml>=6.0.2
+Description-Content-Type: text/markdown
+
+# Ordin Agent Runtime
+
+Ordin 是一个模型中立、平台无关的 Python Agent Runtime。宿主平台提供已认证身份、持久化的用户消息、
+Conversation 引用、不可变资源快照和运行时 Ports；Ordin 执行完整 Agent 链路：意图识别、
+direct/clarify/Mission 路由、Task DAG、动态 sub-Agent、Context/LLM/Tool 循环、结果验收与最终聚合。
+
+Ordin Core 不实现消息队列、Worker host、PostgreSQL 或具体对象存储。它定义领域模型、窄 Port、
+CAS/原子提交/fencing/effect-ledger 合同，并在 `arbor.testing` 提供可执行的内存参考 Adapter。
+
+PyPI distribution 名称是 `ordin`，当前稳定 Python 导入命名空间是 `arbor`。
+
+## 安装与校验
+
+从 PyPI 安装：
+
+```bash
+pip install ordin
+```
+
+源码开发与完整校验：
+
+```bash
+uv sync
+uv run python scripts/docs.py --check
+uv run pytest tests/test_docs.py
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+## 最小示例
+
+下面用内存 Adapter 模拟平台先持久化 `UserMessage`、再提交 `ExecutionRequest`。生产平台应以自己的
+事务存储和对象存储实现相同 Ports。
+
+```python
+from arbor.agent import Agent
+from arbor.common import Identity
+from arbor.llm import LLMCallPipeline, LLMProfile
+from arbor.mission import ConcatAggregator, SingleTaskPlanner
+from arbor.observability import EventBroker
+from arbor.runtime import Runtime
+from arbor.testing import InMemoryObjectStore, InMemoryRuntimeBackend
+
+backend = InMemoryRuntimeBackend()
+events = EventBroker(backend)
+llm_calls = LLMCallPipeline(
+    provider=my_llm_provider,
+    recorder=backend,
+    event_sink=events,
+)
+runtime = Runtime(
+    llm_calls=llm_calls,
+    events=events,
+    llm_profile=LLMProfile(id="private-model"),
+    backend=backend,
+    object_store=InMemoryObjectStore(),
+    direct_agent=Agent[None](name="direct", instructions="Answer the request."),
+    planner=SingleTaskPlanner(),
+    aggregator=ConcatAggregator(),
+    enable_memory_tools=False,
+)
+
+identity = Identity(user_id="u-1")
+request = await backend.prepare_execution(
+    "实现一个可测试的分析流程",
+    identity=identity,
+)
+result = await runtime.execute(request, context=None)
+```
+
+`Runtime.start()` 返回 direct/clarify 结果或 `MissionHandle`；`Runtime.execute()` 等待完整执行完成。
+两者都只接受平台已经装配好的 `ExecutionRequest`，不会接收并持久化原始用户消息。
+
+当同一 Branch 已有活跃 Execution 时，平台不应再创建并发 Execution，而应在同一事务追加
+Conversation `UserMessage` 和 `SupervisorMessage`。Supervisor 会把消息分类为指导、目标修订、状态
+查询、取消、暂停、恢复或后继目标。内存参考 Adapter 的 `append_supervisor_text()` 展示了该原子入口。
+
+## 生产组合
+
+推荐使用 PostgreSQL 保存 Conversation、Execution/Mission、Plan/Task、command cursor、LLM call、
+effect ledger 和 Artifact metadata，使用 S3/MinIO 等对象存储保存大字节。队列、lease、Worker 部署、
+认证、租户、配额和资源授权都由宿主平台负责。平台的 execution authority 必须在每次关键提交前
+检查所有权；外部 Tool 副作用仍需幂等键、对账和 `needs_attention`，不能宣称 exactly-once。
+
+## 文档
+
+- [文档入口](docs/index.md)
+- [架构总览](docs/architecture/overview.md)
+- [Runtime 与 Supervisor](docs/architecture/runtime.md)
+- [Ports 与生产 Adapter](docs/architecture/persistence.md)
+- [快速开始](docs/guides/quickstart.md)
+- [平台 Adapter 指南](docs/guides/platform-adapters.md)
+- [代码树](docs/reference/code-tree.md) 与 [公开 API](docs/reference/public-api.md)
+- [ADR-0007：平台无关 Runtime](docs/adr/0007-platform-independent-runtime.md)
+- [ADR-0008：Supervisor Inbox](docs/adr/0008-supervisor-inbox.md)
+
+可运行示例位于 `examples/`；其中 `examples/csv_subagent.py` 展示平台冻结资源快照并构造
+`ExecutionScope` 的完整离线路径。

ordin-0.1.0/README.md

@@ -0,0 +1,100 @@
+# Ordin Agent Runtime
+
+Ordin 是一个模型中立、平台无关的 Python Agent Runtime。宿主平台提供已认证身份、持久化的用户消息、
+Conversation 引用、不可变资源快照和运行时 Ports；Ordin 执行完整 Agent 链路：意图识别、
+direct/clarify/Mission 路由、Task DAG、动态 sub-Agent、Context/LLM/Tool 循环、结果验收与最终聚合。
+
+Ordin Core 不实现消息队列、Worker host、PostgreSQL 或具体对象存储。它定义领域模型、窄 Port、
+CAS/原子提交/fencing/effect-ledger 合同，并在 `arbor.testing` 提供可执行的内存参考 Adapter。
+
+PyPI distribution 名称是 `ordin`，当前稳定 Python 导入命名空间是 `arbor`。
+
+## 安装与校验
+
+从 PyPI 安装：
+
+```bash
+pip install ordin
+```
+
+源码开发与完整校验：
+
+```bash
+uv sync
+uv run python scripts/docs.py --check
+uv run pytest tests/test_docs.py
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+## 最小示例
+
+下面用内存 Adapter 模拟平台先持久化 `UserMessage`、再提交 `ExecutionRequest`。生产平台应以自己的
+事务存储和对象存储实现相同 Ports。
+
+```python
+from arbor.agent import Agent
+from arbor.common import Identity
+from arbor.llm import LLMCallPipeline, LLMProfile
+from arbor.mission import ConcatAggregator, SingleTaskPlanner
+from arbor.observability import EventBroker
+from arbor.runtime import Runtime
+from arbor.testing import InMemoryObjectStore, InMemoryRuntimeBackend
+
+backend = InMemoryRuntimeBackend()
+events = EventBroker(backend)
+llm_calls = LLMCallPipeline(
+    provider=my_llm_provider,
+    recorder=backend,
+    event_sink=events,
+)
+runtime = Runtime(
+    llm_calls=llm_calls,
+    events=events,
+    llm_profile=LLMProfile(id="private-model"),
+    backend=backend,
+    object_store=InMemoryObjectStore(),
+    direct_agent=Agent[None](name="direct", instructions="Answer the request."),
+    planner=SingleTaskPlanner(),
+    aggregator=ConcatAggregator(),
+    enable_memory_tools=False,
+)
+
+identity = Identity(user_id="u-1")
+request = await backend.prepare_execution(
+    "实现一个可测试的分析流程",
+    identity=identity,
+)
+result = await runtime.execute(request, context=None)
+```
+
+`Runtime.start()` 返回 direct/clarify 结果或 `MissionHandle`；`Runtime.execute()` 等待完整执行完成。
+两者都只接受平台已经装配好的 `ExecutionRequest`，不会接收并持久化原始用户消息。
+
+当同一 Branch 已有活跃 Execution 时，平台不应再创建并发 Execution，而应在同一事务追加
+Conversation `UserMessage` 和 `SupervisorMessage`。Supervisor 会把消息分类为指导、目标修订、状态
+查询、取消、暂停、恢复或后继目标。内存参考 Adapter 的 `append_supervisor_text()` 展示了该原子入口。
+
+## 生产组合
+
+推荐使用 PostgreSQL 保存 Conversation、Execution/Mission、Plan/Task、command cursor、LLM call、
+effect ledger 和 Artifact metadata，使用 S3/MinIO 等对象存储保存大字节。队列、lease、Worker 部署、
+认证、租户、配额和资源授权都由宿主平台负责。平台的 execution authority 必须在每次关键提交前
+检查所有权；外部 Tool 副作用仍需幂等键、对账和 `needs_attention`，不能宣称 exactly-once。
+
+## 文档
+
+- [文档入口](docs/index.md)
+- [架构总览](docs/architecture/overview.md)
+- [Runtime 与 Supervisor](docs/architecture/runtime.md)
+- [Ports 与生产 Adapter](docs/architecture/persistence.md)
+- [快速开始](docs/guides/quickstart.md)
+- [平台 Adapter 指南](docs/guides/platform-adapters.md)
+- [代码树](docs/reference/code-tree.md) 与 [公开 API](docs/reference/public-api.md)
+- [ADR-0007：平台无关 Runtime](docs/adr/0007-platform-independent-runtime.md)
+- [ADR-0008：Supervisor Inbox](docs/adr/0008-supervisor-inbox.md)
+
+可运行示例位于 `examples/`；其中 `examples/csv_subagent.py` 展示平台冻结资源快照并构造
+`ExecutionScope` 的完整离线路径。

ordin-0.1.0/benchmarks/context_stability.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import os
+from time import monotonic
+from typing import Any
+
+from arbor.common import canonical_json_bytes, ordered_json
+from arbor.context import CharacterTokenEstimator
+from arbor.llm import Message, LLMRequest, OpenAICompatibleLLMProvider
+
+_STREAM_DOMAIN = b"arbor-rendered-message-stream-v1\0"
+
+
+def rendered_message_stream(request: LLMRequest) -> bytes:
+    """Serialize only Arbor-rendered instructions/messages for prefix diagnostics."""
+
+    parts: list[bytes] = []
+    if request.instructions is not None:
+        parts.append(canonical_json_bytes(["instructions", request.instructions]))
+    parts.extend(
+        canonical_json_bytes(["message", message.model_dump(mode="json", exclude={"metadata"})])
+        for message in request.messages
+    )
+    encoded = bytearray(_STREAM_DOMAIN)
+    for part in parts:
+        encoded.extend(f"{len(part)}:".encode("ascii"))
+        encoded.extend(part)
+    return bytes(encoded)
+
+
+def common_prefix_bytes(left: bytes, right: bytes) -> int:
+    for index, (left_byte, right_byte) in enumerate(zip(left, right, strict=False)):
+        if left_byte != right_byte:
+            return index
+    return min(len(left), len(right))
+
+
+def component_hashes(request: LLMRequest) -> dict[str, str | None]:
+    tools = [
+        {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": ordered_json(tool.input_schema),
+        }
+        for tool in request.tools
+    ]
+    return {
+        "ordered_tools_hash": hashlib.sha256(
+            canonical_json_bytes(["arbor-benchmark-tools-v1", tools])
+        ).hexdigest(),
+        "output_schema_hash": (
+            hashlib.sha256(
+                canonical_json_bytes(
+                    [
+                        "arbor-benchmark-output-schema-v1",
+                        ordered_json(request.output_schema),
+                    ]
+                )
+            ).hexdigest()
+            if request.output_schema is not None
+            else None
+        ),
+    }
+
+
+def offline_report(requests: list[LLMRequest]) -> dict[str, Any]:
+    estimator = CharacterTokenEstimator()
+    streams = [rendered_message_stream(request) for request in requests]
+    adjacent = []
+    for index in range(1, len(streams)):
+        prefix_size = common_prefix_bytes(streams[index - 1], streams[index])
+        adjacent.append(
+            {
+                "left": index - 1,
+                "right": index,
+                "common_prefix_bytes": prefix_size,
+                "estimated_draft_common_prefix_tokens": estimator.estimate(
+                    streams[index][:prefix_size].decode("utf-8", errors="ignore")
+                ),
+            }
+        )
+    return {
+        "metric": "arbor-rendered-message-common-prefix",
+        "requests": len(requests),
+        "adjacent": adjacent,
+        "components": [component_hashes(request) for request in requests],
+    }
+
+
+async def live_report(request: LLMRequest, repeats: int) -> dict[str, Any]:
+    if os.getenv("RUN_LIVE_CONTEXT_CACHE_BENCHMARK") != "1":
+        raise RuntimeError("set RUN_LIVE_CONTEXT_CACHE_BENCHMARK=1 to enable Provider requests")
+    provider = OpenAICompatibleLLMProvider.from_env()
+    calls = []
+    for _ in range(repeats):
+        started = monotonic()
+        response = await provider.complete(request.model_copy(deep=True))
+        calls.append(
+            {
+                "duration_ms": (monotonic() - started) * 1000,
+                "input_tokens": response.usage.input_tokens,
+                "cached_input_tokens": response.usage.cached_input_tokens,
+                "deployment": response.provider_metadata.get("deployment"),
+            }
+        )
+    return {"metric": "provider-reported-cache-observation", "calls": calls}
+
+
+def example_requests() -> list[LLMRequest]:
+    base = LLMRequest(
+        llm_profile_id=os.getenv("LLM_MODEL", "offline-model"),
+        instructions="Use the stable task contract.",
+        messages=[Message(role="user", content="task envelope")],
+    )
+    return [
+        base,
+        base.model_copy(
+            update={
+                "messages": [
+                    *base.messages,
+                    Message(role="assistant", content="first turn"),
+                ]
+            },
+            deep=True,
+        ),
+    ]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--live", action="store_true")
+    parser.add_argument("--repeats", type=int, default=2)
+    arguments = parser.parse_args()
+    requests = example_requests()
+    report = (
+        asyncio.run(live_report(requests[0], arguments.repeats))
+        if arguments.live
+        else offline_report(requests)
+    )
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

ordin-0.1.0/docs/adr/0001-agent-definition-instance.md

@@ -0,0 +1,30 @@
+# ADR-0001：统一 Agent 定义与执行实例
+
+- 状态：Accepted；执行循环部分由 ADR-0005 修订
+- 日期：2026-08-17
+
+## 上下文
+
+系统既需要复用 Excel、文档、演示文稿、Python 和网络检索等预定义专家 Agent，也需要
+在目录无明确匹配时，根据 Task 动态创建 sub_agent。如果为 Mission 子任务再引入一套平行的
+执行定义，Runner、Context、Hook、Tool、Skill 和持久化路径都会出现重复概念。
+
+## 决策
+
+1. `Agent` 是唯一完整执行定义，可来自 `AgentCatalog` 或 `DynamicAgentFactory`。
+2. `AgentManifest` 是 predefined Agent 的 implementation-free 搜索投影，不是第二套执行配置。
+3. `AgentInstance` 表示某个 `Agent` 执行某个 Task 的一次持久化实例，记录
+   Agent name/version/source/definition hash、branch、turn、status 和 CAS revision。
+4. `sub_agent` 只是 Mission 子任务 Agent 的角色称呼，不新增领域类型。
+5. predefined 和 dynamic Agent 使用相同的执行生命周期、Context、Tool、Skill、Hook、Artifact
+   和 Result 路径；具体 Executor 合同由 [ADR-0005](0005-agent-executor-contract.md) 修订。
+
+## 结果
+
+- Agent 目录可以为空，没有匹配时动态创建不是错误。
+- 预定义 Agent 的增加只优化专业性、稳定性和资源组合，不需要修改 Supervisor 主链路。
+- 恢复和诊断可通过 `agent_definition_hash` 识别实际执行定义。
+- 不保留重复的子执行配置类型或兼容 API。
+
+参见 [架构总览](../architecture/overview.md) 和
+[Agent、Tool 与 Skill 资源](../architecture/resources.md)。

ordin-0.1.0/docs/adr/0002-task-dag-and-aggregation.md

@@ -0,0 +1,31 @@
+# ADR-0002：统一 Task DAG 与唯一最终聚合
+
+- 状态：Accepted
+- 日期：2026-08-17
+
+## 上下文
+
+一般多步任务常表现为依赖链，复杂任务则包含可并发分支和运行中调整。将它们建模为两种
+planning mode 会混淆计划拓扑和是否允许修订这两个维度。同时，子任务结果若直接回答原始
+请求，会造成重复综合、冲突结论和上下文泄漏。
+
+## 决策
+
+1. 所有 Mission 都使用 `ExecutionPlan.tasks` 构成的 DAG。
+2. 线性计划是每个 Task 依赖前一 Task 的 DAG；无依赖 Task 由 Supervisor 在
+   `max_concurrency` 内并发执行。
+3. Planner 负责目标拆解、deliverable、acceptance criteria、out-of-scope 和 dependencies，
+   不指定 Agent 或硬 capability。
+4. Plan 自适应是 Supervisor 的独立、有上限能力，由 `max_plan_versions` 控制，不是
+   intent planning mode。
+5. sub_agent 只产生 Task-local `ResultEnvelope`；`TaskEvaluator` 先完成局部验收。
+6. `Aggregator.aggregate()` 是唯一 Mission 最终综合入口，把 Task 结果当作不可信数据。
+
+## 结果
+
+- 一套 Plan 模型同时表达串行、并行和混合任务。
+- Supervisor 仅执行依赖已完成的 ready Task，依赖失败会使下游 Task 变为 `BLOCKED`。
+- Task 失败和验收拒绝进入相同 Plan 修订路径。
+- Mission 目标不可在修订中静默改变；目标变更需要用户澄清。
+
+参见 [Runtime 与 Mission](../architecture/runtime.md)。

ordin-0.1.0/docs/adr/0003-manifest-first-resources.md

@@ -0,0 +1,32 @@
+# ADR-0003：Manifest-first 资源目录与延迟加载
+
+- 状态：Accepted
+- 日期：2026-08-17
+
+## 上下文
+
+随着 predefined Agent、Tool 和 Skill 数量增长，如果 Runtime 启动时加载全部实现，或在每次调用中
+向模型发送全部 Tool schema 和 Skill 内容，初始化成本、Context token 和模型选择错误都会增长。
+资源授权同时已由上游宿主在注册前处理，不应在 Agent 中重复建立用户级或 Agent 级权限层。
+
+## 决策
+
+1. `AgentCatalog`、`ToolRegistry` 和 `SkillRegistry` 都先注册轻量 Manifest，支持 identity-checked
+   lazy loader。
+2. 所有成功注册 Tool/Skill 都视为宿主已确认的可用资源；Ordin 不做用户级或 Agent 级
+   资源授权。
+3. `Agent.capabilities` 是稳定小写 semantic ID 组成的软搜索元数据，不是 Task 硬路由合同。
+4. `eager_tool_ids` 表示首轮预激活资源，不是 Tool 可用性上限。Agent 可通过 `search_tools`
+   查找其他全局注册 Tool，并通过 `activate_tools` 在下一 turn 加载 native schema。
+5. Skill 首轮只提供 Manifest 和 preload sections，通过 `read_skill` 有上限地读取其他章节。
+6. Ordin 继续验证 ID、loader identity、Tool name/schema、Skill Tool 依赖、LLM Profile 协议和
+   Artifact provenance；这些是结构完整性，不是权限检查。
+
+## 结果
+
+- Runtime 可先加载整个资源目录，但只为当前 Task 加载相关实现和 LLM-visible schemas。
+- 空 AgentCatalog 不影响 Mission 通过动态 Agent 完成。
+- 添加 Excel、文档、演示文稿、Python 或网络检索 Agent 时，只需增加注册资源，不修改 Supervisor 主链路。
+- 首轮 Context 大小与已安装资源总数解耦。
+
+参见 [Agent、Tool 与 Skill 资源](../architecture/resources.md)。

ordin-0.1.0/docs/adr/0004-atomic-plan-revision.md

@@ -0,0 +1,34 @@
+# ADR-0004：Plan 修订使用 Store 级原子切换
+
+- 状态：Accepted
+- 日期：2026-08-17
+
+## 上下文
+
+当 Task 执行失败、被验收拒绝或依赖阻断时，Supervisor 可在版本上限内生成新 Plan。
+如果“标记旧 Task 为 `SUPERSEDED`”、“插入新 Plan/Task”和“切换
+`Mission.current_plan_version`”是三组独立写入，任一失败都可使 Mission 留在无法继续的混合状态。
+
+## 决策
+
+1. `ExecutionPlan` 版本 append-only，同 Mission/version 不允许覆盖。
+2. 初始 Plan 通过 `RuntimeStore.save_plan()` 单次创建。
+3. 修订 Plan 统一通过
+   `RuntimeStore.save_revised_plan(user_id, previous_plan, revised_plan)` 提交。
+4. 该操作在一个 Store 原子区间内：
+   - 锁定并校验当前 Plan version；
+   - 校验新版本连续且保留全部 completed Tasks；
+   - 插入新 Plan 和新 Tasks；
+   - 标记旧版本中未完成 Tasks 为 `SUPERSEDED`；
+   - 切换 `Mission.current_plan_version`。
+5. `MemoryStore` 使用单一 lock，`PsycopgStore` 使用单一事务和行锁。
+6. `task.superseded` 和 `mission.plan_revised` 事件只在 Store commit 成功后发送。
+
+## 结果
+
+- 修订成功时，新 Plan、Task 状态和 current version 对读取者同时可见。
+- 修订失败时，旧 Plan 仍保持可解释状态，不提前破坏旧 Tasks。
+- completed Task 结果可在新 Plan 中复用，不重复执行。
+- RuntimeEvent 仍不与 Store Adapter 形成跨系统事务；Store 状态是恢复时的真相。
+
+参见 [持久化与恢复边界](../architecture/persistence.md)。

ordin-0.1.0/docs/adr/0005-agent-executor-contract.md

@@ -0,0 +1,38 @@
+# ADR-0005：统一 Agent 生命周期与可替换 Executor
+
+- 状态：Accepted
+- 日期：2026-08-18
+
+## 上下文
+
+`Agent` 当前描述 instructions、Tool、Skill、输出类型和执行限制，`Runner` 同时拥有
+AgentInstance 生命周期与固定的 Context/LLM/Tool turn loop。下游领域 Agent 可能已经有自己的
+执行循环，但仍必须遵守 Ordin 的 Task、状态、取消、审计、Artifact 和结果合同。
+
+## 决策
+
+1. `AgentExecutionCoordinator` 是 AgentInstance 生命周期的唯一所有者，负责状态、CAS、Hook、
+   timeout、取消、事件、usage、Artifact provenance、输出校验和 `RunResult`。
+2. `AgentExecutor` 只执行一次 Task attempt 的领域循环，通过受控 `AgentExecutionSession` 使用
+   canonical Task、dependency results、input Artifacts、Context、LLM、Tool、Artifact 和统一
+   checkpoint 能力。
+3. `DefaultAgentExecutor` 实现当前 Ordin 的 Context/LLM/Tool 多轮循环；领域实现可以提供其他
+   Executor，但不能直接修改 Mission、Task、AgentInstance 或 Store。
+4. Executor 接收 canonical `Task`。领域代码可以派生结构化领域输入，但不能改写 Mission goal、
+   Task instruction、deliverable、acceptance criteria、dependencies 或 out-of-scope。
+5. 所有 Executor 都返回统一 `AgentExecutionOutcome`，最终由 Coordinator 生成
+   `ResultEnvelope` 和 `RunResult`。
+6. 不保留旧 `Runner` 兼容入口；迁移完成后统一使用 Coordinator。
+7. Executor 即使不主动轮询，也会被 Coordinator 与 cancellation/lease guard 竞速；失去 Worker
+   所有权时不得再提交 AgentInstance 或事件。
+8. Session 不暴露可直接调用的 FunctionTool；默认与自定义 Executor 都通过
+   `session.execute_tools()` 进入同一 Policy、Hook、Artifact 和 invocation ledger 边界。
+
+## 结果
+
+- 预定义、动态和下游领域 Agent 共享相同状态、审计和结果语义。
+- 自定义循环不能绕过 Runtime Policy、取消和持久化边界。
+- `Agent` 保持模型中立，Executor 的实现身份进入版本化领域 Agent release hash。
+
+参见 [架构总览](../architecture/overview.md) 和
+[Runtime 与 Mission](../architecture/runtime.md)。

ordin-0.1.0/docs/adr/0006-domain-agent-release-discovery.md

@@ -0,0 +1,38 @@
+# ADR-0006：版本化领域 Agent Release 与受控发现
+
+- 状态：Accepted
+- 日期：2026-08-18
+
+## 上下文
+
+应用需要把内部团队维护的 Excel、PPT、ERP 和其他领域 Agent 快速接入 Ordin，并允许同一逻辑
+Agent 的多个历史版本共存。目录约定应提高开发效率，但不能让文件遍历顺序、隐式覆盖或任意
+Python import 决定运行行为。
+
+## 决策
+
+1. 一个不可变版本目录构建一个 `DomainAgentRelease`，包含 Agent 定义、Executor、不可变
+   `ExecutorConfig`、私有 Tool、共享 Tool、release-local Skill、输出合同、资产摘要和完整 bundle
+   hash。hash 覆盖 Agent metadata，且 release 与 Agent 必须声明相同 `output_type`。
+2. 领域代码位于受控根目录的 `<agent>/versions/<version>/`，使用 implementation-free Manifest
+   和固定 `adapter.py:build()` 入口。
+3. Scanner 使用安全 YAML 解析和严格模型校验，只扫描约定路径，拒绝路径逃逸、重复 release、
+   name/version 不一致和未知字段。
+4. Scanner 不激活 Agent、不授予用户权限，也不边扫描边修改运行中的 Registry；所有 release
+   通过验证后生成不可变 `CodeReleaseCatalog`。
+5. 同一 `(agent_name, version)` 的内容不可原地改变。bundle hash 覆盖 Manifest、Executor 合同、
+   Tool schema/执行属性、Skill version/content hash、输出 schema 和资产 bytes。
+6. 配置和 adapter 是 release 定义真相；数据库 release 行是不可变投影；数据库 Catalog 保存
+   active version；用户 grant 保存可用逻辑 Agent；submission snapshot 保存实际执行版本。
+7. 私有 Tool 随 release 绑定。只有明确允许同一 submission 内其他 Agent 发现的能力才进入共享
+   ToolRegistry；重复 semantic ID/name 继续显式失败，不实现 Layer 覆盖语义。
+8. `active_releases()` 只构建根配置启用的目标版本；Scope 建立前重新验证内存 identity 与磁盘文件，
+   组装后 seal Agent、Tool、Skill Registry。Agent 不得隐式绑定其他 release 拥有的 Skill。
+
+## 结果
+
+- 新目录可以被发现，但不会自动启用或授权。
+- 运行和恢复可以验证精确版本及完整资源身份。
+- 目录结构服务开发体验，机器行为由严格 Release 合同决定。
+
+参见 [Agent、Tool 与 Skill 资源](../architecture/resources.md)。