arkaos 2.0.0-alpha.1

package/core/tasks/manager.py

@@ -0,0 +1,150 @@
+"""Task manager — queue, track, and manage background tasks."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from core.tasks.schema import Task, TaskStatus, TaskType
+
+
+class TaskManager:
+    """Manages background task lifecycle.
+
+    Tasks are stored in memory and optionally persisted to a JSON file
+    for cross-session recovery.
+    """
+
+    def __init__(self, storage_path: str | Path = "") -> None:
+        self._tasks: dict[str, Task] = {}
+        self._counter: int = 0
+        self._storage_path = Path(storage_path) if storage_path else None
+        if self._storage_path and self._storage_path.exists():
+            self._load()
+
+    def create(
+        self,
+        title: str,
+        task_type: TaskType = TaskType.CUSTOM,
+        description: str = "",
+        department: str = "",
+        agent_id: str = "",
+        input_data: dict | None = None,
+    ) -> Task:
+        """Create and queue a new task."""
+        self._counter += 1
+        task_id = f"task-{self._counter:04d}"
+
+        task = Task(
+            id=task_id,
+            type=task_type,
+            title=title,
+            description=description,
+            status=TaskStatus.QUEUED,
+            department=department,
+            agent_id=agent_id,
+            input_data=input_data or {},
+            created_at=datetime.now().isoformat(),
+        )
+
+        self._tasks[task_id] = task
+        self._save()
+        return task
+
+    def get(self, task_id: str) -> Optional[Task]:
+        return self._tasks.get(task_id)
+
+    def start(self, task_id: str) -> bool:
+        task = self._tasks.get(task_id)
+        if task is None or task.is_terminal:
+            return False
+        task.start()
+        self._save()
+        return True
+
+    def complete(self, task_id: str, output: dict | None = None, path: str = "") -> bool:
+        task = self._tasks.get(task_id)
+        if task is None:
+            return False
+        task.complete(output, path)
+        self._save()
+        return True
+
+    def fail(self, task_id: str, error: str) -> bool:
+        task = self._tasks.get(task_id)
+        if task is None:
+            return False
+        task.fail(error)
+        self._save()
+        return True
+
+    def cancel(self, task_id: str) -> bool:
+        task = self._tasks.get(task_id)
+        if task is None or task.is_terminal:
+            return False
+        task.cancel()
+        self._save()
+        return True
+
+    def update_progress(self, task_id: str, percent: int, message: str = "") -> bool:
+        task = self._tasks.get(task_id)
+        if task is None:
+            return False
+        task.update_progress(percent, message)
+        self._save()
+        return True
+
+    def list_all(self, status: Optional[TaskStatus] = None) -> list[Task]:
+        if status:
+            return [t for t in self._tasks.values() if t.status == status]
+        return list(self._tasks.values())
+
+    def list_active(self) -> list[Task]:
+        return [t for t in self._tasks.values() if t.is_active]
+
+    def list_queued(self) -> list[Task]:
+        return self.list_all(TaskStatus.QUEUED)
+
+    def cleanup_completed(self, keep_last: int = 50) -> int:
+        """Remove old completed tasks, keeping the most recent."""
+        completed = [t for t in self._tasks.values() if t.is_terminal]
+        completed.sort(key=lambda t: t.completed_at or t.created_at, reverse=True)
+        to_remove = completed[keep_last:]
+        for task in to_remove:
+            del self._tasks[task.id]
+        if to_remove:
+            self._save()
+        return len(to_remove)
+
+    def summary(self) -> dict:
+        by_status: dict[str, int] = {}
+        for task in self._tasks.values():
+            by_status[task.status.value] = by_status.get(task.status.value, 0) + 1
+        return {
+            "total": len(self._tasks),
+            "by_status": by_status,
+            "active": len(self.list_active()),
+            "queued": len(self.list_queued()),
+        }
+
+    def _save(self) -> None:
+        if self._storage_path is None:
+            return
+        self._storage_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "counter": self._counter,
+            "tasks": {tid: t.model_dump(mode="json") for tid, t in self._tasks.items()},
+        }
+        with open(self._storage_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def _load(self) -> None:
+        if self._storage_path is None or not self._storage_path.exists():
+            return
+        content = self._storage_path.read_text().strip()
+        if not content:
+            return
+        data = json.loads(content)
+        self._counter = data.get("counter", 0)
+        for tid, tdata in data.get("tasks", {}).items():
+            self._tasks[tid] = Task.model_validate(tdata)

package/core/tasks/schema.py

@@ -0,0 +1,108 @@
+"""Task schema for background operations.
+
+Tasks represent async work: KB downloads, transcriptions, long-running
+analysis, AI generation, etc. Each task has a lifecycle and can be
+queried for status.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Any
+from pydantic import BaseModel, Field
+
+
+class TaskStatus(str, Enum):
+    QUEUED = "queued"
+    DOWNLOADING = "downloading"
+    PROCESSING = "processing"
+    READY = "ready"             # Needs human/AI interaction to continue
+    ANALYZING = "analyzing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class TaskType(str, Enum):
+    KB_DOWNLOAD = "kb_download"       # Download media (YouTube, etc.)
+    KB_TRANSCRIBE = "kb_transcribe"   # Transcribe audio/video
+    KB_ANALYZE = "kb_analyze"         # AI analysis of content
+    RESEARCH = "research"             # Background research
+    GENERATION = "generation"         # AI content/image generation
+    EXPORT = "export"                 # Export to external system
+    CUSTOM = "custom"
+
+
+class Task(BaseModel):
+    """A background task with lifecycle tracking."""
+    id: str
+    type: TaskType = TaskType.CUSTOM
+    title: str
+    description: str = ""
+    status: TaskStatus = TaskStatus.QUEUED
+    department: str = ""
+    agent_id: str = ""
+
+    # Input/output
+    input_data: dict[str, Any] = Field(default_factory=dict)
+    output_data: dict[str, Any] = Field(default_factory=dict)
+    output_path: str = ""             # File path for output
+
+    # Progress
+    progress_percent: int = 0         # 0-100
+    progress_message: str = ""
+
+    # Timing
+    created_at: str = ""
+    started_at: str = ""
+    completed_at: str = ""
+
+    # Error
+    error: str = ""
+    retry_count: int = 0
+    max_retries: int = 3
+
+    def start(self) -> None:
+        self.status = TaskStatus.PROCESSING
+        self.started_at = datetime.now().isoformat()
+
+    def complete(self, output: dict | None = None, path: str = "") -> None:
+        self.status = TaskStatus.COMPLETED
+        self.completed_at = datetime.now().isoformat()
+        self.progress_percent = 100
+        if output:
+            self.output_data = output
+        if path:
+            self.output_path = path
+
+    def fail(self, error: str) -> None:
+        self.error = error
+        if self.retry_count < self.max_retries:
+            self.retry_count += 1
+            self.status = TaskStatus.QUEUED
+            self.progress_message = f"Retry {self.retry_count}/{self.max_retries}"
+        else:
+            self.status = TaskStatus.FAILED
+
+    def cancel(self) -> None:
+        self.status = TaskStatus.CANCELLED
+
+    def update_progress(self, percent: int, message: str = "") -> None:
+        self.progress_percent = min(percent, 100)
+        if message:
+            self.progress_message = message
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in (TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.CANCELLED)
+
+    @property
+    def is_active(self) -> bool:
+        return self.status in (TaskStatus.DOWNLOADING, TaskStatus.PROCESSING, TaskStatus.ANALYZING)
+
+    @property
+    def duration_seconds(self) -> float | None:
+        if not self.started_at:
+            return None
+        start = datetime.fromisoformat(self.started_at)
+        end = datetime.fromisoformat(self.completed_at) if self.completed_at else datetime.now()
+        return (end - start).total_seconds()

package/core/workflow/__init__.py

@@ -0,0 +1,10 @@
+"""YAML-based workflow engine for ArkaOS v2.
+
+Declarative workflows with phases, conditions, gates, and parallelization.
+"""
+
+from core.workflow.schema import Workflow, Phase, Gate, PhaseStatus
+from core.workflow.engine import WorkflowEngine
+from core.workflow.loader import load_workflow
+
+__all__ = ["Workflow", "Phase", "Gate", "PhaseStatus", "WorkflowEngine", "load_workflow"]

package/core/workflow/engine.py

@@ -0,0 +1,216 @@
+"""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,
+    ):
+        """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._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)
+
+            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 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_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

package/core/workflow/loader.py

@@ -0,0 +1,28 @@
+"""Workflow YAML loader."""
+
+from pathlib import Path
+import yaml
+
+from core.workflow.schema import Workflow
+
+
+def load_workflow(path: str | Path) -> Workflow:
+    """Load a workflow from a YAML file.
+
+    Args:
+        path: Path to the workflow YAML file.
+
+    Returns:
+        Validated Workflow instance.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Workflow file not found: {path}")
+
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    if data is None:
+        raise ValueError(f"Empty workflow file: {path}")
+
+    return Workflow.model_validate(data)

package/core/workflow/schema.py

@@ -0,0 +1,129 @@
+"""Workflow schema — Pydantic models for declarative YAML workflows.
+
+Workflows define multi-phase execution plans with:
+- Sequential phases with assigned agents
+- Gates between phases (user approval, quality check, auto)
+- Conditions for skipping or branching
+- Parallel execution of independent agents within a phase
+- Quality Gate integration (mandatory for all departments)
+"""
+
+from enum import Enum
+from typing import Optional, Any
+from pydantic import BaseModel, Field
+
+
+class PhaseStatus(str, Enum):
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+class GateType(str, Enum):
+    USER_APPROVAL = "user_approval"     # Requires user to confirm
+    QUALITY_GATE = "quality_gate"       # Marta + Eduardo + Francisca
+    AUTO = "auto"                       # Passes automatically if phase succeeds
+    CONDITION = "condition"             # Passes if condition evaluates true
+
+
+class Gate(BaseModel):
+    """A gate between phases — controls flow progression."""
+    type: GateType = GateType.AUTO
+    description: str = ""
+    condition: Optional[str] = None     # Python expression for CONDITION type
+    required_verdict: str = "APPROVED"  # For QUALITY_GATE type
+    timeout_seconds: int = 0            # 0 = no timeout
+
+
+class AgentAssignment(BaseModel):
+    """An agent assigned to work within a phase."""
+    agent_id: str
+    role: str = ""                      # What this agent does in this phase
+    parallel: bool = False              # Can run in parallel with other agents
+    optional: bool = False              # Phase can complete without this agent
+
+
+class PhaseOutput(BaseModel):
+    """Expected output from a phase."""
+    type: str = "document"              # document, code, review, decision
+    format: str = ""                    # markdown, yaml, json, code
+    obsidian_path: str = ""             # Where to save in Obsidian vault
+    description: str = ""
+
+
+class Phase(BaseModel):
+    """A single phase in a workflow."""
+    id: str
+    name: str
+    description: str = ""
+    agents: list[AgentAssignment] = Field(default_factory=list)
+    gate: Gate = Field(default_factory=Gate)
+    outputs: list[PhaseOutput] = Field(default_factory=list)
+    depends_on: list[str] = Field(default_factory=list)
+    skip_if: Optional[str] = None       # Condition to skip this phase
+    status: PhaseStatus = PhaseStatus.PENDING
+    result: Optional[str] = None
+
+
+class WorkflowTier(str, Enum):
+    ENTERPRISE = "enterprise"           # Full 7-10 phase workflow
+    FOCUSED = "focused"                 # 3-4 phases for medium tasks
+    SPECIALIST = "specialist"           # 1-2 phases for simple tasks
+
+
+class Workflow(BaseModel):
+    """Complete workflow definition.
+
+    A workflow is a sequence of phases with gates between them.
+    Each phase has assigned agents and expected outputs.
+    Quality Gate (Phase N-1) is mandatory for all workflows.
+    """
+    id: str
+    name: str
+    description: str = ""
+    department: str
+    tier: WorkflowTier = WorkflowTier.ENTERPRISE
+    command: str = ""                   # The CLI command that triggers this
+
+    phases: list[Phase] = Field(default_factory=list)
+
+    # Workflow-level config
+    requires_branch: bool = False       # Must run on feature branch
+    requires_spec: bool = False         # Must have approved spec first
+    quality_gate_required: bool = True  # Quality Gate phase mandatory
+    max_duration_minutes: int = 0       # 0 = no limit
+
+    # Runtime state
+    current_phase: int = 0
+    status: PhaseStatus = PhaseStatus.PENDING
+
+    def get_current_phase(self) -> Optional[Phase]:
+        """Get the currently active phase."""
+        if 0 <= self.current_phase < len(self.phases):
+            return self.phases[self.current_phase]
+        return None
+
+    def get_phase_by_id(self, phase_id: str) -> Optional[Phase]:
+        """Find a phase by its ID."""
+        for phase in self.phases:
+            if phase.id == phase_id:
+                return phase
+        return None
+
+    def all_phases_complete(self) -> bool:
+        """Check if all phases are completed or skipped."""
+        return all(
+            p.status in (PhaseStatus.COMPLETED, PhaseStatus.SKIPPED)
+            for p in self.phases
+        )
+
+    def next_phase(self) -> Optional[Phase]:
+        """Get the next pending phase."""
+        for i, phase in enumerate(self.phases):
+            if phase.status == PhaseStatus.PENDING:
+                self.current_phase = i
+                return phase
+        return None