arkaos 4.7.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.7.0"
+version = "4.8.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/core/workflow/announcer.py

@@ -1,246 +0,0 @@
-"""Phase announcement system for ArkaOS workflows.
-
-Provides structured, visible announcements for workflow phases
-enforcing the Constitution's "full visibility" rule.
-
-Format: [PHASE] Starting: {name} | [PHASE] Completed: {name} ({duration}ms)
-"""
-
-import time
-from dataclasses import dataclass, field
-from typing import Callable
-
-
-@dataclass
-class Announcement:
-    """A single announcement record."""
-
-    phase_id: str
-    phase_name: str
-    event: str  # "starting" | "completed" | "failed" | "blocked" | "skipped"
-    duration_ms: int = 0
-    metadata: dict = field(default_factory=dict)
-    at: float = field(default_factory=time.time)
-
-
-class PhaseAnnouncer:
-    """Manages phase announcements with structured output.
-
-    Integrates with WorkflowEngine via on_visibility callback.
-    Tracks all announcements for session summary generation.
-    """
-
-    def __init__(self, on_announce: Callable[[str], None] | None = None):
-        """Initialize announcer.
-
-        Args:
-            on_announce: Callback to output announcement. Defaults to print.
-        """
-        self._on_announce = on_announce or print
-        self._announcements: list[Announcement] = []
-        self._phase_start_times: dict[str, float] = {}
-
-    def starting(self, phase_id: str, phase_name: str, **metadata: str) -> None:
-        """Announce phase starting.
-
-        Args:
-            phase_id: Unique phase identifier
-            phase_name: Human-readable phase name
-            **metadata: Additional context (agents, department, etc.)
-        """
-        self._phase_start_times[phase_id] = time.time()
-        announcement = Announcement(
-            phase_id=phase_id,
-            phase_name=phase_name,
-            event="starting",
-            metadata=metadata,
-        )
-        self._announcements.append(announcement)
-        self._emit(announcement)
-
-    def completed(self, phase_id: str, phase_name: str, output: str = "", **metadata: str) -> int:
-        """Announce phase completed.
-
-        Args:
-            phase_id: Unique phase identifier
-            phase_name: Human-readable phase name
-            output: Phase result summary
-            **metadata: Additional context
-
-        Returns:
-            Duration in milliseconds
-        """
-        start_time = self._phase_start_times.pop(phase_id, time.time())
-        duration_ms = int((time.time() - start_time) * 1000)
-
-        announcement = Announcement(
-            phase_id=phase_id,
-            phase_name=phase_name,
-            event="completed",
-            duration_ms=duration_ms,
-            metadata=metadata,
-        )
-        self._announcements.append(announcement)
-        self._emit(announcement)
-        return duration_ms
-
-    def failed(self, phase_id: str, phase_name: str, reason: str = "") -> None:
-        """Announce phase failed.
-
-        Args:
-            phase_id: Unique phase identifier
-            phase_name: Human-readable phase name
-            reason: Failure reason
-        """
-        announcement = Announcement(
-            phase_id=phase_id,
-            phase_name=phase_name,
-            event="failed",
-            metadata={"reason": reason} if reason else {},
-        )
-        self._announcements.append(announcement)
-        self._emit(announcement)
-
-    def blocked(self, phase_id: str, phase_name: str, reason: str = "") -> None:
-        """Announce phase blocked.
-
-        Args:
-            phase_id: Unique phase identifier
-            phase_name: Human-readable phase name
-            reason: Block reason
-        """
-        announcement = Announcement(
-            phase_id=phase_id,
-            phase_name=phase_name,
-            event="blocked",
-            metadata={"reason": reason} if reason else {},
-        )
-        self._announcements.append(announcement)
-        self._emit(announcement)
-
-    def skipped(self, phase_id: str, phase_name: str, reason: str = "") -> None:
-        """Announce phase skipped.
-
-        Args:
-            phase_id: Unique phase identifier
-            phase_name: Human-readable phase name
-            reason: Skip reason
-        """
-        announcement = Announcement(
-            phase_id=phase_id,
-            phase_name=phase_name,
-            event="skipped",
-            metadata={"reason": reason} if reason else {},
-        )
-        self._announcements.append(announcement)
-        self._emit(announcement)
-
-    def workflow_start(self, workflow_name: str, phase_count: int, tier: str) -> None:
-        """Announce workflow starting.
-
-        Args:
-            workflow_name: Name of the workflow
-            phase_count: Number of phases
-            tier: Workflow tier
-        """
-        msg = f"[WORKFLOW] Starting: {workflow_name} ({phase_count} phases, tier: {tier})"
-        self._on_announce(msg)
-
-    def workflow_complete(self, workflow_name: str, total_duration_ms: int) -> None:
-        """Announce workflow completed.
-
-        Args:
-            workflow_name: Name of the workflow
-            total_duration_ms: Total execution time
-        """
-        msg = f"[WORKFLOW] Completed: {workflow_name} (total: {total_duration_ms}ms)"
-        self._on_announce(msg)
-
-    def _emit(self, announcement: Announcement) -> None:
-        """Format and emit an announcement."""
-        if announcement.event == "starting":
-            agents = announcement.metadata.get("agents", "")
-            msg = f"[PHASE] Starting: {announcement.phase_name}"
-            if agents:
-                msg += f" (agents: {agents})"
-        elif announcement.event == "completed":
-            msg = f"[PHASE] Completed: {announcement.phase_name} ({announcement.duration_ms}ms)"
-        elif announcement.event == "failed":
-            reason = announcement.metadata.get("reason", "")
-            msg = f"[PHASE] Failed: {announcement.phase_name}"
-            if reason:
-                msg += f" — {reason}"
-        elif announcement.event == "blocked":
-            reason = announcement.metadata.get("reason", "")
-            msg = f"[PHASE] Blocked: {announcement.phase_name}"
-            if reason:
-                msg += f" (waiting for: {reason})"
-        elif announcement.event == "skipped":
-            reason = announcement.metadata.get("reason", "")
-            msg = f"[PHASE] Skipped: {announcement.phase_name}"
-            if reason:
-                msg += f" ({reason})"
-        else:
-            msg = f"[PHASE] {announcement.phase_name} — {announcement.event.upper()}"
-
-        self._on_announce(msg)
-
-    @property
-    def announcements(self) -> list[Announcement]:
-        """Get all announcements for this session."""
-        return self._announcements.copy()
-
-    def get_phase_announcements(
-        self, phase_id: str
-    ) -> tuple[Announcement | None, Announcement | None]:
-        """Get start and completion announcements for a phase.
-
-        Args:
-            phase_id: The phase identifier
-
-        Returns:
-            Tuple of (starting_announcement, completed_announcement) or (None, None)
-        """
-        start_ann = None
-        complete_ann = None
-        for ann in self._announcements:
-            if ann.phase_id == phase_id:
-                if ann.event == "starting":
-                    start_ann = ann
-                elif ann.event == "completed":
-                    complete_ann = ann
-        return start_ann, complete_ann
-
-    def validate_phase_completion(self, phase_id: str) -> bool:
-        """Check if a phase has both start and completion announcements.
-
-        Args:
-            phase_id: The phase to validate
-
-        Returns:
-            True if phase has both starting and completed announcements
-        """
-        start_ann, complete_ann = self.get_phase_announcements(phase_id)
-        return start_ann is not None and complete_ann is not None
-
-    def get_total_duration_ms(self) -> int:
-        """Calculate total duration across all completed phases.
-
-        Returns:
-            Total milliseconds
-        """
-        return sum(ann.duration_ms for ann in self._announcements if ann.event == "completed")
-
-
-def make_announcer(
-    on_announce: Callable[[str], None] | None = None,
-) -> PhaseAnnouncer:
-    """Factory to create a PhaseAnnouncer.
-
-    Args:
-        on_announce: Optional output callback
-
-    Returns:
-        Configured PhaseAnnouncer instance
-    """
-    return PhaseAnnouncer(on_announce=on_announce)

package/core/workflow/engine.py

@@ -1,260 +0,0 @@
-"""Workflow execution engine.
-
-Executes workflows phase by phase, respecting gates, conditions,
-and agent assignments. Enforces the Constitution's sequential validation
-and full visibility rules.
-"""
-
-from dataclasses import dataclass, field
-from typing import Optional, Callable, Any
-
-from core.workflow.schema import (
-    Workflow, Phase, PhaseStatus, GateType, Gate,
-)
-
-
-@dataclass
-class PhaseResult:
-    """Result of executing a single phase."""
-    phase_id: str
-    status: PhaseStatus
-    output: str = ""
-    agent_outputs: dict[str, str] = field(default_factory=dict)
-    duration_ms: int = 0
-
-
-@dataclass
-class GateResult:
-    """Result of evaluating a gate."""
-    passed: bool
-    gate_type: GateType
-    message: str = ""
-    verdict: str = ""
-
-
-class WorkflowEngine:
-    """Executes YAML-defined workflows with phase gates and visibility.
-
-    The engine enforces:
-    1. Sequential validation — Phase N+1 only starts after N completes
-    2. Full visibility — Every phase announces what's starting and what resulted
-    3. Quality Gate — Mandatory review before delivery
-    4. Gate evaluation — User approval, quality checks, or conditions
-    """
-
-    def __init__(
-        self,
-        on_phase_start: Optional[Callable[[Phase], None]] = None,
-        on_phase_complete: Optional[Callable[[Phase, PhaseResult], None]] = None,
-        on_gate_check: Optional[Callable[[Gate], GateResult]] = None,
-        on_visibility: Optional[Callable[[str], None]] = None,
-        budget_manager: Any = None,
-        obsidian_writer: Any = None,
-    ):
-        """Initialize the workflow engine.
-
-        Args:
-            on_phase_start: Called when a phase begins execution.
-            on_phase_complete: Called when a phase finishes.
-            on_gate_check: Called to evaluate a gate. Must return GateResult.
-            on_visibility: Called to announce status to the user.
-        """
-        self._on_phase_start = on_phase_start
-        self._on_phase_complete = on_phase_complete
-        self._on_gate_check = on_gate_check
-        self._on_visibility = on_visibility
-        self._budget_manager = budget_manager
-        self._obsidian_writer = obsidian_writer
-        self._history: list[PhaseResult] = []
-
-    def announce(self, message: str) -> None:
-        """Announce a status message (full visibility rule)."""
-        if self._on_visibility:
-            self._on_visibility(message)
-
-    def execute(self, workflow: Workflow) -> list[PhaseResult]:
-        """Execute a workflow from start to finish.
-
-        Phases run sequentially. Each phase must complete and pass
-        its gate before the next phase starts.
-
-        Args:
-            workflow: The workflow definition to execute.
-
-        Returns:
-            List of PhaseResults for each executed phase.
-        """
-        workflow.status = PhaseStatus.IN_PROGRESS
-        results: list[PhaseResult] = []
-
-        self.announce(
-            f"Starting workflow: {workflow.name} "
-            f"({len(workflow.phases)} phases, tier: {workflow.tier.value})"
-        )
-
-        for i, phase in enumerate(workflow.phases):
-            # Check skip condition
-            if phase.skip_if and self._evaluate_condition(phase.skip_if):
-                phase.status = PhaseStatus.SKIPPED
-                self.announce(f"Phase {i}: {phase.name} — SKIPPED (condition met)")
-                results.append(PhaseResult(
-                    phase_id=phase.id,
-                    status=PhaseStatus.SKIPPED,
-                    output="Skipped: condition evaluated to true",
-                ))
-                continue
-
-            # Check dependencies
-            if phase.depends_on:
-                unmet = [
-                    dep for dep in phase.depends_on
-                    if not self._is_phase_complete(workflow, dep)
-                ]
-                if unmet:
-                    phase.status = PhaseStatus.BLOCKED
-                    self.announce(
-                        f"Phase {i}: {phase.name} — BLOCKED "
-                        f"(waiting for: {', '.join(unmet)})"
-                    )
-                    results.append(PhaseResult(
-                        phase_id=phase.id,
-                        status=PhaseStatus.BLOCKED,
-                        output=f"Blocked by: {', '.join(unmet)}",
-                    ))
-                    continue
-
-            # Execute phase
-            self.announce(
-                f"Phase {i}: {phase.name} — STARTING "
-                f"(agents: {', '.join(a.agent_id for a in phase.agents)})"
-            )
-            phase.status = PhaseStatus.IN_PROGRESS
-
-            if self._on_phase_start:
-                self._on_phase_start(phase)
-
-            result = self._execute_phase(phase)
-            results.append(result)
-
-            if result.status == PhaseStatus.FAILED:
-                phase.status = PhaseStatus.FAILED
-                workflow.status = PhaseStatus.FAILED
-                self.announce(f"Phase {i}: {phase.name} — FAILED: {result.output}")
-                break
-
-            phase.status = PhaseStatus.COMPLETED
-            phase.result = result.output
-
-            if self._on_phase_complete:
-                self._on_phase_complete(phase, result)
-
-            # Save outputs to Obsidian vault (NON-NEGOTIABLE: obsidian-output)
-            if self._obsidian_writer and hasattr(phase, "outputs"):
-                for output in getattr(phase, "outputs", []):
-                    obsidian_path = getattr(output, "obsidian_path", "")
-                    if obsidian_path and result.output:
-                        try:
-                            saved = self._obsidian_writer.save(
-                                obsidian_path=obsidian_path,
-                                content=result.output,
-                                department=workflow.department,
-                                workflow=workflow.id,
-                            )
-                            self.announce(f"Saved to vault: {saved.name}")
-                        except Exception as e:
-                            self.announce(f"Vault save failed: {e}")
-
-            self.announce(f"Phase {i}: {phase.name} — COMPLETED")
-
-            # Evaluate gate
-            gate_result = self._evaluate_gate(phase.gate)
-            if not gate_result.passed:
-                self.announce(
-                    f"Gate after Phase {i} — REJECTED: {gate_result.message}"
-                )
-                # Loop back: reset phase to pending for retry
-                phase.status = PhaseStatus.PENDING
-                results.append(PhaseResult(
-                    phase_id=f"{phase.id}_gate",
-                    status=PhaseStatus.FAILED,
-                    output=f"Gate rejected: {gate_result.message}",
-                ))
-                workflow.status = PhaseStatus.FAILED
-                break
-
-        if workflow.all_phases_complete():
-            workflow.status = PhaseStatus.COMPLETED
-            self.announce(f"Workflow {workflow.name} — COMPLETED")
-
-        self._history.extend(results)
-        return results
-
-    def _execute_phase(self, phase: Phase) -> PhaseResult:
-        """Execute a single phase.
-
-        In the real implementation, this dispatches to agents via
-        the runtime adapter. Here we return a placeholder result
-        that the calling code fills in.
-        """
-        agent_ids = [a.agent_id for a in phase.agents]
-        return PhaseResult(
-            phase_id=phase.id,
-            status=PhaseStatus.COMPLETED,
-            output=f"Phase {phase.name} executed by {', '.join(agent_ids)}",
-            agent_outputs={a.agent_id: "completed" for a in phase.agents},
-        )
-
-    def _evaluate_gate(self, gate: Gate) -> GateResult:
-        """Evaluate a phase gate."""
-        if gate.type == GateType.AUTO:
-            return GateResult(passed=True, gate_type=GateType.AUTO, message="Auto-pass")
-
-        if gate.type == GateType.BUDGET_CHECK and self._budget_manager:
-            return self._evaluate_budget_gate(gate)
-
-        if self._on_gate_check:
-            return self._on_gate_check(gate)
-
-        # Default: pass
-        return GateResult(passed=True, gate_type=gate.type, message="Default pass")
-
-    def _evaluate_budget_gate(self, gate: Gate) -> GateResult:
-        """Evaluate a budget gate using the budget manager."""
-        # Default tier for budget checks (can be overridden via gate metadata)
-        tier = 2
-        estimated_tokens = 50_000  # Default estimate per phase
-
-        if self._budget_manager.check_budget(tier, estimated_tokens):
-            needs_approval = self._budget_manager.needs_approval(tier)
-            msg = "Budget OK"
-            if needs_approval:
-                msg = "Budget OK (>80% used — Tier 0 notified)"
-                self.announce(f"Budget warning: tier {tier} at >80% monthly usage")
-            return GateResult(passed=True, gate_type=GateType.BUDGET_CHECK, message=msg)
-
-        summary = self._budget_manager.get_summary(tier)
-        return GateResult(
-            passed=False,
-            gate_type=GateType.BUDGET_CHECK,
-            message=f"Budget exceeded: {summary.used}/{summary.allocated} tokens used ({summary.percent_used}%). Needs Tier 0 approval.",
-        )
-
-    def _evaluate_condition(self, condition: str) -> bool:
-        """Evaluate a skip/branch condition.
-
-        For safety, only evaluates simple boolean expressions.
-        """
-        # In production, this would evaluate against workflow context
-        return False
-
-    def _is_phase_complete(self, workflow: Workflow, phase_id: str) -> bool:
-        """Check if a specific phase is complete."""
-        phase = workflow.get_phase_by_id(phase_id)
-        if phase is None:
-            return False
-        return phase.status in (PhaseStatus.COMPLETED, PhaseStatus.SKIPPED)
-
-    @property
-    def history(self) -> list[PhaseResult]:
-        """Get the execution history."""
-        return self._history