cybertron-agents 0.1.0__py3-none-any.whl

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/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/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/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/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:
+        ...

cybertron/exporters.py

@@ -0,0 +1,150 @@
+"""把角色注册表编译成 OpenCode V2 配置和 DeepSeek Harness 静态预设。"""
+
+from __future__ import annotations
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Dict, List
+from .registry import THIRTEEN_PRIMES_REGISTRY
+
+# ============================================================================
+
+def compile_opencode_v2_assets(target_dir: Path, *, include_feishu: bool = False) -> List[Path]:
+    """Generates OpenCode V2 native configuration files for all 13 Primes."""
+    generated: List[Path] = []
+    agents_dir = target_dir / ".opencode" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+
+    agents_json_map: Dict[str, Any] = {}
+    for prime in THIRTEEN_PRIMES_REGISTRY:
+        perm_dicts = [
+            {"action": r.action, "resource": r.resource, "effect": r.effect.value}
+            for r in prime.permissions
+        ]
+        perm_yaml_lines = [
+            f'  - action: "{r.action}"\n    resource: "{r.resource}"\n    effect: "{r.effect.value}"'
+            for r in prime.permissions
+        ]
+        perm_yaml_block = "\n".join(perm_yaml_lines)
+
+        md_text = (
+            f"---\n"
+            f'description: "[{prime.cn_name} · {prime.en_name}] {prime.description}"\n'
+            f"mode: {prime.mode.value}\n"
+            f"model: {prime.model}\n"
+            f"steps: {prime.max_steps}\n"
+            f'color: "{prime.color}"\n'
+            f"permissions:\n{perm_yaml_block}\n"
+            f"---\n\n"
+            f"# {prime.cn_name} ({prime.en_name}) — 神器：{prime.artifact}\n"
+            f"- **所属生命周期阶段 (SDLC Stage)**: `{prime.sdlc_stage}`\n"
+            f"- **唯一专职领域 (Exclusive Domain)**: {prime.exclusive_domain}\n"
+            f"- **绝对禁止红线 (Strict Prohibitions)**: {prime.strict_prohibitions}\n"
+            f"- **标准输入契约 (Input Contract)**: {prime.input_contract}\n"
+            f"- **标准输出契约 (Output Contract)**: {prime.output_contract}\n"
+            f"- **飞书知识库角色**: {prime.feishu_wiki_role}\n\n"
+            f"{prime.system_prompt}\n"
+        )
+        md_file = agents_dir / f"{prime.agent_id}.md"
+        md_file.write_text(md_text, encoding="utf-8")
+        generated.append(md_file)
+
+        agents_json_map[prime.agent_id] = {
+            "description": f"[{prime.cn_name}] {prime.description}",
+            "mode": prime.mode.value,
+            "model": prime.model,
+            "steps": prime.max_steps,
+            "color": prime.color,
+            "permissions": perm_dicts,
+        }
+
+    opencode_jsonc = {
+        "$schema": "https://opencode.ai/config.json",
+        "default_agent": "prima",
+        "agents": agents_json_map,
+    }
+    if include_feishu:
+        opencode_jsonc["mcp"] = {
+            "timeout": {
+                "startup": 45000,
+                "catalog": 30000,
+                "execution": 120000,
+            },
+            "servers": {
+                "feishu_wiki": {
+                    "type": "local",
+                    "codemode": False,
+                    "command": [
+                        "npx",
+                        "-y",
+                        "@larksuiteoapi/lark-mcp",
+                        "mcp",
+                        "-a",
+                        "{env:FEISHU_APP_ID}",
+                        "-s",
+                        "{env:FEISHU_APP_SECRET}",
+                        "--token-mode",
+                        "tenant_access_token",
+                        "-c",
+                        "dot",
+                        "-t",
+                        "wiki.v2.space.getNode,docx.v1.document.rawContent",
+                    ],
+                    "environment": {
+                        "FEISHU_APP_ID": "{env:FEISHU_APP_ID}",
+                        "FEISHU_APP_SECRET": "{env:FEISHU_APP_SECRET}",
+                        "FEISHU_WIKI_SPACE_ID": "{env:FEISHU_WIKI_SPACE_ID}",
+                    },
+                }
+            },
+        }
+    jsonc_path = target_dir / "opencode.jsonc"
+    jsonc_path.write_text(json.dumps(opencode_jsonc, ensure_ascii=False, indent=2), encoding="utf-8")
+    generated.append(jsonc_path)
+    return generated
+
+
+def compile_deepseek_harness_assets(target_dir: Path) -> List[Path]:
+    """Generates DeepSeek Harness (dsh) Cordis plugin and preset files."""
+    dsh_dir = target_dir / ".dsh"
+    dsh_dir.mkdir(parents=True, exist_ok=True)
+    generated: List[Path] = []
+
+    preset_data = {
+        "name": "cybertron-thirteen-primes-sdlc-hardware",
+        "version": "5.0.0",
+        "supported_modes": ["standard", "ptc"],
+        "orchestration": {
+            "pattern": "picoagents-plan-based-sdlc-hardware-ledger",
+            "primary_orchestrator": "prima",
+            "documentation_and_wiki_steward": "alpha-trion",
+            "l1_code_reviewer": "micronus-prime",
+            "l2_security_reviewer": "liege-maximo",
+            "qa_and_sil_verifier": "alchemist",
+            "cross_compile_and_prep": "nexus-prime",
+            "physical_flash_gatekeeper": "megatronus",
+        },
+        "agents": [
+            {
+                "id": p.agent_id,
+                "cn_name": p.cn_name,
+                "en_name": p.en_name,
+                "artifact": p.artifact,
+                "sdlc_stage": p.sdlc_stage,
+                "mode": p.mode.value,
+                "model": p.model,
+                "max_steps": p.max_steps,
+                "exclusive_domain": p.exclusive_domain,
+                "strict_prohibitions": p.strict_prohibitions,
+                "input_contract": p.input_contract,
+                "output_contract": p.output_contract,
+                "feishu_wiki_role": p.feishu_wiki_role,
+                "permissions": [asdict(r) for r in p.permissions],
+            }
+            for p in THIRTEEN_PRIMES_REGISTRY
+        ],
+    }
+    preset_file = dsh_dir / "cybertron-primes-preset.json"
+    preset_file.write_text(json.dumps(preset_data, ensure_ascii=False, indent=2), encoding="utf-8")
+    generated.append(preset_file)
+    return generated