sid-harness 0.3.0__py3-none-any.whl

sid_harness/receipt.py

@@ -0,0 +1,142 @@
+"""The harness run receipt.
+
+One JSON artifact per run, written to disk so a run explains itself: what was
+asked, what the loop did, the diff, the route, and — honestly — whether the
+approved tests ran (SUB-80: executed locally, with backend/exit/passed and a
+bounded output capture; ``tests_executed`` stays false when no approved test
+command ran). Durable per-session history is SUB-58.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+RECEIPT_VERSION = 1
+HARNESS_NAME = "sid-harness"
+
+
+def new_run_id() -> str:
+    return f"run_{uuid.uuid4().hex}"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def default_receipt_path(directory: Path, run_id: str) -> Path:
+    return Path(directory) / ".sid" / "runs" / f"{run_id}.json"
+
+
+def build_receipt(
+    *,
+    run_id: str,
+    task: str,
+    directory: Path,
+    base_url: str,
+    routing_profile: str,
+    requested_model: str,
+    workspace: dict[str, Any],
+    result: dict[str, Any],
+    verify: dict[str, Any] | None = None,
+    started_at: str | None = None,
+    finished_at: str | None = None,
+    git: dict[str, Any] | None = None,
+    git_status: list[str] | None = None,
+    wrote: list[str] | None = None,
+    deleted: list[str] | None = None,
+    pending_deletions: list[str] | None = None,
+    context: dict[str, Any] | None = None,
+    tools: dict[str, Any] | None = None,
+    bounds: dict[str, Any] | None = None,
+    policy: dict[str, Any] | None = None,
+    diagnostics: dict[str, Any] | None = None,
+    git_write: dict[str, Any] | None = None,
+    project_rules: dict[str, Any] | None = None,
+    skills: dict[str, Any] | None = None,
+    subagents: list[dict[str, Any]] | None = None,
+    plan: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    test = result.get("test") or {}
+    receipt = {
+        "receipt_version": RECEIPT_VERSION,
+        "run_id": run_id,
+        "harness": {"name": HARNESS_NAME, "engine": "native"},
+        "created_at": utc_now(),
+        "started_at": started_at,
+        "finished_at": finished_at,
+        "task": task,
+        "dir": str(directory),
+        "backend": {"base_url": base_url, "routing_profile": routing_profile},
+        "requested_model": requested_model,
+        "workspace": workspace,
+        "tests_executed": bool(test.get("executed")),
+        "test_backend": test.get("backend"),
+        "test_exit_code": test.get("exit_code"),
+        "test_passed": test.get("passed"),
+        "test_timed_out": bool(test.get("timed_out", False)),
+        "changed": result.get("changed", []),
+        "diff": result.get("diff"),
+        "patches": result.get("patches", []),
+        "final_response": result.get("final_response"),
+        "model": result.get("model"),
+        "steps": result.get("steps"),
+        "tool_calls": result.get("tool_calls"),
+        "turn_trace": result.get("turn_trace", []),
+        "route_calls": result.get("route_calls", []),
+        "test": test,
+        "shell": result.get("shell", []),
+        "shell_executed": any(
+            bool(entry.get("executed")) for entry in (result.get("shell") or [])
+        ),
+        "verify": verify,
+    }
+    if git is not None:
+        receipt["git"] = git
+        receipt["git_status"] = git_status or []
+    if wrote is not None:
+        receipt["wrote"] = wrote
+    if deleted is not None:
+        receipt["deleted"] = deleted
+    if pending_deletions is not None:
+        receipt["pending_deletions"] = pending_deletions
+    if context is not None:
+        receipt["context"] = context
+    if tools is not None:
+        receipt["tools"] = tools
+    if bounds is not None:
+        receipt["bounds"] = bounds
+    if policy is not None:
+        receipt["policy"] = policy
+    if diagnostics is not None:
+        receipt["diagnostics"] = diagnostics
+    readback = result.get("readback")
+    if isinstance(readback, dict) and readback:
+        receipt["readback"] = readback
+    if git_write is not None:
+        receipt["git_write"] = git_write
+    if project_rules is not None:
+        receipt["project_rules"] = project_rules
+    if skills is not None:
+        receipt["skills"] = skills
+    if subagents:
+        receipt["subagents"] = subagents
+    if plan is not None:
+        receipt["plan"] = plan
+    return receipt
+
+
+def write_receipt(path: str | os.PathLike[str], receipt: dict[str, Any]) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_name(target.name + ".tmp")
+    tmp.write_text(
+        json.dumps(receipt, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    os.replace(tmp, target)
+    return target

sid_harness/runner.py

@@ -0,0 +1,468 @@
+"""One run: load the workspace, drive the shared loop, verify, write a receipt."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import receipt as receipt_mod
+from .client import SIDClient
+from .gateway import native_agent
+from .local_workspace import LocalWorkspace
+from .loop import execute_test_argv, run_loop
+
+DEFAULT_CONTEXT_K = 4
+DEFAULT_MAX_CONTEXT_CHARS = 24000
+
+_NUMBERED_STEP = re.compile(r"^\s*(?:\d+[.)]|[-*])\s+(.+?)\s*$")
+
+
+class RunError(RuntimeError):
+    """A run option (project policy, skill, plan) could not be honoured."""
+
+
+def _sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _config_string_list(config: dict[str, Any], key: str) -> list[str]:
+    value = config.get(key)
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise RunError(f"project policy .sid/config field {key!r} must be a list of strings")
+    return [item.strip() for item in value if item.strip()]
+
+
+def _config_subagent_tasks(config: dict[str, Any]) -> list[dict[str, str]]:
+    value = config.get("subagents")
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise RunError("project policy .sid/config field 'subagents' must be a list")
+    tasks: list[dict[str, str]] = []
+    for index, item in enumerate(value, start=1):
+        if isinstance(item, str) and item.strip():
+            tasks.append({"id": f"sub{index}", "task": item.strip()})
+        elif isinstance(item, dict) and str(item.get("task") or "").strip():
+            tasks.append(
+                {
+                    "id": str(item.get("id") or f"sub{index}").strip() or f"sub{index}",
+                    "task": str(item["task"]).strip(),
+                }
+            )
+        else:
+            raise RunError(
+                "project policy .sid/config subagent entries must be strings "
+                "or objects with a non-empty 'task'"
+            )
+    return tasks
+
+
+def _load_skills(
+    *,
+    root: str | Path | None,
+    names: list[str],
+    config: dict[str, Any],
+    project_root: Path,
+    source: str,
+) -> tuple[str, dict[str, Any]]:
+    from .tools.skills import SkillCatalog, SkillError, default_skills_root
+
+    resolved = Path(root).expanduser() if root else None
+    if resolved is None and isinstance(config.get("skills_root"), str) and config["skills_root"].strip():
+        resolved = Path(config["skills_root"].strip()).expanduser()
+        if not resolved.is_absolute():
+            resolved = project_root / resolved
+    if resolved is None:
+        resolved = default_skills_root(project_root) or default_skills_root()
+    if resolved is None:
+        raise RunError(
+            "skills were requested but no .opencode/skills directory was found; "
+            "pass --skills-root <dir>"
+        )
+    try:
+        catalog = SkillCatalog.load(resolved)
+        rendered = catalog.render(names)
+    except SkillError as exc:
+        raise RunError(str(exc)) from exc
+    loaded = []
+    for name in names:
+        skill = catalog.get(name)
+        try:
+            digest = _sha256_text(skill.path.read_text(encoding="utf-8"))
+        except OSError as exc:
+            raise RunError(f"cannot hash skill {name!r}: {exc}") from exc
+        loaded.append({"name": skill.name, "path": str(skill.path), "sha256": digest})
+    return rendered, {"root": str(resolved), "source": source, "loaded": loaded}
+
+
+@dataclass
+class RunOutcome:
+    receipt: dict[str, Any]
+    receipt_path: Path
+
+
+def _build_context(
+    workspace: LocalWorkspace,
+    query: str,
+    *,
+    k: int,
+    max_chars: int,
+    embedder: Any | None = None,
+) -> tuple[str, dict[str, Any]]:
+    """Repo-scale retrieval over ``workspace`` (SUB-55) for ``query``.
+
+    Local, read-only, and reuses the gateway's ``app.rag`` retrieval seam. The
+    returned text is data-boundaried and sanitized; it is prepended to the task.
+    """
+    from .context import build_index, context_block
+
+    index = build_index(workspace)
+    block, meta = context_block(index, query, k=k, embedder=embedder)
+    truncated = len(block) > max_chars
+    if truncated:
+        block = block[:max_chars]
+    meta = {
+        **meta,
+        "indexed_files": len(index.files),
+        "index_truncated": index.truncated,
+        "chars": len(block),
+        "truncated": truncated,
+    }
+    return block, meta
+
+
+def execute_run(
+    *,
+    task: str,
+    directory: str | Path,
+    client: SIDClient,
+    model: str = "auto",
+    criteria: list[str] | None = None,
+    out_of_scope: list[str] | None = None,
+    test_argv: list[str] | None = None,
+    max_tokens: int = 8000,
+    reasoning_effort: str | None = None,
+    verify: bool = False,
+    write: bool = False,
+    allow_delete: bool = False,
+    git_write: bool = False,
+    git_branch: str | None = None,
+    git_message: str | None = None,
+    git_base: str | None = None,
+    git_pr: bool = True,
+    git_approve: Any | None = None,
+    gh_runner: Any | None = None,
+    receipt_path: str | Path | None = None,
+    reporter: Callable[[str], None] | None = None,
+    context: bool = False,
+    context_k: int = DEFAULT_CONTEXT_K,
+    max_context_chars: int = DEFAULT_MAX_CONTEXT_CHARS,
+    registry: Any | None = None,
+    bounds: Any | None = None,
+    diagnostics: bool = True,
+    shell_policy: Any | None = None,
+    skills: list[str] | None = None,
+    skills_root: str | Path | None = None,
+    subagents: list[str] | None = None,
+    plan: bool = False,
+    todos: list[str] | None = None,
+) -> RunOutcome:
+    emit = reporter or (lambda _message: None)
+    workspace = LocalWorkspace.open(directory)
+    load_kwargs: dict[str, Any] = {}
+    if bounds is not None:
+        load_kwargs = {
+            "max_files": bounds.max_files,
+            "max_bytes": bounds.max_workspace_bytes,
+            "max_file_bytes": bounds.max_file_bytes,
+        }
+    selection = workspace.load(**load_kwargs)
+    emit(f"workspace: {len(selection.files)} file(s) from {selection.root}")
+    if workspace.git.is_repo:
+        where = "worktree" if workspace.git.is_worktree else "checkout"
+        emit(f"git: {where} branch={workspace.git.branch or '?'} ({workspace.git.root})")
+    for path, reason in selection.skipped:
+        emit(f"skipped: {path} ({reason})")
+
+    # SUB-55: repo-scale context. Retrieval is over the whole indexed tree; the
+    # sanitized, data-boundaried block is prepended to the task.
+    effective_task = task
+    context_meta: dict[str, Any] | None = None
+    if context:
+        block, context_meta = _build_context(
+            workspace, task, k=context_k, max_chars=max_context_chars
+        )
+        if block:
+            effective_task = f"{block}\n\nTask: {task}"
+        emit(f"context: {context_meta['chunks_used']} chunk(s) from {context_meta['indexed_files']} file(s)")
+
+    # SUB-96: the editor/LSP diagnostics feed (``sid lsp`` writes it) is
+    # prepended to the task so the one loop sees the compiler's findings.
+    diagnostics_meta: dict[str, Any] | None = None
+    if diagnostics:
+        from .lsp import diagnostics_context
+
+        diag_block, diagnostics_meta = diagnostics_context(selection.root)
+        if diag_block:
+            effective_task = f"{diag_block}\n\n{effective_task}"
+            emit(f"diagnostics: {diagnostics_meta['count']} item(s) from the editor/LSP feed")
+
+    # SUB-94: the project policy the run will obey. The loop loads the same
+    # files into its system prompt; reading it here lets `.sid/config` supply
+    # run options (skills/subagents/plan) exactly as documented, with explicit
+    # CLI flags taking precedence.
+    try:
+        project_rules = native_agent.load_project_rules(selection.files)
+    except native_agent.NativeAgentInputError as exc:
+        raise RunError(str(exc)) from exc
+    project_config = project_rules.get("config") or {}
+
+    config_plan = project_config.get("plan")
+    if config_plan is not None and not isinstance(config_plan, bool):
+        raise RunError("project policy .sid/config field 'plan' must be true or false")
+    plan_active = bool(plan or config_plan)
+    plan_source = "flag" if plan else ("config" if config_plan else None)
+
+    skills_meta: dict[str, Any] | None = None
+    skill_names = (
+        [name.strip() for name in skills if name and name.strip()]
+        if skills is not None
+        else _config_string_list(project_config, "skills")
+    )
+    if skill_names:
+        rendered, skills_meta = _load_skills(
+            root=skills_root,
+            names=skill_names,
+            config=project_config,
+            project_root=selection.root,
+            source="flags" if skills is not None else "config",
+        )
+        effective_task = f"SKILLS — loaded project skills:\n{rendered}\n\n{effective_task}"
+        emit(f"skills: {', '.join(skill_names)}")
+
+    if subagents is not None:
+        subagent_specs = [
+            {"id": f"sub{index}", "task": text.strip()}
+            for index, text in enumerate(subagents, start=1)
+            if text and text.strip()
+        ]
+    else:
+        subagent_specs = _config_subagent_tasks(project_config)
+    from .tools.subagents import SubTask
+
+    subagent_tasks = [
+        SubTask(id=spec["id"], task=spec["task"]) for spec in subagent_specs
+    ]
+    todo_texts = [text.strip() for text in (todos or []) if text and text.strip()]
+
+    acceptance = criteria or ["Complete the task described in the goal."]
+    scope = out_of_scope or []
+    run_id = receipt_mod.new_run_id()
+    started_at = receipt_mod.utc_now()
+
+    result = asyncio.run(
+        run_loop(
+            client=client,
+            task=effective_task,
+            workspace_files=selection.files,
+            acceptance_criteria=acceptance,
+            out_of_scope=scope,
+            test_argv=test_argv or [],
+            workspace_root=selection.root,
+            model=model,
+            max_tokens=max_tokens,
+            reasoning_effort=reasoning_effort,
+            registry=registry,
+            bounds=bounds,
+            shell_policy=shell_policy,
+            plan_only=plan_active,
+            subagent_tasks=subagent_tasks,
+        )
+    )
+    finished_at = receipt_mod.utc_now()
+
+    plan_meta: dict[str, Any] | None = None
+    if plan_active or todo_texts:
+        from .tools.plan import PlanError, PlanGate
+
+        gate = PlanGate(require_plan=plan_active)
+        for text in todo_texts:
+            gate.todos.add(text)
+        if plan_active:
+            steps = [
+                match.group(1)
+                for line in (result.get("plan") or "").splitlines()
+                if (match := _NUMBERED_STEP.match(line))
+            ]
+            if steps:
+                try:
+                    gate.set_plan(steps)
+                except PlanError:
+                    pass
+        plan_meta = {
+            "mode": "plan" if plan_active else "write",
+            "source": plan_source or "flags",
+            "gate": gate.snapshot(),
+        }
+
+    # SUB-54: opt-in write-back to the real tree. Never a commit, never a push.
+    # Deletions are never silent: plan_apply separates writes from deletions and
+    # a deletion reaches disk only when --allow-delete approves it explicitly.
+    # SUB-57: the platform write policy gates it — inside the platform repo a
+    # source write from the MAIN checkout is refused.
+    apply_plan = workspace.plan_apply(
+        result.get("changed", []), result.get("readback", {})
+    )
+    wrote: list[str] = []
+    deleted: list[str] = []
+    pending_deletions: list[str] = []
+    policy_block: dict[str, Any] | None = None
+    if write:
+        from .policy import preflight_write
+
+        decision = preflight_write(workspace.root, list(result.get("changed", [])))
+        policy_block = decision.as_dict()
+        if decision.allowed:
+            approved_deletions = apply_plan["deletions"] if allow_delete else []
+            wrote = workspace.apply(
+                result.get("changed", []),
+                result.get("readback", {}),
+                approved_deletions=approved_deletions,
+            )
+            deleted = list(approved_deletions)
+            pending_deletions = [
+                rel for rel in apply_plan["deletions"] if rel not in approved_deletions
+            ]
+            emit(f"wrote: {len(wrote)} file(s) to {workspace.root}")
+            if deleted:
+                emit(f"deleted (approved): {', '.join(deleted)}")
+            if pending_deletions:
+                emit(
+                    "deletions awaiting explicit approval (--allow-delete): "
+                    + ", ".join(pending_deletions)
+                )
+        else:
+            emit(f"write refused by repo policy: {decision.explanation}")
+
+    # SUB-80: the in-loop run executes the approved argv against the on-disk
+    # tree. When --write applied the model's edits, re-run it so the receipt's
+    # test block describes the tree the user now has, not the pre-write tree.
+    if wrote and test_argv:
+        fresh = execute_test_argv(test_argv, root=workspace.root)
+        result["test"] = fresh
+        result["tests"] = fresh
+        emit(f"tests re-run on the written tree: {fresh.get('detail')}")
+
+    # SUB-95: explicit opt-in git write path (branch -> commit -> push -> PR).
+    # The default stays read-only. Only files actually applied are committed;
+    # each step needs its own approval, and main/master is refused inside the
+    # module before any mutation. The receipt names the branch, commit and PR.
+    git_write_block: dict[str, Any] | None = None
+    if git_write:
+        from .git_write import (
+            GitWritePlan,
+            default_branch_name,
+            default_commit_message,
+            execute_git_write,
+        )
+
+        planned_branch = git_branch or default_branch_name(run_id)
+        if not write:
+            git_write_block = {
+                "status": "refused",
+                "reason": "--git-write requires --write so there is an approved diff to commit",
+                "branch": planned_branch,
+                "commit": None,
+                "pr_url": None,
+                "pushed": False,
+                "steps": [],
+                "commands": [],
+            }
+        elif not wrote:
+            git_write_block = {
+                "status": "refused",
+                "reason": "no approved changes were applied to the working tree",
+                "branch": planned_branch,
+                "commit": None,
+                "pr_url": None,
+                "pushed": False,
+                "steps": [],
+                "commands": [],
+            }
+        else:
+            plan = GitWritePlan(
+                directory=workspace.root,
+                branch=planned_branch,
+                message=git_message or default_commit_message(task, run_id),
+                paths=tuple(wrote),
+                base_branch=git_base or "main",
+                open_pr=git_pr,
+            )
+            git_outcome = execute_git_write(
+                plan, approve=git_approve, gh_runner=gh_runner
+            )
+            git_write_block = git_outcome.as_dict()
+            emit(
+                f"git-write: {git_outcome.status} branch={git_outcome.branch} "
+                f"commit={git_outcome.commit} pr={git_outcome.pr_url}"
+            )
+
+    verify_block: dict[str, Any] | None = None
+    if verify and result.get("diff"):
+        try:
+            verify_block = client.verify_patch(
+                result["diff"],
+                model=model,
+                context="\n".join(acceptance),
+            )
+        except Exception as exc:  # verify is advisory; never mask the run itself
+            verify_block = {"verdict": "unavailable", "error": str(exc)}
+
+    receipt = receipt_mod.build_receipt(
+        run_id=run_id,
+        task=effective_task,
+        directory=selection.root,
+        base_url=client.base_url,
+        routing_profile=client.routing_profile,
+        requested_model=model,
+        workspace={
+            "files": len(selection.files),
+            "bytes": selection.total_bytes,
+            "skipped": selection.skipped_report(),
+        },
+        result=result,
+        verify=verify_block,
+        started_at=started_at,
+        finished_at=finished_at,
+        git=workspace.git.as_dict(),
+        git_status=workspace.status(),
+        wrote=wrote,
+        deleted=deleted,
+        pending_deletions=pending_deletions,
+        context=context_meta,
+        tools={"extension_tools": registry.extension_names(), "all_tools": registry.names()}
+        if registry is not None
+        else None,
+        bounds=bounds.as_dict() if bounds is not None else None,
+        policy=policy_block,
+        diagnostics=diagnostics_meta,
+        git_write=git_write_block,
+        project_rules=project_rules,
+        skills=skills_meta,
+        subagents=result.get("subagents") or [],
+        plan=plan_meta,
+    )
+    target = (
+        Path(receipt_path)
+        if receipt_path
+        else receipt_mod.default_receipt_path(selection.root, run_id)
+    )
+    written = receipt_mod.write_receipt(target, receipt)
+    return RunOutcome(receipt=receipt, receipt_path=written)