ags-cli 0.1.0__py3-none-any.whl

harness/api/v1/project.py

@@ -0,0 +1,302 @@
+"""Project folder + plan/write mode for a workspace — runtime, no restart.
+
+These are stored in ``workspace.settings`` and read by the orchestrator on each run,
+so changing them here takes effect on the next message. Drives ``ags project``."""
+
+from __future__ import annotations
+
+import asyncio
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+from harness.deps import CurrentPrincipal, DbSession
+from harness.services import project_git
+from harness.services.files import (
+    create_entry,
+    delete_entry,
+    file_path,
+    find_files,
+    list_dir,
+    read_file,
+    rename_entry,
+    search_content,
+    write_file,
+)
+from harness.services.ssh import (
+    browse_dirs_remote,
+    ssh_check,
+    validate_host,
+    list_dir_remote,
+    read_file_remote,
+    write_file_remote,
+    delete_file_remote,
+    create_file_remote,
+)
+from harness.services.workspaces import browse_dirs, get_project_settings, set_project_settings
+
+router = APIRouter(prefix="/project", tags=["project"])
+
+
+class ProjectUpdate(BaseModel):
+    project_dir: str | None = None
+    project_host: str | None = None  # "" clears (back to local)
+    write_mode: bool | None = None
+    default_workspace_mode: str | None = None  # "main" | "worktree" (new sessions)
+    remote_hosts: list[dict] | None = None  # saved-host address book [{label, host}]
+
+
+class SshTest(BaseModel):
+    host: str
+    path: str | None = None
+    bin: str | None = None
+
+
+class FileWrite(BaseModel):
+    subpath: str
+    text: str
+
+
+class EntryCreate(BaseModel):
+    subpath: str
+    kind: str  # "file" | "dir"
+
+
+class EntryRename(BaseModel):
+    src: str
+    dst: str
+
+
+@router.get("")
+async def get_project(db: DbSession, _: CurrentPrincipal, workspace: str = "default") -> dict:
+    return await get_project_settings(db, workspace)
+
+
+@router.get("/browse")
+async def browse(
+    _: CurrentPrincipal, path: str | None = None, strict: bool = False,
+    host: str | None = None,
+) -> dict:
+    """List subdirectories of ``path`` (default: home) for the GUI folder picker.
+    ``strict`` 404s on a non-directory instead of falling back to home (autocomplete).
+    ``host`` browses a remote ssh host instead of the server's filesystem."""
+    try:
+        if host:
+            return await browse_dirs_remote(host, path)
+        return browse_dirs(path, strict=strict)
+    except ValueError as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except (TimeoutError, OSError) as exc:
+        raise HTTPException(502, f"ssh to {host!r} failed: {exc}") from exc
+
+
+@router.post("/ssh-test")
+async def ssh_test(req: SshTest, _: CurrentPrincipal) -> dict:
+    """Probe an ssh host for the settings page — connectivity, optional remote dir,
+    optional agent-CLI version. Connection failures return ``ok: false``, never 5xx."""
+    try:
+        validate_host(req.host)
+    except ValueError as exc:
+        raise HTTPException(422, str(exc)) from exc
+    return await ssh_check(req.host, path=req.path, bin=req.bin)
+
+
+def _reject_remote(project: dict, what: str) -> None:
+    """Local-filesystem endpoints refuse remote projects with a clear 400 — the
+    server can't (and shouldn't) read the remote host's files."""
+    if project.get("project_host"):
+        raise HTTPException(
+            400, f"{what} unavailable for remote project on {project['project_host']!r}")
+
+
+@router.get("/tree")
+async def tree(
+    db: DbSession, _: CurrentPrincipal, subpath: str = "", workspace: str = "default"
+) -> dict:
+    """List files + subdirectories of ``subpath`` within the workspace's active project
+    folder (read-only, scoped to that folder). Drives the GUI file explorer."""
+    project = await get_project_settings(db, workspace)
+    if project.get("project_host"):
+        try:
+            return await list_dir_remote(project["project_host"], project["project_dir"], subpath)
+        except ValueError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except (TimeoutError, OSError) as exc:
+            raise HTTPException(502, f"SSH error: {exc}") from exc
+    _reject_remote(project, "file explorer")
+    try:
+        return list_dir(project["project_dir"], subpath)
+    except ValueError as exc:
+        raise HTTPException(404, str(exc)) from exc
+
+
+@router.get("/file")
+async def file(
+    db: DbSession, _: CurrentPrincipal, subpath: str, workspace: str = "default"
+) -> dict:
+    """Return the UTF-8 text of a file within the workspace's active project folder.
+    Paths are resolved and asserted to stay inside that folder."""
+    project = await get_project_settings(db, workspace)
+    if project.get("project_host"):
+        try:
+            return await read_file_remote(project["project_host"], project["project_dir"], subpath)
+        except ValueError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except (TimeoutError, OSError) as exc:
+            raise HTTPException(502, f"SSH error: {exc}") from exc
+    _reject_remote(project, "file explorer")
+    try:
+        return read_file(project["project_dir"], subpath)
+    except ValueError as exc:
+        raise HTTPException(404, str(exc)) from exc
+
+
+@router.get("/raw")
+async def raw(
+    db: DbSession, _: CurrentPrincipal, subpath: str, workspace: str = "default"
+) -> FileResponse:
+    """Stream a file's raw bytes (content-type guessed from the name) so the GUI can
+    render images and other binaries. Path-scoped to the project folder."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "file explorer")
+    try:
+        path = file_path(project["project_dir"], subpath)
+    except ValueError as exc:
+        raise HTTPException(404, str(exc)) from exc
+    return FileResponse(path)
+
+
+@router.put("/file")
+async def write(
+    req: FileWrite, db: DbSession, _: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    """Write UTF-8 text to a file within the project folder (creating it if needed).
+    Path-scoped via ``_safe_join``; refuses directories and over-cap payloads."""
+    project = await get_project_settings(db, workspace)
+    if project.get("project_host"):
+        try:
+            return await write_file_remote(
+                project["project_host"], project["project_dir"], req.subpath, req.text
+            )
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        except (TimeoutError, OSError) as exc:
+            raise HTTPException(502, f"SSH error: {exc}") from exc
+    _reject_remote(project, "file editing")
+    try:
+        return write_file(project["project_dir"], req.subpath, req.text)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+@router.post("/entry", status_code=201)
+async def create(
+    req: EntryCreate, db: DbSession, _: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    """Create a new empty file or directory within the project folder."""
+    project = await get_project_settings(db, workspace)
+    if project.get("project_host"):
+        try:
+            return await create_file_remote(
+                project["project_host"], project["project_dir"], req.subpath, req.kind == "dir"
+            )
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        except (TimeoutError, OSError) as exc:
+            raise HTTPException(502, f"SSH error: {exc}") from exc
+    _reject_remote(project, "file management")
+    try:
+        return create_entry(project["project_dir"], req.subpath, req.kind)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+@router.post("/rename")
+async def rename(
+    req: EntryRename, db: DbSession, _: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    """Rename/move a file or directory within the project folder."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "file management")
+    try:
+        return rename_entry(project["project_dir"], req.src, req.dst)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+@router.delete("/file")
+async def delete(
+    db: DbSession, _: CurrentPrincipal, subpath: str, workspace: str = "default"
+) -> dict:
+    """Soft-delete a file or directory (moved into ``.ags-trash/`` at the project root)."""
+    project = await get_project_settings(db, workspace)
+    if project.get("project_host"):
+        try:
+            return await delete_file_remote(
+                project["project_host"], project["project_dir"], subpath
+            )
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        except (TimeoutError, OSError) as exc:
+            raise HTTPException(502, f"SSH error: {exc}") from exc
+    _reject_remote(project, "file management")
+    try:
+        return delete_entry(project["project_dir"], subpath)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+@router.get("/find")
+async def find(
+    db: DbSession, _: CurrentPrincipal, q: str, workspace: str = "default"
+) -> dict:
+    """Quick-open: files whose path matches every token of ``q`` (case-insensitive)."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "file search")
+    return await asyncio.to_thread(find_files, project["project_dir"], q)
+
+
+@router.get("/search")
+async def search(
+    db: DbSession, _: CurrentPrincipal, q: str, workspace: str = "default"
+) -> dict:
+    """Full-text content search across project files (ripgrep when available)."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "file search")
+    return await asyncio.to_thread(search_content, project["project_dir"], q)
+
+
+@router.get("/git-status")
+async def git_status(
+    db: DbSession, _: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    """Working-tree git status ({subpath: modified|added|deleted|renamed|untracked})."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "git status")
+    return await asyncio.to_thread(project_git.git_status, project["project_dir"])
+
+
+@router.get("/git-diff")
+async def git_diff(
+    db: DbSession, _: CurrentPrincipal, subpath: str, workspace: str = "default"
+) -> dict:
+    """Per-file working-tree diff vs HEAD (falls back to full content for new files)."""
+    project = await get_project_settings(db, workspace)
+    _reject_remote(project, "git diff")
+    return await asyncio.to_thread(project_git.file_diff, project["project_dir"], subpath)
+
+
+@router.put("")
+async def put_project(
+    req: ProjectUpdate, db: DbSession, principal: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    try:
+        return await set_project_settings(
+            db, workspace, project_dir=req.project_dir, project_host=req.project_host,
+            write_mode=req.write_mode,
+            default_workspace_mode=req.default_workspace_mode,
+            remote_hosts=req.remote_hosts, actor=principal.subject,
+        )
+    except ValueError as exc:
+        raise HTTPException(422, str(exc)) from exc

harness/api/v1/runs.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, HTTPException
+
+from harness.deps import CurrentPrincipal, DbSession
+from harness.orchestrator.lifecycle import get_canceller
+from harness.schemas.common import Message
+from harness.schemas.run import (
+    CompareRequest,
+    ComparisonOut,
+    MergeRequest,
+    RunOut,
+    RunStartRequest,
+    RunStartResponse,
+)
+from harness.services.comparison import compare_runs, merge_runs
+from harness.services.runs import start_run
+from harness.services.runs_diff import latest_run_diff, run_diff
+
+router = APIRouter(prefix="/runs", tags=["runs"])
+
+
+@router.post("/start", response_model=RunStartResponse, status_code=201)
+async def start(
+    req: RunStartRequest, db: DbSession, principal: CurrentPrincipal,
+    inline: bool = False,
+) -> RunStartResponse:
+    try:
+        session_id, runs, dispatched = await start_run(
+            db, req, inline=inline, actor=principal.subject
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return RunStartResponse(
+        session_id=session_id,
+        runs=[RunOut.model_validate(r) for r in runs],
+        dispatched=dispatched,
+    )
+
+
+@router.post("/{run_id}/cancel", response_model=Message)
+async def cancel(run_id: uuid.UUID, _: CurrentPrincipal) -> Message:
+    canceller = get_canceller()
+    await canceller.request_cancel(str(run_id))
+    await canceller.aclose()  # no-op for the in-memory (local) registry
+    return Message(message=f"cancellation requested for run {run_id}")
+
+
+@router.post("/compare", response_model=ComparisonOut)
+async def compare(req: CompareRequest, db: DbSession, _: CurrentPrincipal) -> ComparisonOut:
+    try:
+        comp = await compare_runs(
+            db, run_ids=req.run_ids, strategy=req.strategy,
+            judge_provider=req.judge_provider, judge_model=req.judge_model,
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return ComparisonOut.model_validate(comp)
+
+
+@router.post("/merge", response_model=ComparisonOut)
+async def merge(req: MergeRequest, db: DbSession, _: CurrentPrincipal) -> ComparisonOut:
+    try:
+        comp = await merge_runs(
+            db, run_ids=req.run_ids, persist=req.persist, merged_content=req.merged_content
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return ComparisonOut.model_validate(comp)
+
+
+@router.get("/{run_id}/diff")
+async def diff(run_id: uuid.UUID, db: DbSession, _: CurrentPrincipal) -> dict:
+    """Return the git diff between the run's pre-run snapshot and the current HEAD.
+
+    404 when the run has no snapshot artifact (e.g. read-only / plan-mode runs).
+    Response: ``{"run_id", "snapshot", "diff", "truncated"}``.
+    """
+    try:
+        return await run_diff(db, run_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("/diff/latest")
+async def diff_latest(
+    db: DbSession, _: CurrentPrincipal, workspace: str = "default"
+) -> dict:
+    """Return the diff for the newest run (in *workspace*) that has a snapshot artifact.
+
+    404 when no qualifying run exists.
+    """
+    try:
+        return await latest_run_diff(db, workspace)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc

harness/api/v1/sessions.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from harness.deps import CurrentPrincipal, DbSession
+from harness.schemas.run import RunEventOut, RunOut, RunStartRequest, RunStartResponse
+from harness.schemas.session import (
+    SessionBranchRequest,
+    SessionClearRequest,
+    SessionClearResponse,
+    SessionMergeRequest,
+    SessionMergeResponse,
+    SessionModeOut,
+    SessionOut,
+    SessionResumeRequest,
+    SessionSettingsUpdate,
+    SessionWorkspaceOut,
+)
+from harness.services.retention import compact_sessions
+from harness.services.runs import start_run
+from harness.services.sessions import (
+    branch_session,
+    delete_sessions,
+    get_session,
+    get_session_mode,
+    list_recent_sessions,
+    list_run_events,
+    list_session_runs,
+    select_sessions_to_clear,
+    set_session_settings,
+)
+from harness.services.stats import session_stats
+
+
+class CompactRequest(BaseModel):
+    older_than_days: int = Field(..., ge=1)
+    dry_run: bool = False
+
+
+class CompactResponse(BaseModel):
+    sessions: int
+    events_deleted: int
+    dry_run: bool
+
+router = APIRouter(prefix="/sessions", tags=["sessions"])
+
+
+@router.get("", response_model=list[SessionOut])
+async def index(db: DbSession, _: CurrentPrincipal, limit: int = 50) -> list[SessionOut]:
+    return [SessionOut.model_validate(s) for s in await list_recent_sessions(db, limit=limit)]
+
+
+@router.post("/compact", response_model=CompactResponse)
+async def compact(
+    req: CompactRequest, db: DbSession, _: CurrentPrincipal
+) -> CompactResponse:
+    """Prune bulky token and tool_result events from old terminal sessions.
+
+    Keeps the essential audit trail (message, status, cost, adapter_meta,
+    tool_call, error, artifact). With ``dry_run`` it only reports counts."""
+    report = await compact_sessions(db, older_than_days=req.older_than_days, dry_run=req.dry_run)
+    return CompactResponse(
+        sessions=report.sessions,
+        events_deleted=report.events_deleted,
+        dry_run=req.dry_run,
+    )
+
+
+@router.post("/clear", response_model=SessionClearResponse)
+async def clear(
+    req: SessionClearRequest, db: DbSession, _: CurrentPrincipal
+) -> SessionClearResponse:
+    """Hard-delete sessions matching the filters (AND-combined). With ``dry_run`` it only
+    reports the matches. Refuses an unfiltered request unless ``all`` is set."""
+    if not (req.all or req.status or req.older_than_days or req.workspace or req.ids):
+        raise HTTPException(400, "refusing to clear without a filter (set all=true to wipe all)")
+    matches = await select_sessions_to_clear(
+        db, all=req.all, status=req.status, older_than_days=req.older_than_days,
+        workspace_slug=req.workspace, ids=req.ids,
+    )
+    out = [SessionOut.model_validate(s) for s in matches]
+    if req.dry_run:
+        return SessionClearResponse(count=len(out), deleted=False, sessions=out)
+    n = await delete_sessions(db, matches)
+    return SessionClearResponse(count=n, deleted=True, sessions=out)
+
+
+@router.post("/prune-worktrees")
+async def prune_worktrees(db: DbSession, _: CurrentPrincipal) -> dict:
+    """Remove worktree directories whose session no longer exists."""
+    from harness.services.worktrees import prune_orphan_worktrees
+
+    return await prune_orphan_worktrees(db)
+
+
+@router.get("/{session_id}", response_model=SessionOut)
+async def get(session_id: uuid.UUID, db: DbSession, _: CurrentPrincipal) -> SessionOut:
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise HTTPException(404, "session not found")
+    return SessionOut.model_validate(sess)
+
+
+@router.get("/{session_id}/settings", response_model=SessionModeOut)
+async def get_settings(
+    session_id: uuid.UUID, db: DbSession, _: CurrentPrincipal
+) -> SessionModeOut:
+    """The session's plan/write mode: its own override plus the resolved effective value."""
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise HTTPException(404, "session not found")
+    return SessionModeOut(**await get_session_mode(db, sess))
+
+
+@router.put("/{session_id}/settings", response_model=SessionModeOut)
+async def put_settings(
+    session_id: uuid.UUID, req: SessionSettingsUpdate, db: DbSession,
+    principal: CurrentPrincipal,
+) -> SessionModeOut:
+    """Set (true/false) or clear (explicit null) the session's write-mode override.
+    Takes effect on the session's next turn."""
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise HTTPException(404, "session not found")
+    if "write_mode" in req.model_fields_set:
+        sess = await set_session_settings(
+            db, session_id, write_mode=req.write_mode, actor=principal.subject
+        )
+    return SessionModeOut(**await get_session_mode(db, sess))
+
+
+@router.get("/{session_id}/workspace", response_model=SessionWorkspaceOut)
+async def workspace_status(
+    session_id: uuid.UUID, db: DbSession, _: CurrentPrincipal
+) -> SessionWorkspaceOut:
+    """Isolation state of the session's private workspace (worktree)."""
+    from harness.services.worktrees import worktree_status
+
+    try:
+        return SessionWorkspaceOut(**await worktree_status(db, session_id))
+    except ValueError as exc:
+        raise HTTPException(404, str(exc)) from exc
+
+
+@router.post("/{session_id}/merge", response_model=SessionMergeResponse)
+async def merge_workspace(
+    session_id: uuid.UUID, req: SessionMergeRequest, db: DbSession,
+    principal: CurrentPrincipal,
+) -> SessionMergeResponse:
+    """Merge the session's private branch back into its base branch. Conflicts
+    abort cleanly and come back in ``conflicts``; user-fixable refusals are 400."""
+    from harness.services.worktrees import merge_session_worktree
+
+    try:
+        out = await merge_session_worktree(
+            db, session_id, squash=req.squash, delete_worktree=req.delete_worktree,
+            message=req.message, actor=principal.subject,
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return SessionMergeResponse(**out)
+
+
+@router.delete("/{session_id}/workspace")
+async def discard_workspace(
+    session_id: uuid.UUID, db: DbSession, principal: CurrentPrincipal,
+) -> dict:
+    """Discard the session's worktree AND its branch (keep the session). This is
+    an explicit destructive action — the next turn gets a fresh worktree off the
+    current base. (Session *deletion* keeps unmerged branches as a safety net;
+    discard means discard.)"""
+    from harness.services.sessions import get_session as _get
+    from harness.services.worktrees import remove_worktree
+
+    sess = await _get(db, session_id)
+    if sess is None:
+        raise HTTPException(404, "session not found")
+    removed = await remove_worktree(
+        db, session_id, delete_branch=True, actor=principal.subject,
+    )
+    return {"removed": removed}
+
+
+@router.get("/{session_id}/runs", response_model=list[RunOut])
+async def runs(session_id: uuid.UUID, db: DbSession, _: CurrentPrincipal) -> list[RunOut]:
+    return [RunOut.model_validate(r) for r in await list_session_runs(db, session_id)]
+
+
+@router.get("/{session_id}/runs/{run_id}/events", response_model=list[RunEventOut])
+async def events(
+    session_id: uuid.UUID, run_id: uuid.UUID, db: DbSession, _: CurrentPrincipal
+) -> list[RunEventOut]:
+    return [
+        RunEventOut(seq=e.seq, type=e.type.value, ts=e.ts, payload=e.payload)
+        for e in await list_run_events(db, run_id)
+    ]
+
+
+@router.post("/{session_id}/resume", response_model=RunStartResponse, status_code=201)
+async def resume(
+    session_id: uuid.UUID, req: SessionResumeRequest, db: DbSession, principal: CurrentPrincipal,
+    inline: bool = False,
+) -> RunStartResponse:
+    """Continue a session from its canonical summary (not raw transcript)."""
+    sess = await get_session(db, session_id)
+    if sess is None:
+        raise HTTPException(404, "session not found")
+    start_req = RunStartRequest(
+        session_id=session_id, policy=req.policy, providers=req.providers,
+        additional_objective=req.additional_objective, model=req.model, models=req.models,
+        attachments=req.attachments,
+    )
+    try:
+        sid, runs_, dispatched = await start_run(
+            db, start_req, inline=inline, actor=principal.subject
+        )
+    except ValueError as exc:  # user-fixable (e.g. attachment rejections) → 400
+        raise HTTPException(400, str(exc)) from exc
+    return RunStartResponse(
+        session_id=sid, runs=[RunOut.model_validate(r) for r in runs_], dispatched=dispatched
+    )
+
+
+@router.post("/{session_id}/branch", response_model=SessionOut, status_code=201)
+async def branch(
+    session_id: uuid.UUID, _req: SessionBranchRequest, db: DbSession, principal: CurrentPrincipal
+) -> SessionOut:
+    child = await branch_session(db, session_id, actor=principal.subject)
+    return SessionOut.model_validate(child)
+
+
+@router.get("/{session_id}/stats", response_model=list[dict])
+async def stats(session_id: uuid.UUID, db: DbSession, _: CurrentPrincipal) -> list[dict]:
+    """Per-run latency and token breakdown for a session.
+
+    Returns a list of dicts (one per run, ordered by created_at) with keys:
+    - run_id: The run UUID
+    - provider: The adapter kind (e.g. claude_code)
+    - queue_ms: Time from created_at to started_at (int, None if not started)
+    - first_event_ms: Time from started_at to first RunEvent (int, None if no events)
+    - total_ms: Time from started_at to finished_at (int, None if not finished)
+    - tokens: {prompt: int, completion: int} from run.cost (default 0)
+    - resume: Resume mode from run.context_meta, or None
+    """
+    return await session_stats(db, session_id)