ags-cli 0.1.0__py3-none-any.whl

harness/models/run_event.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, Enum, ForeignKey, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base
+from harness.models.enums import RunEventType
+from harness.models.types import GUID, json_col
+
+
+class RunEvent(Base):
+    """Append-only event ledger — the source of truth for a run. Run/session rows
+    are projections rebuilt from these events where practical. ``(run_id, seq)`` is
+    unique and monotonic for deterministic replay and timeline rendering."""
+
+    __tablename__ = "run_events"
+    __table_args__ = (
+        UniqueConstraint("run_id", "seq", name="uq_run_events_run_id_seq"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    run_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("runs.id", ondelete="CASCADE"), index=True
+    )
+    seq: Mapped[int] = mapped_column(BigInteger)
+    ts: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    type: Mapped[RunEventType] = mapped_column(Enum(RunEventType, name="run_event_type"))
+    payload: Mapped[dict] = mapped_column(json_col(), default=dict)

harness/models/session.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Enum, ForeignKey, Index, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import SessionStatus
+from harness.models.types import GUID, json_col
+
+
+class Session(Base, TimestampMixin):
+    """A canonical, provider-independent unit of context. Holds the objective,
+    constraints, rolling summary, and references to provider runs. Sessions can
+    branch (``parent_session_id``) and be resumed from the summary, not the raw
+    transcript."""
+
+    __tablename__ = "sessions"
+    __table_args__ = (
+        # Recent-session lookup per workspace.
+        Index("ix_sessions_workspace_updated", "workspace_id", "updated_at"),
+    )
+
+    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
+    )
+    task_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("tasks.id", ondelete="SET NULL"), nullable=True
+    )
+    parent_session_id: Mapped[uuid.UUID | None] = mapped_column(
+        GUID(), ForeignKey("sessions.id", ondelete="SET NULL"), nullable=True
+    )
+    canonical_objective: Mapped[str] = mapped_column(Text)
+    constraints: Mapped[dict] = mapped_column(json_col(), default=dict)
+    # Per-session runtime settings overriding workspace defaults. Keys:
+    # write_mode (bool|None: None = inherit workspace), workspace_mode
+    # ("main"|"worktree"), worktree_path/branch/base, worktree_fallback_reason,
+    # merged_at, merge_commit. Writers must copy-then-reassign the dict so the
+    # JSON column is flagged dirty (same pattern as Workspace.settings).
+    settings: Mapped[dict] = mapped_column(json_col(), default=dict)
+    native_sessions: Mapped[dict] = mapped_column(json_col(), default=dict)
+    summary: Mapped[str] = mapped_column(Text, default="")
+    summary_snapshots: Mapped[list] = mapped_column(json_col(), default=list)
+    status: Mapped[SessionStatus] = mapped_column(
+        Enum(SessionStatus, name="session_status"), default=SessionStatus.open
+    )

harness/models/task.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Enum, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import TaskStatus
+from harness.models.types import GUID, json_col
+
+
+class Task(Base, TimestampMixin):
+    """A unit of work the user wants done; may spawn one or many sessions/runs."""
+
+    __tablename__ = "tasks"
+
+    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
+    )
+    title: Mapped[str] = mapped_column(String(512))
+    objective: Mapped[str] = mapped_column(Text)
+    constraints: Mapped[dict] = mapped_column(json_col(), default=dict)
+    status: Mapped[TaskStatus] = mapped_column(
+        Enum(TaskStatus, name="task_status"), default=TaskStatus.created
+    )
+    created_by: Mapped[str] = mapped_column(String(128), default="cli")

harness/models/types.py

@@ -0,0 +1,63 @@
+"""Portable column types.
+
+The platform runs on SQLite (daemonless, single profile). These helpers wrap the
+column types used across the ORM models so that intent (UUID, JSON object/array,
+list of strings, list of UUIDs, embedding vector) reads clearly at the model
+definition site, even though most of them now just delegate to a plain SQLAlchemy
+type.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import JSON, Uuid
+from sqlalchemy.types import TypeDecorator, TypeEngine
+
+
+def GUID() -> TypeEngine:
+    """UUID column, stored as ``CHAR(32)`` on SQLite.
+
+    ``Uuid`` returns/accepts ``uuid.UUID`` objects."""
+    return Uuid(as_uuid=True)
+
+
+def json_col() -> TypeEngine:
+    """A JSON object/array column."""
+    return JSON()
+
+
+def str_array() -> TypeEngine:
+    """A list of strings, stored as a JSON list."""
+    return JSON()
+
+
+class _UUIDListJSON(TypeDecorator):
+    """Stores ``list[uuid.UUID]`` as a JSON array of strings.
+
+    Coerces to/from ``uuid.UUID`` so callers see UUID objects rather than raw
+    strings."""
+
+    impl = JSON
+    cache_ok = True
+
+    def process_bind_param(self, value, dialect):  # noqa: ANN001
+        if value is None:
+            return None
+        return [str(v) for v in value]
+
+    def process_result_value(self, value, dialect):  # noqa: ANN001
+        if value is None:
+            return None
+        return [v if isinstance(v, uuid.UUID) else uuid.UUID(v) for v in value]
+
+
+def uuid_array() -> TypeEngine:
+    """A list of UUIDs, stored as a JSON list of strings."""
+    return _UUIDListJSON()
+
+
+def embedding_col(dim: int) -> TypeEngine:
+    """An embedding vector, stored as a JSON list of floats. Similarity is computed
+    in Python (see ``memory/service.py``)."""
+    return JSON()

harness/models/workspace.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Enum, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from harness.db import Base, TimestampMixin
+from harness.models.enums import TrustPolicy
+from harness.models.types import GUID, json_col
+
+
+class Workspace(Base, TimestampMixin):
+    """A memory partition and trust boundary (e.g. one repo/project)."""
+
+    __tablename__ = "workspaces"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), primary_key=True, default=uuid.uuid4
+    )
+    slug: Mapped[str] = mapped_column(String(128), unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(256))
+    trust_policy: Mapped[TrustPolicy] = mapped_column(
+        Enum(TrustPolicy, name="trust_policy"), default=TrustPolicy.restricted
+    )
+    default_routing_policy: Mapped[str] = mapped_column(String(128), default="single")
+    settings: Mapped[dict] = mapped_column(json_col(), default=dict)

harness/observability/__init__.py

@@ -0,0 +1,4 @@
+from harness.observability.audit import verify_chain, write_audit
+from harness.observability.logging import configure_logging, get_logger
+
+__all__ = ["configure_logging", "get_logger", "verify_chain", "write_audit"]

harness/observability/audit.py

@@ -0,0 +1,88 @@
+"""Immutable, hash-chained audit log writer.
+
+Each record's ``hash = sha256(prev_hash || canonical_json(record))``. The chain
+makes tampering or deletion detectable: re-computing the chain and comparing the
+head hash verifies integrity. Application code only ever appends."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.audit_log import AuditLog
+
+
+def _canonical(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def _compute_hash(prev_hash: str | None, record: dict[str, Any]) -> str:
+    h = hashlib.sha256()
+    h.update((prev_hash or "").encode())
+    h.update(_canonical(record).encode())
+    return h.hexdigest()
+
+
+async def write_audit(
+    session: AsyncSession,
+    *,
+    actor: str,
+    action: str,
+    target_type: str,
+    target_id: str | None = None,
+    before: dict | None = None,
+    after: dict | None = None,
+) -> AuditLog:
+    """Append one tamper-evident audit row. Caller's transaction commits it."""
+    prev = (
+        await session.execute(
+            select(AuditLog).order_by(AuditLog.ts.desc()).limit(1)
+        )
+    ).scalar_one_or_none()
+    prev_hash = prev.hash if prev else None
+
+    record = {
+        "actor": actor,
+        "action": action,
+        "target_type": target_type,
+        "target_id": target_id,
+        "before": before,
+        "after": after,
+    }
+    row = AuditLog(
+        actor=actor,
+        action=action,
+        target_type=target_type,
+        target_id=target_id,
+        before=before,
+        after=after,
+        prev_hash=prev_hash,
+        hash=_compute_hash(prev_hash, record),
+    )
+    session.add(row)
+    return row
+
+
+async def verify_chain(session: AsyncSession) -> bool:
+    """Recompute the whole chain; returns True iff every link is intact."""
+    rows = (
+        await session.execute(select(AuditLog).order_by(AuditLog.ts.asc()))
+    ).scalars().all()
+    prev_hash: str | None = None
+    for row in rows:
+        record = {
+            "actor": row.actor,
+            "action": row.action,
+            "target_type": row.target_type,
+            "target_id": row.target_id,
+            "before": row.before,
+            "after": row.after,
+        }
+        if row.prev_hash != prev_hash or row.hash != _compute_hash(prev_hash, record):
+            return False
+        prev_hash = row.hash
+    return True

harness/observability/logging.py

@@ -0,0 +1,47 @@
+"""Structured JSON logging via structlog. One configuration entrypoint called at
+app and worker startup."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import structlog
+
+from harness.settings import get_settings
+
+_configured = False
+
+
+def configure_logging() -> None:
+    global _configured
+    if _configured:
+        return
+    settings = get_settings()
+    level = getattr(logging, settings.log_level.upper(), logging.INFO)
+
+    shared = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+    renderer = (
+        structlog.processors.JSONRenderer()
+        if settings.log_json
+        else structlog.dev.ConsoleRenderer()
+    )
+    structlog.configure(
+        processors=[*shared, renderer],
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+    logging.basicConfig(level=level, stream=sys.stdout, format="%(message)s")
+    _configured = True
+
+
+def get_logger(name: str = "harness") -> structlog.stdlib.BoundLogger:
+    configure_logging()
+    return structlog.get_logger(name)

harness/observability/metrics.py

@@ -0,0 +1,43 @@
+"""Prometheus metrics. Exposed at ``GET /metrics`` (see api.v1.health)."""
+
+from __future__ import annotations
+
+from prometheus_client import Counter, Gauge, Histogram
+
+ADAPTER_LATENCY = Histogram(
+    "harness_adapter_latency_seconds",
+    "End-to-end adapter run latency.",
+    ["adapter_kind", "provider"],
+    buckets=(0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300),
+)
+
+RUN_TOTAL = Counter(
+    "harness_runs_total", "Runs by terminal status.", ["adapter_kind", "status"]
+)
+
+RUN_FAILURES = Counter(
+    "harness_run_failures_total", "Run failures by adapter and reason.",
+    ["adapter_kind", "reason"],
+)
+
+TOKENS_TOTAL = Counter(
+    "harness_tokens_total", "Token accounting.", ["adapter_kind", "direction"]
+)
+
+COST_USD_TOTAL = Counter(
+    "harness_cost_usd_total", "Estimated cost in USD where known.", ["adapter_kind"]
+)
+
+MEMORY_QUERIES = Counter("harness_memory_queries_total", "Memory retrieval queries.")
+MEMORY_HITS = Counter(
+    "harness_memory_hits_total", "Retrievals that returned >=1 item above threshold."
+)
+
+ACTIVE_RUNS = Gauge("harness_active_runs", "Currently running/streaming runs.")
+
+
+def memory_hit_rate() -> float:
+    """Convenience for the GUI/health endpoint."""
+    queries = MEMORY_QUERIES._value.get()  # type: ignore[attr-defined]
+    hits = MEMORY_HITS._value.get()  # type: ignore[attr-defined]
+    return (hits / queries) if queries else 0.0

harness/observability/tracing.py

@@ -0,0 +1,38 @@
+"""OpenTelemetry bootstrap. No-op unless ``HARNESS_OTEL_ENABLED=true`` so local
+dev and CI stay dependency-light."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from harness.settings import get_settings
+
+_tracer: Any = None
+
+
+def setup_tracing(app: Any = None) -> None:
+    global _tracer
+    settings = get_settings()
+    if not settings.otel_enabled:
+        return
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    provider = TracerProvider(resource=Resource.create({"service.name": "ags"}))
+    provider.add_span_processor(
+        BatchSpanProcessor(OTLPSpanExporter(endpoint=settings.otel_exporter_otlp_endpoint))
+    )
+    trace.set_tracer_provider(provider)
+    _tracer = trace.get_tracer("harness")
+
+    if app is not None:
+        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+        FastAPIInstrumentor.instrument_app(app)
+
+
+def get_tracer() -> Any:
+    return _tracer

harness/orchestrator/__init__.py

@@ -0,0 +1,19 @@
+from harness.orchestrator.engine import (
+    NodeResult,
+    create_runs,
+    execute_node,
+    execute_session,
+)
+from harness.orchestrator.policies import CompiledPolicy, compile_policy, load_policy_specs
+from harness.orchestrator.run_graph import RunGraph
+
+__all__ = [
+    "CompiledPolicy",
+    "NodeResult",
+    "RunGraph",
+    "compile_policy",
+    "create_runs",
+    "execute_node",
+    "execute_session",
+    "load_policy_specs",
+]