execforge 0.1.0__py3-none-any.whl

orchestrator/services/agent_service.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+
+from sqlalchemy import delete
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orchestrator.exceptions import ConfigError
+from orchestrator.storage.models import AgentORM, RunORM
+
+
+class AgentService:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def add(
+        self,
+        name: str,
+        prompt_source_id: int,
+        project_repo_id: int,
+        execution_backend: str = "multi",
+        task_selector_strategy: str = "priority_then_oldest",
+        validation_policy: list[dict] | None = None,
+        model_settings: dict | None = None,
+        safety_settings: dict | None = None,
+        push_policy: str = "never",
+        autonomy_level: str = "semi-auto",
+        max_steps: int = 20,
+    ) -> AgentORM:
+        item = AgentORM(
+            name=name,
+            prompt_source_id=prompt_source_id,
+            project_repo_id=project_repo_id,
+            execution_backend=execution_backend,
+            task_selector_strategy=task_selector_strategy,
+            validation_policy_json=json.dumps(validation_policy or []),
+            model_settings_json=json.dumps(model_settings or {}),
+            safety_settings_json=json.dumps(safety_settings or {}),
+            commit_policy_json=json.dumps({"message_template": "feat(agent): complete {task_ref} {title}"}),
+            push_policy=push_policy,
+            autonomy_level=autonomy_level,
+            max_steps=max_steps,
+            active=True,
+        )
+        self.session.add(item)
+        self.session.flush()
+        return item
+
+    def list(self) -> list[AgentORM]:
+        return list(self.session.scalars(select(AgentORM).order_by(AgentORM.id)).all())
+
+    def get(self, agent_id_or_name: str) -> AgentORM | None:
+        stmt = select(AgentORM).where(AgentORM.name == agent_id_or_name)
+        item = self.session.scalar(stmt)
+        if item:
+            return item
+        if agent_id_or_name.isdigit():
+            return self.session.get(AgentORM, int(agent_id_or_name))
+        return None
+
+    def update(self, agent: AgentORM, updates: dict[str, str]) -> AgentORM:
+        def parse_jsonish(value: str):
+            lowered = value.strip().lower()
+            if lowered == "true":
+                return True
+            if lowered == "false":
+                return False
+            if lowered == "null":
+                return None
+            try:
+                if value.strip().isdigit() or (value.strip().startswith("-") and value.strip()[1:].isdigit()):
+                    return int(value)
+            except Exception:
+                pass
+            return value
+
+        for key, value in updates.items():
+            if key in {"name", "execution_backend", "task_selector_strategy", "push_policy", "autonomy_level"}:
+                setattr(agent, key, str(value))
+                continue
+            if key in {"max_steps"}:
+                try:
+                    setattr(agent, key, int(value))
+                except ValueError as exc:
+                    raise ConfigError(f"Invalid integer for {key}: {value}") from exc
+                continue
+            if key in {"active"}:
+                lowered = str(value).strip().lower()
+                if lowered in {"true", "1", "yes", "y", "on"}:
+                    setattr(agent, key, True)
+                elif lowered in {"false", "0", "no", "n", "off"}:
+                    setattr(agent, key, False)
+                else:
+                    raise ConfigError(f"Invalid boolean for {key}: {value}")
+                continue
+            if key.startswith("model_settings."):
+                inner_key = key.removeprefix("model_settings.")
+                payload = json.loads(agent.model_settings_json or "{}")
+                payload[inner_key] = parse_jsonish(value)
+                agent.model_settings_json = json.dumps(payload)
+                continue
+            if key.startswith("safety_settings."):
+                inner_key = key.removeprefix("safety_settings.")
+                payload = json.loads(agent.safety_settings_json or "{}")
+                payload[inner_key] = parse_jsonish(value)
+                agent.safety_settings_json = json.dumps(payload)
+                continue
+            if key.startswith("commit_policy."):
+                inner_key = key.removeprefix("commit_policy.")
+                payload = json.loads(agent.commit_policy_json or "{}")
+                payload[inner_key] = parse_jsonish(value)
+                agent.commit_policy_json = json.dumps(payload)
+                continue
+            raise ConfigError(f"Unknown agent config key: {key}")
+        self.session.flush()
+        return agent
+
+    def delete_full(self, agent: AgentORM) -> None:
+        self.session.execute(delete(RunORM).where(RunORM.agent_id == agent.id))
+        self.session.delete(agent)
+        self.session.flush()

orchestrator/services/project_service.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orchestrator.git.service import GitService
+from orchestrator.storage.models import ProjectRepoORM
+
+
+class ProjectService:
+    def __init__(self, session: Session, git: GitService):
+        self.session = session
+        self.git = git
+
+    def add(
+        self,
+        name: str,
+        local_path: str,
+        default_branch: str = "main",
+        allowed_branch_pattern: str = "agent/*",
+    ) -> ProjectRepoORM:
+        repo_path = Path(local_path).expanduser().resolve()
+        self.git.ensure_git_repo(repo_path)
+        item = ProjectRepoORM(
+            name=name,
+            local_path=str(repo_path),
+            default_branch=default_branch,
+            allowed_branch_pattern=allowed_branch_pattern,
+            active=True,
+        )
+        self.session.add(item)
+        self.session.flush()
+        return item
+
+    def list(self) -> list[ProjectRepoORM]:
+        return list(self.session.scalars(select(ProjectRepoORM).order_by(ProjectRepoORM.id)).all())
+
+    def get(self, repo_id_or_name: str) -> ProjectRepoORM | None:
+        stmt = select(ProjectRepoORM).where(ProjectRepoORM.name == repo_id_or_name)
+        item = self.session.scalar(stmt)
+        if item:
+            return item
+        if repo_id_or_name.isdigit():
+            return self.session.get(ProjectRepoORM, int(repo_id_or_name))
+        return None

orchestrator/services/prompt_source_service.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orchestrator.config import AppPaths
+from orchestrator.git.service import GitService
+from orchestrator.storage.models import PromptSourceORM
+
+
+class PromptSourceService:
+    def __init__(self, session: Session, paths: AppPaths, git: GitService):
+        self.session = session
+        self.paths = paths
+        self.git = git
+
+    def add(
+        self,
+        name: str,
+        repo_url: str,
+        branch: str = "main",
+        folder_scope: str | None = None,
+        sync_strategy: str = "ff-only",
+        clone_path: str | None = None,
+    ) -> PromptSourceORM:
+        clone = Path(clone_path) if clone_path else self.paths.prompt_sources_dir / name
+        item = PromptSourceORM(
+            name=name,
+            repo_url=repo_url,
+            local_clone_path=str(clone),
+            branch=branch,
+            folder_scope=folder_scope,
+            sync_strategy=sync_strategy,
+            active=True,
+        )
+        self.session.add(item)
+        self.session.flush()
+        return item
+
+    def list(self) -> list[PromptSourceORM]:
+        return list(self.session.scalars(select(PromptSourceORM).order_by(PromptSourceORM.id)).all())
+
+    def get(self, source_id_or_name: str) -> PromptSourceORM | None:
+        stmt = select(PromptSourceORM).where(PromptSourceORM.name == source_id_or_name)
+        source = self.session.scalar(stmt)
+        if source:
+            return source
+        if source_id_or_name.isdigit():
+            return self.session.get(PromptSourceORM, int(source_id_or_name))
+        return None
+
+    def sync(self, source: PromptSourceORM, bootstrap_missing_branch: bool = False) -> None:
+        path = Path(source.local_clone_path)
+        if not path.exists():
+            self.git.clone(source.repo_url, path, source.branch, bootstrap_missing_branch=bootstrap_missing_branch)
+        else:
+            self.git.ensure_git_repo(path)
+            self.git.pull(
+                path,
+                source.sync_strategy,
+                branch=source.branch,
+                bootstrap_missing_branch=bootstrap_missing_branch,
+            )

orchestrator/services/run_service.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from datetime import datetime
+import json
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orchestrator.storage.models import RunORM
+
+
+class RunService:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def create(self, agent_id: int, task_id: int | None, logs_path: str | None = None) -> RunORM:
+        run = RunORM(agent_id=agent_id, task_id=task_id, started_at=datetime.utcnow(), status="running", logs_path=logs_path)
+        self.session.add(run)
+        self.session.flush()
+        return run
+
+    def complete(
+        self,
+        run: RunORM,
+        status: str,
+        summary: str,
+        tool_invocations: list[dict] | None = None,
+        validation_results: list[dict] | None = None,
+        commit_sha: str | None = None,
+        branch_name: str | None = None,
+    ) -> None:
+        run.finished_at = datetime.utcnow()
+        run.status = status
+        run.summary = summary
+        run.tool_invocations_json = json.dumps(tool_invocations or [])
+        run.validation_results_json = json.dumps(validation_results or [])
+        run.commit_sha = commit_sha
+        run.branch_name = branch_name
+
+    def list(self, limit: int = 50) -> list[RunORM]:
+        stmt = select(RunORM).order_by(RunORM.id.desc()).limit(limit)
+        return list(self.session.scalars(stmt).all())

orchestrator/services/step_executor.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from orchestrator.backends.base import ExecutionBackend
+from orchestrator.domain.types import BackendContext, StepExecutionResult, TaskStep
+from orchestrator.exceptions import BackendError
+from orchestrator.storage.models import TaskORM
+
+
+class StepExecutor:
+    def __init__(self, registry: dict[str, ExecutionBackend], backend_priority: list[str]):
+        self.registry = registry
+        self.backend_priority = backend_priority
+
+    def execute_steps(
+        self,
+        steps: list[TaskStep],
+        task: TaskORM,
+        project_path: Path,
+        prompt_root: Path,
+        context: BackendContext,
+    ) -> list[StepExecutionResult]:
+        if len(steps) > context.max_steps:
+            raise BackendError(f"Task has {len(steps)} steps but agent max_steps is {context.max_steps}")
+
+        results: list[StepExecutionResult] = []
+        for step in steps:
+            results.append(self.execute_step(step, task, project_path, prompt_root, context))
+        return results
+
+    def execute_step(
+        self,
+        step: TaskStep,
+        task: TaskORM,
+        project_path: Path,
+        prompt_root: Path,
+        context: BackendContext,
+    ) -> StepExecutionResult:
+        candidates = self._candidate_backends(step)
+        attempt_errors: list[str] = []
+        for backend in candidates:
+            backend_result = backend.execute_step(step, task, project_path, prompt_root, context)
+            if backend_result.success:
+                return StepExecutionResult(
+                    step_id=step.id,
+                    step_type=step.type,
+                    backend=backend.name,
+                    success=True,
+                    summary=backend_result.summary,
+                    stdout=backend_result.stdout,
+                    stderr=backend_result.stderr,
+                    tool_invocations=backend_result.tool_invocations,
+                )
+
+            detail = backend_result.stderr.strip() or backend_result.stdout.strip()
+            detail_snippet = f" details={detail[:240]}" if detail else ""
+            attempt_errors.append(f"{backend.name}: {backend_result.summary}{detail_snippet}")
+
+        attempts_text = " | ".join(attempt_errors) if attempt_errors else "no backend attempts executed"
+        raise BackendError(f"Step '{step.id}' failed. Attempts: {attempts_text}")
+
+    def _candidate_backends(self, step: TaskStep) -> list[ExecutionBackend]:
+        preferred = list(step.tool_preferences or [])
+        fallback = [name for name in self.backend_priority if name not in preferred]
+        candidates = preferred + fallback if preferred else list(self.backend_priority)
+
+        # Ensure enabled backends not present in backend_priority are still considered.
+        for backend_name in self.registry.keys():
+            if backend_name not in candidates:
+                candidates.append(backend_name)
+        unavailable: list[str] = []
+        unsupported: list[str] = []
+        selected: list[ExecutionBackend] = []
+        for backend_name in candidates:
+            backend = self.registry.get(backend_name)
+            if not backend:
+                continue
+            if not backend.supports(step):
+                unsupported.append(backend_name)
+                continue
+            if not backend.is_available():
+                unavailable.append(backend_name)
+                continue
+            selected.append(backend)
+        if selected:
+            return selected
+        suffix_parts: list[str] = []
+        if preferred:
+            suffix_parts.append(f"preferred={preferred}")
+            suffix_parts.append(f"fallback={fallback}")
+        if unavailable:
+            suffix_parts.append(f"unavailable={unavailable}")
+        if unsupported:
+            suffix_parts.append(f"unsupported={unsupported}")
+        suffix_parts.append(f"enabled={list(self.registry.keys())}")
+        suffix = " " + " ".join(suffix_parts) if suffix_parts else ""
+        raise BackendError(
+            f"No backend available for step '{step.id}' type='{step.type}' preferences={candidates}{suffix}"
+        )

orchestrator/services/task_service.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from datetime import datetime
+import json
+from pathlib import Path
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from orchestrator.domain.types import PromptTask
+from orchestrator.prompts.parser import parse_task_file, parse_task_raw
+from orchestrator.storage.models import AgentORM, PromptSourceORM, TaskORM
+
+
+PRIORITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+VALID_TASK_STATUSES = {"todo", "ready", "in_progress", "done", "failed", "blocked"}
+
+
+class TaskService:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def discover_and_upsert(self, source: PromptSourceORM) -> int:
+        root = Path(source.local_clone_path)
+        if source.folder_scope:
+            normalized_scope = str(source.folder_scope).lstrip("/\\")
+            scan_root = root / normalized_scope
+        else:
+            scan_root = root
+        if not scan_root.exists():
+            return 0
+        files = sorted(
+            [*scan_root.rglob("*.md"), *scan_root.rglob("*.yaml"), *scan_root.rglob("*.yml")],
+            key=lambda p: str(p),
+        )
+        count = 0
+        for file in files:
+            rel = str(file.relative_to(root)).replace("\\", "/")
+            parsed = parse_task_file(file, rel)
+            self._upsert(source.id, parsed)
+            count += 1
+        return count
+
+    def _upsert(self, prompt_source_id: int, parsed: PromptTask) -> TaskORM:
+        stmt = select(TaskORM).where(
+            TaskORM.prompt_source_id == prompt_source_id,
+            TaskORM.source_path == parsed.source_path,
+        )
+        existing = self.session.scalar(stmt)
+        if existing:
+            existing.title = parsed.title
+            existing.description = parsed.description
+            existing.priority = parsed.priority
+            existing.labels_json = json.dumps(parsed.labels)
+            existing.dependencies_json = json.dumps(parsed.depends_on)
+            existing.target_paths_json = json.dumps(parsed.target_paths)
+            existing.acceptance_criteria_json = json.dumps(parsed.acceptance_criteria)
+            existing.target_repo = parsed.target_repo
+            existing.raw_content = parsed.raw_content
+            existing.last_seen_hash = parsed.last_seen_hash
+            existing.external_id = parsed.external_id
+            existing.updated_at = datetime.utcnow()
+            if existing.status in {"done", "failed", "blocked", "in_progress"}:
+                return existing
+            existing.status = parsed.status
+            return existing
+
+        item = TaskORM(
+            prompt_source_id=prompt_source_id,
+            external_id=parsed.external_id,
+            source_path=parsed.source_path,
+            title=parsed.title,
+            description=parsed.description,
+            labels_json=json.dumps(parsed.labels),
+            priority=parsed.priority,
+            status=parsed.status,
+            dependencies_json=json.dumps(parsed.depends_on),
+            target_paths_json=json.dumps(parsed.target_paths),
+            target_repo=parsed.target_repo,
+            acceptance_criteria_json=json.dumps(parsed.acceptance_criteria),
+            raw_content=parsed.raw_content,
+            last_seen_hash=parsed.last_seen_hash,
+            updated_at=datetime.utcnow(),
+        )
+        self.session.add(item)
+        self.session.flush()
+        return item
+
+    def list(self, status: str | None = None) -> list[TaskORM]:
+        stmt = select(TaskORM)
+        if status:
+            stmt = stmt.where(TaskORM.status == status)
+        tasks = list(self.session.scalars(stmt).all())
+        return sorted(tasks, key=lambda t: (PRIORITY_ORDER.get(t.priority, 99), t.updated_at))
+
+    def get(self, task_id: int) -> TaskORM | None:
+        return self.session.get(TaskORM, task_id)
+
+    def eligible_for_agent(
+        self,
+        agent: AgentORM,
+        project_name: str | None = None,
+        exclude_task_ids: set[int] | None = None,
+    ) -> list[TaskORM]:
+        tasks = self.list(status=None)
+        by_external = {t.external_id: t for t in tasks if t.external_id}
+        excluded = exclude_task_ids or set()
+        eligible: list[TaskORM] = []
+        for task in tasks:
+            if task.prompt_source_id != agent.prompt_source_id:
+                continue
+            if task.id in excluded:
+                continue
+            if task.status not in {"todo", "ready"}:
+                continue
+            if task.target_repo and task.target_repo != "*":
+                if not project_name or task.target_repo != project_name:
+                    continue
+            deps = json.loads(task.dependencies_json or "[]")
+            if deps:
+                resolved = all(by_external.get(dep) and by_external[dep].status == "done" for dep in deps)
+                if not resolved:
+                    continue
+            eligible.append(task)
+        return eligible
+
+    def select_next_for_agent(
+        self,
+        agent: AgentORM,
+        project_name: str | None = None,
+        exclude_task_ids: set[int] | None = None,
+    ) -> TaskORM | None:
+        eligible = self.eligible_for_agent(
+            agent,
+            project_name=project_name,
+            exclude_task_ids=exclude_task_ids,
+        )
+        return eligible[0] if eligible else None
+
+    def mark_status(self, task: TaskORM, status: str) -> None:
+        if status not in VALID_TASK_STATUSES:
+            raise ValueError(f"Invalid task status: {status}")
+        task.status = status
+        task.updated_at = datetime.utcnow()
+
+    def set_status_by_id(self, task_id: int, status: str) -> TaskORM | None:
+        task = self.get(task_id)
+        if not task:
+            return None
+        self.mark_status(task, status)
+        return task
+
+    def parse_raw_task(self, task: TaskORM) -> PromptTask:
+        suffix = Path(task.source_path).suffix or ".md"
+        return parse_task_raw(task.raw_content, rel_path=task.source_path, suffix=suffix)

orchestrator/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage layer and ORM models."""

orchestrator/storage/db.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+
+from orchestrator.storage.models import Base
+
+
+def make_engine(db_file: str):
+    return create_engine(f"sqlite+pysqlite:///{db_file}", future=True)
+
+
+def init_db(engine) -> None:
+    Base.metadata.create_all(engine)
+
+
+@contextmanager
+def session_scope(engine):
+    session = Session(engine)
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

orchestrator/storage/models.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class PromptSourceORM(Base):
+    __tablename__ = "prompt_sources"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(120), unique=True, nullable=False)
+    repo_url: Mapped[str] = mapped_column(String(500), nullable=False)
+    local_clone_path: Mapped[str] = mapped_column(String(500), nullable=False)
+    branch: Mapped[str] = mapped_column(String(128), default="main")
+    folder_scope: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    sync_strategy: Mapped[str] = mapped_column(String(32), default="ff-only")
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+
+class ProjectRepoORM(Base):
+    __tablename__ = "project_repos"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(120), unique=True, nullable=False)
+    local_path: Mapped[str] = mapped_column(String(500), nullable=False)
+    default_branch: Mapped[str] = mapped_column(String(128), default="main")
+    allowed_branch_pattern: Mapped[str] = mapped_column(String(200), default="agent/*")
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+
+class AgentORM(Base):
+    __tablename__ = "agents"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(120), unique=True, nullable=False)
+    prompt_source_id: Mapped[int] = mapped_column(ForeignKey("prompt_sources.id"), nullable=False)
+    project_repo_id: Mapped[int] = mapped_column(ForeignKey("project_repos.id"), nullable=False)
+    task_selector_strategy: Mapped[str] = mapped_column(String(64), default="priority_then_oldest")
+    execution_backend: Mapped[str] = mapped_column(String(64), default="mock")
+    model_settings_json: Mapped[str] = mapped_column(Text, default="{}")
+    validation_policy_json: Mapped[str] = mapped_column(Text, default="[]")
+    commit_policy_json: Mapped[str] = mapped_column(Text, default="{}")
+    push_policy: Mapped[str] = mapped_column(String(32), default="never")
+    autonomy_level: Mapped[str] = mapped_column(String(32), default="semi-auto")
+    max_steps: Mapped[int] = mapped_column(Integer, default=20)
+    safety_settings_json: Mapped[str] = mapped_column(Text, default="{}")
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+
+class TaskORM(Base):
+    __tablename__ = "tasks"
+    __table_args__ = (UniqueConstraint("prompt_source_id", "source_path", name="uq_task_source_path"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    prompt_source_id: Mapped[int] = mapped_column(ForeignKey("prompt_sources.id"), nullable=False)
+    external_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    source_path: Mapped[str] = mapped_column(String(600), nullable=False)
+    title: Mapped[str] = mapped_column(String(300), nullable=False)
+    description: Mapped[str] = mapped_column(Text, default="")
+    labels_json: Mapped[str] = mapped_column(Text, default="[]")
+    priority: Mapped[str] = mapped_column(String(32), default="medium")
+    status: Mapped[str] = mapped_column(String(32), default="todo")
+    dependencies_json: Mapped[str] = mapped_column(Text, default="[]")
+    target_paths_json: Mapped[str] = mapped_column(Text, default="[]")
+    target_repo: Mapped[str | None] = mapped_column(String(120), nullable=True)
+    acceptance_criteria_json: Mapped[str] = mapped_column(Text, default="[]")
+    raw_content: Mapped[str] = mapped_column(Text, default="")
+    last_seen_hash: Mapped[str] = mapped_column(String(128), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+
+class RunORM(Base):
+    __tablename__ = "runs"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    agent_id: Mapped[int] = mapped_column(ForeignKey("agents.id"), nullable=False)
+    task_id: Mapped[int | None] = mapped_column(ForeignKey("tasks.id"), nullable=True)
+    started_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    status: Mapped[str] = mapped_column(String(32), default="running")
+    summary: Mapped[str] = mapped_column(Text, default="")
+    tool_invocations_json: Mapped[str] = mapped_column(Text, default="[]")
+    validation_results_json: Mapped[str] = mapped_column(Text, default="[]")
+    commit_sha: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    branch_name: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    logs_path: Mapped[str | None] = mapped_column(String(500), nullable=True)

orchestrator/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers."""