forge-agent-runtime 0.1.0__py3-none-any.whl

forge_runtime/cli.py

@@ -0,0 +1,400 @@
+"""Forge Runtime command-line interface."""
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from forge_runtime.config import Settings
+from forge_runtime.orchestrator import ForgeMaster
+from forge_runtime.providers.factory import create_provider
+from forge_runtime.registry import AgentForgeRegistry, RegistryError
+from forge_runtime.sandbox import DockerSandboxExecutor, SandboxError
+from forge_runtime.storage import SQLiteStore
+
+app = typer.Typer(name="forge", help="Forge Runtime — multi-agent orchestration.")
+registry_cli = typer.Typer(help="Inspect the AgentForge registry.")
+agent_cli = typer.Typer(help="Inspect specialist agents.")
+skill_cli = typer.Typer(help="Inspect skills.")
+rule_cli = typer.Typer(help="Inspect engineering rules.")
+workflow_cli = typer.Typer(help="Inspect delivery workflows.")
+runs_cli = typer.Typer(help="Inspect orchestration runs.")
+sandbox_cli = typer.Typer(help="Build and operate the isolated Docker command sandbox.")
+app.add_typer(registry_cli, name="registry")
+app.add_typer(agent_cli, name="agent")
+app.add_typer(skill_cli, name="skill")
+app.add_typer(rule_cli, name="rule")
+app.add_typer(workflow_cli, name="workflow")
+app.add_typer(runs_cli, name="runs")
+app.add_typer(sandbox_cli, name="sandbox")
+console = Console()
+
+
+def _update_dotenv(path: Path, values: dict[str, str]) -> None:
+    """Atomically update selected keys without overwriting unrelated settings."""
+    if path.is_symlink():
+        raise ValueError(f"Refusing to write through a symlink: {path}")
+    for key, value in values.items():
+        if "\n" in value or "\r" in value:
+            raise ValueError(f"Environment value for {key} cannot contain a newline.")
+    existing = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    pending = dict(values)
+    output: list[str] = []
+    for line in existing:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#") and "=" in line:
+            key = line.split("=", 1)[0].strip()
+            if key in pending:
+                output.append(f"{key}={pending.pop(key)}")
+                continue
+        output.append(line)
+    for key, value in pending.items():
+        output.append(f"{key}={value}")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            newline="\n",
+            prefix=".forge-env-",
+            dir=path.parent,
+            delete=False,
+        ) as temporary:
+            temporary.write("\n".join(output) + "\n")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+            temporary_name = temporary.name
+        os.chmod(temporary_name, 0o600)
+        os.replace(temporary_name, path)
+    finally:
+        if temporary_name and os.path.exists(temporary_name):
+            os.unlink(temporary_name)
+
+
+@app.command("setup")
+def setup(
+    provider: str = typer.Option(
+        "openai",
+        "--provider",
+        help="Model provider to configure: openai, anthropic or mock.",
+    ),
+) -> None:
+    """Configure a provider and build the Docker sandbox in one step."""
+    normalized = provider.strip().lower()
+    if normalized not in {"openai", "anthropic", "mock"}:
+        console.print("[red]Provider must be openai, anthropic or mock.[/red]")
+        raise typer.Exit(2)
+
+    sdk_name = {"openai": "openai", "anthropic": "anthropic"}.get(normalized)
+    if sdk_name and importlib.util.find_spec(sdk_name) is None:
+        extra = "openai" if normalized == "openai" else "anthropic"
+        console.print(
+            f'[red]Provider SDK missing.[/red] Install it with: pip install -e ".[{extra}]"'
+        )
+        raise typer.Exit(2)
+
+    cfg = Settings()
+    updates = {"FORGE_DEFAULT_PROVIDER": normalized}
+    if cfg.sandbox_image == "forge-runtime-sandbox:latest":
+        updates["FORGE_SANDBOX_IMAGE"] = "forge-runtime-sandbox:internet-v1"
+    if normalized == "openai" and not cfg.openai_api_key:
+        key = typer.prompt("OpenAI API key", hide_input=True, confirmation_prompt=True).strip()
+        if not key:
+            console.print("[red]An OpenAI API key is required.[/red]")
+            raise typer.Exit(2)
+        updates["OPENAI_API_KEY"] = key
+    elif normalized == "anthropic" and not cfg.anthropic_api_key:
+        key = typer.prompt("Anthropic API key", hide_input=True, confirmation_prompt=True).strip()
+        if not key:
+            console.print("[red]An Anthropic API key is required.[/red]")
+            raise typer.Exit(2)
+        updates["ANTHROPIC_API_KEY"] = key
+
+    try:
+        _update_dotenv(Path.cwd() / ".env", updates)
+        executor = get_sandbox()
+        status = asyncio.run(executor.check())
+        if not status["image_available"]:
+            console.print(f"Building [bold]{executor.image}[/bold]...")
+            output = asyncio.run(executor.build_image())
+            if output.strip():
+                console.print(output)
+        final_status = asyncio.run(executor.check())
+        if not final_status["image_available"]:
+            raise SandboxError("Docker image build finished but the image is still unavailable.")
+        if executor.network == "bridge":
+            internet = asyncio.run(
+                executor.run(
+                    [
+                        "curl",
+                        "--fail",
+                        "--silent",
+                        "--show-error",
+                        "--max-time",
+                        "15",
+                        "-I",
+                        "https://pypi.org",
+                    ],
+                    writable=False,
+                    timeout_seconds=20,
+                )
+            )
+            if internet.exit_code != 0:
+                detail = internet.stderr.strip() or internet.stdout.strip()
+                raise SandboxError(
+                    "The Docker bridge is enabled but internet access could not be verified. "
+                    "Check your firewall, VPN or proxy settings. "
+                    f"curl output: {detail[:1000]}"
+                )
+    except (SandboxError, OSError, ValueError, TimeoutError) as exc:
+        console.print(f"[red]Setup failed:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    console.print(
+        f"[green]Forge Runtime is ready.[/green] Provider: [bold]{normalized}[/bold]. "
+        f"Sandbox network: [bold]{executor.network}[/bold]."
+    )
+    console.print('Start with: [bold]forge run "Describe the project task"[/bold]')
+
+
+def get_sandbox() -> DockerSandboxExecutor:
+    cfg = Settings()
+    return DockerSandboxExecutor(
+        workspace_root=cfg.workspace_root,
+        image=cfg.sandbox_image,
+        docker_binary=cfg.sandbox_docker_binary,
+        cpu_limit=cfg.sandbox_cpu_limit,
+        memory_mb=cfg.sandbox_memory_mb,
+        pids_limit=cfg.sandbox_pids_limit,
+        default_timeout_seconds=cfg.sandbox_default_timeout_seconds,
+        max_timeout_seconds=cfg.sandbox_max_timeout_seconds,
+        output_chars=cfg.sandbox_output_chars,
+        network=cfg.sandbox_network,
+        max_snapshot_files=cfg.sandbox_max_snapshot_files,
+        max_snapshot_bytes=cfg.sandbox_max_snapshot_mb * 1024 * 1024,
+    )
+
+
+@sandbox_cli.command("check")
+def sandbox_check() -> None:
+    executor = get_sandbox()
+    try:
+        status = asyncio.run(executor.check())
+    except SandboxError as exc:
+        console.print(f"[red]Sandbox unavailable:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]Docker Engine:[/green] {status['docker_server_version']}")
+    console.print(f"[bold]Workspace:[/bold] {status['workspace']}")
+    if status["image_available"]:
+        console.print(f"[green]Sandbox image ready:[/green] {status['image']}")
+    else:
+        console.print(f"[yellow]Image missing:[/yellow] {status['image']}")
+        console.print("Run [bold]forge sandbox build[/bold] to build it.")
+
+
+@sandbox_cli.command("build")
+def sandbox_build() -> None:
+    executor = get_sandbox()
+    console.print(f"Building [bold]{executor.image}[/bold]...")
+    try:
+        output = asyncio.run(executor.build_image())
+    except (SandboxError, TimeoutError) as exc:
+        console.print(f"[red]Sandbox image build failed:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    if output.strip():
+        console.print(output)
+
+
+@sandbox_cli.command("run")
+def sandbox_run(
+    argv: list[str] = typer.Argument(..., help="Allowlisted command and arguments."),
+    timeout_seconds: int | None = typer.Option(None, min=1, max=600),
+    read_write: bool = typer.Option(
+        False,
+        "--read-write",
+        help="Copy modified files back to the project (use only for trusted local runs).",
+    ),
+) -> None:
+    executor = get_sandbox()
+    try:
+        result = asyncio.run(
+            executor.run(
+                argv,
+                writable=read_write,
+                timeout_seconds=timeout_seconds,
+            )
+        )
+    except SandboxError as exc:
+        console.print(f"[red]Sandbox execution failed:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print_json(json.dumps(result.as_dict(), ensure_ascii=False))
+    if result.exit_code != 0:
+        raise typer.Exit(result.exit_code or 1)
+
+
+def get_registry(path: Path | None = None) -> AgentForgeRegistry:
+    cfg = Settings()
+    registry = AgentForgeRegistry(
+        local_path=path or cfg.agentforge_local_path,
+        repository=cfg.agentforge_repository,
+        ref=cfg.agentforge_ref,
+        source=cfg.agentforge_source,
+    )
+    registry.load()
+    return registry
+
+
+@registry_cli.command("validate")
+def registry_validate(
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    try:
+        registry = get_registry(registry_path)
+        console.print(
+            f"[green]AgentForge registry ready:[/green] "
+            f"{len(registry.agents)} agents, {len(registry.skills)} skills, "
+            f"{len(registry.rules)} rules, {len(registry.workflows)} workflows."
+        )
+        console.print(f"[dim]Source: {registry.loaded_from}[/dim]")
+    except RegistryError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+
+@agent_cli.command("list")
+def agent_list(
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    registry = get_registry(registry_path)
+    table = Table("Agent", "Mode", "Recommended skills", "Description")
+    for agent in registry.agents.values():
+        table.add_row(
+            agent.name,
+            agent.mode,
+            ", ".join(agent.recommended_skills),
+            agent.description,
+        )
+    console.print(table)
+
+
+@agent_cli.command("show")
+def agent_show(
+    name: str,
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    agent = get_registry(registry_path).get_agent(name)
+    console.print(f"[bold]{agent.name}[/bold] ({agent.mode})")
+    console.print(agent.description)
+    console.print(agent.content)
+
+
+@skill_cli.command("list")
+def skill_list(
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    registry = get_registry(registry_path)
+    table = Table("Skill", "Description")
+    for skill in registry.skills.values():
+        table.add_row(skill.name, skill.description)
+    console.print(table)
+
+
+@rule_cli.command("list")
+def rule_list(
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    registry = get_registry(registry_path)
+    for name in registry.rules:
+        console.print(f"- {name}")
+
+
+@workflow_cli.command("list")
+def workflow_list(
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+) -> None:
+    registry = get_registry(registry_path)
+    for name in registry.workflows:
+        console.print(f"- {name}")
+
+
+@app.command("run")
+def run(
+    goal: str = typer.Argument(..., help="Outcome to plan and delegate."),
+    provider: str | None = typer.Option(
+        None, "--provider", help="Provider override: mock, openai or anthropic."
+    ),
+    registry_path: Path | None = typer.Option(None, "--registry-path"),
+    max_parallel: int | None = typer.Option(None, min=1, max=64),
+) -> None:
+    cfg = Settings(
+        max_parallel_tasks=max_parallel or Settings().max_parallel_tasks,
+    )
+    registry = AgentForgeRegistry(
+        local_path=registry_path or cfg.agentforge_local_path,
+        repository=cfg.agentforge_repository,
+        ref=cfg.agentforge_ref,
+        source=cfg.agentforge_source,
+    )
+    runtime = ForgeMaster(
+        registry=registry,
+        provider=create_provider(provider or cfg.default_provider, cfg),
+        settings=cfg,
+    )
+    result = asyncio.run(runtime.execute(goal))
+    console.print(f"[bold]Run:[/bold] {result.id}")
+    console.print(f"[bold]Status:[/bold] {result.status.value}")
+    console.print(result.summary)
+
+
+@app.command("serve")
+def serve(
+    host: str | None = typer.Option(None, help="Bind address. Defaults to 127.0.0.1."),
+    port: int | None = typer.Option(None, min=1, max=65535),
+) -> None:
+    cfg = Settings()
+    bind_host = host or cfg.api_host
+    bind_port = port or cfg.api_port
+    local_hosts = {"127.0.0.1", "localhost", "::1"}
+    if bind_host not in local_hosts and not cfg.api_token:
+        console.print(
+            "[red]Refusing a network bind without FORGE_API_TOKEN.[/red] "
+            "Set a strong token in the environment or bind to 127.0.0.1."
+        )
+        raise typer.Exit(2)
+    try:
+        import uvicorn
+    except ImportError as exc:
+        console.print('[red]Install the API extra: pip install "forge-runtime[api]"[/red]')
+        raise typer.Exit(2) from exc
+    console.print(f"Forge Runtime API listening on http://{bind_host}:{bind_port}")
+    uvicorn.run("forge_runtime.api:app", host=bind_host, port=bind_port)
+
+
+@runs_cli.command("list")
+def runs_list(limit: int = typer.Option(20, min=1, max=100)) -> None:
+    table = Table("Run ID", "Status", "Goal", "Created")
+    for row in SQLiteStore(Settings().database_url).list_runs(limit):
+        table.add_row(row["id"], row["status"], row["goal"], row["created_at"])
+    console.print(table)
+
+
+@runs_cli.command("show")
+def runs_show(run_id: str) -> None:
+    data = SQLiteStore(Settings().database_url).get_run(run_id)
+    if data is None:
+        console.print("[red]Run not found.[/red]")
+        raise typer.Exit(1)
+    console.print_json(json.dumps(data, ensure_ascii=False, default=str))
+
+
+if __name__ == "__main__":
+    app()

forge_runtime/config.py

@@ -0,0 +1,41 @@
+"""Environment-backed runtime configuration."""
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="FORGE_", env_file=".env", extra="ignore")
+    environment: str = "development"
+    log_level: str = "INFO"
+    database_url: str = "sqlite:///./.forge/forge.db"
+    workspace_root: Path = Path(".")
+    max_parallel_tasks: int = Field(default=4, ge=1, le=64)
+    task_timeout_seconds: int = Field(default=900, ge=1, le=86400)
+    sandbox_enabled: bool = True
+    sandbox_network: Literal["bridge", "none"] = "bridge"
+    sandbox_image: str = "forge-runtime-sandbox:internet-v1"
+    sandbox_docker_binary: str = "docker"
+    sandbox_cpu_limit: float = Field(default=2.0, ge=0.25, le=16)
+    sandbox_memory_mb: int = Field(default=2048, ge=256, le=32768)
+    sandbox_pids_limit: int = Field(default=128, ge=32, le=2048)
+    sandbox_default_timeout_seconds: int = Field(default=180, ge=1, le=600)
+    sandbox_max_timeout_seconds: int = Field(default=600, ge=1, le=600)
+    sandbox_output_chars: int = Field(default=24000, ge=1000, le=100000)
+    sandbox_max_snapshot_files: int = Field(default=5000, ge=1, le=50000)
+    sandbox_max_snapshot_mb: int = Field(default=512, ge=1, le=4096)
+    default_provider: str = "mock"
+    agentforge_repository: str = "https://github.com/mhingan/agent-forge"
+    agentforge_ref: str = "main"
+    agentforge_source: Literal["auto", "installed", "local", "github"] = "auto"
+    agentforge_local_path: Path | None = None
+    openai_model: str = Field(default="gpt-4.1", validation_alias="OPENAI_MODEL")
+    openai_api_key: str | None = Field(default=None, validation_alias="OPENAI_API_KEY")
+    openai_base_url: str | None = Field(default=None, validation_alias="OPENAI_BASE_URL")
+    anthropic_model: str = Field(default="claude-sonnet-4-5", validation_alias="ANTHROPIC_MODEL")
+    anthropic_api_key: str | None = Field(default=None, validation_alias="ANTHROPIC_API_KEY")
+    api_host: str = "127.0.0.1"
+    api_port: int = Field(default=8787, ge=1, le=65535)
+    api_token: str | None = None

forge_runtime/evaluation.py

@@ -0,0 +1,22 @@
+"""Baseline output checks; replace or extend for domain-specific quality gates."""
+from dataclasses import dataclass
+
+from forge_runtime.models import AgentResult, TaskSpec
+
+
+@dataclass(frozen=True)
+class Evaluation:
+    passed: bool
+    reasons: tuple[str, ...]
+
+
+class Evaluator:
+    def evaluate(self, task: TaskSpec, result: AgentResult) -> Evaluation:
+        reasons = []
+        if not result.output.strip():
+            reasons.append("Output is empty.")
+        if not result.summary.strip():
+            reasons.append("Summary is empty.")
+        if len(result.output) > 100_000:
+            reasons.append("Output exceeds 100,000 characters.")
+        return Evaluation(passed=not reasons, reasons=tuple(reasons))

forge_runtime/graph.py

@@ -0,0 +1,85 @@
+"""Validate execution plans before any specialist task is dispatched."""
+from collections import defaultdict, deque
+
+from forge_runtime.models import ExecutionPlan
+
+
+class GraphError(ValueError):
+    """An execution plan violates a runtime invariant."""
+
+
+def validate_plan(
+    plan: ExecutionPlan,
+    known_agents: set[str],
+    known_skills: set[str],
+) -> None:
+    if not plan.goal.strip():
+        raise GraphError("Plan goal cannot be empty.")
+    if not plan.tasks or len(plan.tasks) > 100:
+        raise GraphError("Plan must contain between 1 and 100 tasks.")
+
+    ids = [task.id for task in plan.tasks]
+    if len(ids) != len(set(ids)):
+        raise GraphError("Duplicate task IDs in execution plan.")
+    known_ids = set(ids)
+
+    for task in plan.tasks:
+        if task.agent not in known_agents:
+            raise GraphError(
+                f"Unknown agent for task {task.id}: {task.agent}"
+            )
+        unknown_skills = set(task.skill_names) - known_skills
+        if unknown_skills:
+            raise GraphError(
+                f"Task {task.id} references unknown skills: {sorted(unknown_skills)}"
+            )
+        if task.requires_approval:
+            raise GraphError(
+                f"Task {task.id} requires human approval, but approval gates are not "
+                "enabled in this runtime version. The task was not dispatched."
+            )
+        if task.id in task.dependencies:
+            raise GraphError(f"Task {task.id} cannot depend on itself.")
+        missing = set(task.dependencies) - known_ids
+        if missing:
+            raise GraphError(
+                f"Task {task.id} references missing dependencies: {sorted(missing)}"
+            )
+
+    indegree = {task.id: len(task.dependencies) for task in plan.tasks}
+    children: dict[str, list[str]] = defaultdict(list)
+    for task in plan.tasks:
+        for dependency in task.dependencies:
+            children[dependency].append(task.id)
+
+    queue = deque(task_id for task_id, degree in indegree.items() if degree == 0)
+    visited = 0
+    while queue:
+        current = queue.popleft()
+        visited += 1
+        for child in children[current]:
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                queue.append(child)
+
+    if visited != len(plan.tasks):
+        raise GraphError("Task dependencies contain a cycle.")
+
+
+def blocked_tasks(
+    plan: ExecutionPlan,
+    failed: set[str],
+    completed: set[str],
+) -> set[str]:
+    """Return every nonterminal task that depends on failed work, directly or indirectly."""
+    blocked: set[str] = set()
+    changed = True
+    while changed:
+        changed = False
+        for task in plan.tasks:
+            if task.id in completed | failed | blocked:
+                continue
+            if set(task.dependencies) & (failed | blocked):
+                blocked.add(task.id)
+                changed = True
+    return blocked

forge_runtime/models.py

@@ -0,0 +1,137 @@
+"""Typed contracts for plans, tasks, agents, runs and events."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid4().hex[:12]}"
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class RunStatus(StrEnum):
+    PENDING = "pending"
+    PLANNING = "planning"
+    RUNNING = "running"
+    WAITING_APPROVAL = "waiting_approval"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class TaskStatus(StrEnum):
+    PENDING = "pending"
+    READY = "ready"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+    CANCELLED = "cancelled"
+
+
+class EventLevel(StrEnum):
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class AgentDefinition(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    name: str
+    description: str
+    path: str
+    content: str
+    recommended_skills: tuple[str, ...] = ()
+    mode: str = "subagent"
+
+
+class SkillDefinition(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    name: str
+    description: str
+    path: str
+    content: str = ""
+    references: dict[str, str] = Field(default_factory=dict)
+
+
+class TaskSpec(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("task"))
+    title: str
+    description: str
+    agent: str
+    dependencies: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    skill_names: list[str] = Field(default_factory=list)
+    max_attempts: int = Field(default=2, ge=1, le=5)
+    timeout_seconds: int = Field(default=900, ge=1)
+    requires_approval: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExecutionPlan(BaseModel):
+    goal: str
+    summary: str
+    tasks: list[TaskSpec]
+    final_acceptance_criteria: list[str] = Field(default_factory=list)
+
+
+class AgentRequest(BaseModel):
+    run_id: str
+    task: TaskSpec
+    agent: AgentDefinition
+    skills: list[SkillDefinition] = Field(default_factory=list)
+    project_context: str = ""
+    previous_results: dict[str, str] = Field(default_factory=dict)
+    attempt: int = 1
+
+
+class AgentResult(BaseModel):
+    output: str
+    summary: str
+    artifacts: list[dict[str, Any]] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    usage: dict[str, Any] = Field(default_factory=dict)
+
+
+class TaskRecord(BaseModel):
+    id: str
+    run_id: str
+    title: str
+    agent: str
+    status: TaskStatus = TaskStatus.PENDING
+    attempt: int = 0
+    output: str | None = None
+    error: str | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class RunRecord(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("run"))
+    goal: str
+    status: RunStatus = RunStatus.PENDING
+    plan: ExecutionPlan | None = None
+    summary: str | None = None
+    created_at: datetime = Field(default_factory=utc_now)
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class RuntimeEvent(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("evt"))
+    run_id: str
+    task_id: str | None = None
+    level: EventLevel = EventLevel.INFO
+    event_type: str
+    message: str
+    data: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=utc_now)