sdxloop-worker 0.1.0__py3-none-any.whl

sdxloop_worker/__init__.py

@@ -0,0 +1,10 @@
+"""sdxloop-worker — the in-sandbox runtime for sdxloop.
+
+Runs inside a Docker Sandbox microVM. Hosts the shared host/worker protocol
+models, the agent backends (GitHub Copilot SDK), and the job runner invoked
+via ``python -m sdxloop_worker``.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

sdxloop_worker/__main__.py

@@ -0,0 +1,89 @@
+"""Worker entry point: ``python -m sdxloop_worker run --job J --events E --result R``.
+
+Exit codes: 0 when a result file was written (including error/timeout
+results — the result file is the outcome channel); 64 for usage errors;
+70 when the result could not be produced at all.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shlex
+import sys
+from pathlib import Path
+
+from sdxloop_worker.protocol import JobRequest
+from sdxloop_worker.runner import JobRunner
+
+DEFAULT_ENV_FILE = Path.home() / ".sdxloop" / "env.sh"
+
+_EXPORT_RE = re.compile(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+
+def load_env_file(path: Path) -> dict[str, str]:
+    """Parse ``export KEY=VALUE`` lines (shell-quoted values supported).
+
+    Used by the plain-env secret strategy: the provisioner writes tokens to
+    ``~/.sdxloop/env.sh`` and the worker loads them at startup. Existing
+    process environment always wins.
+    """
+    loaded: dict[str, str] = {}
+    if not path.is_file():
+        return loaded
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = _EXPORT_RE.match(line)
+        if not match:
+            continue
+        key, raw = match.groups()
+        try:
+            parts = shlex.split(raw)
+        except ValueError:
+            continue
+        loaded[key] = parts[0] if parts else ""
+    return loaded
+
+
+def apply_env_file(path: Path) -> None:
+    for key, value in load_env_file(path).items():
+        os.environ.setdefault(key, value)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sdxloop_worker")
+    sub = parser.add_subparsers(dest="command", required=True)
+    run = sub.add_parser("run", help="run one job")
+    run.add_argument("--job", required=True, type=Path)
+    run.add_argument("--events", required=True, type=Path)
+    run.add_argument("--result", required=True, type=Path)
+    run.add_argument("--heartbeat", type=float, default=15.0)
+    run.add_argument("--env-file", type=Path, default=DEFAULT_ENV_FILE)
+    args = parser.parse_args(argv)
+
+    apply_env_file(args.env_file)
+
+    try:
+        job = JobRequest.model_validate_json(args.job.read_text())
+    except (OSError, ValueError) as exc:
+        print(f"sdxloop_worker: invalid job file {args.job}: {exc}", file=sys.stderr)
+        return 64
+
+    try:
+        JobRunner(
+            job,
+            events_path=args.events,
+            result_path=args.result,
+            heartbeat_s=args.heartbeat,
+        ).run()
+    except BaseException as exc:
+        print(f"sdxloop_worker: fatal: {exc}", file=sys.stderr)
+        return 70
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sdxloop_worker/_json.py

@@ -0,0 +1,29 @@
+"""Extraction of structured JSON from agent output text."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_FENCE_RE = re.compile(r"```(?:json)?\s*\n(.*?)```", re.DOTALL)
+
+
+def extract_json(text: str) -> dict[str, Any] | list[Any] | None:
+    """Pull a JSON object/array out of agent output.
+
+    Preference order: the last fenced ``json`` block (agents often narrate
+    before the final answer), then the whole text. Returns None when nothing
+    parses to a dict or list.
+    """
+    candidates = [match.group(1) for match in _FENCE_RE.finditer(text)]
+    candidates.reverse()
+    candidates.append(text)
+    for candidate in candidates:
+        try:
+            value = json.loads(candidate.strip())
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict | list):
+            return value
+    return None

sdxloop_worker/backends/__init__.py

@@ -0,0 +1,48 @@
+"""Agent backends: the pluggable engine that runs one agent session."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from sdxloop_worker.protocol import Event, JobRequest, Usage
+
+# emit("agent.message", content="...") -> Event
+EmitFn = Callable[..., Event]
+
+BACKEND_ENV = "SDXLOOP_WORKER_BACKEND"
+
+
+class BackendUnavailableError(RuntimeError):
+    """The requested backend cannot run in this environment."""
+
+
+@dataclass
+class BackendResult:
+    output_text: str = ""
+    output_json: dict[str, Any] | list[Any] | None = None
+    session_id: str | None = None
+    usage: Usage | None = None
+    artifacts: list[str] = field(default_factory=list)
+
+
+class AgentBackend(Protocol):
+    name: str
+
+    def run_session(self, job: JobRequest, emit: EmitFn) -> BackendResult: ...
+
+
+def get_backend(name: str | None = None) -> AgentBackend:
+    """Resolve a backend by name (default: $SDXLOOP_WORKER_BACKEND or copilot)."""
+    resolved = name or os.environ.get(BACKEND_ENV) or "copilot"
+    if resolved == "echo":
+        from sdxloop_worker.backends.echo import EchoBackend
+
+        return EchoBackend()
+    if resolved == "copilot":
+        from sdxloop_worker.backends.copilot import CopilotBackend
+
+        return CopilotBackend()
+    raise BackendUnavailableError(f"unknown agent backend {resolved!r}")

sdxloop_worker/backends/copilot.py

@@ -0,0 +1,151 @@
+"""GitHub Copilot SDK backend.
+
+Runs one agentic session inside the sandbox via the ``github-copilot-sdk``
+package (installed with the ``[copilot]`` extra; wheels bundle the Copilot
+CLI runtime). Imports are deferred so the worker package works without the
+SDK for shell/github jobs and for test environments.
+
+Auth: the SDK auto-detects ``COPILOT_GITHUB_TOKEN``, which the sdxloop
+provisioner injects into the agent sandbox (proxy-bound to the Copilot API
+hosts under the default secret strategy).
+
+This module is exercised by the real-sbx e2e workflow rather than unit
+tests (it needs the SDK runtime + a Copilot subscription), and is excluded
+from unit coverage accordingly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from sdxloop_worker._json import extract_json
+from sdxloop_worker.backends import BackendResult, BackendUnavailableError, EmitFn
+from sdxloop_worker.protocol import EventTypes, JobRequest, Usage
+
+READ_ONLY_DENIED_KINDS = {"shell", "write"}
+
+
+class CopilotBackend:
+    name = "copilot"
+
+    def run_session(self, job: JobRequest, emit: EmitFn) -> BackendResult:
+        try:
+            import copilot  # noqa: F401
+        except ImportError as exc:
+            raise BackendUnavailableError(
+                "github-copilot-sdk is not installed; install sdxloop-worker[copilot]"
+            ) from exc
+        return asyncio.run(self._run(job, emit))
+
+    async def _run(self, job: JobRequest, emit: EmitFn) -> BackendResult:
+        from copilot import CopilotClient
+
+        usage = Usage()
+        final_text: list[str] = []
+
+        def on_event(event: Any) -> None:
+            nonlocal usage
+            data = getattr(event, "data", None)
+            type_name = type(data).__name__ if data is not None else type(event).__name__
+            if type_name == "AssistantMessageDeltaData":
+                emit(
+                    EventTypes.AGENT_MESSAGE_DELTA,
+                    delta=getattr(data, "delta_content", "") or "",
+                )
+            elif type_name == "AssistantMessageData":
+                content = getattr(data, "content", "") or ""
+                if content:
+                    final_text.append(content)
+                emit(EventTypes.AGENT_MESSAGE, content=content)
+            elif type_name.startswith("ToolExecutionStart"):
+                emit(
+                    EventTypes.AGENT_TOOL_START,
+                    tool=getattr(data, "tool_name", None) or getattr(data, "toolName", None),
+                    tool_call_id=getattr(data, "tool_call_id", None)
+                    or getattr(data, "toolCallId", None),
+                )
+            elif type_name.startswith("ToolExecutionComplete"):
+                emit(
+                    EventTypes.AGENT_TOOL_END,
+                    tool_call_id=getattr(data, "tool_call_id", None)
+                    or getattr(data, "toolCallId", None),
+                    success=getattr(data, "success", None),
+                )
+            elif type_name == "AssistantUsageData":
+                sample = Usage(
+                    model=getattr(data, "model", None),
+                    input_tokens=getattr(data, "input_tokens", None)
+                    or getattr(data, "inputTokens", None),
+                    output_tokens=getattr(data, "output_tokens", None)
+                    or getattr(data, "outputTokens", None),
+                )
+                usage = usage.merged(sample)
+                emit(EventTypes.AGENT_USAGE, **sample.model_dump(exclude_none=True))
+
+        async with CopilotClient() as client:
+            session = await self._open_session(client, job)
+            try:
+                session.on(on_event)
+                assert job.prompt is not None
+                response = await session.send_and_wait(job.prompt, timeout=job.timeout_s)
+                text = self._response_text(response) or "\n".join(final_text)
+                output_json = extract_json(text) if job.expect == "json" else None
+                session_id = getattr(session, "session_id", None) or getattr(session, "id", None)
+                return BackendResult(
+                    output_text=text,
+                    output_json=output_json,
+                    session_id=session_id,
+                    usage=usage if usage != Usage() else None,
+                )
+            finally:
+                await self._close_session(session)
+
+    async def _open_session(self, client: Any, job: JobRequest) -> Any:
+        kwargs: dict[str, Any] = {
+            "on_permission_request": self._permission_handler(job),
+            "streaming": True,
+        }
+        if job.model and job.model != "auto":
+            kwargs["model"] = job.model
+        if job.system_message:
+            kwargs["system_message"] = {"mode": "append", "content": job.system_message}
+        if job.resume_session_id:
+            return await client.resume_session(job.resume_session_id, **kwargs)
+        return await client.create_session(**kwargs)
+
+    def _permission_handler(self, job: JobRequest) -> Any:
+        if job.permission_mode == "auto":
+            # The microVM (network policy + secret proxy) is the security
+            # boundary; inside it the agent runs unattended.
+            from copilot.session import PermissionHandler
+
+            return PermissionHandler.approve_all
+
+        def read_only_handler(request: Any, invocation: Any = None) -> Any:
+            from copilot.rpc import PermissionDecisionApproveOnce, PermissionDecisionReject
+
+            kind = getattr(request, "kind", None)
+            if kind in READ_ONLY_DENIED_KINDS:
+                return PermissionDecisionReject(
+                    feedback="this is a read-only review session; do not modify anything"
+                )
+            return PermissionDecisionApproveOnce()
+
+        return read_only_handler
+
+    @staticmethod
+    def _response_text(response: Any) -> str:
+        data = getattr(response, "data", None)
+        return getattr(data, "content", None) or getattr(response, "content", None) or ""
+
+    @staticmethod
+    async def _close_session(session: Any) -> None:
+        disconnect = getattr(session, "disconnect", None)
+        if disconnect is not None:
+            try:
+                result = disconnect()
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                pass

sdxloop_worker/backends/echo.py

@@ -0,0 +1,89 @@
+"""Deterministic test backend.
+
+Without a script it echoes the prompt. With ``SDXLOOP_ECHO_SCRIPT`` pointing
+at a JSON file (a list of response objects), responses are consumed in order
+— across worker processes — via a sidecar ``<script>.state`` cursor file, so
+multi-job engine tests can script an entire run.
+
+Response object shape (all fields optional):
+``{"text": str, "json": dict|list, "session_id": str, "sleep_s": float,
+"events": [{"type": str, "data": {...}}], "fail": str}``
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from sdxloop_worker._json import extract_json
+from sdxloop_worker.backends import BackendResult, EmitFn
+from sdxloop_worker.protocol import EventTypes, JobRequest, Usage
+
+SCRIPT_ENV = "SDXLOOP_ECHO_SCRIPT"
+
+
+class EchoBackend:
+    name = "echo"
+
+    def run_session(self, job: JobRequest, emit: EmitFn) -> BackendResult:
+        scripted = self._next_scripted_response()
+        if scripted is None:
+            return self._echo(job, emit)
+        return self._scripted(job, emit, scripted)
+
+    # -- default echo mode -------------------------------------------------
+
+    def _echo(self, job: JobRequest, emit: EmitFn) -> BackendResult:
+        assert job.prompt is not None
+        text = f"echo: {job.prompt}"
+        emit(EventTypes.AGENT_MESSAGE, content=text)
+        output_json = {"echo": job.prompt} if job.expect == "json" else None
+        return BackendResult(
+            output_text=text,
+            output_json=output_json,
+            session_id=f"echo-{job.job_id}",
+            usage=Usage(model="echo", input_tokens=len(job.prompt.split()), output_tokens=2),
+        )
+
+    # -- scripted mode -----------------------------------------------------
+
+    def _next_scripted_response(self) -> dict[str, Any] | None:
+        raw = os.environ.get(SCRIPT_ENV)
+        if not raw:
+            return None
+        script_path = Path(raw)
+        responses = json.loads(script_path.read_text())
+        state_path = script_path.with_suffix(script_path.suffix + ".state")
+        cursor = int(state_path.read_text()) if state_path.is_file() else 0
+        if cursor >= len(responses):
+            raise RuntimeError(
+                f"echo script exhausted: {cursor} responses consumed, job wanted one more"
+            )
+        state_path.write_text(str(cursor + 1))
+        response = responses[cursor]
+        if not isinstance(response, dict):
+            raise TypeError(f"echo script entry {cursor} must be an object")
+        return response
+
+    def _scripted(self, job: JobRequest, emit: EmitFn, response: dict[str, Any]) -> BackendResult:
+        if "fail" in response:
+            raise RuntimeError(str(response["fail"]))
+        if sleep_s := float(response.get("sleep_s", 0)):
+            time.sleep(sleep_s)
+        for scripted_event in response.get("events", []):
+            emit(scripted_event["type"], **scripted_event.get("data", {}))
+        text = str(response.get("text", ""))
+        if text:
+            emit(EventTypes.AGENT_MESSAGE, content=text)
+        output_json = response.get("json")
+        if output_json is None and job.expect == "json":
+            output_json = extract_json(text)
+        return BackendResult(
+            output_text=text,
+            output_json=output_json,
+            session_id=str(response.get("session_id", f"echo-{job.job_id}")),
+            usage=Usage(model="echo"),
+        )

sdxloop_worker/events.py

@@ -0,0 +1,61 @@
+"""Worker-side event emission: JSONL file (durable) + stdout mirror (live)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from types import TracebackType
+from typing import Any, TextIO
+
+from sdxloop_worker.protocol import Event
+
+
+class EventWriter:
+    """Appends events to a JSONL file (fsync per line) and mirrors to stdout.
+
+    The file is the durable record the host can always recover with ``cp``;
+    the stdout mirror is the live telemetry channel when the host streams
+    ``sbx exec`` output. Either channel may be lost independently — the
+    result file, not events, is the source of truth for job outcomes.
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        run_id: str,
+        job_id: str | None = None,
+        mirror: TextIO | None = None,
+    ) -> None:
+        self.run_id = run_id
+        self.job_id = job_id
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._file: TextIO | None = path.open("a", encoding="utf-8")
+        self._mirror = sys.stdout if mirror is None else mirror
+
+    def emit(self, type: str, **data: Any) -> Event:
+        event = Event.now(type, self.run_id, job_id=self.job_id, **data)
+        line = event.to_json_line()
+        if self._file is not None:
+            self._file.write(line + "\n")
+            self._file.flush()
+            os.fsync(self._file.fileno())
+        if self._mirror is not None:
+            print(line, file=self._mirror, flush=True)
+        return event
+
+    def close(self) -> None:
+        if self._file is not None:
+            self._file.close()
+            self._file = None
+
+    def __enter__(self) -> EventWriter:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()

sdxloop_worker/githubops.py

@@ -0,0 +1,245 @@
+"""GitHub operations executed inside the github-ops sandbox.
+
+Every operation is expressed as a GitHub REST call and executed through one
+of two transports:
+
+- **gh CLI** (preferred when present): ``gh api`` — inherits `GH_TOKEN`
+  handling, retries, and pagination behavior from gh.
+- **urllib REST** (mandatory fallback): the sandbox `shell` template does not
+  guarantee gh, so a pure-stdlib client using ``GH_TOKEN``/``GITHUB_TOKEN``
+  directly is required, not optional polish.
+
+The op registry maps stable sdxloop op names (``issue.create``, ...) to
+request builders + response shapers, so both transports produce identical
+results for the host.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import subprocess
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from typing import Any, Protocol
+
+API_ROOT = "https://api.github.com"
+API_VERSION = "2022-11-28"
+
+JsonValue = dict[str, Any] | list[Any]
+
+
+class GithubOpError(RuntimeError):
+    """A GitHub operation failed (bad op, transport error, HTTP error)."""
+
+
+class Transport(Protocol):
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> JsonValue: ...
+
+
+class GhCliTransport:
+    """Executes REST calls through ``gh api``."""
+
+    def __init__(self, gh: str = "gh") -> None:
+        self.gh = gh
+
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> JsonValue:
+        argv = [
+            self.gh,
+            "api",
+            "-X",
+            method,
+            "-H",
+            f"X-GitHub-Api-Version: {API_VERSION}",
+            path,
+        ]
+        stdin: str | None = None
+        if body is not None:
+            argv += ["--input", "-"]
+            stdin = json.dumps(body)
+        proc = subprocess.run(
+            argv, capture_output=True, text=True, input=stdin, timeout=120, check=False
+        )
+        if proc.returncode != 0:
+            raise GithubOpError(
+                f"gh api {method} {path} failed (rc={proc.returncode}): "
+                f"{proc.stderr.strip()[:2000]}"
+            )
+        if not proc.stdout.strip():
+            return {}
+        parsed: JsonValue = json.loads(proc.stdout)
+        return parsed
+
+
+class RestTransport:
+    """Pure-stdlib GitHub REST client using the injected token."""
+
+    def __init__(self, token: str | None = None) -> None:
+        self.token = token or os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+        if not self.token:
+            raise GithubOpError(
+                "no GitHub token available: GH_TOKEN/GITHUB_TOKEN are not set and gh is absent"
+            )
+
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> JsonValue:
+        url = path if path.startswith("http") else f"{API_ROOT}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": API_VERSION,
+                "User-Agent": "sdxloop-worker",
+                **({"Content-Type": "application/json"} if data else {}),
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=60) as response:
+                raw = response.read().decode()
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode(errors="replace")[:2000]
+            raise GithubOpError(f"{method} {url} -> HTTP {exc.code}: {detail}") from exc
+        except urllib.error.URLError as exc:
+            raise GithubOpError(f"{method} {url} failed: {exc.reason}") from exc
+        if not raw.strip():
+            return {}
+        parsed: JsonValue = json.loads(raw)
+        return parsed
+
+
+def select_transport() -> Transport:
+    if shutil.which("gh"):
+        return GhCliTransport()
+    return RestTransport()
+
+
+# -- op registry -------------------------------------------------------------
+
+OpImpl = Callable[[Transport, dict[str, Any]], JsonValue]
+
+
+def _require(params: dict[str, Any], *names: str) -> None:
+    missing = [n for n in names if not params.get(n)]
+    if missing:
+        raise GithubOpError(f"missing required params: {', '.join(missing)}")
+
+
+def _issue_create(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo", "title")
+    body: dict[str, Any] = {"title": p["title"]}
+    if p.get("body"):
+        body["body"] = p["body"]
+    if p.get("labels"):
+        body["labels"] = p["labels"]
+    data = t.request("POST", f"/repos/{p['repo']}/issues", body)
+    assert isinstance(data, dict)
+    return {"number": data.get("number"), "url": data.get("html_url")}
+
+
+def _issue_comment(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo", "number", "body")
+    data = t.request(
+        "POST", f"/repos/{p['repo']}/issues/{p['number']}/comments", {"body": p["body"]}
+    )
+    assert isinstance(data, dict)
+    return {"url": data.get("html_url")}
+
+
+def _pr_create(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo", "base", "head", "title")
+    body: dict[str, Any] = {"title": p["title"], "base": p["base"], "head": p["head"]}
+    if p.get("body"):
+        body["body"] = p["body"]
+    if p.get("draft"):
+        body["draft"] = True
+    data = t.request("POST", f"/repos/{p['repo']}/pulls", body)
+    assert isinstance(data, dict)
+    return {"number": data.get("number"), "url": data.get("html_url")}
+
+
+def _contents_read(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo", "path")
+    path = f"/repos/{p['repo']}/contents/{p['path']}"
+    if p.get("ref"):
+        path += f"?ref={urllib.parse.quote(str(p['ref']))}"
+    data = t.request("GET", path)
+    assert isinstance(data, dict)
+    result: dict[str, Any] = {"path": data.get("path"), "sha": data.get("sha")}
+    if data.get("encoding") == "base64" and isinstance(data.get("content"), str):
+        raw = base64.b64decode(data["content"])
+        try:
+            result["content"] = raw.decode("utf-8")
+            result["binary"] = False
+        except UnicodeDecodeError:
+            result["content"] = base64.b64encode(raw).decode()
+            result["binary"] = True
+    else:
+        result["content"] = data.get("content")
+        result["binary"] = False
+    return result
+
+
+def _status_create(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo", "sha", "state")
+    body = {
+        "state": p["state"],
+        "context": p.get("context", "sdxloop"),
+    }
+    if p.get("description"):
+        body["description"] = p["description"]
+    if p.get("target_url"):
+        body["target_url"] = p["target_url"]
+    data = t.request("POST", f"/repos/{p['repo']}/statuses/{p['sha']}", body)
+    assert isinstance(data, dict)
+    return {"id": data.get("id"), "state": data.get("state")}
+
+
+def _repo_get(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "repo")
+    return t.request("GET", f"/repos/{p['repo']}")
+
+
+def _search_issues(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "query")
+    query = urllib.parse.quote(str(p["query"]))
+    per_page = int(p.get("per_page", 30))
+    data = t.request("GET", f"/search/issues?q={query}&per_page={per_page}")
+    assert isinstance(data, dict)
+    items = data.get("items", [])
+    return items if isinstance(items, list) else []
+
+
+def _raw_api(t: Transport, p: dict[str, Any]) -> JsonValue:
+    _require(p, "method", "path")
+    return t.request(str(p["method"]).upper(), str(p["path"]), p.get("body"))
+
+
+OPS: dict[str, OpImpl] = {
+    "issue.create": _issue_create,
+    "issue.comment": _issue_comment,
+    "pr.create": _pr_create,
+    "pr.comment": _issue_comment,  # PR comments go through the issues API
+    "contents.read": _contents_read,
+    "status.create": _status_create,
+    "repo.get": _repo_get,
+    "search.issues": _search_issues,
+    "raw.api": _raw_api,
+}
+
+
+def execute_op(
+    op: str,
+    params: dict[str, Any],
+    transport: Transport | None = None,
+) -> JsonValue:
+    impl = OPS.get(op)
+    if impl is None:
+        raise GithubOpError(f"unknown github op {op!r}; known: {', '.join(sorted(OPS))}")
+    return impl(transport or select_transport(), params)

sdxloop_worker/protocol.py

@@ -0,0 +1,191 @@
+"""Shared host/worker protocol models.
+
+These models are the contract between the sdxloop host orchestrator and the
+in-sandbox worker. Both sides import this exact module (the host depends on
+``sdxloop-worker``), so drift is a type error rather than a runtime surprise.
+
+Every object carries a protocol version ``v``; host and worker versions are
+kept in lockstep, so models reject unknown fields outright.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+PROTOCOL_VERSION = 1
+
+JobKind = Literal["agent.session", "shell.check", "github.op"]
+JobStatus = Literal["ok", "error", "timeout"]
+PermissionMode = Literal["auto", "read_only"]
+ExpectMode = Literal["text", "json"]
+
+
+class ProtocolModel(BaseModel):
+    """Base for all wire models: strict, no silent extra fields."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Usage(ProtocolModel):
+    """Model/token usage reported by an agent backend for one job."""
+
+    model: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    cost: float | None = None
+
+    def merged(self, other: Usage) -> Usage:
+        """Accumulate another usage sample into this one (None-safe sums)."""
+
+        def add(a: int | None, b: int | None) -> int | None:
+            if a is None and b is None:
+                return None
+            return (a or 0) + (b or 0)
+
+        cost: float | None = None
+        if self.cost is not None or other.cost is not None:
+            cost = (self.cost or 0.0) + (other.cost or 0.0)
+        return Usage(
+            model=other.model or self.model,
+            input_tokens=add(self.input_tokens, other.input_tokens),
+            output_tokens=add(self.output_tokens, other.output_tokens),
+            cache_read_tokens=add(self.cache_read_tokens, other.cache_read_tokens),
+            cache_write_tokens=add(self.cache_write_tokens, other.cache_write_tokens),
+            cost=cost,
+        )
+
+
+class ErrorInfo(ProtocolModel):
+    """Structured error carried in a JobResult or error event."""
+
+    type: str
+    message: str
+    detail: str | None = None
+
+
+class JobRequest(ProtocolModel):
+    """One unit of work the host submits to a worker.
+
+    Exactly one job kind is used per request; kind-specific fields for other
+    kinds must be left at their defaults (validated below).
+    """
+
+    v: int = PROTOCOL_VERSION
+    job_id: str
+    run_id: str
+    kind: JobKind
+    timeout_s: float = 900.0
+
+    # kind == "agent.session"
+    prompt: str | None = None
+    system_message: str | None = None
+    model: str | None = None
+    resume_session_id: str | None = None
+    permission_mode: PermissionMode = "auto"
+    expect: ExpectMode = "text"
+
+    # kind == "shell.check"
+    argv: list[str] | None = None
+    cwd: str | None = None
+
+    # kind == "github.op"
+    op: str | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _check_kind_fields(self) -> JobRequest:
+        if self.kind == "agent.session":
+            if not self.prompt:
+                raise ValueError("agent.session requires a non-empty prompt")
+            if self.argv is not None or self.op is not None:
+                raise ValueError("agent.session must not set argv or op")
+        elif self.kind == "shell.check":
+            if not self.argv:
+                raise ValueError("shell.check requires a non-empty argv")
+            if self.prompt is not None or self.op is not None:
+                raise ValueError("shell.check must not set prompt or op")
+        elif self.kind == "github.op":
+            if not self.op:
+                raise ValueError("github.op requires an op name")
+            if self.prompt is not None or self.argv is not None:
+                raise ValueError("github.op must not set prompt or argv")
+        return self
+
+
+class JobResult(ProtocolModel):
+    """Authoritative outcome of a job, written to the result file by the worker.
+
+    The event stream is best-effort telemetry; this file is the source of truth.
+    """
+
+    v: int = PROTOCOL_VERSION
+    job_id: str
+    status: JobStatus
+    output_text: str | None = None
+    output_json: dict[str, Any] | list[Any] | None = None
+    session_id: str | None = None
+    usage: Usage | None = None
+    exit_code: int | None = None
+    error: ErrorInfo | None = None
+    artifacts: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_status(self) -> JobResult:
+        if self.status != "ok" and self.error is None:
+            raise ValueError(f"status={self.status!r} requires an error")
+        return self
+
+
+class Event(ProtocolModel):
+    """One line of the JSONL event stream (worker- or host-emitted)."""
+
+    v: int = PROTOCOL_VERSION
+    ts: float
+    run_id: str
+    job_id: str | None = None
+    type: str
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def now(
+        cls,
+        type: str,
+        run_id: str,
+        job_id: str | None = None,
+        **data: Any,
+    ) -> Event:
+        return cls(ts=time.time(), run_id=run_id, job_id=job_id, type=type, data=data)
+
+    def to_json_line(self) -> str:
+        """Serialize to a single JSONL line (no trailing newline)."""
+        return json.dumps(self.model_dump(mode="json"), separators=(",", ":"), sort_keys=True)
+
+    @classmethod
+    def from_json_line(cls, line: str) -> Event:
+        return cls.model_validate(json.loads(line))
+
+
+# Well-known event types. Kept as plain strings on the wire; these constants
+# exist so emitters and consumers share one spelling.
+class EventTypes:
+    WORKER_START = "worker.start"
+    WORKER_HEARTBEAT = "worker.heartbeat"
+    WORKER_STDOUT = "worker.stdout"
+    WORKER_RESULT = "worker.result"
+    WORKER_ERROR = "worker.error"
+    WORKER_END = "worker.end"
+
+    AGENT_MESSAGE = "agent.message"
+    AGENT_MESSAGE_DELTA = "agent.message_delta"
+    AGENT_TOOL_START = "agent.tool_start"
+    AGENT_TOOL_END = "agent.tool_end"
+    AGENT_USAGE = "agent.usage"
+
+    GH_OP_START = "gh.op_start"
+    GH_OP_END = "gh.op_end"

sdxloop_worker/runner.py

@@ -0,0 +1,160 @@
+"""The worker job runner: dispatch one JobRequest, emit events, write the result."""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import traceback
+from pathlib import Path
+
+from sdxloop_worker.backends import get_backend
+from sdxloop_worker.events import EventWriter
+from sdxloop_worker.protocol import ErrorInfo, EventTypes, JobRequest, JobResult
+
+OUTPUT_TAIL_CHARS = 20_000
+
+
+class JobRunner:
+    def __init__(
+        self,
+        job: JobRequest,
+        events_path: Path,
+        result_path: Path,
+        *,
+        heartbeat_s: float = 15.0,
+        backend_name: str | None = None,
+    ) -> None:
+        self.job = job
+        self.events_path = events_path
+        self.result_path = result_path
+        self.heartbeat_s = heartbeat_s
+        self.backend_name = backend_name
+
+    def run(self) -> JobResult:
+        """Execute the job and write the authoritative result file.
+
+        Never raises for job-level failures — they become error results.
+        """
+        with EventWriter(self.events_path, self.job.run_id, self.job.job_id) as writer:
+            heartbeat_stop = self._start_heartbeat(writer)
+            try:
+                writer.emit(EventTypes.WORKER_START, kind=self.job.kind)
+                result = self._dispatch(writer)
+            except subprocess.TimeoutExpired:
+                result = self._error_result("timeout", "Timeout", "job timed out")
+            except BaseException as exc:
+                result = self._error_result(
+                    "error",
+                    type(exc).__name__,
+                    str(exc) or repr(exc),
+                    detail="".join(traceback.format_exception(exc))[-OUTPUT_TAIL_CHARS:],
+                )
+            finally:
+                heartbeat_stop.set()
+
+            self.result_path.parent.mkdir(parents=True, exist_ok=True)
+            self.result_path.write_text(result.model_dump_json())
+            if result.status == "ok":
+                writer.emit(EventTypes.WORKER_RESULT, status=result.status)
+            else:
+                assert result.error is not None
+                writer.emit(
+                    EventTypes.WORKER_ERROR,
+                    status=result.status,
+                    error_type=result.error.type,
+                    message=result.error.message,
+                )
+            writer.emit(EventTypes.WORKER_END)
+            return result
+
+    # -- dispatch ----------------------------------------------------------
+
+    def _dispatch(self, writer: EventWriter) -> JobResult:
+        if self.job.kind == "agent.session":
+            return self._run_agent_session(writer)
+        if self.job.kind == "shell.check":
+            return self._run_shell_check()
+        return self._run_github_op(writer)
+
+    def _run_agent_session(self, writer: EventWriter) -> JobResult:
+        backend = get_backend(self.backend_name)
+        outcome = backend.run_session(self.job, writer.emit)
+        if self.job.expect == "json" and outcome.output_json is None:
+            return self._error_result(
+                "error",
+                "ExpectedJsonMissing",
+                "agent response contained no parseable JSON",
+                detail=outcome.output_text[-OUTPUT_TAIL_CHARS:],
+            )
+        return JobResult(
+            job_id=self.job.job_id,
+            status="ok",
+            output_text=outcome.output_text,
+            output_json=outcome.output_json,
+            session_id=outcome.session_id,
+            usage=outcome.usage,
+            artifacts=outcome.artifacts,
+        )
+
+    def _run_shell_check(self) -> JobResult:
+        assert self.job.argv is not None
+        proc = subprocess.run(
+            self.job.argv,
+            capture_output=True,
+            text=True,
+            cwd=self.job.cwd,
+            timeout=self.job.timeout_s,
+            check=False,
+        )
+        output = proc.stdout + (("\n" + proc.stderr) if proc.stderr else "")
+        # A nonzero inner exit code is still a successful *job*: the engine
+        # inspects exit_code to decide whether verification passed.
+        return JobResult(
+            job_id=self.job.job_id,
+            status="ok",
+            exit_code=proc.returncode,
+            output_text=output[-OUTPUT_TAIL_CHARS:],
+        )
+
+    def _run_github_op(self, writer: EventWriter) -> JobResult:
+        from sdxloop_worker.githubops import execute_op
+
+        assert self.job.op is not None
+        writer.emit(EventTypes.GH_OP_START, op=self.job.op)
+        output = execute_op(self.job.op, self.job.params)
+        writer.emit(EventTypes.GH_OP_END, op=self.job.op)
+        return JobResult(job_id=self.job.job_id, status="ok", output_json=output)
+
+    # -- helpers -----------------------------------------------------------
+
+    def _error_result(
+        self,
+        status: str,
+        type_: str,
+        message: str,
+        detail: str | None = None,
+    ) -> JobResult:
+        return JobResult.model_validate(
+            {
+                "job_id": self.job.job_id,
+                "status": status,
+                "error": ErrorInfo(type=type_, message=message, detail=detail).model_dump(),
+            }
+        )
+
+    def _start_heartbeat(self, writer: EventWriter) -> threading.Event:
+        stop = threading.Event()
+        if self.heartbeat_s <= 0:
+            stop.set()
+            return stop
+
+        def beat() -> None:
+            while not stop.wait(self.heartbeat_s):
+                try:
+                    writer.emit(EventTypes.WORKER_HEARTBEAT)
+                except Exception:  # pragma: no cover - writer closed during shutdown
+                    return
+
+        thread = threading.Thread(target=beat, name="sdxloop-heartbeat", daemon=True)
+        thread.start()
+        return stop

sdxloop_worker-0.1.0.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: sdxloop-worker
+Version: 0.1.0
+Summary: In-sandbox worker runtime for sdxloop (protocol models, agent backends, job runner)
+Project-URL: Homepage, https://github.com/brettbergin/sdxloop
+Project-URL: Repository, https://github.com/brettbergin/sdxloop
+Author: Brett Bergin
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Provides-Extra: copilot
+Requires-Dist: github-copilot-sdk>=1.0.8; extra == 'copilot'
+Description-Content-Type: text/markdown
+
+# sdxloop-worker
+
+The in-sandbox runtime for [sdxloop](https://github.com/brettbergin/sdxloop):
+shared host/worker protocol models, the job runner (`python -m sdxloop_worker`),
+and agent backends. Install with the `copilot` extra inside agent sandboxes:
+
+```bash
+pip install "sdxloop-worker[copilot]"
+```
+
+You normally never install this directly — the sdxloop host package provisions
+it into sandboxes automatically.

sdxloop_worker-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sdxloop_worker/__init__.py,sha256=jW5aIvWS4rTqv3rHAdLJ-ZHl0hMRw7alxYJA-uaq-sU,299
+sdxloop_worker/__main__.py,sha256=Ph5WXKZnJ6sfrUp4vHKtHlrGAPbW9dAsCalSPdsNHDY,2765
+sdxloop_worker/_json.py,sha256=jobk9AMqZOSxzs2n14SPutv6uJfctZ2f6f69bdw-oyg,882
+sdxloop_worker/events.py,sha256=JmVQLCaoobhM4QfyqJ7gE95MI0cfyKyzIC1xs4Bol2E,1875
+sdxloop_worker/githubops.py,sha256=Xm5HROeeSc8d7s_fJIWCkIEuyevuk35QW_yNA22YezE,8382
+sdxloop_worker/protocol.py,sha256=2eFWcBp0Z25Byi5QKN05XpMbkfYI4fY11Oa_b10n72g,6237
+sdxloop_worker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sdxloop_worker/runner.py,sha256=o4-lIJRjA493Gw0NBhHXSf-B47akXtf6MCnqMBQZQak,5778
+sdxloop_worker/backends/__init__.py,sha256=7X8_IjrHMN8Khe5pd3MlNGR4zJFHwXIjcRXVgBNk1vs,1414
+sdxloop_worker/backends/copilot.py,sha256=u7lOIX4nIg2CqHNe_FZ6AaEI8XCw8Z7YZiexbE2dij8,6392
+sdxloop_worker/backends/echo.py,sha256=jLJK_SNnxjA0zB0Yoev81hL-pdK7zbW4ElO6O8IDFDk,3471
+sdxloop_worker-0.1.0.dist-info/METADATA,sha256=7zVXOelFmR6DzGZisE-MfTNopZgqpUZFvgiTNkVQv-E,1238
+sdxloop_worker-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sdxloop_worker-0.1.0.dist-info/RECORD,,

sdxloop_worker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any