whiletrue 0.1.0__py3-none-any.whl

whiletrue/basics/shell.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from whiletrue.basics.process import run_command, tail
+from whiletrue.core import (
+    ActionModule,
+    ConfigIssue,
+    Emit,
+    Ports,
+    PortSpec,
+    StepContext,
+    define_action,
+    parse_duration,
+)
+from whiletrue.core.module import PortValues
+
+
+class ShellConfig(BaseModel):
+    run: str = Field(min_length=1)
+    cwd: str | None = None
+    env: dict[str, str] | None = None
+    timeout: str | int | float | None = None
+    #: On success, pass the step's input on instead of the command's output (for gates in a chain).
+    pass_input: bool = False
+
+
+class GateTestsConfig(ShellConfig):
+    run: str = Field(default="pytest", min_length=1)
+
+
+def _make_shell[Cfg: ShellConfig](
+    module_id: str, effects: Literal["side-effect", "deterministic"], config_cls: type[Cfg]
+) -> ActionModule[Cfg]:
+    def validate(config: Cfg, _vctx: object) -> list[ConfigIssue]:
+        if config.timeout is None:
+            return []
+        try:
+            parse_duration(config.timeout)
+        except ValueError as error:
+            return [ConfigIssue("error", str(error))]
+        return []
+
+    async def run(input: PortValues, ctx: StepContext[Cfg]) -> Emit:
+        cfg = ctx.config
+        result = await run_command(
+            "sh",
+            ["-c", cfg.run],
+            cwd=str((Path(ctx.cwd) / (cfg.cwd or ".")).resolve()),
+            env=cfg.env,
+            signal=ctx.signal,
+            timeout_ms=None if cfg.timeout is None else parse_duration(cfg.timeout),
+        )
+        if result.code == 0:
+            return Emit("ok", input.get("in") if cfg.pass_input else result.stdout)
+        if result.timed_out:
+            reason = "timed out"
+        elif result.aborted:
+            reason = "aborted"
+        else:
+            reason = f"exited with code {'unknown' if result.code is None else result.code}"
+        return Emit(
+            "fail",
+            {
+                "error": f"`{cfg.run}` {reason}",
+                "exit_code": result.code,
+                "output": tail(result.stdout + result.stderr),
+            },
+        )
+
+    return define_action(
+        ActionModule(
+            id=module_id,
+            config=config_cls,
+            ports=Ports(
+                inputs=[PortSpec("in", "Any")],
+                outputs=[PortSpec("out", "Any")],
+            ),
+            effects=effects,
+            validate=validate,  # pyright: ignore[reportArgumentType]
+            cacheable=False,
+            idempotency_key=(lambda _i, ctx: f"shell:{ctx.step_key}")
+            if effects == "side-effect"
+            else None,
+            run=run,
+        )
+    )
+
+
+#: Runs a shell command. Fires `ok` on exit 0, otherwise `fail` with the output tail.
+shell_module = _make_shell("shell", "side-effect", ShellConfig)
+#: A deterministic gate: pass/fail by exit code only.
+gate_shell_module = _make_shell("gate.shell", "deterministic", ShellConfig)
+#: A deterministic gate for the test suite: `run` defaults to `pytest`.
+gate_tests_module = _make_shell("gate.tests", "deterministic", GateTestsConfig)

whiletrue/basics/wake.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from whiletrue.core import WakeContext, WakeResult, parse_duration
+
+
+class FileExistsWake:
+    """Approves when a file appears (relative to the project): a build artifact, a sign-off file."""
+
+    async def check(self, arg: Any, ctx: WakeContext) -> WakeResult | None:
+        if not isinstance(arg, str) or not arg:
+            return None
+        if (Path(ctx.cwd) / arg).exists():
+            return WakeResult("approved", f"{arg} exists", by="file_exists")
+        return None
+
+
+class TimerWake:
+    """Approves once a duration has passed since the item was parked (a cooling-off period)."""
+
+    async def check(self, arg: Any, ctx: WakeContext) -> WakeResult | None:
+        waited = ctx.now() - ctx.park.created_at
+        if waited >= parse_duration(arg):
+            return WakeResult("approved", f"{arg} elapsed", by="timer")
+        return None

whiletrue/claude_code/__init__.py

@@ -0,0 +1,58 @@
+"""Claude Code runners: headless (`claude -p`) and interactive (a live pane)."""
+
+from whiletrue.claude_code.endpoint import EventEndpoint, SessionHandler, ToolResult
+from whiletrue.claude_code.headless import (
+    HeadlessOptions,
+    HeadlessRunner,
+    build_headless_args,
+    create_headless_runner,
+)
+from whiletrue.claude_code.interactive import (
+    PLUGIN_DIR,
+    InteractiveOptions,
+    InteractiveRunner,
+    build_interactive_args,
+    create_interactive_runner,
+)
+from whiletrue.claude_code.panes import (
+    Pane,
+    PaneHost,
+    ProcessPaneHost,
+    StreamMirror,
+    TmuxPaneHost,
+)
+from whiletrue.core import PluginApi, SimplePlugin
+
+
+def claude_code_plugin(
+    options: HeadlessOptions | None = None, interactive: InteractiveOptions | None = None
+) -> SimplePlugin:
+    """Registers the Claude Code runners."""
+
+    def register(api: PluginApi) -> None:
+        api.register_runner(create_headless_runner(options))
+        api.register_runner(create_interactive_runner(interactive))
+
+    return SimplePlugin(name="whiletrue.claude_code", register=register)
+
+
+__all__ = [
+    "PLUGIN_DIR",
+    "EventEndpoint",
+    "HeadlessOptions",
+    "HeadlessRunner",
+    "InteractiveOptions",
+    "InteractiveRunner",
+    "Pane",
+    "PaneHost",
+    "ProcessPaneHost",
+    "SessionHandler",
+    "StreamMirror",
+    "TmuxPaneHost",
+    "ToolResult",
+    "build_headless_args",
+    "build_interactive_args",
+    "claude_code_plugin",
+    "create_headless_runner",
+    "create_interactive_runner",
+]

whiletrue/claude_code/endpoint.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import secrets
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol, cast
+
+
+@dataclass
+class ToolResult:
+    text: str
+    is_error: bool = False
+
+
+class SessionHandler(Protocol):
+    """What the endpoint needs from one live agent session."""
+
+    async def on_hook(self, event: str, payload: dict[str, Any]) -> dict[str, Any] | None:
+        """Handles a Claude Code hook. The returned object is printed back to the hook."""
+        ...
+
+    def tools(self) -> list[dict[str, Any]]:
+        """MCP tool descriptors (`name`, `description`, `inputSchema`) for this session."""
+        ...
+
+    async def on_tool(self, name: str, args: dict[str, Any]) -> ToolResult: ...
+
+
+_MAX_BODY = 8 * 1024 * 1024
+_REASONS = {200: "OK", 400: "Bad Request", 401: "Unauthorized", 404: "Not Found", 500: "Error"}
+
+
+class EventEndpoint:
+    """A loopback HTTP server inside the whiletrue process.
+
+    The bundled plugin's hook script and MCP server post here. Requests carry a shared secret
+    (`X-WT-Token`) and the id of the session they belong to (`X-WT-Session`); the endpoint routes
+    them to whatever handler registered under that id.
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 0) -> None:
+        self._host = host
+        self._port = port
+        self.token = secrets.token_hex(16)
+        self._handlers: dict[str, SessionHandler] = {}
+        self._server: asyncio.Server | None = None
+
+    @property
+    def port(self) -> int:
+        assert self._server is not None, "endpoint not started"
+        return int(self._server.sockets[0].getsockname()[1])
+
+    @property
+    def started(self) -> bool:
+        return self._server is not None
+
+    @property
+    def url(self) -> str:
+        return f"http://{self._host}:{self.port}"
+
+    async def start(self) -> None:
+        self._server = await asyncio.start_server(self._serve, self._host, self._port)
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    def register(self, key: str, handler: SessionHandler) -> Callable[[], None]:
+        if key in self._handlers:
+            raise ValueError(f'Session "{key}" is already registered')
+        self._handlers[key] = handler
+
+        def unregister() -> None:
+            self._handlers.pop(key, None)
+
+        return unregister
+
+    def env_for(self, key: str) -> dict[str, str]:
+        """Environment that points the plugin's scripts at this endpoint for one session."""
+        return {"WT_ENDPOINT": self.url, "WT_TOKEN": self.token, "WT_SESSION": key}
+
+    async def _serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            status, body = await self._handle(reader)
+        except (ValueError, asyncio.IncompleteReadError, asyncio.LimitOverrunError):
+            status, body = 400, {"error": "bad request"}
+        except Exception as error:
+            status, body = 500, {"error": str(error)}
+        payload = json.dumps(body).encode()
+        head = (
+            f"HTTP/1.1 {status} {_REASONS.get(status, 'Error')}\r\n"
+            "Content-Type: application/json\r\n"
+            f"Content-Length: {len(payload)}\r\nConnection: close\r\n\r\n"
+        )
+        try:
+            writer.write(head.encode() + payload)
+            await writer.drain()
+        except ConnectionError:  # pragma: no cover (the client went away)
+            pass
+        finally:
+            writer.close()
+
+    async def _handle(self, reader: asyncio.StreamReader) -> tuple[int, Any]:
+        request_line = (await reader.readline()).decode("latin-1").split()
+        if len(request_line) != 3:
+            raise ValueError("malformed request line")
+        method, path = request_line[0], request_line[1]
+        headers: dict[str, str] = {}
+        while (line := (await reader.readline()).decode("latin-1").strip()) != "":
+            name, _, value = line.partition(":")
+            headers[name.strip().lower()] = value.strip()
+        length = int(headers.get("content-length", "0"))
+        if length > _MAX_BODY:
+            raise ValueError("body too large")
+        raw = await reader.readexactly(length) if length else b""
+        if method != "POST":
+            return 404, {"error": "not found"}
+        if not secrets.compare_digest(headers.get("x-wt-token", ""), self.token):
+            return 401, {"error": "bad token"}
+        handler = self._handlers.get(headers.get("x-wt-session", ""))
+        if handler is None:
+            return 404, {"error": "unknown session"}
+        parsed: Any = json.loads(raw) if raw else {}
+        if not isinstance(parsed, dict):
+            raise ValueError("body must be an object")
+        request = cast(dict[str, Any], parsed)
+        if path == "/hook":
+            reply = await handler.on_hook(
+                str(request.get("event", "")), request.get("payload") or {}
+            )
+            return 200, reply or {}
+        if path == "/tools/list":
+            return 200, {"tools": handler.tools()}
+        if path == "/tools/call":
+            result = await handler.on_tool(
+                str(request.get("name", "")), request.get("arguments") or {}
+            )
+            return 200, {"text": result.text, "is_error": result.is_error}
+        return 404, {"error": "not found"}

whiletrue/claude_code/headless.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+from whiletrue.basics.process import kill_process_group
+from whiletrue.core import AgentRequest, AgentResult, RunContext, RunnerCapabilities
+
+#: Stream-json lines can be large (tool results); lift asyncio's 64 KiB default.
+_LINE_LIMIT = 64 * 1024 * 1024
+
+
+@dataclass
+class HeadlessOptions:
+    #: The claude binary. Defaults to `claude` on PATH.
+    command: str = "claude"
+    #: Extra args appended after the generated ones (e.g. `--bare` for reproducible runs).
+    extra_args: list[str] = field(default_factory=lambda: [])
+
+
+def _num(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def build_headless_args(req: AgentRequest, extra_args: list[str] | None = None) -> list[str]:
+    """Builds the argv for `claude -p`. The prompt itself goes over stdin."""
+    args = ["-p", "--output-format", "stream-json", "--verbose", "--permission-prompts", "none"]
+    if req.model:
+        args += ["--model", req.model]
+    if req.allowed_tools:
+        args += ["--allowedTools", ",".join(req.allowed_tools)]
+    if req.disallowed_tools:
+        args += ["--disallowedTools", ",".join(req.disallowed_tools)]
+    if req.tools:
+        args += ["--tools", ",".join(req.tools)]
+    if req.permission_mode:
+        args += ["--permission-mode", req.permission_mode]
+    if req.system_prompt_append:
+        args += ["--append-system-prompt", req.system_prompt_append]
+    if req.output_schema:
+        args += ["--json-schema", json.dumps(req.output_schema, separators=(",", ":"))]
+    if req.limits is not None and req.limits.turns is not None:
+        args += ["--max-turns", str(req.limits.turns)]
+    if req.limits is not None and req.limits.budget_usd is not None:
+        args += ["--max-budget-usd", _num(req.limits.budget_usd)]
+    if req.resume:
+        args += ["--resume", req.resume]
+    elif req.session_id:
+        args += ["--session-id", req.session_id]
+    return [*args, *(extra_args or [])]
+
+
+def _to_result(msg: dict[str, Any]) -> AgentResult:
+    ok = msg.get("is_error") is not True and msg.get("subtype") == "success"
+    errors = msg.get("errors")
+    error: str | None = None
+    if not ok:
+        joined = (
+            "; ".join(str(e) for e in cast(list[Any], errors)) if isinstance(errors, list) else ""
+        )
+        error = joined or msg.get("subtype") or "claude reported an error"
+    return AgentResult(
+        ok=ok,
+        text=msg.get("result") or "",
+        output=msg.get("structured_output"),
+        session_id=msg.get("session_id"),
+        cost_usd=msg.get("total_cost_usd"),
+        turns=msg.get("num_turns"),
+        error=error,
+    )
+
+
+class HeadlessRunner:
+    """Unattended runner: `claude -p --output-format stream-json` (CI, cheap utility steps)."""
+
+    id = "claude-code-headless"
+    capabilities = RunnerCapabilities(
+        interactive=False, structured_output=True, resume=True, fork=False, budget=True
+    )
+
+    def __init__(self, options: HeadlessOptions | None = None) -> None:
+        self._options = options or HeadlessOptions()
+
+    async def run(self, request: AgentRequest, ctx: RunContext) -> AgentResult:
+        command = self._options.command
+        if ctx.signal.aborted:
+            return AgentResult(ok=False, text="", error="aborted")
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                command,
+                *build_headless_args(request, self._options.extra_args),
+                cwd=request.cwd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                start_new_session=True,
+                limit=_LINE_LIMIT,
+            )
+        except OSError as error:
+            return AgentResult(ok=False, text="", error=f"Failed to start {command}: {error}")
+
+        async def drive() -> AgentResult:
+            assert proc.stdin is not None
+            assert proc.stdout is not None
+            assert proc.stderr is not None
+            stderr_task = asyncio.ensure_future(proc.stderr.read())
+            try:
+                with contextlib.suppress(BrokenPipeError, ConnectionResetError):
+                    proc.stdin.write(request.prompt.encode())
+                    await proc.stdin.drain()
+                    proc.stdin.close()
+                final: AgentResult | None = None
+                while line := await proc.stdout.readline():
+                    msg = _parse_line(line)
+                    if msg is None:
+                        continue
+                    if msg.get("type") == "result":
+                        final = _to_result(msg)
+                        _emit(ctx, {"kind": "result", "subtype": msg.get("subtype")})
+                    elif msg.get("type") == "assistant":
+                        message: dict[str, Any] = msg.get("message") or {}
+                        blocks: list[dict[str, Any]] = message.get("content") or []
+                        for block in blocks:
+                            if block.get("type") == "tool_use":
+                                _emit(ctx, {"kind": "tool_use", "name": block.get("name") or ""})
+                            elif block.get("type") == "text":
+                                _emit(ctx, {"kind": "text"})
+                code = await proc.wait()
+                if final is not None:
+                    return final
+                stderr = (await stderr_task).decode(errors="replace").strip()
+                detail = f": {stderr[-500:]}" if stderr else ""
+                return AgentResult(
+                    ok=False,
+                    text="",
+                    error=f"{command} exited with code {code} without a result{detail}",
+                )
+            finally:
+                stderr_task.cancel()
+
+        drive_task = asyncio.ensure_future(drive())
+        abort_task = asyncio.ensure_future(ctx.signal.wait())
+        wall_ms = request.limits.wall_ms if request.limits is not None else None
+        try:
+            done, _ = await asyncio.wait(
+                {drive_task, abort_task},
+                timeout=None if wall_ms is None else wall_ms / 1000,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if drive_task in done:
+                return drive_task.result()
+            # Kill the whole process group so grandchildren cannot keep our pipes open.
+            kill_process_group(proc.pid)
+            drive_task.cancel()
+            await asyncio.gather(drive_task, return_exceptions=True)
+            await proc.wait()
+            if abort_task in done:
+                return AgentResult(ok=False, text="", error="aborted")
+            return AgentResult(ok=False, text="", error="wall-time limit exceeded")
+        finally:
+            abort_task.cancel()
+
+
+def _parse_line(line: bytes) -> dict[str, Any] | None:
+    try:
+        msg = json.loads(line)
+    except ValueError:
+        return None
+    return msg if isinstance(msg, dict) else None  # pyright: ignore[reportUnknownVariableType]
+
+
+def _emit(ctx: RunContext, event: dict[str, Any]) -> None:
+    if ctx.on_event is not None:
+        ctx.on_event(event)
+
+
+def create_headless_runner(options: HeadlessOptions | None = None) -> HeadlessRunner:
+    return HeadlessRunner(options)