openhands: strengthen role agent prompts

.github/workflows/openhands-audit-integrity.yml

@@ -0,0 +1,53 @@
+name: OpenHands Audit Integrity
+
+on:
+  pull_request:
+    paths:
+      - "aios_core/openhands/**"
+      - "tests/test_openhands_*.py"
+      - ".github/workflows/openhands-audit-integrity.yml"
+  push:
+    branches:
+      - main
+      - "agent/**"
+    paths:
+      - "aios_core/openhands/**"
+      - "tests/test_openhands_*.py"
+      - ".github/workflows/openhands-audit-integrity.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  audit-integrity:
+    name: OpenHands audit chain integrity
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
+          pip install pytest
+
+      - name: Run OpenHands audit tests
+        run: |
+          pytest -q tests/test_openhands_checkpoint_chain.py \
+            tests/test_openhands_checkpoint_identity.py \
+            tests/test_openhands_checkpoint_integrity.py \
+            tests/test_openhands_critical_checkpoints.py \
+            tests/test_openhands_git_identity_gate.py \
+            tests/test_openhands_audit_restore_fail_closed.py
+
+      - name: Verify Python syntax
+        run: python -m compileall -q aios_core/openhands

aios_core/openhands/__init__.py

@@ -1,78 +1,37 @@
-"""OpenHands-контур AIOS: оркестрация OpenHands-разговоров как специализированных агентов.
-
-AIOS владеет оркестрацией, состоянием задач, правами и аудитом; OpenHands (Cloud API)
-владеет исполнением в sandbox. Роли (Architect/Coder/Tester/Reviewer/...) — профили
-разговоров, а не новые классы агентов. Подробнее: AIOS_OPENHANDS_INTEGRATION_PLAN.md.
-"""
-
+"""OpenHands-контур AIOS."""
+from .agent_score import AgentScoreboard, AgentStats
 from .api import router as oh_contour_router
+from .ci_provenance import CIProvenance, CIProvenanceCollector
 from .client import OpenHandsClient, resolve_api_key
-from .errors import (
-    OpenHandsAPIError,
-    OpenHandsAuthError,
-    OpenHandsError,
-    OpenHandsStartError,
-    OpenHandsTimeoutError,
-)
+from .errors import OpenHandsAPIError, OpenHandsAuthError, OpenHandsError, OpenHandsStartError, OpenHandsTimeoutError
+from .evidence import CompletionReport, DoDItem, Evidence, EvidenceKind, dod_for_role
+from .evaluation_suite import EvaluationScenario, SCENARIOS, assert_evaluation_suite, run_prompt_evaluation
+from .evaluator import PromptEvaluation, assert_prompt_contract, evaluate_prompt
 from .github import GitHubHelper, GitOperationError, GitRunner
-from .models import (
-    MVP_ROLES,
-    AgentPermissions,
-    AgentProfile,
-    AgentRole,
-    FailureReport,
-    Gate,
-    ReviewDecision,
-    TaskExtras,
-)
+from .memory import AgentMemoryEntry, TaskMemory
+from .meta_review import MetaReview, SpecialistVerdict, aggregate_verdicts
+from .micro_agents import MICRO_AGENTS, MicroAgentSpec, select_micro_agents
+from .models import MVP_ROLES, AgentPermissions, AgentProfile, AgentRole, FailureReport, Gate, ReviewDecision, TaskExtras
 from .permissions import PROFILES, check_paths, path_allowed, rbac_role_name, register_roles
 from .profiles import build_prompt, conversation_title
+from .prompt_optimizer import PromptOptimizationSuggestion, suggest_improvements
+from .prompt_security import PromptSecurityResult, inspect_untrusted_input, sanitize_context
+from .router import AdaptiveRouter, RouteDecision, default_route_candidates
 from .runner import OHOrchestrator, RunResult
 from .service import ContourService, ContourTask
-from .state_machine import (
-    TransitionError,
-    allowed_transitions,
-    can_transition,
-    transition,
-)
+from .specialist_pipeline import SpecialistResult, SpecialistReviewPipeline, conservative_executor
+from .state_machine import TransitionError, allowed_transitions, can_transition, transition
 from .store import ContourStore
+from .task_profiles import TaskType, classify_task, guidance_for
 from .verdicts import parse_review_verdict
 
 __all__ = [
-    "MVP_ROLES",
-    "PROFILES",
-    "AgentPermissions",
-    "AgentProfile",
-    "AgentRole",
-    "ContourService",
-    "ContourStore",
-    "ContourTask",
-    "FailureReport",
-    "Gate",
-    "GitHubHelper",
-    "GitOperationError",
-    "GitRunner",
-    "OHOrchestrator",
-    "OpenHandsAPIError",
-    "OpenHandsAuthError",
-    "OpenHandsClient",
-    "OpenHandsError",
-    "OpenHandsStartError",
-    "OpenHandsTimeoutError",
-    "ReviewDecision",
-    "RunResult",
-    "TaskExtras",
-    "TransitionError",
-    "allowed_transitions",
-    "build_prompt",
-    "can_transition",
-    "check_paths",
-    "conversation_title",
-    "oh_contour_router",
-    "parse_review_verdict",
-    "path_allowed",
-    "rbac_role_name",
-    "register_roles",
-    "resolve_api_key",
-    "transition",
+    "MVP_ROLES", "PROFILES", "AgentPermissions", "AgentProfile", "AgentRole", "AgentMemoryEntry", "AgentScoreboard", "AgentStats",
+    "AdaptiveRouter", "CIProvenance", "CIProvenanceCollector", "CompletionReport", "ContourService", "ContourStore", "ContourTask", "DoDItem", "Evidence", "EvidenceKind", "EvaluationScenario", "SCENARIOS", "FailureReport", "Gate",
+    "GitHubHelper", "GitOperationError", "GitRunner", "MICRO_AGENTS", "MetaReview", "MicroAgentSpec", "OHOrchestrator", "OpenHandsAPIError", "OpenHandsAuthError",
+    "OpenHandsClient", "OpenHandsError", "OpenHandsStartError", "OpenHandsTimeoutError", "PromptEvaluation", "PromptOptimizationSuggestion",
+    "PromptSecurityResult", "ReviewDecision", "RouteDecision", "RunResult", "SpecialistResult", "SpecialistReviewPipeline", "SpecialistVerdict", "TaskExtras", "TaskMemory", "TaskType", "TransitionError", "allowed_transitions",
+    "aggregate_verdicts", "assert_evaluation_suite", "assert_prompt_contract", "build_prompt", "can_transition", "check_paths", "classify_task", "conservative_executor", "conversation_title", "default_route_candidates", "dod_for_role", "evaluate_prompt",
+    "guidance_for", "inspect_untrusted_input", "oh_contour_router", "parse_review_verdict", "path_allowed", "rbac_role_name", "register_roles",
+    "resolve_api_key", "run_prompt_evaluation", "sanitize_context", "select_micro_agents", "suggest_improvements", "transition",
 ]

aios_core/openhands/agent_score.py

@@ -0,0 +1,77 @@
+"""Observable agent quality statistics for routing and prompt evaluation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AgentStats:
+    attempts: int = 0
+    successes: int = 0
+    first_pass_successes: int = 0
+    failures: int = 0
+    reviewer_rejections: int = 0
+    security_violations: int = 0
+    total_iterations: int = 0
+
+    @property
+    def success_rate(self) -> float:
+        return self.successes / self.attempts if self.attempts else 0.0
+
+    @property
+    def first_pass_rate(self) -> float:
+        return self.first_pass_successes / self.attempts if self.attempts else 0.0
+
+    @property
+    def avg_iterations(self) -> float:
+        return self.total_iterations / self.attempts if self.attempts else 0.0
+
+
+@dataclass
+class AgentScoreboard:
+    stats: dict[str, AgentStats] = field(default_factory=dict)
+
+    def record(
+        self,
+        role: str,
+        *,
+        success: bool,
+        iterations: int = 1,
+        reviewer_rejected: bool = False,
+        security_violation: bool = False,
+    ) -> None:
+        stat = self.stats.setdefault(role, AgentStats())
+        stat.attempts += 1
+        normalized_iterations = max(1, iterations)
+        stat.total_iterations += normalized_iterations
+        if success:
+            stat.successes += 1
+            if normalized_iterations == 1 and not reviewer_rejected:
+                stat.first_pass_successes += 1
+        else:
+            stat.failures += 1
+        if reviewer_rejected:
+            stat.reviewer_rejections += 1
+        if security_violation:
+            stat.security_violations += 1
+
+    def score(self, role: str, *, min_attempts: int = 3) -> float:
+        """Conservative score; sparse agents are not promoted over proven agents."""
+        stat = self.stats.get(role)
+        if not stat or not stat.attempts:
+            return 0.0
+        base = stat.success_rate
+        penalty = min(
+            0.5,
+            stat.reviewer_rejections / stat.attempts * 0.25
+            + stat.security_violations / stat.attempts * 0.5,
+        )
+        iteration_penalty = min(0.25, max(0.0, stat.avg_iterations - 1.0) * 0.1)
+        score = max(0.0, base - penalty - iteration_penalty)
+        if stat.attempts < min_attempts:
+            score *= stat.attempts / min_attempts
+        return score
+
+    def rank(self, roles: list[str] | tuple[str, ...]) -> list[str]:
+        return sorted(roles, key=self.score, reverse=True)

aios_core/openhands/audit.py

@@ -1,39 +1,24 @@
-"""Аудит-события OpenHands-контура поверх ``aios_core.audit_logger.AuditLogger``.
-
-Все значения проходят маскирование секретов до записи: в лог не попадают
-passwords, tokens, API keys, private keys, cookies (Этап 17 master-плана).
-"""
-
+"""OpenHands audit with secret masking and cryptographically linked checkpoints."""
 import re
 from typing import Any
+from uuid import uuid4
 
 from aios_core.audit_logger import AuditLogger
 
+from .audit_chain import AuditChain, ChainCheckpoint
 from .models import AgentRole
 
 EVENT_PREFIX = "openhands"
-
-# Ключи, значения которых маскируются всегда.
-_SENSITIVE_KEY = re.compile(
-    r"(password|passwd|secret|token|api[_-]?key|private[_-]?key|cookie|credential|authorization)",
-    re.IGNORECASE,
-)
-# Значения, похожие на секреты: длинные base64/hex-строки (≥20 символов).
+CHECKPOINT_ACTION = "audit_checkpoint"
+CRITICAL_ACTIONS = frozenset({"gate_pass", "gate_block", "handoff", "security_review"})
+_SENSITIVE_KEY = re.compile(r"(password|passwd|secret|token|api[_-]?key|private[_-]?key|cookie|credential|authorization)", re.IGNORECASE)
 _SENSITIVE_VALUE = re.compile(r"\b[A-Za-z0-9+/=_-]{20,}\b")
-
 MASK = "***"
 
 
 def mask_secrets(obj: Any) -> Any:
-    """Рекурсивно замаскировать секреты в dict/list/str перед записью в лог."""
     if isinstance(obj, dict):
-        masked = {}
-        for key, value in obj.items():
-            if _SENSITIVE_KEY.search(str(key)):
-                masked[key] = MASK
-            else:
-                masked[key] = mask_secrets(value)
-        return masked
+        return {key: MASK if _SENSITIVE_KEY.search(str(key)) else mask_secrets(value) for key, value in obj.items()}
     if isinstance(obj, (list, tuple)):
         return [mask_secrets(item) for item in obj]
     if isinstance(obj, str):
@@ -42,37 +27,59 @@ def mask_secrets(obj: Any) -> Any:
 
 
 class OHAuditLogger:
-    """Обёртка над AuditLogger: контурный тип события + маскирование секретов."""
+    """OpenHands audit facade with durable, cryptographically linked checkpoints."""
 
-    def __init__(self, logger: AuditLogger | None = None) -> None:
+    def __init__(self, logger: AuditLogger | None = None, chain: AuditChain | None = None) -> None:
         self._logger = logger or AuditLogger()
+        if chain is not None:
+            self._chain = chain
+        else:
+            persisted = [event for event in self._logger.query(limit=100000) if str(event.get("type", "")).startswith(f"{EVENT_PREFIX}.")]
+            self._chain = AuditChain.from_persisted(persisted)
 
-    def log(
-        self,
-        action: str,
-        task_id: str,
-        agent: AgentRole | str,
-        **fields: Any,
-    ) -> dict:
-        """Записать событие контура (тип ``openhands.<action>``) с маскированием."""
+    def log(self, action: str, task_id: str, agent: AgentRole | str, **fields: Any) -> dict:
         role = agent.value if isinstance(agent, AgentRole) else str(agent)
-        event = {
-            "type": f"{EVENT_PREFIX}.{action}",
-            "task_id": task_id,
-            "agent": role,
-            **fields,
-        }
-        return self._logger.record(mask_secrets(event))
+        event_id = uuid4().hex
+        event = mask_secrets({"type": f"{EVENT_PREFIX}.{action}", "task_id": task_id, "agent": role, **fields})
+        chain_event = self._chain.append(event_id, event)
+        event.update({"event_id": event_id, "parent_event_id": chain_event.parent_event_id, "event_hash": chain_event.event_hash})
+        result = self._logger.record(event)
+        if action in CRITICAL_ACTIONS:
+            self.checkpoint(task_id, agent, gate_decision=fields.get("decision"), commit_sha=fields.get("commit_sha"), diff_hash=fields.get("diff_hash"))
+        return result
 
     def log_transition(self, task_id: str, agent: AgentRole | str, src: str, dst: str, **fields: Any) -> dict:
-        """Событие смены статуса задачи."""
         return self.log("transition", task_id, agent, src=src, dst=dst, **fields)
 
     def log_decision(self, task_id: str, agent: AgentRole | str, decision: str, **fields: Any) -> dict:
-        """Событие решения (gate, review, retry, fail)."""
         return self.log("decision", task_id, agent, decision=decision, **fields)
 
+    def checkpoint(self, task_id: str = "system", agent: AgentRole | str = "system", *, gate_decision: str | None = None, commit_sha: str | None = None, diff_hash: str | None = None) -> ChainCheckpoint:
+        checkpoint = self._chain.checkpoint(task_id=task_id, agent=agent.value if isinstance(agent, AgentRole) else str(agent), gate_decision=gate_decision, commit_sha=commit_sha, diff_hash=diff_hash)
+        role = agent.value if isinstance(agent, AgentRole) else str(agent)
+        event = {
+            "type": f"{EVENT_PREFIX}.{CHECKPOINT_ACTION}",
+            "task_id": task_id,
+            "agent": role,
+            "sequence": checkpoint.sequence,
+            "last_event_id": checkpoint.last_event_id,
+            "root_hash": checkpoint.root_hash,
+            "gate_decision": checkpoint.gate_decision,
+            "commit_sha": checkpoint.commit_sha,
+            "diff_hash": checkpoint.diff_hash,
+            "previous_checkpoint_hash": checkpoint.previous_checkpoint_hash,
+            "checkpoint_hash": checkpoint.checkpoint_hash,
+        }
+        self._logger.record(event)
+        return checkpoint
+
+    def verify_chain(self) -> bool:
+        return self._chain.verify()
+
+    @property
+    def chain(self) -> AuditChain:
+        return self._chain
+
     @property
     def backend(self) -> AuditLogger:
-        """Нижележащий AuditLogger (для query/stats)."""
         return self._logger