sid-harness 0.3.0__py3-none-any.whl

sid_harness/selftest.py

@@ -0,0 +1,149 @@
+"""Self-contained proof that the harness drives the shared loop end to end.
+
+Starts a local stub of SID's ``/v1`` (chat completions + verify/patch), runs one
+real loop turn through ``native_agent`` against it, and writes a receipt. No
+network, no key, no spend — the same path a live run takes, minus the provider.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+from .client import SIDClient
+from .runner import RunOutcome, execute_run
+
+STUB_MODEL = "sid-harness-selftest"
+SELFTEST_KEY = "selftest-key"
+
+
+def _completion(messages: list[dict[str, Any]]) -> dict[str, Any]:
+    """Turn 1: one write_file tool call. Turn 2: a final answer."""
+    has_tool_result = any(message.get("role") == "tool" for message in messages)
+    if not has_tool_result:
+        return {
+            "id": "chatcmpl-selftest-1",
+            "object": "chat.completion",
+            "model": STUB_MODEL,
+            "choices": [
+                {
+                    "index": 0,
+                    "finish_reason": "tool_calls",
+                    "message": {
+                        "role": "assistant",
+                        "content": None,
+                        "tool_calls": [
+                            {
+                                "id": "call_selftest_1",
+                                "type": "function",
+                                "function": {
+                                    "name": "write_file",
+                                    "arguments": json.dumps(
+                                        {
+                                            "path": "greeting.txt",
+                                            "content": "hello from sid-harness\n",
+                                        }
+                                    ),
+                                },
+                            }
+                        ],
+                    },
+                }
+            ],
+            "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+        }
+    return {
+        "id": "chatcmpl-selftest-2",
+        "object": "chat.completion",
+        "model": STUB_MODEL,
+        "choices": [
+            {
+                "index": 0,
+                "finish_reason": "stop",
+                "message": {"role": "assistant", "content": "Updated greeting.txt."},
+            }
+        ],
+        "usage": {"prompt_tokens": 12, "completion_tokens": 4, "total_tokens": 16},
+    }
+
+
+class _StubHandler(BaseHTTPRequestHandler):
+    def log_message(self, *args: Any) -> None:  # silence the stub
+        pass
+
+    def _send(self, code: int, payload: dict[str, Any]) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler API
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length) if length else b"{}"
+        try:
+            payload = json.loads(raw or b"{}")
+        except json.JSONDecodeError:
+            payload = {}
+        if self.path.endswith("/chat/completions"):
+            self._send(200, _completion(payload.get("messages") or []))
+        elif self.path.endswith("/verify/patch"):
+            self._send(
+                200,
+                {
+                    "verdict": "pass",
+                    "issues": [],
+                    "confidence": 1.0,
+                    "parse_ok": True,
+                    "executed": False,
+                },
+            )
+        else:
+            self._send(404, {"error": "stub: unknown path", "path": self.path})
+
+
+def start_stub_server() -> tuple[ThreadingHTTPServer, str]:
+    """Return a running in-process SID stub and its base URL."""
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _StubHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    host, port = server.server_address
+    return server, f"http://{host}:{port}"
+
+
+def run_selftest(
+    *, receipt_path: str | Path | None = None, directory: str | Path | None = None
+) -> RunOutcome:
+    """Drive one loop turn against a local stub and write a run receipt."""
+    server, base_url = start_stub_server()
+    temp_dir: tempfile.TemporaryDirectory[str] | None = None
+    try:
+        if directory is None:
+            temp_dir = tempfile.TemporaryDirectory(prefix="sid-harness-selftest-")
+            root = Path(temp_dir.name)
+            (root / "notes.txt").write_text("start\n", encoding="utf-8")
+        else:
+            root = Path(directory)
+        client = SIDClient(
+            base_url=base_url, routing_profile="agent", api_key=SELFTEST_KEY
+        )
+        return execute_run(
+            task="Create greeting.txt with a hello message.",
+            directory=root,
+            client=client,
+            model="auto",
+            criteria=["greeting.txt contains a hello message."],
+            out_of_scope=["Do not add any other files."],
+            verify=True,
+            receipt_path=receipt_path,
+        )
+    finally:
+        server.shutdown()
+        server.server_close()
+        if temp_dir is not None:
+            temp_dir.cleanup()

sid_harness/session/__init__.py

@@ -0,0 +1,33 @@
+"""SID local session UX (SUB-58).
+
+Durable local sessions for the first-party harness: resume/replay, a clean
+interrupt that writes a durable receipt, an approve-before-apply diff gate, and
+loop bounds that are configurable (defaults are the shared native loop's
+constants — this package never removes them).
+
+The session record lives at ``<dir>/.sid/sessions/<session_id>.json`` and its
+runs are the harness's EXISTING receipts at ``<dir>/.sid/runs/<run_id>.json`` —
+one receipt format (the LQ-573 shape), not two. No multi-user, no remote.
+"""
+
+from __future__ import annotations
+
+from .bounds import BoundsError, SessionBounds
+from .diff_gate import Approver, DiffProposal, DiffReview, build_review
+from .session import Session, SessionError, SessionOutcome
+from .store import SessionStore, SessionStoreError, new_session_id
+
+__all__ = [
+    "Approver",
+    "BoundsError",
+    "DiffProposal",
+    "DiffReview",
+    "Session",
+    "SessionBounds",
+    "SessionError",
+    "SessionOutcome",
+    "SessionStore",
+    "SessionStoreError",
+    "build_review",
+    "new_session_id",
+]

sid_harness/session/bounds.py

@@ -0,0 +1,140 @@
+"""Configurable loop bounds (SUB-58).
+
+The native loop's ceilings (turns, tool calls, output size, workspace size) are
+parameters of ``native_agent.run_native_agent`` that default to the module
+constants in ``infra/sid-gateway/app/native_agent.py``. Those constants are kept
+and never removed — this module only lets a session override them per run, from
+an optional JSON config file, environment variables, or explicit overrides.
+
+Precedence (lowest to highest): module defaults → environment → config file →
+explicit overrides.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from sid_harness.gateway import native_agent
+
+# Environment names are stable, documented config — not a vendor/model.
+_ENV_KEYS = {
+    "SID_MAX_TURNS": "max_turns",
+    "SID_MAX_TOOL_CALLS": "max_tool_calls",
+    "SID_MAX_TOOL_OUTPUT_CHARS": "max_tool_output_chars",
+    "SID_MAX_FILES": "max_files",
+    "SID_MAX_WORKSPACE_BYTES": "max_workspace_bytes",
+    "SID_MAX_FILE_BYTES": "max_file_bytes",
+}
+
+_FIELDS = tuple(_ENV_KEYS.values())
+
+
+class BoundsError(ValueError):
+    """A bounds value was unknown or not a positive integer."""
+
+
+def _coerce_int(name: str, value: Any) -> int:
+    if isinstance(value, bool):
+        raise BoundsError(f"bounds.{name} must be a positive integer, got a boolean")
+    if isinstance(value, int):
+        number = value
+    elif isinstance(value, str) and value.strip().isdigit():
+        number = int(value.strip())
+    else:
+        raise BoundsError(f"bounds.{name} must be a positive integer, got {value!r}")
+    if number <= 0:
+        raise BoundsError(f"bounds.{name} must be positive, got {number}")
+    return number
+
+
+@dataclass(frozen=True)
+class SessionBounds:
+    """Overridable ceilings for one session's runs (defaults = native constants)."""
+
+    max_turns: int = native_agent.MAX_TURNS
+    max_tool_calls: int = native_agent.MAX_TOOL_CALLS
+    max_tool_output_chars: int = native_agent.MAX_TOOL_OUTPUT_CHARS
+    max_files: int = native_agent.MAX_FILES
+    max_workspace_bytes: int = native_agent.MAX_WORKSPACE_BYTES
+    max_file_bytes: int = native_agent.MAX_FILE_BYTES
+
+    def as_dict(self) -> dict[str, int]:
+        return {name: getattr(self, name) for name in _FIELDS}
+
+    def to_native_kwargs(self) -> dict[str, int]:
+        """Keyword arguments accepted by ``native_agent.run_native_agent``."""
+        return self.as_dict()
+
+    @classmethod
+    def defaults(cls) -> "SessionBounds":
+        return cls()
+
+    @classmethod
+    def from_mapping(
+        cls, data: Mapping[str, Any], *, base: "SessionBounds | None" = None
+    ) -> "SessionBounds":
+        start = base or cls()
+        unknown = set(data) - set(_FIELDS)
+        if unknown:
+            raise BoundsError(
+                "unknown bound(s): " + ", ".join(sorted(unknown))
+            )
+        updates = {name: _coerce_int(name, data[name]) for name in data}
+        return replace(start, **updates)
+
+    @classmethod
+    def from_file(
+        cls, path: str | os.PathLike[str], *, base: "SessionBounds | None" = None
+    ) -> "SessionBounds":
+        target = Path(path).expanduser()
+        if not target.is_file():
+            raise BoundsError(f"bounds config not found: {target}")
+        try:
+            data = json.loads(target.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise BoundsError(f"bounds config is not valid JSON: {target}: {exc}") from exc
+        if not isinstance(data, Mapping):
+            raise BoundsError("bounds config must be a JSON object")
+        return cls.from_mapping(data, base=base)
+
+    @classmethod
+    def from_env(
+        cls,
+        environ: Mapping[str, str] | None = None,
+        *,
+        base: "SessionBounds | None" = None,
+    ) -> "SessionBounds":
+        env = environ if environ is not None else os.environ
+        present = {
+            field: env[var]
+            for var, field in _ENV_KEYS.items()
+            if env.get(var) not in (None, "")
+        }
+        if not present:
+            return base or cls()
+        return cls.from_mapping(present, base=base)
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        config_path: str | os.PathLike[str] | None = None,
+        overrides: Mapping[str, Any] | None = None,
+        environ: Mapping[str, str] | None = None,
+        base: "SessionBounds | None" = None,
+    ) -> "SessionBounds":
+        """Compose environment → config file → explicit overrides onto defaults."""
+        bounds = cls.from_env(environ, base=base or cls())
+        if config_path is not None:
+            bounds = cls.from_file(config_path, base=bounds)
+        if overrides:
+            bounds = cls.from_mapping(overrides, base=bounds)
+        return bounds
+
+
+__all__ = ["BoundsError", "SessionBounds"]

sid_harness/session/diff_gate.py

@@ -0,0 +1,93 @@
+"""Approve-before-apply diff gate (SUB-58).
+
+A run may produce a diff. Applying it to the user's real working tree is gated:
+the caller receives the diff and the changed paths and must approve before any
+write happens. The default is DENY — no approver, a falsy decision, an approver
+that raises, or a read-only run all refuse the apply and say why.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class DiffProposal:
+    """What the approver is asked to accept: the diff and the changed paths."""
+
+    diff: str | None
+    changed: list[str]
+
+    def render(self) -> str:
+        header = "changed: " + (", ".join(self.changed) or "(none)")
+        if not self.diff:
+            return header
+        return f"{header}\n\n{self.diff}"
+
+
+@dataclass(frozen=True)
+class DiffReview:
+    """The gate's decision, recorded on the run receipt."""
+
+    diff: str | None
+    changed: list[str]
+    approved: bool
+    reason: str
+    reviewed_by: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "approved": self.approved,
+            "reason": self.reason,
+            "changed": list(self.changed),
+            "reviewed_by": self.reviewed_by,
+            "has_diff": bool(self.diff),
+        }
+
+
+Approver = Callable[[DiffProposal], bool]
+
+
+def build_review(
+    result: dict[str, Any],
+    *,
+    approve: Approver | None = None,
+    reviewer: str | None = None,
+    requested: bool = True,
+) -> DiffReview:
+    """Decide whether the run's changes may be applied to the real tree."""
+    diff = result.get("diff")
+    changed = list(result.get("changed") or [])
+    proposal = DiffProposal(diff=diff, changed=list(changed))
+
+    if not requested:
+        return DiffReview(
+            diff, list(changed), approved=False, reason="write not requested", reviewed_by=reviewer
+        )
+    if not changed:
+        return DiffReview(diff, list(changed), approved=True, reason="no changes to apply", reviewed_by=reviewer)
+    if approve is None:
+        return DiffReview(
+            diff,
+            list(changed),
+            approved=False,
+            reason="no approver provided; changes not applied (fail closed)",
+            reviewed_by=reviewer,
+        )
+    try:
+        approved = bool(approve(proposal))
+    except Exception as exc:  # a broken approver must never silently apply
+        return DiffReview(
+            diff,
+            list(changed),
+            approved=False,
+            reason=f"approver raised {type(exc).__name__}: {exc}",
+            reviewed_by=reviewer,
+        )
+    reason = "approved by reviewer" if approved else "rejected by reviewer"
+    return DiffReview(diff, list(changed), approved=approved, reason=reason, reviewed_by=reviewer)
+
+
+__all__ = ["Approver", "DiffProposal", "DiffReview", "build_review"]