ags-cli 0.1.0__py3-none-any.whl

harness/schemas/run.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from harness.models.enums import AdapterKind, RunRole, RunStatus
+from harness.schemas.common import IdModel
+
+
+class RunStartRequest(BaseModel):
+    task_id: uuid.UUID | None = Field(
+        default=None, description="Existing task to run; or provide objective inline."
+    )
+    objective: str | None = None
+    workspace: str = "default"
+    policy: str = Field(default="single", description="Routing policy name from config.")
+    providers: list[str] | None = Field(
+        default=None, description="Override provider set for single/fanout (e.g. [mock, local])."
+    )
+    session_id: uuid.UUID | None = Field(
+        default=None, description="Resume/extend an existing session."
+    )
+    additional_objective: str | None = Field(
+        default=None,
+        description="Per-turn prompt for this run; overrides the session's original "
+        "objective as the message while still inheriting shared memory.",
+    )
+    model: str | None = Field(
+        default=None,
+        description="One-off model override for this run (e.g. 'gemini-3.5-flash' or 'llama3.1').",
+    )
+    models: dict[str, str] | None = Field(
+        default=None,
+        description="Per-provider model override keyed by provider name, for fanout "
+        "waves where each agent should run on its own model (e.g. "
+        "{'claude': 'claude-opus-4-8', 'local': 'llama3.1'}). Takes precedence over "
+        "`model` for the providers it names; others fall back to `model`, then to the "
+        "provider's configured default.",
+    )
+    workspace_mode: Literal["main", "worktree"] | None = Field(
+        default=None,
+        description="For a NEW session: 'worktree' isolates it in a private git "
+        "worktree on its own branch; 'main' works directly in the project dir. "
+        "Defaults to the workspace's default_workspace_mode (worktree).",
+    )
+    write_mode: bool | None = Field(
+        default=None,
+        description="For a NEW session: True = edit mode (agent may write files), "
+        "False = plan/read-only. Omitted (None) inherits the workspace/env default "
+        "(plan unless HARNESS_WRITE is set).",
+    )
+    attachments: list[uuid.UUID] | None = Field(
+        default=None,
+        description="Ids of previously uploaded attachments (POST /attachments) "
+        "to include with this turn's message.",
+    )
+
+
+class RunOut(IdModel):
+    session_id: uuid.UUID
+    adapter_kind: AdapterKind
+    role: RunRole
+    status: RunStatus
+    graph_node_id: str
+    error: str | None = None
+    cost: dict
+    context_meta: dict = {}
+    final_output: str | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class RunStartResponse(BaseModel):
+    session_id: uuid.UUID
+    runs: list[RunOut]
+    dispatched: bool
+
+
+class RunEventOut(BaseModel):
+    seq: int
+    type: str
+    ts: datetime
+    payload: dict
+
+
+class CompareRequest(BaseModel):
+    run_ids: list[uuid.UUID]
+    strategy: str = Field(default="judge", description="judge | merge | manual")
+    judge_provider: str | None = Field(
+        default=None,
+        description="Provider to use as the judge. Defaults to the first enabled one.",
+    )
+    judge_model: str | None = Field(
+        default=None,
+        description="Model override for the judge call; defaults to the judge "
+        "provider's configured model.",
+    )
+
+
+class MergeRequest(BaseModel):
+    run_ids: list[uuid.UUID]
+    persist: bool = Field(default=True, description="Persist merged result as workspace memory.")
+    merged_content: str | None = Field(
+        default=None, description="Manual merge text; if omitted a deterministic merge is built."
+    )
+
+
+class ComparisonOut(IdModel):
+    session_id: uuid.UUID
+    run_ids: list[uuid.UUID]
+    strategy: str
+    result: dict
+    canonical_memory_item_id: uuid.UUID | None = None

harness/schemas/session.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import uuid
+
+from pydantic import BaseModel
+
+from harness.models.enums import SessionStatus
+from harness.schemas.common import IdModel
+
+
+class SessionOut(IdModel):
+    workspace_id: uuid.UUID
+    task_id: uuid.UUID | None = None
+    parent_session_id: uuid.UUID | None = None
+    canonical_objective: str
+    constraints: dict
+    settings: dict = {}
+    summary: str
+    status: SessionStatus
+
+
+class SessionResumeRequest(BaseModel):
+    policy: str = "single"
+    providers: list[str] | None = None
+    additional_objective: str | None = None
+    model: str | None = None
+    models: dict[str, str] | None = None
+    attachments: list[uuid.UUID] | None = None
+
+
+class SessionSettingsUpdate(BaseModel):
+    """PUT /sessions/{id}/settings body. ``write_mode`` explicit null clears the
+    session override back to inherit; omitting the field leaves it unchanged
+    (distinguished via ``model_fields_set``)."""
+
+    write_mode: bool | None = None
+
+
+class SessionModeOut(BaseModel):
+    write_mode: bool | None = None
+    workspace_write_mode: bool
+    effective_write_mode: bool
+    mode: str
+
+
+class SessionWorkspaceOut(BaseModel):
+    """Isolation state of a session's private workspace (worktree)."""
+
+    workspace_mode: str
+    path: str | None = None
+    branch: str | None = None
+    base: str | None = None
+    exists: bool = False
+    dirty: bool = False
+    changed_files: list[str] = []
+    ahead: int = 0
+    behind: int = 0
+    merged_at: str | None = None
+    merge_commit: str | None = None
+    fallback_reason: str | None = None
+
+
+class SessionMergeRequest(BaseModel):
+    squash: bool = False
+    delete_worktree: bool = False
+    message: str | None = None
+
+
+class SessionMergeResponse(BaseModel):
+    merged: bool
+    nothing_to_merge: bool = False
+    commit: str | None = None
+    conflicts: list[str] = []
+    reason: str | None = None
+
+
+class SessionBranchRequest(BaseModel):
+    note: str | None = None
+
+
+class SessionClearRequest(BaseModel):
+    all: bool = False
+    status: SessionStatus | None = None
+    older_than_days: int | None = None
+    workspace: str | None = None
+    ids: list[uuid.UUID] | None = None
+    dry_run: bool = False
+
+
+class SessionClearResponse(BaseModel):
+    count: int
+    deleted: bool
+    sessions: list[SessionOut]

harness/schemas/task.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import uuid
+
+from pydantic import BaseModel, Field
+
+from harness.models.enums import TaskStatus
+from harness.schemas.common import IdModel
+
+
+class TaskCreate(BaseModel):
+    workspace: str = Field(default="default", description="Workspace slug.")
+    title: str
+    objective: str
+    constraints: dict = Field(default_factory=dict)
+
+
+class TaskOut(IdModel):
+    workspace_id: uuid.UUID
+    title: str
+    objective: str
+    constraints: dict
+    status: TaskStatus
+    created_by: str

harness/security/__init__.py

@@ -0,0 +1,5 @@
+from harness.security.permissions import PermissionContext
+from harness.security.risk import RiskDecision, classify
+from harness.security.secrets import resolve_secret_ref
+
+__all__ = ["PermissionContext", "RiskDecision", "classify", "resolve_secret_ref"]

harness/security/approval_policy.py

@@ -0,0 +1,107 @@
+"""Approval gate policy: decides whether a proposed tool call must pause for a
+human decision before it executes, layered on top of the risk classification
+in ``harness.security.risk``.
+
+``risk.classify`` maps an abstract action (e.g. ``shell.exec``) to a risk class
+and says whether that CLASS of action needs approval under the workspace's
+trust policy. This module adds a second, narrower layer: even an action class
+that requires approval can be auto-approved when its concrete invocation
+matches a conservative allowlist of known-harmless commands (``pytest``,
+``git status``, ...) — so routine dev workflows don't grind to a halt waiting
+on a human for every shell call, while anything else (most notably destructive
+commands like ``rm -rf``) still pauses for approval.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from harness.models.enums import ApprovalActionClass, TrustPolicy
+from harness.security.risk import classify
+
+# Tool name (as offered by harness.tools.fs_tools.tool_specs) -> abstract risk
+# action understood by harness.security.risk.ACTION_RISK. Tools with no entry
+# here are never gated (read_file/list_dir/grep, and writes — already confined
+# to the workspace root, so never "outside allowlist").
+TOOL_ACTION: dict[str, str] = {
+    "execute_command": "shell.exec",
+}
+
+# Command prefixes safe enough to auto-approve even though shell.exec is
+# normally gated. Anchored at the start of the (stripped) command so
+# `pytest -k foo` matches but `rm pytest_leftover.txt` doesn't. Keep this list
+# to read-only / side-effect-free operations.
+AUTO_APPROVE_PATTERNS: tuple[str, ...] = (
+    r"pytest\b",
+    r"python -m pytest\b",
+    r"npm (test|run test|run lint|run build|run typecheck)\b",
+    r"yarn (test|lint|build)\b",
+    r"pnpm (test|lint|build)\b",
+    r"(git|hg) (status|log|diff|show|branch)\b",
+    r"ls\b",
+    r"cat\b",
+    r"pwd\b",
+    r"echo\b",
+    r"mypy\b",
+    r"ruff\b",
+    r"tsc\b",
+    r"grep\b",
+)
+_AUTO_APPROVE_RE = re.compile(r"^\s*(" + "|".join(AUTO_APPROVE_PATTERNS) + r")")
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    tool_name: str
+    action: str | None
+    action_class: ApprovalActionClass | None
+    requires_approval: bool
+    reason: str
+    auto_approved: bool = False
+
+
+def _auto_approved(action: str, args: dict) -> bool:
+    if action != "shell.exec":
+        return False
+    return bool(_AUTO_APPROVE_RE.match(str(args.get("command", ""))))
+
+
+def evaluate_gate(
+    tool_name: str,
+    args: dict,
+    *,
+    trust_policy: TrustPolicy = TrustPolicy.restricted,
+) -> GateDecision:
+    """Decide whether *tool_name* (called with *args*) may run immediately or
+    must pause for a human approval."""
+    action = TOOL_ACTION.get(tool_name)
+    if action is None:
+        return GateDecision(tool_name, None, None, False, "unclassified/low-risk tool")
+
+    decision = classify(action, trust_policy=trust_policy)
+    if not decision.requires_approval:
+        return GateDecision(tool_name, action, decision.action_class, False, decision.reason)
+
+    if _auto_approved(action, args):
+        return GateDecision(
+            tool_name, action, decision.action_class, False,
+            f"{decision.reason}; auto-approved by allowlist", auto_approved=True,
+        )
+
+    return GateDecision(tool_name, action, decision.action_class, True, decision.reason)
+
+
+class ApprovalRequired(Exception):
+    """Raised by a tool executor when a gated action needs a human decision
+    before it may run. Carries enough to record an Approval and, once granted,
+    re-execute the exact same call."""
+
+    def __init__(self, tool_name: str, args: dict, decision: GateDecision) -> None:
+        # NOTE: BaseException.args is a reserved attribute (Exception.__init__
+        # overwrites it) — the tool's call arguments are stored as tool_args to
+        # avoid silently clobbering the standard exception message tuple.
+        super().__init__(f"approval required for {tool_name!r}: {decision.reason}")
+        self.tool_name = tool_name
+        self.tool_args = args
+        self.decision = decision

harness/security/auth.py

@@ -0,0 +1,106 @@
+"""Authentication abstraction. ``LocalPasswordAuth`` is the local-first default;
+``OIDCAuth`` is an OIDC-ready stub (env-configured issuer/client) completed when a
+self-hosted GUI needs SSO. The API depends on the ``AuthProvider`` protocol only.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol
+
+import bcrypt
+import jwt
+from pydantic import BaseModel
+
+from harness.settings import Settings, get_settings
+
+
+def _hash_password(password: str) -> bytes:
+    # bcrypt's input limit is 72 bytes; truncate defensively (passwords longer
+    # than that gain no additional entropy under bcrypt).
+    return bcrypt.hashpw(password.encode()[:72], bcrypt.gensalt())
+
+
+def _verify_password(password: str, hashed: bytes) -> bool:
+    try:
+        return bcrypt.checkpw(password.encode()[:72], hashed)
+    except ValueError:
+        return False
+
+
+class Principal(BaseModel):
+    subject: str
+    roles: list[str] = ["user"]
+
+
+class AuthProvider(Protocol):
+    def authenticate(self, username: str, password: str) -> Principal | None: ...
+    def issue_token(self, principal: Principal) -> str: ...
+    def verify_token(self, token: str) -> Principal | None: ...
+
+
+class LocalPasswordAuth:
+    """Single-admin local auth backed by env-configured credentials. Tokens are
+    HS256 JWTs signed with ``HARNESS_AUTH_SECRET``."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._admin_user = settings.local_admin_user
+        # Hash the configured admin password at startup; never store plaintext.
+        self._admin_hash = _hash_password(settings.local_admin_password)
+
+    def authenticate(self, username: str, password: str) -> Principal | None:
+        if username == self._admin_user and _verify_password(password, self._admin_hash):
+            return Principal(subject=username, roles=["admin", "user"])
+        return None
+
+    def issue_token(self, principal: Principal) -> str:
+        payload = {
+            "sub": principal.subject,
+            "roles": principal.roles,
+            "iat": int(time.time()),
+            "exp": int(time.time()) + 86400,
+        }
+        return jwt.encode(payload, self._settings.auth_secret, algorithm="HS256")
+
+    def verify_token(self, token: str) -> Principal | None:
+        try:
+            data = jwt.decode(token, self._settings.auth_secret, algorithms=["HS256"])
+        except jwt.PyJWTError:
+            return None
+        return Principal(subject=data["sub"], roles=data.get("roles", ["user"]))
+
+
+class OIDCAuth:
+    """OIDC-ready stub. Validates RS256 tokens against a configured issuer's JWKS.
+    Completed when SSO is enabled; raises clearly until configured."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+
+    def authenticate(self, username: str, password: str) -> Principal | None:
+        raise NotImplementedError(
+            "OIDC uses an external authorization-code flow, not password auth."
+        )
+
+    def issue_token(self, principal: Principal) -> str:  # pragma: no cover
+        raise NotImplementedError("Tokens are issued by the OIDC provider.")
+
+    def verify_token(self, token: str) -> Principal | None:
+        # Planned: fetch JWKS from {issuer}/.well-known, validate RS256, map claims.
+        raise NotImplementedError("OIDC verification is not yet implemented.")
+
+
+_provider_cache: AuthProvider | None = None
+
+
+def get_auth_provider(settings: Settings | None = None) -> AuthProvider:
+    global _provider_cache
+    if _provider_cache is not None and settings is None:
+        return _provider_cache
+    settings = settings or get_settings()
+    provider: AuthProvider = (
+        OIDCAuth(settings) if settings.auth_provider == "oidc" else LocalPasswordAuth(settings)
+    )
+    _provider_cache = provider
+    return provider

harness/security/permissions.py

@@ -0,0 +1,59 @@
+"""Permission enforcement: filesystem allowlists, command gates, egress policy,
+and the global read-only / dry-run switches. Safe-by-default — anything not
+explicitly allowed is denied."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from harness.settings import get_settings
+
+
+def write_mode_enabled() -> bool:
+    """Whether the operator opted this process into letting CLI agents EDIT files
+    (set by exporting ``HARNESS_WRITE=1`` before starting ``ags serve``). Off by
+    default: agents run read-only / plan mode unless this is explicitly set."""
+    return os.environ.get("HARNESS_WRITE", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass
+class PermissionContext:
+    """Effective permissions for a run, composed from global settings + workspace
+    policy. ``read_only`` blocks all writes; ``dry_run`` lets the graph execute but
+    skips side effects."""
+
+    fs_allowlist: list[str] = field(default_factory=list)
+    allow_network_egress: bool = False
+    read_only: bool = False
+    dry_run: bool = False
+
+    @classmethod
+    def from_settings(cls, fs_allowlist: list[str] | None = None) -> PermissionContext:
+        s = get_settings()
+        return cls(
+            fs_allowlist=fs_allowlist or [],
+            read_only=s.read_only,
+            dry_run=s.dry_run,
+        )
+
+    def path_allowed(self, path: str | os.PathLike[str]) -> bool:
+        target = Path(path).resolve()
+        for root in self.fs_allowlist:
+            try:
+                target.relative_to(Path(root).resolve())
+                return True
+            except ValueError:
+                continue
+        return False
+
+    def assert_write_allowed(self, path: str | os.PathLike[str]) -> None:
+        if self.read_only:
+            raise PermissionError("read-only mode: writes are disabled")
+        if not self.path_allowed(path):
+            raise PermissionError(f"path outside filesystem allowlist: {path}")
+
+    def assert_egress_allowed(self, url: str) -> None:
+        if not self.allow_network_egress:
+            raise PermissionError(f"network egress denied by policy: {url}")

harness/security/risk.py

@@ -0,0 +1,59 @@
+"""High-risk action classification. Maps a proposed action to a risk class and
+decides whether a human approval gate is required, given workspace trust policy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from harness.models.enums import ApprovalActionClass, TrustPolicy
+
+# Action verbs the orchestrator/adapters may emit, mapped to a risk class.
+ACTION_RISK: dict[str, ApprovalActionClass] = {
+    "shell.exec": ApprovalActionClass.command,
+    "fs.write_outside_allowlist": ApprovalActionClass.high_risk,
+    "net.egress": ApprovalActionClass.egress,
+    "secret.read": ApprovalActionClass.secret,
+    # Calling an external MCP tool can reach the network / external systems; treat it
+    # as egress so trust-policy gating and (once wired) the approval gate cover it.
+    "mcp.tool_call": ApprovalActionClass.egress,
+}
+
+# Actions that always require approval regardless of trust policy.
+ALWAYS_REQUIRE_APPROVAL = {"shell.exec", "net.egress", "secret.read"}
+
+
+@dataclass(frozen=True)
+class RiskDecision:
+    action: str
+    action_class: ApprovalActionClass | None
+    requires_approval: bool
+    reason: str
+
+
+def classify(
+    action: str,
+    *,
+    trust_policy: TrustPolicy = TrustPolicy.restricted,
+    require_approval_for: set[str] | None = None,
+) -> RiskDecision:
+    require_approval_for = require_approval_for or ALWAYS_REQUIRE_APPROVAL
+    action_class = ACTION_RISK.get(action)
+
+    if action_class is None:
+        return RiskDecision(action, None, False, "unclassified/low-risk action")
+
+    # local_only workspaces are the most conservative.
+    requires = action in require_approval_for or action in ALWAYS_REQUIRE_APPROVAL
+    if trust_policy == TrustPolicy.local_only and action_class in {
+        ApprovalActionClass.egress,
+        ApprovalActionClass.secret,
+    }:
+        requires = True
+
+    return RiskDecision(
+        action=action,
+        action_class=action_class,
+        requires_approval=requires,
+        reason=f"classified as {action_class.value} under {trust_policy.value} trust",
+    )

harness/security/secrets.py

@@ -0,0 +1,49 @@
+"""Secret resolution. Secrets are read from the environment (or Docker secrets
+mounted as files) at runtime and held only in process memory. They are NEVER
+written to the database, memory items, or transcripts.
+
+``secret_ref`` grammar:
+    env:NAME        -> os.environ["NAME"]
+    file:/path      -> contents of /path (Docker secret mount)
+    (empty/None)    -> None
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from pathlib import Path
+
+SECRETS_DIR = Path.home() / ".ags" / "secrets"
+
+
+def resolve_secret_ref(ref: str | None) -> str | None:
+    if not ref:
+        return None
+    scheme, _, value = ref.partition(":")
+    if scheme == "env":
+        return os.environ.get(value) or None
+    if scheme == "file":
+        p = Path(value)
+        return p.read_text().strip() if p.exists() else None
+    # Unknown scheme: treat as a literal env var name for convenience, but warn-safe.
+    return os.environ.get(ref) or None
+
+
+def write_secret_file(name: str, value: str) -> str:
+    """Persist a secret to ``~/.ags/secrets/<name>`` (0600) and return its ``file:``
+    ref. Used so a GUI-added provider's API key lives on disk as a file secret —
+    never in the database, memory, or transcripts."""
+    SECRETS_DIR.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(OSError):
+        os.chmod(SECRETS_DIR, 0o700)
+    path = SECRETS_DIR / name
+    path.write_text(value)
+    with contextlib.suppress(OSError):
+        os.chmod(path, 0o600)
+    return f"file:{path}"
+
+
+def delete_secret_file(name: str) -> None:
+    with contextlib.suppress(FileNotFoundError):
+        (SECRETS_DIR / name).unlink()

harness/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer: orchestrates models + repositories behind the API and CLI."""