ags-cli 0.1.0__py3-none-any.whl

harness/memory/summarize.py

@@ -0,0 +1,68 @@
+"""Summarization pipeline.
+
+Produces provider-independent canonical summaries from the raw ``run_events``
+ledger. This is an extractive, deterministic summarizer (no model call) so
+the pipeline is testable offline; an LLM-backed summarizer can be swapped in behind
+the same function signature. The session's rolling ``summary`` lets a session be
+resumed from canonical state instead of a vendor transcript."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.enums import RunEventType
+from harness.models.run import Run
+from harness.models.run_event import RunEvent
+from harness.models.session import Session
+
+
+def _extractive_summary(objective: str, messages: list[str], max_chars: int = 1200) -> str:
+    head = f"Objective: {objective.strip()}"
+    body: list[str] = []
+    used = len(head)
+    for msg in messages:
+        snippet = msg.strip().replace("\n", " ")
+        if not snippet:
+            continue
+        line = f"- {snippet[:240]}"
+        if used + len(line) > max_chars:
+            break
+        body.append(line)
+        used += len(line)
+    return head + ("\nKey outputs:\n" + "\n".join(body) if body else "")
+
+
+async def summarize_session(session: AsyncSession, session_id: uuid.UUID) -> str:
+    """Recompute and persist the canonical session summary + a snapshot."""
+    sess = (
+        await session.execute(select(Session).where(Session.id == session_id))
+    ).scalar_one()
+
+    run_ids = (
+        await session.execute(select(Run.id).where(Run.session_id == session_id))
+    ).scalars().all()
+
+    messages: list[str] = []
+    if run_ids:
+        rows = (
+            await session.execute(
+                select(RunEvent.payload)
+                .where(
+                    RunEvent.run_id.in_(run_ids),
+                    RunEvent.type == RunEventType.message,
+                )
+                .order_by(RunEvent.ts.asc())
+            )
+        ).scalars().all()
+        messages = [p.get("text", "") for p in rows if isinstance(p, dict)]
+
+    summary = _extractive_summary(sess.canonical_objective, messages)
+    sess.summary = summary
+    snapshots = list(sess.summary_snapshots or [])
+    snapshots.append({"summary": summary, "n_messages": len(messages)})
+    sess.summary_snapshots = snapshots
+    await session.flush()
+    return summary

harness/models/__init__.py

@@ -0,0 +1,35 @@
+"""SQLAlchemy models. Importing this package registers every table on
+``Base.metadata`` for ``metadata.create_all`` (used at startup and in tests)."""
+
+from harness.models.adapter_health import AdapterHealth
+from harness.models.approval import Approval
+from harness.models.artifact import Artifact
+from harness.models.audit_log import AuditLog
+from harness.models.comparison import Comparison
+from harness.models.mcp_server_config import McpServerConfig
+from harness.models.memory import MemoryEmbedding, MemoryItem
+from harness.models.policy import Policy
+from harness.models.provider_config import ProviderConfig
+from harness.models.run import Run
+from harness.models.run_event import RunEvent
+from harness.models.session import Session
+from harness.models.task import Task
+from harness.models.workspace import Workspace
+
+__all__ = [
+    "AdapterHealth",
+    "Approval",
+    "Artifact",
+    "AuditLog",
+    "Comparison",
+    "McpServerConfig",
+    "MemoryEmbedding",
+    "MemoryItem",
+    "Policy",
+    "ProviderConfig",
+    "Run",
+    "RunEvent",
+    "Session",
+    "Task",
+    "Workspace",
+]

harness/models/adapter_health.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Float, ForeignKey, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base
+from harness.models.types import GUID, json_col
+
+
+class AdapterHealth(Base):
+    """Time-series of adapter health checks for the observability/health page."""
+
+    __tablename__ = "adapter_health"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    provider_config_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("provider_configs.id", ondelete="CASCADE"), index=True
+    )
+    ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    ok: Mapped[bool] = mapped_column(Boolean)
+    latency_ms: Mapped[float] = mapped_column(Float, default=0.0)
+    detail: Mapped[dict] = mapped_column(json_col(), default=dict)

harness/models/approval.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Enum, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import ApprovalActionClass, ApprovalStatus
+from harness.models.types import GUID, json_col
+
+
+class Approval(Base, TimestampMixin):
+    """A human-in-the-loop checkpoint for a sensitive action. Runs that hit a gate
+    transition to ``needs_approval`` and block until a decision is recorded here."""
+
+    __tablename__ = "approvals"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("sessions.id", ondelete="CASCADE"), index=True
+    )
+    run_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("runs.id", ondelete="SET NULL"), nullable=True
+    )
+    action_class: Mapped[ApprovalActionClass] = mapped_column(
+        Enum(ApprovalActionClass, name="approval_action_class")
+    )
+    payload: Mapped[dict] = mapped_column(json_col(), default=dict)
+    status: Mapped[ApprovalStatus] = mapped_column(
+        Enum(ApprovalStatus, name="approval_status"), default=ApprovalStatus.pending
+    )
+    decided_by: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    decided_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

harness/models/artifact.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import BigInteger, Enum, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import ArtifactKind
+from harness.models.types import GUID, json_col
+
+
+class Artifact(Base, TimestampMixin):
+    """A generated output (file, patch, plan, doc). Content addressed by sha256
+    for dedup; stored by reference (path/uri) — large blobs live outside the DB."""
+
+    __tablename__ = "artifacts"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    workspace_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("workspaces.id", ondelete="CASCADE"), index=True
+    )
+    session_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("sessions.id", ondelete="SET NULL"), nullable=True
+    )
+    run_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("runs.id", ondelete="SET NULL"), nullable=True
+    )
+    kind: Mapped[ArtifactKind] = mapped_column(Enum(ArtifactKind, name="artifact_kind"))
+    uri: Mapped[str] = mapped_column(String(1024))
+    sha256: Mapped[str] = mapped_column(String(64), index=True)
+    size: Mapped[int] = mapped_column(BigInteger, default=0)
+    meta: Mapped[dict] = mapped_column(json_col(), default=dict)

harness/models/audit_log.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base
+from harness.models.types import GUID, json_col
+
+
+class AuditLog(Base):
+    """Immutable, hash-chained audit record. Each row's ``hash`` covers its own
+    content plus ``prev_hash``, making tampering detectable. Append-only — never
+    updated or deleted by application code."""
+
+    __tablename__ = "audit_log"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    ts: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True
+    )
+    actor: Mapped[str] = mapped_column(String(128))
+    action: Mapped[str] = mapped_column(String(128), index=True)
+    target_type: Mapped[str] = mapped_column(String(64))
+    target_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    before: Mapped[dict | None] = mapped_column(json_col(), nullable=True)
+    after: Mapped[dict | None] = mapped_column(json_col(), nullable=True)
+    prev_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    hash: Mapped[str] = mapped_column(String(64))

harness/models/comparison.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Enum, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import ComparisonStrategy
+from harness.models.types import GUID, json_col, uuid_array
+
+
+class Comparison(Base, TimestampMixin):
+    """The result of comparing/merging two or more runs into a canonical answer.
+    When a merge is persisted, ``canonical_memory_item_id`` links the resulting
+    workspace-memory record."""
+
+    __tablename__ = "comparisons"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("sessions.id", ondelete="CASCADE"), index=True
+    )
+    run_ids: Mapped[list[uuid.UUID]] = mapped_column(uuid_array())
+    strategy: Mapped[ComparisonStrategy] = mapped_column(
+        Enum(ComparisonStrategy, name="comparison_strategy")
+    )
+    result: Mapped[dict] = mapped_column(json_col(), default=dict)
+    canonical_memory_item_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("memory_items.id", ondelete="SET NULL"), nullable=True
+    )

harness/models/enums.py

@@ -0,0 +1,146 @@
+"""Enumerations shared across models and schemas (single source of truth)."""
+
+from __future__ import annotations
+
+import enum
+
+
+class TrustPolicy(str, enum.Enum):
+    open = "open"
+    restricted = "restricted"
+    local_only = "local_only"
+
+
+class AdapterKind(str, enum.Enum):
+    mock = "mock"
+    openai_local = "openai_local"  # any OpenAI-compatible endpoint, local or remote
+    claude_code = "claude_code"
+    antigravity = "antigravity"  # Google's official `agy` CLI (Gemini successor)
+
+
+# Friendly config aliases for `kind:` in config.yaml. Remote OpenAI-compatible
+# endpoints read more naturally as `kind: openai`; both normalize to `openai_local`,
+# so no DB enum migration is needed and the canonical value stays valid.
+_KIND_ALIASES = {"openai": "openai_local", "openai_compatible": "openai_local"}
+
+
+def adapter_kind_from_config(raw: str) -> AdapterKind:
+    """Resolve a config.yaml ``kind:`` string to an :class:`AdapterKind`, honoring
+    friendly aliases (``openai`` / ``openai_compatible`` → ``openai_local``)."""
+    return AdapterKind(_KIND_ALIASES.get(raw, raw))
+
+
+class McpTransport(str, enum.Enum):
+    """How the harness reaches an MCP server.
+
+    ``stdio`` launches a local subprocess and speaks MCP over its stdin/stdout;
+    ``http`` connects to a remote streamable-HTTP / SSE endpoint."""
+
+    stdio = "stdio"
+    http = "http"
+
+
+class TaskStatus(str, enum.Enum):
+    created = "created"
+    running = "running"
+    done = "done"
+    failed = "failed"
+    cancelled = "cancelled"
+
+
+class SessionStatus(str, enum.Enum):
+    open = "open"
+    running = "running"
+    completed = "completed"
+    failed = "failed"
+    archived = "archived"
+
+
+class RunRole(str, enum.Enum):
+    primary = "primary"
+    draft = "draft"
+    verifier = "verifier"
+    judge = "judge"
+    merger = "merger"
+    secondary = "secondary"
+
+
+class RunStatus(str, enum.Enum):
+    queued = "queued"
+    running = "running"
+    streaming = "streaming"
+    succeeded = "succeeded"
+    failed = "failed"
+    cancelled = "cancelled"
+    needs_approval = "needs_approval"
+
+
+class RunEventType(str, enum.Enum):
+    token = "token"
+    message = "message"
+    tool_call = "tool_call"
+    tool_result = "tool_result"
+    artifact = "artifact"
+    status = "status"
+    cost = "cost"
+    adapter_meta = "adapter_meta"
+    error = "error"
+
+
+class ArtifactKind(str, enum.Enum):
+    file = "file"
+    patch = "patch"
+    plan = "plan"
+    doc = "doc"
+
+
+class MemoryScope(str, enum.Enum):
+    session = "session"
+    workspace = "workspace"
+
+
+class MemoryType(str, enum.Enum):
+    fact = "fact"
+    decision = "decision"
+    preference = "preference"
+    architecture = "architecture"
+    episodic = "episodic"
+    policy = "policy"
+    artifact_ref = "artifact_ref"
+    summary = "summary"
+
+
+class PolicyKind(str, enum.Enum):
+    routing = "routing"
+    approval = "approval"
+    egress = "egress"
+    fs_allowlist = "fs_allowlist"
+
+
+class ApprovalActionClass(str, enum.Enum):
+    high_risk = "high_risk"
+    command = "command"
+    egress = "egress"
+    secret = "secret"
+
+
+class ApprovalStatus(str, enum.Enum):
+    pending = "pending"
+    approved = "approved"
+    denied = "denied"
+
+
+class ComparisonStrategy(str, enum.Enum):
+    judge = "judge"
+    merge = "merge"
+    manual = "manual"
+
+
+class RoutingMode(str, enum.Enum):
+    single = "single"
+    fanout = "fanout"
+    fallback = "fallback"
+    judge_select = "judge_select"
+    propose_merge = "propose_merge"
+    cheap_first_escalate = "cheap_first_escalate"
+    local_first_escalate = "local_first_escalate"

harness/models/mcp_server_config.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Boolean, Enum, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import McpTransport
+from harness.models.types import GUID, json_col
+
+
+class McpServerConfig(Base, TimestampMixin):
+    """A configured MCP (Model Context Protocol) server the harness may expose to
+    its agents.
+
+    Mirrors :class:`~harness.models.provider_config.ProviderConfig`: declared in
+    ``config.yaml`` (``mcp.servers``), seeded into the DB, and resolvable by name.
+    Secrets are referenced via ``secret_ref`` (e.g. ``env:GITHUB_TOKEN``) and never
+    stored. ``bind`` scopes the server to workspaces/providers; ``tool_allowlist``
+    (empty = all) restricts which of the server's tools are offered.
+    """
+
+    __tablename__ = "mcp_server_configs"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    # Name is the global lookup key and the tool-namespace segment (mcp__<name>__<tool>),
+    # so it must be unique.
+    name: Mapped[str] = mapped_column(String(128), index=True, unique=True)
+    transport: Mapped[McpTransport] = mapped_column(
+        Enum(McpTransport, name="mcp_transport")
+    )
+    # stdio transport: command + args + env.
+    command: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    args: Mapped[list] = mapped_column(json_col(), default=list)
+    env: Mapped[dict] = mapped_column(json_col(), default=dict)
+    # http transport: url + headers.
+    url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    headers: Mapped[dict] = mapped_column(json_col(), default=dict)
+    # Optional bearer/token secret, resolved at use time (never persisted in plaintext).
+    secret_ref: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    # Empty list ⇒ all tools the server advertises are allowed.
+    tool_allowlist: Mapped[list] = mapped_column(json_col(), default=list)
+    # {"workspaces": [...], "providers": [...]} — empty lists ⇒ unrestricted.
+    bind: Mapped[dict] = mapped_column(json_col(), default=dict)
+    # When true the server's tools are considered side-effect-free and remain offered
+    # in read-only / plan runs and local_only workspaces.
+    read_only: Mapped[bool] = mapped_column(Boolean, default=False)
+    enabled: Mapped[bool] = mapped_column(Boolean, default=True)

harness/models/memory.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    text,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import MemoryScope, MemoryType
+from harness.models.types import GUID, embedding_col, json_col, str_array
+from harness.settings import get_settings
+
+EMBEDDING_DIM = get_settings().embedding_dim
+
+
+class MemoryItem(Base, TimestampMixin):
+    """Canonical, vendor-neutral memory. ``namespace`` is a composite partition
+    (``ws/<slug>[/project][/provider][/session]``) enforcing isolation. Volatile
+    items carry a ``ttl_expires_at``; durable workspace items leave it null."""
+
+    __tablename__ = "memory_items"
+    __table_args__ = (
+        Index("ix_memory_namespace_scope_type", "namespace", "scope", "type"),
+        Index(
+            "ix_memory_ttl",
+            "ttl_expires_at",
+            postgresql_where=text("ttl_expires_at IS NOT NULL"),
+        ),
+        Index("uq_memory_dedup", "namespace", "dedup_hash", unique=True),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    namespace: Mapped[str] = mapped_column(String(512), index=True)
+    scope: Mapped[MemoryScope] = mapped_column(Enum(MemoryScope, name="memory_scope"))
+    type: Mapped[MemoryType] = mapped_column(Enum(MemoryType, name="memory_type"))
+    content: Mapped[str] = mapped_column(Text)
+    tags: Mapped[list[str]] = mapped_column(str_array(), default=list)
+    source_run_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("runs.id", ondelete="SET NULL"), nullable=True
+    )
+    dedup_hash: Mapped[str] = mapped_column(String(64), index=True)
+    redacted: Mapped[bool] = mapped_column(Boolean, default=False)
+    ttl_expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+
+class MemoryEmbedding(Base):
+    """Chunked embeddings for a memory item. Kept in a separate table so transcript
+    storage, canonical memory, and vectors remain cleanly decoupled."""
+
+    __tablename__ = "memory_embeddings"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    memory_item_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("memory_items.id", ondelete="CASCADE"), index=True
+    )
+    chunk_idx: Mapped[int] = mapped_column(Integer, default=0)
+    model: Mapped[str] = mapped_column(String(128))
+    embedding: Mapped[list[float]] = mapped_column(embedding_col(EMBEDDING_DIM))
+    meta: Mapped[dict] = mapped_column(json_col(), default=dict)

harness/models/policy.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Enum, ForeignKey, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import PolicyKind
+from harness.models.types import GUID, json_col
+
+
+class Policy(Base, TimestampMixin):
+    """A workspace-scoped policy: routing rules, approval rules, egress rules, or
+    filesystem allowlists. ``spec`` is a typed-by-kind JSON document; higher
+    ``priority`` wins on conflict."""
+
+    __tablename__ = "policies"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    workspace_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("workspaces.id", ondelete="CASCADE"), index=True
+    )
+    name: Mapped[str] = mapped_column(String(128))
+    kind: Mapped[PolicyKind] = mapped_column(Enum(PolicyKind, name="policy_kind"))
+    spec: Mapped[dict] = mapped_column(json_col(), default=dict)
+    priority: Mapped[int] = mapped_column(Integer, default=0)

harness/models/provider_config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Boolean, Enum, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import AdapterKind
+from harness.models.types import GUID, json_col
+
+
+class ProviderConfig(Base, TimestampMixin):
+    """A configured adapter instance. ``secret_ref`` points into env/Docker
+    secrets (e.g. ``env:LOCAL_LLM_API_KEY``) — the secret value is never stored."""
+
+    __tablename__ = "provider_configs"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    workspace_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=True
+    )
+    # Provider name is the global lookup key (adapter test/models/run routing all
+    # resolve by name), so it must be unique — otherwise duplicate rows make
+    # single-row lookups raise MultipleResultsFound. See migration 0003.
+    name: Mapped[str] = mapped_column(String(128), index=True, unique=True)
+    kind: Mapped[AdapterKind] = mapped_column(Enum(AdapterKind, name="adapter_kind"))
+    base_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    model: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    secret_ref: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    params: Mapped[dict] = mapped_column(json_col(), default=dict)
+    capabilities: Mapped[dict] = mapped_column(json_col(), default=dict)
+    enabled: Mapped[bool] = mapped_column(Boolean, default=True)

harness/models/run.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import DateTime, Enum, ForeignKey, Index, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import AdapterKind, RunRole, RunStatus
+from harness.models.types import GUID, json_col
+
+
+class Run(Base, TimestampMixin):
+    """A single provider execution within a session. The unit of idempotency for
+    workers (``idempotency_key``) and the node identity in the orchestration graph."""
+
+    __tablename__ = "runs"
+    __table_args__ = (
+        Index("ix_runs_session_status", "session_id", "status"),
+        Index("ix_runs_status_started", "status", "started_at"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("sessions.id", ondelete="CASCADE"), index=True
+    )
+    provider_config_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("provider_configs.id", ondelete="SET NULL"), nullable=True
+    )
+    adapter_kind: Mapped[AdapterKind] = mapped_column(Enum(AdapterKind, name="adapter_kind"))
+    role: Mapped[RunRole] = mapped_column(
+        Enum(RunRole, name="run_role"), default=RunRole.primary
+    )
+    status: Mapped[RunStatus] = mapped_column(
+        Enum(RunStatus, name="run_status"), default=RunStatus.queued
+    )
+    graph_node_id: Mapped[str] = mapped_column(String(128), default="root")
+    idempotency_key: Mapped[str] = mapped_column(String(256), unique=True)
+    started_at: Mapped[object | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    finished_at: Mapped[object | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    cost: Mapped[dict] = mapped_column(json_col(), default=dict)
+    context_meta: Mapped[dict] = mapped_column(json_col(), default=dict)
+    final_output: Mapped[str | None] = mapped_column(Text, nullable=True)