cybertron-agents 0.1.0__tar.gz

cybertron_agents-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: cybertron-agents
+Version: 0.1.0
+Summary: Install the 13 Cybertron Primes agents and the /cybertron command into OpenCode
+License: MIT
+Project-URL: Homepage, https://github.com/zhiwenC125/Cybertron-agents
+Project-URL: Repository, https://github.com/zhiwenC125/Cybertron-agents.git
+Keywords: opencode,agents,cybertron,multi-agent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Cybertron Thirteen Primes
+
+当前开发阶段和每阶段验收条件见 [开发计划](DEVELOPMENT_PLAN.md)。
+
+当前项目协作与权限基线见 [AGENTS.md](AGENTS.md)。普通角色的测试、构建和静态检查 Shell 权限暂时关闭；阶段 5 的本地隔离运行器尚未接入 OpenCode 角色工具调用。
+
+**当前状态（2026-11-14）**：七阶段的最小闭环基线已达到。阶段 7 的 STM32 最小 App 已经人工批准真机烧录、读回、观察 SRAM 心跳并恢复原固件；完整 OTA App、ESP32-S3、九步自动接力和宿主审批接口仍在开发。证据见[阶段 7 文档](docs/stages/07-deployment.md)。在其他电脑使用或规划一条命令安装，请先看[安装与发布方案](docs/packaging-and-installation.md)。
+
+各阶段的代码摘录、验收记录与后续实现建议见 [阶段文档目录](docs/stages/01-foundation.md)：[1](docs/stages/01-foundation.md) · [2](docs/stages/02-local-execution.md) · [3](docs/stages/03-opencode-config.md) · [4](docs/stages/04-opencode-executor.md) · [5](docs/stages/05-quality-gates.md) · [6](docs/stages/06-feishu.md) · [7](docs/stages/07-deployment.md)。参考资料新增 [Datawhale Hello Agents](https://datawhalechina.github.io/hello-agents/#/)。
+
+本仓库是 [v5 架构白皮书](design/cybertron_13_primes_architecture.md)的 Python 原型。当前实现包含 13 个角色的静态定义、权限规则、9 步任务账本、飞书 Wiki OpenAPI 网关，以及 OpenCode V2 / DeepSeek Harness 配置导出。已有一个只读角色的 OpenCode V2 命令行适配器；完整多智能体流程仍在开发中。角色模型 ID 以 `cybertron/registry.py` 为准；白皮书中的旧 DeepSeek 模型名保留为当时的设计记录。
+
+## 运行
+
+需要 Python 3.9 或更新版本，无第三方 Python 依赖。
+
+项目根目录已包含可供 OpenCode V2 加载的 `opencode.jsonc` 与 `.opencode/agents/`。本机 `opencode2` v2.3.0 的 `debug config` 与 `debug agents` 已确认加载 13 个 Cybertron 角色；首次在新电脑使用时请自行连接 DeepSeek，并用 `opencode2 models` 核对 `deepseek/deepseek-flash` 与 `deepseek/deepseek-v4-pro`。以下单元测试、导出和配置检查均不会调用模型；交互提示和第 1 步真实执行会调用模型。
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 cybertron_primes_engine.py
+python3 -m cybertron.simulation "开发示例功能"
+python3 -m cybertron.opencode_v2 --output opencode_v2_smoke
+python3 -m cybertron.opencode_run "请澄清 STM32F4 电机控制任务还缺少哪些关键参数"
+```
+
+第二条命令会在当前目录生成 `cybertron_workspace_dist/`，其中有 13 份 OpenCode 智能体 Markdown、`opencode.jsonc` 和一份 DeepSeek Harness 预设 JSON。原脚本路径继续作为兼容入口；实现已拆分到 `cybertron/`。
+
+第三条命令使用统一的 `AgentTask` / `AgentResult` 执行接口运行本地模拟接力。第 3 步依次派发锐天骁、维克多、昆图斯；第 5 步派发微米天、谎言天尊；第 9 步派发钛师傅、第十三天尊。默认在第 8 步硬件审批前停下，不会调用模型、飞书或硬件工具。若只想检验九步状态转换，可显式运行 `python3 -m cybertron.simulation --simulate-hardware-approval`；该选项仅改变模拟结果，不代表真实人工授权。
+
+第四条命令生成供 OpenCode V2 配置加载测试的独立目录，默认不启用飞书 MCP。进入 `opencode_v2_smoke/` 后运行 `opencode2 debug config` 检查宿主加载；此步骤不会调用模型。飞书 MCP 可在有凭证时通过导出命令的 `--include-feishu` 显式启用。
+
+第五条命令在项目根目录运行，会真实调用 OpenCode V2 的 `thirteenth` 角色。若终端仍在 `opencode_v2_smoke/`，重新生成导出包后可直接运行 `python3 run_first_agent.py "请澄清 STM32F4 电机控制任务还缺少哪些关键参数"`。此测试需要该角色配置的 DeepSeek 模型可用。它只执行账本第 1 步，不继续派发其他角色；模型回复不符合结构化格式、超时或命令失败时，账本会阻塞。
+
+阶段 5 的只读接力探针在项目根目录运行：`python3 -m cybertron.opencode_readonly "查看本项目源码与当前 Git 基线"`。项目根目录已生成 `opencode.jsonc` 和 `.opencode/agents/`，让角色能读取真正的项目源码。探针用模拟前置条件跳过步骤 1、2，只真实调用 `onyx-prime` 和 `vector-prime`，不会执行后续写入角色。
+
+阶段 5 保留 `cybertron.opencode_l2_probe` 作为真实宿主审查探针；前置步骤和 L1 是模拟结果。用户已决定不向外部模型发送项目文件，因此它不属于当前离线验收命令。
+
+阶段 5 的离线终端验收运行 `python3 -m unittest discover -s tests -q`、`python3 -m cybertron.stage5_verify` 和 `opencode2 debug config`。第二条命令通过 macOS `sandbox-exec` 核查项目写入、设备读取及网络连接均被拒绝，再将实际单元测试报告作为 `test` 证据写入账本；不会调用模型或飞书。
+
+阶段 6 的离线测试包含在单元测试中。真实飞书测试使用自建应用身份：在本机设置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 和测试空间的 `FEISHU_WIKI_SPACE_ID`，依次运行 `python3 -m cybertron.stage6_verify --check-env`、`--check-auth` 和 `--live`；最后一项会在该空间创建并保留一篇测试文档、追加正文并回读验证。完整步骤见[阶段 6 文档](docs/stages/06-feishu.md)。不要把 App Secret 或租户令牌提交到仓库或贴进聊天。
+
+## 安装到 OpenCode
+
+三条安装路径共享同一份 payload，默认 dry-run，`--apply` 才写入：
+
+- npm：`npx cybertron-agents@0.1.0 init --dry-run`（发布后）
+- shell：`sh install.sh --dry-run --project .`
+- pipx：`pipx install .` 后 `cybertron init --dry-run`
+
+详见[安装与发布方案](docs/packaging-and-installation.md)。
+
+## 模块
+
+| 模块 | 职责 |
+| --- | --- |
+| `schema.py` | 消息和工具调用数据结构 |
+| `compaction.py` | 上下文首尾压缩 |
+| `policy.py` | 本地权限与循环熔断检查 |
+| `feishu.py` | 自建应用凭证读取、租户令牌缓存、Wiki 节点及 Docx 正文读写网关 |
+| `registry.py` | 13 个角色配置 |
+| `ledger.py` | SDLC 计划和顺序状态转换 |
+| `execution.py` | 宿主无关的任务、结果和执行器协议 |
+| `dispatch.py` | 派单、结果校验和账本推进 |
+| `simulation.py` | 不产生外部副作用的本地模拟执行器 |
+| `isolated_runner.py` | macOS 沙箱内运行单元测试并生成 QA 证据 |
+| `deployment.py` | 第七阶段固件、设备、擦写与回滚契约及无硬件仿真 |
+| `exporters.py` | 双宿主静态配置导出 |
+| `installer.py` | npm / shell / pipx 三条安装路径的 Python 入口 |
+| `selfcheck.py` | 命令行自检 |
+
+## 当前边界与下一步
+
+1. `ledger.py` 与 `dispatch.py` 已实现 L1/L2 拒绝后返回编码、重审及超限阻塞；本地隔离测试能生成 QA 回执。真实 L1/L2 宿主审查和人工烧录授权仍需后续阶段接入。
+2. `policy.py` 是本地策略原型，不能代替宿主层权限和命令解析。生成配置后的真实权限仍需在目标宿主中验证。
+3. DeepSeek Harness 目前只导出预设 JSON，白皮书中的 `.dsh/cordis-cybertron-plugin.mjs` 尚未实现。
+4. 阶段 6 的 Wiki OpenAPI 读写已由开发者在专用测试空间验收；阶段 7 的 STM32 最小真机烧录及回滚已通过。完整 OTA App、ESP32-S3、外部 Flash 备份和隔离构建仍待开发。
+
+缺少飞书 App ID 或 App Secret 时，网关默认报错。模拟租户令牌仅能通过显式传入 `mock_if_unset=True` 用于局部测试，不会进入真实 Wiki 请求。

cybertron_agents-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Cybertron Thirteen Primes
+
+当前开发阶段和每阶段验收条件见 [开发计划](DEVELOPMENT_PLAN.md)。
+
+当前项目协作与权限基线见 [AGENTS.md](AGENTS.md)。普通角色的测试、构建和静态检查 Shell 权限暂时关闭；阶段 5 的本地隔离运行器尚未接入 OpenCode 角色工具调用。
+
+**当前状态（2026-11-14）**：七阶段的最小闭环基线已达到。阶段 7 的 STM32 最小 App 已经人工批准真机烧录、读回、观察 SRAM 心跳并恢复原固件；完整 OTA App、ESP32-S3、九步自动接力和宿主审批接口仍在开发。证据见[阶段 7 文档](docs/stages/07-deployment.md)。在其他电脑使用或规划一条命令安装，请先看[安装与发布方案](docs/packaging-and-installation.md)。
+
+各阶段的代码摘录、验收记录与后续实现建议见 [阶段文档目录](docs/stages/01-foundation.md)：[1](docs/stages/01-foundation.md) · [2](docs/stages/02-local-execution.md) · [3](docs/stages/03-opencode-config.md) · [4](docs/stages/04-opencode-executor.md) · [5](docs/stages/05-quality-gates.md) · [6](docs/stages/06-feishu.md) · [7](docs/stages/07-deployment.md)。参考资料新增 [Datawhale Hello Agents](https://datawhalechina.github.io/hello-agents/#/)。
+
+本仓库是 [v5 架构白皮书](design/cybertron_13_primes_architecture.md)的 Python 原型。当前实现包含 13 个角色的静态定义、权限规则、9 步任务账本、飞书 Wiki OpenAPI 网关，以及 OpenCode V2 / DeepSeek Harness 配置导出。已有一个只读角色的 OpenCode V2 命令行适配器；完整多智能体流程仍在开发中。角色模型 ID 以 `cybertron/registry.py` 为准；白皮书中的旧 DeepSeek 模型名保留为当时的设计记录。
+
+## 运行
+
+需要 Python 3.9 或更新版本，无第三方 Python 依赖。
+
+项目根目录已包含可供 OpenCode V2 加载的 `opencode.jsonc` 与 `.opencode/agents/`。本机 `opencode2` v2.3.0 的 `debug config` 与 `debug agents` 已确认加载 13 个 Cybertron 角色；首次在新电脑使用时请自行连接 DeepSeek，并用 `opencode2 models` 核对 `deepseek/deepseek-flash` 与 `deepseek/deepseek-v4-pro`。以下单元测试、导出和配置检查均不会调用模型；交互提示和第 1 步真实执行会调用模型。
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 cybertron_primes_engine.py
+python3 -m cybertron.simulation "开发示例功能"
+python3 -m cybertron.opencode_v2 --output opencode_v2_smoke
+python3 -m cybertron.opencode_run "请澄清 STM32F4 电机控制任务还缺少哪些关键参数"
+```
+
+第二条命令会在当前目录生成 `cybertron_workspace_dist/`，其中有 13 份 OpenCode 智能体 Markdown、`opencode.jsonc` 和一份 DeepSeek Harness 预设 JSON。原脚本路径继续作为兼容入口；实现已拆分到 `cybertron/`。
+
+第三条命令使用统一的 `AgentTask` / `AgentResult` 执行接口运行本地模拟接力。第 3 步依次派发锐天骁、维克多、昆图斯；第 5 步派发微米天、谎言天尊；第 9 步派发钛师傅、第十三天尊。默认在第 8 步硬件审批前停下，不会调用模型、飞书或硬件工具。若只想检验九步状态转换，可显式运行 `python3 -m cybertron.simulation --simulate-hardware-approval`；该选项仅改变模拟结果，不代表真实人工授权。
+
+第四条命令生成供 OpenCode V2 配置加载测试的独立目录，默认不启用飞书 MCP。进入 `opencode_v2_smoke/` 后运行 `opencode2 debug config` 检查宿主加载；此步骤不会调用模型。飞书 MCP 可在有凭证时通过导出命令的 `--include-feishu` 显式启用。
+
+第五条命令在项目根目录运行，会真实调用 OpenCode V2 的 `thirteenth` 角色。若终端仍在 `opencode_v2_smoke/`，重新生成导出包后可直接运行 `python3 run_first_agent.py "请澄清 STM32F4 电机控制任务还缺少哪些关键参数"`。此测试需要该角色配置的 DeepSeek 模型可用。它只执行账本第 1 步，不继续派发其他角色；模型回复不符合结构化格式、超时或命令失败时，账本会阻塞。
+
+阶段 5 的只读接力探针在项目根目录运行：`python3 -m cybertron.opencode_readonly "查看本项目源码与当前 Git 基线"`。项目根目录已生成 `opencode.jsonc` 和 `.opencode/agents/`，让角色能读取真正的项目源码。探针用模拟前置条件跳过步骤 1、2，只真实调用 `onyx-prime` 和 `vector-prime`，不会执行后续写入角色。
+
+阶段 5 保留 `cybertron.opencode_l2_probe` 作为真实宿主审查探针；前置步骤和 L1 是模拟结果。用户已决定不向外部模型发送项目文件，因此它不属于当前离线验收命令。
+
+阶段 5 的离线终端验收运行 `python3 -m unittest discover -s tests -q`、`python3 -m cybertron.stage5_verify` 和 `opencode2 debug config`。第二条命令通过 macOS `sandbox-exec` 核查项目写入、设备读取及网络连接均被拒绝，再将实际单元测试报告作为 `test` 证据写入账本；不会调用模型或飞书。
+
+阶段 6 的离线测试包含在单元测试中。真实飞书测试使用自建应用身份：在本机设置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 和测试空间的 `FEISHU_WIKI_SPACE_ID`，依次运行 `python3 -m cybertron.stage6_verify --check-env`、`--check-auth` 和 `--live`；最后一项会在该空间创建并保留一篇测试文档、追加正文并回读验证。完整步骤见[阶段 6 文档](docs/stages/06-feishu.md)。不要把 App Secret 或租户令牌提交到仓库或贴进聊天。
+
+## 安装到 OpenCode
+
+三条安装路径共享同一份 payload，默认 dry-run，`--apply` 才写入：
+
+- npm：`npx cybertron-agents@0.1.0 init --dry-run`（发布后）
+- shell：`sh install.sh --dry-run --project .`
+- pipx：`pipx install .` 后 `cybertron init --dry-run`
+
+详见[安装与发布方案](docs/packaging-and-installation.md)。
+
+## 模块
+
+| 模块 | 职责 |
+| --- | --- |
+| `schema.py` | 消息和工具调用数据结构 |
+| `compaction.py` | 上下文首尾压缩 |
+| `policy.py` | 本地权限与循环熔断检查 |
+| `feishu.py` | 自建应用凭证读取、租户令牌缓存、Wiki 节点及 Docx 正文读写网关 |
+| `registry.py` | 13 个角色配置 |
+| `ledger.py` | SDLC 计划和顺序状态转换 |
+| `execution.py` | 宿主无关的任务、结果和执行器协议 |
+| `dispatch.py` | 派单、结果校验和账本推进 |
+| `simulation.py` | 不产生外部副作用的本地模拟执行器 |
+| `isolated_runner.py` | macOS 沙箱内运行单元测试并生成 QA 证据 |
+| `deployment.py` | 第七阶段固件、设备、擦写与回滚契约及无硬件仿真 |
+| `exporters.py` | 双宿主静态配置导出 |
+| `installer.py` | npm / shell / pipx 三条安装路径的 Python 入口 |
+| `selfcheck.py` | 命令行自检 |
+
+## 当前边界与下一步
+
+1. `ledger.py` 与 `dispatch.py` 已实现 L1/L2 拒绝后返回编码、重审及超限阻塞；本地隔离测试能生成 QA 回执。真实 L1/L2 宿主审查和人工烧录授权仍需后续阶段接入。
+2. `policy.py` 是本地策略原型，不能代替宿主层权限和命令解析。生成配置后的真实权限仍需在目标宿主中验证。
+3. DeepSeek Harness 目前只导出预设 JSON，白皮书中的 `.dsh/cordis-cybertron-plugin.mjs` 尚未实现。
+4. 阶段 6 的 Wiki OpenAPI 读写已由开发者在专用测试空间验收；阶段 7 的 STM32 最小真机烧录及回滚已通过。完整 OTA App、ESP32-S3、外部 Flash 备份和隔离构建仍待开发。
+
+缺少飞书 App ID 或 App Secret 时，网关默认报错。模拟租户令牌仅能通过显式传入 `mock_if_unset=True` 用于局部测试，不会进入真实 Wiki 请求。

cybertron_agents-0.1.0/cybertron/__init__.py

@@ -0,0 +1,11 @@
+"""Cybertron multi-agent configuration and orchestration primitives."""
+from .schema import Message, ToolCallRequest, function_to_json_schema
+from .compaction import AlphaTrionHeadTailCompaction, CompactionStrategy
+from .policy import MegatronusCircuitBreaker, PermissionEffect, PermissionRule
+from .feishu import FeishuWikiGovernanceConfig, FeishuWikiKnowledgeClient
+from .registry import AgentMode, PrimeAgentSpec, THIRTEEN_PRIMES_REGISTRY
+from .ledger import CybertronTaskLedger, LedgerStep, PrimaPlanOrchestrator
+from .exporters import compile_deepseek_harness_assets, compile_opencode_v2_assets
+from .selfcheck import run_self_verification
+from .execution import AgentExecutor, AgentResult, AgentTask, QualityEvidence, QualityKind, ResultStatus
+from .dispatch import PrimaDispatcher

cybertron_agents-0.1.0/cybertron/compaction.py

@@ -0,0 +1,107 @@
+"""在模型上下文超预算时保留早期约束与近期消息，并保持工具调用和结果成组。"""
+
+from __future__ import annotations
+import json
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from typing import List, Protocol, Set, Tuple, runtime_checkable
+from .schema import Message
+
+# MODULE 2: Alpha Trion Context Compaction Engine (Ref: picoagents/compaction.py)
+# ============================================================================
+
+@runtime_checkable
+class CompactionStrategy(Protocol):
+    """Protocol for context compaction executed INSIDE the agent tool loop."""
+
+    @abstractmethod
+    def compact(self, messages: List[Message]) -> List[Message]:
+        ...
+
+
+@dataclass
+class AlphaTrionHeadTailCompaction:
+    """
+    Token-aware Head+Tail Compaction (Alpha Trion's Quill).
+    Preserves:
+      - Head (25% budget): System prompt, initial user requirement, and Feishu Wiki architectural/hardware constraints.
+      - Tail (75% budget): Most recent tool calls and results (working memory).
+    Crucially preserves 'atomic groups': an assistant message containing `tool_calls`
+    is NEVER separated from its corresponding `ToolMessage` results.
+    """
+    token_budget: int = 64_000
+    head_ratio: float = 0.25
+    compaction_count: int = field(default=0, repr=False)
+    total_tokens_saved: int = field(default=0, repr=False)
+
+    @staticmethod
+    def estimate_tokens(messages: List[Message]) -> int:
+        total = 0
+        for msg in messages:
+            total += 4 + len(msg.content or "") // 4
+            for tc in msg.tool_calls:
+                total += 8 + len(tc.tool_name) + len(json.dumps(tc.parameters, ensure_ascii=False)) // 4
+        return total
+
+    @staticmethod
+    def find_atomic_groups(messages: List[Message]) -> List[Tuple[int, ...]]:
+        groups: List[Tuple[int, ...]] = []
+        i = 0
+        while i < len(messages):
+            msg = messages[i]
+            if msg.role == "assistant" and msg.tool_calls:
+                pending_ids: Set[str] = {tc.call_id for tc in msg.tool_calls}
+                group_indices = [i]
+                j = i + 1
+                while j < len(messages) and pending_ids:
+                    if messages[j].role == "tool" and messages[j].tool_call_id in pending_ids:
+                        group_indices.append(j)
+                        pending_ids.remove(messages[j].tool_call_id)  # type: ignore[arg-type]
+                    j += 1
+                groups.append(tuple(group_indices))
+                i = max(group_indices) + 1
+            else:
+                groups.append((i,))
+                i += 1
+        return groups
+
+    def compact(self, messages: List[Message]) -> List[Message]:
+        if not messages:
+            return messages
+        current_tokens = self.estimate_tokens(messages)
+        if current_tokens <= self.token_budget:
+            return messages
+
+        self.compaction_count += 1
+        groups = self.find_atomic_groups(messages)
+        head_budget = int(self.token_budget * self.head_ratio)
+        tail_budget = self.token_budget - head_budget
+
+        head_groups: List[Tuple[int, ...]] = []
+        head_tokens = 0
+        for grp in groups:
+            grp_tokens = self.estimate_tokens([messages[idx] for idx in grp])
+            if head_tokens + grp_tokens <= head_budget:
+                head_groups.append(grp)
+                head_tokens += grp_tokens
+            else:
+                break
+
+        remaining = groups[len(head_groups):]
+        tail_groups: List[Tuple[int, ...]] = []
+        tail_tokens = 0
+        for grp in reversed(remaining):
+            grp_tokens = self.estimate_tokens([messages[idx] for idx in grp])
+            if tail_tokens + grp_tokens <= tail_budget:
+                tail_groups.insert(0, grp)
+                tail_tokens += grp_tokens
+            else:
+                break
+
+        kept_indices: Set[int] = set()
+        for grp in head_groups + tail_groups:
+            kept_indices.update(grp)
+
+        compacted = [messages[idx] for idx in sorted(kept_indices)]
+        self.total_tokens_saved += current_tokens - self.estimate_tokens(compacted)
+        return compacted

cybertron_agents-0.1.0/cybertron/deployment.py

@@ -0,0 +1,141 @@
+"""Offline stage 7 deployment contracts; no device or shell operations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+_FIRMWARE_SUFFIXES = {".bin", ".elf", ".hex", ".uf2"}
+
+
+def _required(value: str, label: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} is required")
+    return value.strip()
+
+
+@dataclass(frozen=True)
+class FirmwareArtifact:
+    path: str
+    sha256: str
+    size_bytes: int
+
+    @classmethod
+    def inspect(cls, path: Path) -> FirmwareArtifact:
+        if path.is_symlink() or path.suffix.lower() not in _FIRMWARE_SUFFIXES:
+            raise ValueError("Firmware must be a regular .bin/.elf/.hex/.uf2 file")
+        if not path.is_file():
+            raise FileNotFoundError("Firmware file is missing")
+        digest = hashlib.sha256()
+        size = 0
+        with path.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+                size += len(chunk)
+        if size == 0:
+            raise ValueError("Firmware file is empty")
+        return cls(str(path.resolve()), digest.hexdigest(), size)
+
+    def verify(self) -> None:
+        current = type(self).inspect(Path(self.path))
+        if current.sha256 != self.sha256 or current.size_bytes != self.size_bytes:
+            raise ValueError("Firmware changed after inspection")
+
+
+@dataclass(frozen=True)
+class DeviceTarget:
+    device_id: str
+    board: str
+    connection: str
+    flash_start: int
+    flash_end: int  # exclusive
+
+    def validate(self) -> None:
+        for label in ("device_id", "board", "connection"):
+            _required(getattr(self, label), label)
+        if not (isinstance(self.flash_start, int) and isinstance(self.flash_end, int)
+                and 0 <= self.flash_start < self.flash_end):
+            raise ValueError("Target flash range must be a nonempty address interval")
+
+
+@dataclass(frozen=True)
+class FlashPlan:
+    target: DeviceTarget
+    firmware: FirmwareArtifact
+    rollback: FirmwareArtifact
+    erase_start: int
+    erase_end: int  # exclusive
+    rollback_procedure: str
+    heartbeat_marker: str
+    plan_digest: str
+
+    @classmethod
+    def prepare(cls, target: DeviceTarget, firmware: FirmwareArtifact,
+                rollback: FirmwareArtifact, *, erase_start: int, erase_end: int,
+                rollback_procedure: str, heartbeat_marker: str) -> FlashPlan:
+        target.validate()
+        firmware.verify()
+        rollback.verify()
+        if not (isinstance(erase_start, int) and isinstance(erase_end, int)
+                and target.flash_start <= erase_start < erase_end <= target.flash_end):
+            raise ValueError("Erase range is outside the target flash region")
+        if Path(firmware.path).suffix.lower() == ".bin" and firmware.size_bytes > erase_end - erase_start:
+            raise ValueError("Raw firmware does not fit the erase range")
+        if Path(rollback.path).suffix.lower() == ".bin" and rollback.size_bytes > target.flash_end - target.flash_start:
+            raise ValueError("Rollback firmware does not fit target flash")
+        procedure = _required(rollback_procedure, "rollback_procedure")
+        marker = _required(heartbeat_marker, "heartbeat_marker")
+        if firmware.path == rollback.path or firmware.sha256 == rollback.sha256:
+            raise ValueError("Rollback firmware must be a distinct verified image")
+        values = {
+            "target": asdict(target), "firmware": asdict(firmware),
+            "rollback": asdict(rollback), "erase_start": erase_start,
+            "erase_end": erase_end, "rollback_procedure": procedure,
+            "heartbeat_marker": marker,
+        }
+        digest = hashlib.sha256(json.dumps(values, sort_keys=True).encode()).hexdigest()
+        return cls(target, firmware, rollback, erase_start, erase_end,
+                   procedure, marker, digest)
+
+    def verify(self) -> None:
+        rebuilt = type(self).prepare(
+            self.target, self.firmware, self.rollback,
+            erase_start=self.erase_start, erase_end=self.erase_end,
+            rollback_procedure=self.rollback_procedure,
+            heartbeat_marker=self.heartbeat_marker,
+        )
+        if rebuilt.plan_digest != self.plan_digest:
+            raise ValueError("Flash plan changed after preparation")
+
+    def assessment(self) -> dict:
+        """Reviewable blast-radius data; contains no command or approval claim."""
+        self.verify()
+        return {
+            "plan_digest": self.plan_digest,
+            "target": asdict(self.target),
+            "firmware": asdict(self.firmware),
+            "erase_range": {"start": self.erase_start, "end_exclusive": self.erase_end},
+            "rollback": asdict(self.rollback),
+            "rollback_procedure": self.rollback_procedure,
+            "heartbeat_marker": self.heartbeat_marker,
+            "requires_human_approval": True,
+        }
+
+
+@dataclass(frozen=True)
+class SimulationReceipt:
+    plan_digest: str
+    device_id: str
+    heartbeat_observed: bool
+    simulated: bool = True
+
+
+def simulate_flash(plan: FlashPlan, boot_log: str) -> SimulationReceipt:
+    """Check a supplied fake boot log without opening ports or writing hardware."""
+    plan.verify()
+    if not isinstance(boot_log, str) or plan.heartbeat_marker not in boot_log:
+        raise ValueError("Simulated boot log does not contain the required heartbeat")
+    return SimulationReceipt(plan.plan_digest, plan.target.device_id, True)

cybertron_agents-0.1.0/cybertron/dispatch.py

@@ -0,0 +1,92 @@
+"""Move the ledger one step after validating an executor result."""
+
+from __future__ import annotations
+
+from .execution import AgentExecutor, AgentResult, AgentTask, QualityKind, ResultStatus
+from .ledger import CybertronTaskLedger
+from .registry import THIRTEEN_PRIMES_REGISTRY
+
+
+class PrimaDispatcher:
+    def __init__(self, executor: AgentExecutor) -> None:
+        self.executor = executor
+        self.agent_ids = {agent.agent_id for agent in THIRTEEN_PRIMES_REGISTRY}
+
+    def run_next(self, ledger: CybertronTaskLedger) -> AgentResult | None:
+        step = ledger.next_step()
+        if step is None:
+            return None
+        agent_id = step.next_agent()
+        if agent_id is None:
+            raise ValueError(f"Step {step.step_id} has no remaining agent")
+        if agent_id not in self.agent_ids:
+            raise ValueError(f"Unknown agent: {agent_id}")
+        if ledger.turn_count >= ledger.max_turns:
+            raise RuntimeError("Ledger turn limit reached")
+        if step.status == "blocked":
+            raise ValueError(f"Step {step.step_id} is blocked; resume it first")
+        if step.status == "pending":
+            ledger.start_step(step.step_id)
+
+        task = AgentTask(
+            step_id=step.step_id,
+            agent_id=agent_id,
+            user_request=ledger.user_request,
+            objective=step.participant_objectives.get(agent_id, step.objective),
+            input_artifact=step.input_artifact,
+            expected_output=step.expected_output,
+            feedback=step.feedback,
+            prior_evidence=tuple(
+                item for completed in ledger.plan if completed.status == "completed"
+                for item in completed.evidence
+            ) + tuple(step.evidence),
+        )
+        ledger.turn_count += 1
+        try:
+            result = self.executor.execute(task)
+        except Exception as exc:
+            ledger.block_step(step.step_id, f"Executor error: {exc}")
+            raise
+
+        if result.step_id != task.step_id or result.agent_id != task.agent_id:
+            ledger.block_step(step.step_id, "Executor returned a result for a different task")
+            raise ValueError("Executor returned a result for a different task")
+        if not result.summary.strip():
+            ledger.block_step(step.step_id, "Executor returned an empty summary")
+            raise ValueError("Executor returned an empty summary")
+        if result.status == ResultStatus.COMPLETED:
+            if not result.evidence or not all(item.strip() for item in result.evidence):
+                ledger.block_step(step.step_id, "Completion has no evidence")
+                raise ValueError("Completion requires nonempty evidence")
+            gate_kind = {
+                "micronus-prime": QualityKind.REVIEW_L1,
+                "liege-maximo": QualityKind.REVIEW_L2,
+                "alchemist": QualityKind.TEST,
+            }.get(agent_id)
+            if gate_kind is not None and not any(
+                item.kind == gate_kind and item.passed and item.source.strip()
+                for item in result.quality_evidence
+            ):
+                ledger.block_step(step.step_id, f"Missing passing {gate_kind.value} evidence")
+                raise ValueError(f"Missing passing {gate_kind.value} evidence")
+            ledger.record_agent_completion(step.step_id, agent_id, result.summary,
+                                           list(result.evidence), list(result.artifacts),
+                                           list(result.quality_evidence))
+        elif result.status in (ResultStatus.BLOCKED, ResultStatus.NEEDS_APPROVAL):
+            ledger.block_step(step.step_id, result.summary)
+        elif result.status == ResultStatus.REJECTED:
+            ledger.reject_review(agent_id, result.summary)
+        else:
+            ledger.block_step(step.step_id, "Unknown executor status")
+            raise ValueError("Unknown executor status")
+        return result
+
+    def run_until_blocked(self, ledger: CybertronTaskLedger) -> list[AgentResult]:
+        results: list[AgentResult] = []
+        while ledger.next_step() is not None:
+            result = self.run_next(ledger)
+            assert result is not None
+            results.append(result)
+            if result.status != ResultStatus.COMPLETED:
+                break
+        return results

cybertron_agents-0.1.0/cybertron/execution.py

@@ -0,0 +1,58 @@
+"""Host-neutral task and result contracts for one agent dispatch."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol, Tuple
+
+
+class ResultStatus(str, Enum):
+    COMPLETED = "completed"
+    BLOCKED = "blocked"
+    NEEDS_APPROVAL = "needs_approval"
+    REJECTED = "rejected"
+
+
+class QualityKind(str, Enum):
+    REVIEW_L1 = "review_l1"
+    REVIEW_L2 = "review_l2"
+    TEST = "test"
+
+
+@dataclass(frozen=True)
+class QualityEvidence:
+    """A typed gate result; source identifies the report or run that produced it."""
+    kind: QualityKind
+    passed: bool
+    source: str
+
+
+@dataclass(frozen=True)
+class AgentTask:
+    step_id: int
+    agent_id: str
+    user_request: str
+    objective: str
+    input_artifact: str
+    expected_output: str
+    prior_evidence: Tuple[str, ...] = ()
+    feedback: str = ""
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    step_id: int
+    agent_id: str
+    status: ResultStatus
+    summary: str
+    evidence: Tuple[str, ...] = ()
+    artifacts: Tuple[str, ...] = ()
+    quality_evidence: Tuple[QualityEvidence, ...] = ()
+
+
+class AgentExecutor(Protocol):
+    """An adapter for a model host or deterministic local simulation."""
+
+    def execute(self, task: AgentTask) -> AgentResult:
+        ...