workjig 0.1.0__py3-none-any.whl

workjig/__init__.py

@@ -0,0 +1,16 @@
+"""Run headless LLM coding harnesses as subprocess workers with durable results."""
+
+from .models import CallResult, CommandWorker, LaunchRecord, Request, RetryPolicy
+from .run import RecordError, Run, RunBusyError, UncertainLaunchError
+
+__all__ = [
+    "LaunchRecord",
+    "CallResult",
+    "CommandWorker",
+    "RecordError",
+    "Request",
+    "RetryPolicy",
+    "Run",
+    "RunBusyError",
+    "UncertainLaunchError",
+]

workjig/adapters.py

@@ -0,0 +1,224 @@
+"""Version-scoped command templates and evidence extraction for headless CLIs.
+
+Factories construct commands and declare their output protocols. They do not
+authenticate, launch models, or claim that a requested model was the one served.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from .models import CommandWorker
+
+
+def _required_text(value: str, name: str) -> str:
+    if not isinstance(value, str) or not value or any(char in value for char in "\x00{}\r\n"):
+        raise ValueError(f"{name} must be nonempty text without control or template characters")
+    return value
+
+
+def _tool_list(tools: tuple[str, ...]) -> str:
+    if not tools or not all(
+        isinstance(tool, str) and tool and not any(char in tool for char in ",\x00{}\r\n")
+        for tool in tools
+    ):
+        raise ValueError("tools must be a nonempty tuple of names without commas")
+    return ",".join(tools)
+
+
+_PROMPT_POINTER = "Read the complete task and file paths in `{prompt}`, then perform that task."
+
+
+def codex_worker(
+    model: str,
+    *,
+    sandbox: Literal["read-only", "workspace-write", "danger-full-access"],
+    effort: str | None = None,
+) -> CommandWorker:
+    """Construct a Codex 0.162.1 noninteractive worker.
+
+    The caller chooses the sandbox. ``approval_policy=never`` denies requests
+    that require interactive approval; it does not replace host isolation.
+    """
+    _required_text(model, "model")
+    if sandbox not in {"read-only", "workspace-write", "danger-full-access"}:
+        raise ValueError("unsupported Codex sandbox")
+    argv = [
+        "codex",
+        "exec",
+        "--json",
+        "--skip-git-repo-check",
+        "-C",
+        "{workdir}",
+        "-m",
+        model,
+        "-s",
+        sandbox,
+        "-c",
+        "approval_policy=never",
+    ]
+    if effort is not None:
+        _required_text(effort, "effort")
+        argv.extend(("-c", f"model_reasoning_effort={effort}"))
+    argv.append(_PROMPT_POINTER)
+    return CommandWorker(argv=tuple(argv), name="codex", output_protocol="codex-json")
+
+
+def claude_worker(
+    model: str,
+    *,
+    allowed_tools: tuple[str, ...],
+    permission_mode: Literal["dontAsk", "acceptEdits"] = "dontAsk",
+) -> CommandWorker:
+    """Construct a Claude Code 2.1.303 one-shot worker.
+
+    The caller selects an explicit tool allowlist. Unanswered permission
+    requests are denied; normal settings and instruction loading remain active.
+    """
+    _required_text(model, "model")
+    if permission_mode not in {"dontAsk", "acceptEdits"}:
+        raise ValueError("unsupported Claude permission mode")
+    tools = _tool_list(allowed_tools)
+    return CommandWorker(
+        argv=(
+            "claude",
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--model",
+            model,
+            "--permission-mode",
+            permission_mode,
+            "--permission-prompts",
+            "none",
+            f"--allowedTools={tools}",
+            _PROMPT_POINTER,
+        ),
+        name="claude",
+        output_protocol="claude-stream-json",
+    )
+
+
+def pi_worker(
+    model: str,
+    *,
+    provider: str,
+    tools: tuple[str, ...],
+    project_trust: Literal["approve", "no-approve"],
+) -> CommandWorker:
+    """Construct a Pi 1.3.0 one-shot worker.
+
+    Project trust only controls project resource loading. Pi has no built-in
+    sandbox or per-tool approval; the caller supplies process isolation.
+    """
+    _required_text(model, "model")
+    _required_text(provider, "provider")
+    if project_trust not in {"approve", "no-approve"}:
+        raise ValueError("project_trust must be approve or no-approve")
+    return CommandWorker(
+        argv=(
+            "pi",
+            "--mode",
+            "json",
+            "--provider",
+            provider,
+            "--model",
+            model,
+            "--tools",
+            _tool_list(tools),
+            f"--{project_trust}",
+            "--session-dir",
+            "{launch_dir}",
+            _PROMPT_POINTER,
+        ),
+        name="pi",
+        output_protocol="pi-json",
+    )
+
+
+def parse_evidence(harness: Literal["codex", "claude", "pi"], stdout: str) -> dict[str, object]:
+    """Extract documented fields from retained JSONL without guessing identity.
+
+    Raw stdout remains authoritative evidence. Parsing a partial stream yields
+    only fields actually present; callers retain parse_errors for diagnosis.
+    """
+    if harness not in {"codex", "claude", "pi"}:
+        raise ValueError("unknown harness")
+    records: list[dict[str, object]] = []
+    parse_errors = 0
+    # JSONL is LF-delimited. Unicode paragraph separators can occur in strings.
+    for line in stdout.split("\n"):
+        line = line.removesuffix("\r")
+        if not line.strip():
+            continue
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError:
+            parse_errors += 1
+            continue
+        if isinstance(value, dict):
+            records.append(value)
+        else:
+            parse_errors += 1
+
+    evidence: dict[str, object] = {
+        "harness": harness,
+        "records": len(records),
+        "parse_errors": parse_errors,
+    }
+    if harness == "codex":
+        error_events = 0
+        for record in records:
+            if record.get("type") == "thread.started" and isinstance(record.get("thread_id"), str):
+                evidence["session_id"] = record["thread_id"]
+            if record.get("type") in {"turn.completed", "turn.failed"}:
+                evidence["turn_outcome"] = record["type"]
+            if record.get("type") == "error":
+                error_events += 1
+        if error_events:
+            evidence["error_event_count"] = error_events
+        return evidence
+
+    if harness == "claude":
+        retry_errors: list[str] = []
+        for record in records:
+            if record.get("type") == "system" and record.get("subtype") == "api_retry":
+                if isinstance(record.get("error"), str):
+                    retry_errors.append(record["error"])
+            if record.get("type") == "assistant":
+                message = record.get("message")
+                if isinstance(message, dict) and isinstance(message.get("model"), str):
+                    evidence["reported_model"] = message["model"]
+            if record.get("type") == "result":
+                evidence["last_result_subtype"] = record.get("subtype")
+                if isinstance(record.get("modelUsage"), dict):
+                    evidence["model_usage"] = record["modelUsage"]
+                if isinstance(record.get("session_id"), str):
+                    evidence["session_id"] = record["session_id"]
+                if isinstance(record.get("is_error"), bool):
+                    evidence["is_error"] = record["is_error"]
+        if retry_errors:
+            evidence["retry_error_categories"] = retry_errors
+        return evidence
+
+    for record in records:
+        if record.get("type") == "session" and isinstance(record.get("id"), str):
+            evidence["session_id"] = record["id"]
+        if record.get("type") == "message_end":
+            message = record.get("message")
+            if isinstance(message, dict) and message.get("role") == "assistant":
+                for source, target in (
+                    ("provider", "provider"),
+                    ("model", "reported_model"),
+                    ("responseModel", "served_model"),
+                    ("responseId", "response_id"),
+                    ("stopReason", "stop_reason"),
+                    ("errorMessage", "error_message"),
+                ):
+                    if isinstance(message.get(source), str):
+                        evidence[target] = message[source]
+        if record.get("type") == "agent_settled" and isinstance(record.get("aborted"), bool):
+            evidence["settled_aborted"] = record["aborted"]
+    return evidence

workjig/harness.py

@@ -0,0 +1,255 @@
+"""Per-launch file protocol and local process ownership."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import time
+from collections.abc import Callable, Mapping
+from contextlib import ExitStack
+from dataclasses import replace
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .models import LaunchRecord, Request
+from .outcomes import terminal_failure
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def prepare(
+    request: Request, launch_dir: Path, workdir: Path
+) -> tuple[Mapping[str, Path], tuple[str, ...]]:
+    """Write fresh inputs and a human-readable task frame before reservation."""
+    input_dir = launch_dir / "inputs"
+    output_dir = launch_dir / "outputs"
+    input_dir.mkdir()
+    output_dir.mkdir()
+    for name, content in request.inputs.items():
+        (input_dir / name).write_text(content, encoding="utf-8")
+    prompt = launch_dir / "prompt.txt"
+    lines = ["Task:", request.task, "", "Inputs (read these exact files):"]
+    lines.extend(f"- {name}: {input_dir / name}" for name in sorted(request.inputs))
+    lines.extend(["", "Required outputs (write these exact files):"])
+    lines.extend(f"- {name}: {output_dir / name}" for name in request.required_outputs)
+    if request.optional_outputs:
+        lines.extend(["", "Optional outputs:"])
+        lines.extend(f"- {name}: {output_dir / name}" for name in request.optional_outputs)
+    lines.extend(
+        [
+            "",
+            "If unable to finish, write a JSON object to this problem file:",
+            str(launch_dir / "problem.json"),
+            'Use {"kind":"unable","message":"..."} or {"kind":"usage_limit","message":"..."}.',
+        ]
+    )
+    prompt.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    paths = {
+        "prompt": prompt,
+        "input_dir": input_dir,
+        "output_dir": output_dir,
+        "problem_file": launch_dir / "problem.json",
+        "evidence_file": launch_dir / (request.worker.evidence_file or "evidence.json"),
+        "launch_dir": launch_dir,
+        "workdir": workdir,
+    }
+    return paths, request.worker.command(paths)
+
+
+def _group_exists(pgid: int) -> bool:
+    try:
+        os.killpg(pgid, 0)
+    except ProcessLookupError:
+        return False
+    return True
+
+
+def _cleanup_group(process: subprocess.Popen[bytes]) -> bool:
+    """Terminate descendants even if the leader has already exited."""
+    pgid = process.pid
+    process.poll()
+    if not _group_exists(pgid):
+        return False
+    try:
+        os.killpg(pgid, signal.SIGTERM)
+    except ProcessLookupError:
+        return False
+    deadline = time.monotonic() + 0.25
+    while time.monotonic() < deadline:
+        # Reap the leader so its zombie does not keep an empty group alive.
+        # Still inspect the group: surviving children need cleanup too.
+        process.poll()
+        if not _group_exists(pgid):
+            return True
+        time.sleep(0.01)
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    return True
+
+
+def _read_problem(path: Path) -> tuple[dict[str, str] | None, bool]:
+    if path.is_symlink():
+        return None, True
+    if not path.exists():
+        return None, False
+    if not path.is_file():
+        return None, True
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None, True
+    if (
+        not isinstance(value, dict)
+        or not isinstance(value.get("kind"), str)
+        or value.get("kind") not in {"unable", "usage_limit"}
+        or not isinstance(value.get("message"), str)
+    ):
+        return None, True
+    return {"kind": value["kind"], "message": value["message"]}, False
+
+
+def _read_evidence(path: Path) -> Mapping[str, object] | None:
+    if path.is_symlink() or not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        # Optional metadata must fit the same strict JSON format as run records.
+        # This also rejects overflowing numeric literals and nested nonfinite values.
+        json.dumps(value, allow_nan=False)
+    except (OSError, UnicodeError, ValueError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def launch(
+    request: Request,
+    workdir: Path,
+    paths: Mapping[str, Path],
+    argv: tuple[str, ...],
+    reserved: LaunchRecord,
+    on_started: Callable[[int, tuple[str, ...], str], None],
+) -> tuple[LaunchRecord, dict[str, str]]:
+    """Invoke once, terminate its process group, then collect only its outputs."""
+    started_at = _now()
+    stdout_path = Path(reserved.launch_dir) / "stdout.log"
+    stderr_path = Path(reserved.launch_dir) / "stderr.log"
+    env = os.environ.copy()
+    env.update(request.worker.env)
+
+    def launch_error(error: OSError) -> tuple[LaunchRecord, dict[str, str]]:
+        return (
+            replace(
+                reserved,
+                status="launch_error",
+                argv=argv,
+                started_at=started_at,
+                finished_at=_now(),
+                problem={"kind": "launch_error", "message": str(error)},
+            ),
+            {},
+        )
+
+    files = ExitStack()
+    try:
+        stdout = files.enter_context(stdout_path.open("wb"))
+        stderr = files.enter_context(stderr_path.open("wb"))
+    except OSError as error:
+        files.close()
+        return launch_error(error)
+    try:
+        try:
+            process = subprocess.Popen(
+                argv,
+                cwd=workdir,
+                env=env,
+                stdin=subprocess.DEVNULL,
+                stdout=stdout,
+                stderr=stderr,
+                start_new_session=True,
+            )
+        except OSError as error:
+            return launch_error(error)
+        timed_out = False
+        group_lingered = False
+        try:
+            on_started(process.pid, argv, started_at)
+            process.wait(timeout=request.timeout_seconds)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+        finally:
+            group_lingered = _cleanup_group(process)
+            if process.poll() is None:
+                process.wait(timeout=1)
+    finally:
+        files.close()
+
+    status = "delivered"
+    problem, invalid_problem = _read_problem(paths["problem_file"])
+    evidence = _read_evidence(paths["evidence_file"])
+    outputs: dict[str, str] = {}
+    missing: list[str] = []
+    # Keep emitted invariants consistent with run._attempt_from_dict; preserve
+    # compatibility with records produced by earlier classification rules.
+    harness_failure = (
+        terminal_failure(request.worker.output_protocol, stdout_path)
+        if request.worker.output_protocol is not None and not timed_out
+        else None
+    )
+    if timed_out:
+        status = "timeout"
+    elif harness_failure == "usage_limit" or (
+        problem is not None and problem["kind"] == "usage_limit"
+    ):
+        status = "usage_limit"
+    elif group_lingered:
+        status = "process_error"
+    elif invalid_problem:
+        status = "protocol_error"
+    elif problem is not None:
+        status = "worker_problem"
+    elif process.returncode != 0 or harness_failure is not None:
+        status = "process_error"
+    else:
+        if paths["output_dir"].is_symlink():
+            status = "protocol_error"
+        for name in request.required_outputs + request.optional_outputs:
+            if status != "delivered":
+                break
+            path = paths["output_dir"] / name
+            if path.is_symlink():
+                status = "protocol_error"
+                break
+            if not path.is_file():
+                if name in request.required_outputs:
+                    missing.append(name)
+                continue
+            try:
+                outputs[name] = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeError):
+                status = "protocol_error"
+                break
+        if status == "delivered" and missing:
+            status = "incomplete"
+    if status != "delivered":
+        outputs = {}
+    return (
+        replace(
+            reserved,
+            status=status,
+            argv=argv,
+            pid=process.pid,
+            returncode=process.returncode,
+            started_at=started_at,
+            finished_at=_now(),
+            problem=problem,
+            evidence=evidence,
+            missing_outputs=tuple(missing),
+        ),
+        outputs,
+    )