dirtywork 0.2.0__py3-none-any.whl

dirtywork/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

dirtywork/__main__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .llm import LLMError, LMStudioClient
+from .runner import Runner
+from .tools import ToolExecutor
+from .transcript import Transcript
+from .workspace import (
+    WorkspaceError,
+    create_worktree,
+    ensure_worktrees_excluded,
+    load_repo_context,
+    make_slug,
+    preflight_repo,
+)
+
+RUNS_DIR = Path.home() / ".dirtywork" / "runs"
+DEFAULT_MODEL = "qwen/qwen3-coder-next"
+
+
+def build_system_prompt(worktree: Path, repo_context: str | None) -> str:
+    prompt = f"""You are a coding agent working in a git worktree at {worktree}.
+Complete the task, then reply with a plain-text summary of what you changed and what commands you ran.
+
+Rules:
+- Use edit_file or write_file for ALL file changes. Never modify files via bash (no sed -i, no echo redirects, no heredocs).
+- Paths are relative to the worktree root.
+- Explore before editing: use list_dir, grep, and read_file to understand the code first.
+- Verify your work: run the repo's tests or build via bash before declaring the task complete.
+- Do not run git commit or git branch commands; leave all changes uncommitted for review.
+- When the task is complete, reply WITHOUT calling any tools — that final plain reply ends the run."""
+    if repo_context:
+        prompt += f"\n\nRepository conventions (from the repo's own docs):\n\n{repo_context}"
+    return prompt
+
+
+def _err(msg: str) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dirtywork")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    run_p = sub.add_parser("run", help="run one task in an isolated worktree")
+    run_p.add_argument("task")
+    run_p.add_argument("--repo", required=True, type=Path)
+    run_p.add_argument("--model", default=DEFAULT_MODEL)
+    run_p.add_argument("--branch-from", default=None)
+    run_p.add_argument("--max-turns", type=int, default=40)
+    run_p.add_argument("--timeout", type=int, default=1800)
+    run_p.add_argument("--temperature", type=float, default=None)
+    run_p.add_argument("--base-url", default="http://localhost:1234/v1")
+    args = parser.parse_args(argv)
+
+    repo = args.repo.expanduser().resolve()
+
+    # ---- preflight (exit 2, create nothing) ----
+    client = LMStudioClient(base_url=args.base_url)
+    try:
+        preflight_repo(repo)
+        models = client.list_models()
+    except WorkspaceError as e:
+        _err(str(e))
+        return 2
+    except LLMError as e:
+        _err(f"{e}\nIs LM Studio running? Try: lms ps")
+        return 2
+    if args.model not in models:
+        _err(f"model '{args.model}' not loaded (loaded: {', '.join(models) or 'none'}). "
+             f"Load it with: lms load {args.model}")
+        return 2
+
+    # ---- workspace ----
+    slug = make_slug(args.task, datetime.now())
+    try:
+        ensure_worktrees_excluded(repo)
+        worktree = create_worktree(repo, slug, args.branch_from)
+    except WorkspaceError as e:
+        _err(str(e))
+        return 2
+
+    transcript_path = RUNS_DIR / slug / "transcript.jsonl"
+    print(f"transcript: {transcript_path}", file=sys.stderr)
+    print(f"worktree:   {worktree}", file=sys.stderr)
+
+    # ---- run ----
+    # Everything from here on -- Transcript/ToolExecutor/Runner construction,
+    # system-prompt assembly, and the run itself -- is wrapped in one boundary so
+    # the machine contract (exactly one JSON object on stdout, post-preflight)
+    # holds even if a component other than runner.run() blows up.
+    transcript = None
+    try:
+        transcript = Transcript(transcript_path)
+        executor = ToolExecutor(worktree, transcript=transcript)
+        runner = Runner(client, executor, transcript, model=args.model,
+                        max_turns=args.max_turns, timeout=args.timeout,
+                        temperature=args.temperature,
+                        run_info={"repo": str(repo), "worktree": str(worktree)})
+        system_prompt = build_system_prompt(worktree, load_repo_context(worktree))
+        result = runner.run(system_prompt, args.task)
+    except Exception as e:
+        message = str(e) if isinstance(e, LLMError) else f"unexpected error: {e!r}"
+        if transcript is not None:
+            try:
+                transcript.write("run_end", status="model_error", error=message)
+            except Exception:
+                pass
+        _err(message)
+        print(json.dumps({
+            "status": "model_error",
+            "worktree": str(worktree),
+            "branch": f"dirtywork/{slug}",
+            "transcript": str(transcript_path),
+            "turns": None,
+            "usage": {},
+            "final_message": message,
+        }, indent=2))
+        return 1
+    finally:
+        if transcript is not None:
+            try:
+                transcript.close()
+            except Exception:
+                pass
+
+    print(json.dumps({
+        "status": result.status,
+        "worktree": str(worktree),
+        "branch": f"dirtywork/{slug}",
+        "transcript": str(transcript_path),
+        "turns": result.turns,
+        "usage": result.usage,
+        "final_message": result.final_message,
+    }, indent=2))
+    return 0 if result.status == "completed" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dirtywork/guardrails.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+class GuardrailError(Exception):
+    """Raised when a tool call violates a containment rule."""
+
+
+def resolve_in_worktree(path_str: str, worktree: Path, writing: bool = False) -> Path:
+    """Resolve a tool-supplied path and require it to land inside the worktree.
+
+    Symlinks are followed (Path.resolve), so a link pointing outside is caught.
+    For not-yet-existing paths, resolve() still normalizes .. components.
+    """
+    wt = worktree.resolve()
+    raw = Path(path_str)
+    candidate = raw if raw.is_absolute() else wt / raw
+    resolved = candidate.resolve()
+
+    if not (resolved == wt or wt in resolved.parents):
+        raise GuardrailError(
+            f"Path '{path_str}' resolves outside the worktree ({resolved}). "
+            f"Use paths relative to the worktree root."
+        )
+    if writing:
+        rel_parts = resolved.relative_to(wt).parts
+        if rel_parts and rel_parts[0] == ".git":
+            raise GuardrailError(
+                f"Writing inside .git/ is not allowed (got '{path_str}')."
+            )
+    return resolved
+
+# (reason, pattern) — case-insensitive. Blocks accidents, not adversaries.
+_DENYLIST: list[tuple[str, str]] = [
+    ("sudo is not allowed", r"\bsudo\b"),
+    ("git push is not allowed — leave changes uncommitted for review",
+     r"\bgit\s+push\b"),
+    ("destructive command targeting an absolute or home path",
+     r"\b(rm|mv|chmod|chown)\b[^|;&]*\s['\"]?(/|~)"),
+    ("piping a download into a shell is not allowed",
+     r"\b(curl|wget)\b[^|;&]*\|\s*['\"]?\w*\s*(ba|z|da)?sh\b"),
+    ("system-control commands are not allowed",
+     r"\b(osascript|launchctl|shutdown|reboot|killall)\b"),
+    ("redirecting output to an absolute or home path outside the worktree",
+     r">>?\s*['\"]?(?!/dev/null)(/|~)"),
+    ("changing directory out of the worktree is not allowed",
+     r"\b(cd|pushd)\s+['\"]?(/|~|\.\.)"),
+]
+
+_COMPILED = [(reason, re.compile(pat, re.IGNORECASE)) for reason, pat in _DENYLIST]
+
+
+def check_bash_command(command: str) -> str | None:
+    """Return a rejection reason if the command matches the denylist, else None."""
+    for reason, rx in _COMPILED:
+        if rx.search(command):
+            return f"BLOCKED: {reason}. Rework the command to stay inside the worktree."
+    return None
+
+
+def build_env() -> dict:
+    """Minimal env for bash subprocesses — parent shell secrets are not inherited."""
+    keep = ("PATH", "HOME", "TERM", "LANG", "TMPDIR")
+    return {k: os.environ[k] for k in keep if k in os.environ}

dirtywork/llm.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import http.client
+import json
+import socket
+import urllib.error
+import urllib.request
+
+
+class LLMError(Exception):
+    """Raised when the LM Studio server is unreachable or returns garbage."""
+
+
+class LLMTimeout(LLMError):
+    """Raised when a request to LM Studio times out."""
+
+
+class LMStudioClient:
+    def __init__(self, base_url: str = "http://localhost:1234/v1", timeout: int = 600):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, path: str, payload: dict | None = None,
+                 timeout: float | None = None) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            data = json.dumps(payload).encode() if payload is not None else None
+            req = urllib.request.Request(
+                url, data=data, headers={"Content-Type": "application/json"}
+            )
+        except (ValueError, TypeError) as e:
+            raise LLMError(f"invalid request for LM Studio at {self.base_url!r}: {e}")
+        effective_timeout = timeout if timeout is not None else self.timeout
+        try:
+            with urllib.request.urlopen(req, timeout=effective_timeout) as resp:
+                body = resp.read()
+        except urllib.error.HTTPError as e:
+            try:
+                detail = e.read()[:500]
+            except Exception:
+                detail = b"<unreadable error body>"
+            raise LLMError(f"LM Studio HTTP {e.code} on {path}: {detail!r}")
+        except (urllib.error.URLError, OSError, http.client.HTTPException, ValueError) as e:
+            if isinstance(e, socket.timeout) or isinstance(getattr(e, "reason", None), socket.timeout):
+                raise LLMTimeout(f"request to {path} timed out after {effective_timeout}s")
+            raise LLMError(f"cannot reach LM Studio at {self.base_url}: {e}")
+        try:
+            return json.loads(body.decode())
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            raise LLMError(f"invalid JSON from LM Studio on {path}: {e}")
+
+    def list_models(self) -> list[str]:
+        body = self._request("/models")
+        if not isinstance(body, dict) or not isinstance(body.get("data"), list):
+            raise LLMError("unexpected /models response shape from LM Studio")
+        ids = []
+        for m in body["data"]:
+            if not isinstance(m, dict) or not isinstance(m.get("id"), str):
+                raise LLMError("unexpected /models entry shape from LM Studio")
+            ids.append(m["id"])
+        return ids
+
+    def chat(
+        self,
+        model: str,
+        messages: list,
+        tools: list,
+        temperature: float | None = None,
+        max_tokens: int = 4096,
+        timeout: float | None = None,
+    ) -> dict:
+        payload = {"model": model, "messages": messages, "max_tokens": max_tokens}
+        if tools:
+            payload["tools"] = tools
+        if temperature is not None:
+            payload["temperature"] = temperature
+        return self._request("/chat/completions", payload, timeout=timeout)

dirtywork/runner.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+
+from .llm import LLMTimeout
+
+CONTEXT_WINDOWS = {
+    "qwen/qwen3-coder-next": 65536,
+    "mistralai/devstral-small-2-2512": 32768,
+}
+DEFAULT_WINDOW = 32768
+TRIM_MARKER = "[result trimmed — re-run the tool if needed]"
+CHARS_PER_TOKEN = 4
+BUDGET_FRACTION = 0.75
+MAX_CONSECUTIVE_FAILURES = 3
+
+
+def _valid_tool_call(tc) -> bool:
+    """Structurally valid OpenAI tool call: non-empty string id, function object
+    with non-empty string name, arguments absent/None or a string."""
+    if not isinstance(tc, dict):
+        return False
+    if not isinstance(tc.get("id"), str) or not tc["id"]:
+        return False
+    fn = tc.get("function")
+    if not isinstance(fn, dict):
+        return False
+    if not isinstance(fn.get("name"), str) or not fn["name"]:
+        return False
+    args = fn.get("arguments")
+    return args is None or isinstance(args, str)
+
+
+def _canonical_tool_call(tc: dict) -> dict:
+    """Rebuild an accepted call in canonical OpenAI wire shape."""
+    fn = tc["function"]
+    return {"id": tc["id"], "type": "function",
+            "function": {"name": fn["name"], "arguments": fn.get("arguments") or "{}"}}
+
+
+def _total_chars(messages: list) -> int:
+    total = 0
+    for m in messages:
+        total += len(m.get("content") or "")
+        for tc in m.get("tool_calls") or []:
+            if not isinstance(tc, dict):
+                continue
+            total += len((tc.get("function") or {}).get("arguments") or "")
+    return total
+
+
+def trim_messages(messages: list, char_budget: int) -> bool:
+    """Replace oldest tool results with TRIM_MARKER until under budget."""
+    for m in messages:
+        if _total_chars(messages) <= char_budget:
+            return True
+        if m.get("role") == "tool" and m.get("content") != TRIM_MARKER:
+            m["content"] = TRIM_MARKER
+    return _total_chars(messages) <= char_budget
+
+
+@dataclass
+class RunResult:
+    status: str
+    turns: int
+    final_message: str
+    usage: dict = field(default_factory=dict)
+
+
+class Runner:
+    def __init__(self, client, executor, transcript, model,
+                 max_turns: int = 40, timeout: int = 1800,
+                 temperature: float | None = None,
+                 run_info: dict | None = None):
+        self.client = client
+        self.executor = executor
+        self.transcript = transcript
+        self.model = model
+        self.max_turns = max_turns
+        self.timeout = timeout
+        self.temperature = temperature
+        self.run_info = run_info
+        window = CONTEXT_WINDOWS.get(model, DEFAULT_WINDOW)
+        self.char_budget = int(window * BUDGET_FRACTION * CHARS_PER_TOKEN)
+
+    def run(self, system_prompt: str, task: str) -> RunResult:
+        from .tools import TOOL_SCHEMAS
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": task},
+        ]
+        self.transcript.write("run_start", task=task, model=self.model,
+                              max_turns=self.max_turns, timeout=self.timeout,
+                              **(self.run_info or {}))
+        usage = {"prompt_tokens": 0, "completion_tokens": 0}
+        turns = 0
+        failures = 0
+        start = time.monotonic()
+        deadline = start + self.timeout
+        self.executor.deadline = deadline
+
+        def finish(status: str, final: str) -> RunResult:
+            self.transcript.write("run_end", status=status, turns=turns,
+                                  duration_s=round(time.monotonic() - start, 1),
+                                  usage=usage)
+            return RunResult(status, turns, final, usage)
+
+        try:
+            while True:
+                if turns >= self.max_turns:
+                    return finish("max_turns", "")
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return finish("timeout", "")
+                if not trim_messages(messages, self.char_budget):
+                    return finish("context_exhausted", "")
+
+                try:
+                    resp = self.client.chat(self.model, messages, tools=TOOL_SCHEMAS,
+                                            temperature=self.temperature,
+                                            timeout=max(1.0, remaining))
+                except LLMTimeout:
+                    if time.monotonic() >= deadline - 0.5:
+                        return finish("timeout", "")
+                    else:
+                        return finish("model_error",
+                                      "model request timed out before the run deadline")
+                turns += 1
+                try:
+                    msg = resp["choices"][0]["message"]
+                    if not isinstance(msg, dict):
+                        raise TypeError("message is not an object")
+                except (KeyError, IndexError, TypeError):
+                    return finish("model_error",
+                                  "malformed response from server (no choices[0].message)")
+                finish_reason = resp["choices"][0].get("finish_reason")
+                resp_usage = resp.get("usage") or {}
+                for k in usage:
+                    usage[k] += resp_usage.get(k, 0) or 0
+                raw = msg.get("tool_calls") or []
+                if not isinstance(raw, list):
+                    raw = []
+                tool_calls = [_canonical_tool_call(tc) for tc in raw if _valid_tool_call(tc)]
+                malformed_count = len(raw) - len(tool_calls)
+                self.transcript.write(
+                    "assistant", text=msg.get("content"),
+                    tool_calls=[{"name": (tc.get("function") or {}).get("name"),
+                                 "arguments": ((tc.get("function") or {}).get("arguments") or "")[:2000]}
+                                for tc in tool_calls])
+                if raw:
+                    # Rebuild in canonical wire shape (id, type: "function", function
+                    # with a string arguments) so the history we send back stays
+                    # protocol-valid for strict OpenAI-compatible servers, on every
+                    # path that resends tool calls -- not just when malformed.
+                    clean_msg = {"role": "assistant", "content": msg.get("content") or ""}
+                    if tool_calls:
+                        clean_msg["tool_calls"] = tool_calls
+                    messages.append(clean_msg)
+                else:
+                    messages.append(msg)
+                    return finish("completed", msg.get("content") or "")
+
+                for _ in range(malformed_count):
+                    failures += 1
+                    result = "ERROR: malformed tool call entry (missing or invalid id/function fields)"
+                    self.transcript.write("tool_result", tool="", args="", result=result)
+                if malformed_count > 0 and failures >= MAX_CONSECUTIVE_FAILURES:
+                    return finish("model_error",
+                                  "aborted after repeated malformed tool calls")
+
+                for tc in tool_calls:
+                    fn_info = tc.get("function") or {}
+                    name = fn_info.get("name") or ""
+                    raw_args = fn_info.get("arguments") or "{}"
+                    call_id = tc.get("id", "")
+                    try:
+                        args = json.loads(raw_args)
+                        if not isinstance(args, dict):
+                            raise ValueError("arguments must be a JSON object")
+                        result = self.executor.execute(name, args)
+                        failures = 0
+                    except (json.JSONDecodeError, ValueError) as e:
+                        failures += 1
+                        if finish_reason == "length":
+                            result = (
+                                "ERROR: your reply was cut off at the token limit before "
+                                "the tool call completed. Emit smaller tool calls — e.g. "
+                                "write the file in pieces using multiple write_file/"
+                                "edit_file calls."
+                            )
+                        else:
+                            result = f"ERROR: malformed tool arguments: {e}"
+                    except KeyError:
+                        failures += 1
+                        available_tools = ', '.join(s['function']['name'] for s in TOOL_SCHEMAS)
+                        result = f"ERROR: unknown tool '{name}'. Available: {available_tools}."
+                    except TypeError as e:
+                        failures += 1
+                        result = f"ERROR: bad arguments for {name}: {e}"
+                    self.transcript.write("tool_result", tool=name,
+                                          args=raw_args[:500],
+                                          result=result[:2000])
+                    messages.append({"role": "tool", "tool_call_id": call_id,
+                                     "content": result})
+                    if failures >= MAX_CONSECUTIVE_FAILURES:
+                        return finish("model_error",
+                                      "aborted after repeated malformed tool calls")
+
+                if malformed_count > 0:
+                    messages.append({
+                        "role": "user",
+                        "content": (f"{malformed_count} of your tool calls were malformed "
+                                    "(missing or invalid id/function fields) and were "
+                                    "discarded. Re-issue them as valid tool calls."),
+                    })
+        except KeyboardInterrupt:
+            return finish("interrupted", "")

dirtywork/tools.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from .guardrails import GuardrailError, build_env, check_bash_command, resolve_in_worktree
+
+MAX_RESULT_CHARS = 8000
+
+
+def _cap(text: str, cap: int = MAX_RESULT_CHARS, note: str = "") -> str:
+    if len(text) <= cap:
+        return text
+    suffix = f"\n[output truncated at {cap} chars{note}]"
+    return text[:cap] + suffix
+
+
+def read_file(worktree: Path, path: str, offset: int = 0, limit: int = 400) -> str:
+    try:
+        p = resolve_in_worktree(path, worktree)
+        lines = p.read_text(encoding="utf-8", errors="replace").splitlines()
+    except GuardrailError as e:
+        return f"ERROR: {e}"
+    except OSError as e:
+        return f"ERROR: cannot read '{path}': {e}"
+    window = lines[offset : offset + limit]
+    numbered = "\n".join(f"{i:6}\t{line}" for i, line in enumerate(window, offset + 1))
+    if offset + limit < len(lines):
+        numbered += (
+            f"\n[showing lines {offset + 1}-{offset + len(window)} of {len(lines)}; "
+            f"re-run with offset={offset + limit} for more]"
+        )
+    return _cap(numbered, note=" — re-run with offset/limit to see more")
+
+
+def write_file(worktree: Path, path: str, content: str) -> str:
+    try:
+        p = resolve_in_worktree(path, worktree, writing=True)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+    except GuardrailError as e:
+        return f"ERROR: {e}"
+    except OSError as e:
+        return f"ERROR: cannot write '{path}': {e}"
+    return f"Wrote {len(content.encode('utf-8'))} bytes to {path}"
+
+
+def edit_file(worktree: Path, path: str, old_string: str, new_string: str) -> str:
+    try:
+        p = resolve_in_worktree(path, worktree, writing=True)
+        text = p.read_text(encoding="utf-8")
+    except GuardrailError as e:
+        return f"ERROR: {e}"
+    except UnicodeDecodeError:
+        return f"ERROR: {path} is not valid UTF-8 text; edit_file only works on text files"
+    except OSError as e:
+        return f"ERROR: cannot read '{path}': {e}"
+    count = text.count(old_string)
+    if count != 1:
+        return (
+            f"ERROR: old_string occurs {count} times in {path}; it must occur exactly "
+            f"once. Include more surrounding context to make it unique."
+        )
+    try:
+        p.write_text(text.replace(old_string, new_string, 1), encoding="utf-8")
+    except OSError as e:
+        return f"ERROR: cannot write '{path}': {e}"
+    return f"Edited {path}"
+
+
+def list_dir(worktree: Path, path: str = ".") -> str:
+    try:
+        p = resolve_in_worktree(path, worktree)
+        entries = sorted(p.iterdir(), key=lambda e: e.name)
+    except GuardrailError as e:
+        return f"ERROR: {e}"
+    except OSError as e:
+        return f"ERROR: cannot list '{path}': {e}"
+    rows = []
+    for e in entries:
+        try:
+            if e.is_dir():
+                rows.append(f"{e.name}/")
+            else:
+                rows.append(f"{e.name}  ({e.stat().st_size} bytes)")
+        except OSError:
+            rows.append(f"{e.name}  (broken symlink)")
+    return _cap("\n".join(rows) or "(empty directory)")
+
+
+def grep(worktree: Path, pattern: str, path: str = ".", glob: str | None = None,
+         timeout: int = 30) -> str:
+    try:
+        p = resolve_in_worktree(path, worktree)
+    except GuardrailError as e:
+        return f"ERROR: {e}"
+    except OSError as e:
+        return f"ERROR: cannot access '{path}': {e}"
+    rg = shutil.which("rg")
+    if rg:
+        cmd = [rg, "-n", "--no-heading", "-M", "300", "-e", pattern]
+        if glob:
+            cmd += ["-g", glob]
+        cmd.append(str(p))
+    else:
+        cmd = ["grep", "-rn", "-e", pattern]
+        if glob:
+            cmd += [f"--include={glob}"]
+        cmd.append(str(p))
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return f"ERROR: grep timed out after {timeout}s — narrow the pattern or path."
+    except OSError as e:
+        return f"ERROR: grep failed: {e}"
+    if res.returncode not in (0, 1):
+        return f"ERROR: grep failed: {res.stderr.strip()[:500]}"
+    if not res.stdout.strip():
+        return "No matches found."
+    # strip the worktree prefix so results read as relative paths
+    out = res.stdout.replace(str(worktree.resolve()) + "/", "")
+    return _cap(out, note=" — narrow the pattern or path for full results")
+
+
+MAX_BASH_CHARS = 10000
+
+
+def bash(worktree: Path, command: str, timeout: int = 120) -> str:
+    reason = check_bash_command(command)
+    if reason:
+        return reason  # starts with "BLOCKED:"
+    timeout = max(1, min(int(timeout), 600))
+    try:
+        res = subprocess.run(
+            ["bash", "-c", command],
+            cwd=str(worktree),
+            env=build_env(),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return f"ERROR: command timed out after {timeout}s."
+    except OSError as e:
+        return f"ERROR: bash failed: {e}"
+    combined = (res.stdout + res.stderr).strip()
+    return _cap(f"exit code: {res.returncode}\n{combined}", cap=MAX_BASH_CHARS)
+
+
+def _param(props: dict, required: list) -> dict:
+    return {"type": "object", "properties": props, "required": required}
+
+
+TOOL_SCHEMAS = [
+    {"type": "function", "function": {
+        "name": "read_file",
+        "description": "Read a file, returning numbered lines. Large files are "
+                       "windowed; use offset/limit to page through.",
+        "parameters": _param({
+            "path": {"type": "string", "description": "Path relative to worktree root"},
+            "offset": {"type": "integer", "description": "0-based first line, default 0"},
+            "limit": {"type": "integer", "description": "Max lines, default 400"},
+        }, ["path"])}},
+    {"type": "function", "function": {
+        "name": "write_file",
+        "description": "Create or overwrite a file. Parent directories are created.",
+        "parameters": _param({
+            "path": {"type": "string"},
+            "content": {"type": "string"},
+        }, ["path", "content"])}},
+    {"type": "function", "function": {
+        "name": "edit_file",
+        "description": "Replace old_string with new_string in a file. old_string "
+                       "must occur exactly once — include surrounding context.",
+        "parameters": _param({
+            "path": {"type": "string"},
+            "old_string": {"type": "string"},
+            "new_string": {"type": "string"},
+        }, ["path", "old_string", "new_string"])}},
+    {"type": "function", "function": {
+        "name": "list_dir",
+        "description": "List a directory's entries (dirs end with /).",
+        "parameters": _param({"path": {"type": "string", "description": "Default '.'"}}, [])}},
+    {"type": "function", "function": {
+        "name": "grep",
+        "description": "Search file contents with a regex. Optional glob filter "
+                       "like '*.cs' or '*.tsx'.",
+        "parameters": _param({
+            "pattern": {"type": "string"},
+            "path": {"type": "string", "description": "Default '.'"},
+            "glob": {"type": "string"},
+        }, ["pattern"])}},
+    {"type": "function", "function": {
+        "name": "bash",
+        "description": "Run a shell command in the worktree (cwd is the worktree "
+                       "root). Use for builds/tests/git-status, NEVER for editing "
+                       "files. 120s default timeout, 600s max.",
+        "parameters": _param({
+            "command": {"type": "string"},
+            "timeout": {"type": "integer", "description": "Seconds, default 120, max 600"},
+        }, ["command"])}},
+]
+
+
+class ToolExecutor:
+    """Dispatches validated tool calls. Unknown names raise KeyError."""
+
+    def __init__(self, worktree: Path, transcript=None):
+        self.worktree = worktree
+        self.transcript = transcript
+        self.deadline = None
+        self._table = {
+            "read_file": read_file,
+            "write_file": write_file,
+            "edit_file": edit_file,
+            "list_dir": list_dir,
+            "grep": grep,
+            "bash": bash,
+        }
+
+    def execute(self, name: str, args: dict) -> str:
+        fn = self._table[name]  # KeyError → runner counts a model failure
+        if self.deadline is not None:
+            remaining = self.deadline - time.monotonic()
+            if remaining <= 0:
+                return ("ERROR: run deadline exceeded; stop calling tools and "
+                        "summarize what you have done.")
+            if name in ("bash", "grep"):
+                args = dict(args)
+                default = 120 if name == "bash" else 30
+                args["timeout"] = min(int(args.get("timeout", default)), max(1, int(remaining)))
+        result = fn(self.worktree, **args)
+        if result.startswith("BLOCKED:") and self.transcript is not None:
+            self.transcript.write("guardrail_block", tool=name, args=args, reason=result)
+        return result

dirtywork/transcript.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class Transcript:
+    """Append-only JSONL event log, flushed per line so `tail -f` works."""
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._fh = open(self.path, "a", encoding="utf-8")
+
+    def write(self, event: str, **fields) -> None:
+        record = {"ts": datetime.now(timezone.utc).isoformat(), "event": event}
+        record.update(fields)
+        self._fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+        self._fh.flush()
+
+    def close(self) -> None:
+        self._fh.close()

dirtywork/workspace.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import re
+import secrets
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+
+class WorkspaceError(Exception):
+    """Raised when the target repo or worktree operation is unusable."""
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args], capture_output=True, text=True
+    )
+
+
+def preflight_repo(repo: Path) -> None:
+    if not repo.is_dir():
+        raise WorkspaceError(f"{repo} is not a directory")
+    if _git(repo, "rev-parse", "--is-inside-work-tree").returncode != 0:
+        raise WorkspaceError(f"{repo} is not a git repository")
+    if _git(repo, "rev-parse", "HEAD").returncode != 0:
+        raise WorkspaceError(f"{repo} has no commits (worktrees need a base ref)")
+
+
+def make_slug(task: str, now: datetime, salt: str | None = None) -> str:
+    words = re.sub(r"[^a-z0-9\s-]", "", task.lower()).split()[:5]
+    base = re.sub(r"-+", "-", "-".join(words))[:40].strip("-") or "task"
+    if salt is None:
+        salt = secrets.token_hex(2)
+    return f"{base}-{now.strftime('%m%d%H%M%S')}-{salt}"
+
+
+def create_worktree(repo: Path, slug: str, branch_from: str | None) -> Path:
+    rel = Path(".worktrees") / f"dw-{slug}"
+    ref = branch_from or "HEAD"
+    branch = f"dirtywork/{slug}"
+    existed = _git(repo, "rev-parse", "--verify", "--quiet",
+                    f"refs/heads/{branch}").returncode == 0
+    res = _git(repo, "worktree", "add", "-b", branch, str(rel), ref)
+    if res.returncode != 0:
+        if not existed:
+            _git(repo, "branch", "-D", branch)  # best-effort cleanup; ignore result
+        raise WorkspaceError(f"git worktree add failed: {res.stderr.strip()}")
+    return repo / rel
+
+
+def ensure_worktrees_excluded(repo: Path) -> None:
+    # Use --git-path (not --git-dir) so this resolves to the shared repository's
+    # info/exclude even when `repo` is itself a linked worktree — a linked
+    # worktree's --git-dir is its private .git/worktrees/<name> dir, but git only
+    # ever consults the common/shared info/exclude for status/ignore purposes.
+    res = _git(repo, "rev-parse", "--git-path", "info/exclude")
+    if res.returncode != 0:
+        raise WorkspaceError(f"cannot locate git dir for {repo}")
+    exclude = Path(res.stdout.strip())
+    if not exclude.is_absolute():
+        exclude = repo / exclude
+    exclude.parent.mkdir(parents=True, exist_ok=True)
+    existing = exclude.read_text() if exclude.exists() else ""
+    if ".worktrees/" not in existing:
+        with open(exclude, "a", encoding="utf-8") as fh:
+            if existing and not existing.endswith("\n"):
+                fh.write("\n")
+            fh.write(".worktrees/\n")
+
+
+def load_repo_context(repo: Path) -> str | None:
+    for name in ("CLAUDE.md", "AGENTS.md"):
+        p = repo / name
+        if p.is_file():
+            return p.read_text(encoding="utf-8", errors="replace")
+    return None

dirtywork-0.2.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: dirtywork
+Version: 0.2.0
+Summary: Agentic tool-use loop harness for local LM Studio models — an expensive-model orchestrator's free local workforce
+Author: Dirt Simple Solutions, LLC
+License: MIT
+Project-URL: Repository, https://github.com/JimboSchneider/dirtywork
+Project-URL: Homepage, https://dirtywork.run
+Keywords: llm,agent,lm-studio,local-llm,coding-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dirtywork
+
+[![CI](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml/badge.svg)](https://github.com/JimboSchneider/dirtywork/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dirtywork.svg)](https://pypi.org/project/dirtywork/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://github.com/JimboSchneider/dirtywork/blob/main/pyproject.toml)
+
+*Frontier models do the thinking. Local models do the dirty work.*
+
+Runs one coding task against a local LM Studio model in an agentic tool-use
+loop, inside an isolated git worktree. Built to be driven by an orchestrating
+agent (Claude Code, in our case) — the expensive frontier model orchestrates
+and reviews, the free local model grinds. Humans watch with `tail -f`.
+
+**The division of labor:**
+
+| | Role |
+|---|---|
+| Orchestrator (a frontier model, e.g. Claude Code — or you) | Picks the task, invokes `dirtywork`, reviews the worktree diff and transcript, commits/PRs what survives review |
+| Worker (local model, via dirtywork) | Explores the repo, edits files, runs builds/tests — inside a worktree it cannot escape |
+
+Nothing the local model does touches your main checkout, and nothing it
+produces merges without review. Parallelism comes from launching multiple
+processes — LM Studio serves 4 concurrent requests per model.
+
+## Requirements
+
+- macOS/Linux, Python 3.9+ (stdlib only — no venv, no pip deps)
+- [LM Studio](https://lmstudio.ai) serving its OpenAI-compatible API at
+  `localhost:1234` with a tool-calling-capable model loaded. Verified
+  working: `qwen/qwen3-coder-next` (65k context, default) and
+  `mistralai/devstral-small-2-2512` (32k context)
+- The target repo must be a git repo with at least one commit
+
+**Other servers:** anything speaking the OpenAI chat-completions API with tool
+calling should work via `--base-url` (e.g. Ollama at
+`http://localhost:11434/v1`) — but only LM Studio is tested today. Reports
+welcome.
+
+## Install
+
+**pipx (PyPI):**
+
+    pipx install dirtywork
+
+**pipx (straight from GitHub):**
+
+    pipx install git+https://github.com/JimboSchneider/dirtywork
+
+**From source:**
+
+    git clone https://github.com/JimboSchneider/dirtywork
+    cd dirtywork
+    chmod +x bin/dirtywork
+    ln -sf "$PWD/bin/dirtywork" ~/.local/bin/dirtywork
+
+The launcher is self-locating, so this works from any clone location.
+
+## Use
+
+    dirtywork run --repo ~/repos/someproject "Add a unit test for X"
+
+- **Watch a run:** `tail -f` the transcript path printed on stderr.
+- **Review a run:** `git -C <worktree> diff`, read the transcript, run the
+  repo's tests — then commit the branch or discard it.
+- **Discard a run:**
+  `git -C <repo> worktree remove --force <worktree> && git -C <repo> branch -D dirtywork/<slug>`
+
+## How a run works
+
+1. **Preflight** — LM Studio reachable, model loaded, repo valid. Any
+   failure exits 2 with nothing created.
+2. **Worktree** — a fresh worktree at `<repo>/.worktrees/dw-<slug>` on new
+   branch `dirtywork/<slug>`, branched from `--branch-from` (default:
+   repo HEAD). `.worktrees/` is added to the repo's local
+   `.git/info/exclude` automatically. If the repo has a `CLAUDE.md` or
+   `AGENTS.md` at its root, its content is injected into the worker's
+   system prompt so it inherits your conventions.
+3. **The loop** — the model gets six tools (`read_file`, `write_file`,
+   `edit_file`, `list_dir`, `grep`, `bash`) via OpenAI function-calling and
+   works until it replies without calling a tool. Context is budgeted per
+   model (oldest tool results get trimmed first); three consecutive
+   malformed tool calls abort the run.
+4. **No auto-commit** — changes stay uncommitted in the worktree; the
+   transcript lands at `~/.dirtywork/runs/<slug>/transcript.jsonl`
+   (outside the worktree, so it can never pollute the diff).
+
+## Safety model
+
+Guardrails block **accidents, not adversaries** — the post-run review is
+the real gate:
+
+- All file tools are path-confined to the worktree (symlink-safe realpath
+  checks; `.git/` is write-protected against hook injection).
+- `bash` runs cwd-pinned in the worktree with a minimal environment (your
+  shell's tokens/keys are not inherited) and a regex denylist: `sudo`,
+  `git push`, `rm`/`mv`/`chmod`/`chown` on absolute or `~` paths,
+  `cd`/`pushd` escapes, downloads piped to a shell, system-control
+  commands, redirects outside the worktree.
+- Every denylist rejection is logged to the transcript as a
+  `guardrail_block` event, so attempted escapes are visible at review time.
+- Network is allowed (package restores need it); per-command timeout 120s
+  default, 600s max.
+
+Plainly: this is **not a sandbox**. Run it against repos where you'd trust
+yourself to review the diff — because that review is the actual gate.
+
+## Development
+
+    python3 -m pytest              # unit suite (no LM Studio needed)
+    python3 -m pytest -m live -v   # live suite (requires LM Studio running;
+                                   # includes a real end-to-end agent run)
+
+Design docs: `docs/superpowers/specs/2026-08-13-localagent-design.md`
+(architecture and contracts) and
+`docs/superpowers/plans/2026-08-14-localagent.md` (implementation plan).
+
+## The story
+
+dirtywork was designed, built, reviewed, and shipped in one day — by the
+exact orchestrator/worker pattern it implements — and its first production
+run surfaced a real cent-level rounding bug in the invoicing app it was
+pointed at. The full postmortem, including a build-one-yourself recipe:
+[the postmortem](https://github.com/JimboSchneider/dirtywork/blob/main/docs/2026-08-14-building-localagent.md)
+(or read [the designed HTML edition](https://dirtywork.run/building-localagent.html)
+served via Pages).
+
+In August 2026 the project was renamed **dirtywork** — same tool, a name that says what it does.
+
+## Troubleshooting
+
+- **exit 2, "cannot reach LM Studio"** — server not running; check `lms ps`
+  and `curl -s localhost:1234/v1/models`.
+- **exit 2, "model not loaded"** — `lms load <model>` (the error names the
+  loaded models).
+- **status `max_turns` / `timeout`** — the worktree is kept; read the
+  transcript to see where it stalled, salvage what's useful, or re-run with
+  higher limits.
+- **status `context_exhausted`** — the task needed more context than the
+  model's window; split the task or use the larger-context model.
+
+## Machine contract
+
+`dirtywork` is built to be driven by another agent (Claude Code) rather than
+read by a human — the primary consumer parses stdout, not the terminal.
+
+**Flags:**
+
+```
+dirtywork run --repo <path> "<task>"
+    [--model qwen/qwen3-coder-next]   # or mistralai/devstral-small-2-2512
+    [--branch-from <ref>]             # default: repo HEAD
+    [--max-turns 40]
+    [--timeout 1800]                  # whole-run wall clock, seconds
+    [--temperature <f>]               # omitted by default → server preset
+    [--base-url http://localhost:1234/v1]  # LM Studio's OpenAI-compatible endpoint
+```
+
+**stdout:** on any run that gets past preflight, exactly one JSON object is
+printed to stdout (nothing else goes to stdout):
+
+```json
+{
+  "status": "completed",
+  "worktree": "/path/to/repo/.worktrees/dw-<slug>",
+  "branch": "dirtywork/<slug>",
+  "transcript": "/path/to/transcript.jsonl",
+  "turns": 7,
+  "usage": {"prompt_tokens": 0, "completion_tokens": 0},
+  "final_message": "..."
+}
+```
+
+`status` is one of: `completed`, `max_turns`, `timeout`,
+`context_exhausted`, `model_error`, `interrupted`. When the run fails before
+a `RunResult` exists — the LLM client raises, post-worktree setup fails (e.g.
+the transcript can't be created), or any other exception escapes the run
+(status `model_error` in every case) — `turns` is `null` and `usage` is `{}`,
+but `status`, `worktree`, `branch`, and `transcript` are still populated so
+the worktree can be located for salvage.
+
+**Exit codes:**
+
+- `0` — `completed`.
+- `1` — run ended abnormally (`max_turns`, `timeout`, `context_exhausted`,
+  `model_error`, `interrupted`); the worktree and branch are kept for
+  salvage/review. `main` catches every `Exception` the run raises (not just
+  ones the runner itself converts to a status) and reports it as
+  `model_error` via the same JSON contract, so a post-preflight run never
+  tracebacks. (Ctrl-C is a `KeyboardInterrupt`, a `BaseException`, not caught
+  here — but the run loop itself already converts in-loop Ctrl-C to status
+  `interrupted` before it would reach this point.)
+- `2` — preflight or environment error (LM Studio unreachable, model not
+  loaded, `--repo` not a git repo, etc.); nothing is created.
+
+All progress (transcript path, worktree path, `error:`-prefixed messages) is
+written to stderr; watch a live run with `tail -f` on the transcript path.
+
+**Transcript events** (JSONL, one per line): `run_start` (task, repo, model,
+config), `assistant` (text + tool calls), `tool_result` (truncated),
+`guardrail_block`, `run_end` (status, turns, duration, cumulative usage).
+
+## Contributing
+
+Issues and PRs welcome. Ground rules:
+
+- Runtime stays **stdlib-only** — that zero-dependency install is a feature,
+  not an accident. Dev-only dependencies (pytest) are fine.
+- `python3 -m pytest` must be green; if your change touches the model-facing
+  path, run the live suite too (`python3 -m pytest -m live -v`, needs a
+  running LM Studio).
+- Tool functions never raise; the client raises `LLMError` only; stdout is
+  exactly one JSON object post-preflight. These contracts have tests — keep
+  them green.
+
+## License
+
+[MIT](https://github.com/JimboSchneider/dirtywork/blob/main/LICENSE) © 2026 Dirt Simple Solutions, LLC

dirtywork-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dirtywork/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+dirtywork/__main__.py,sha256=g9E4aj4OGdN9mxkYfrpvmqpGNBGiLGde70oac4a-ClE,5371
+dirtywork/guardrails.py,sha256=XBpP4sa4h_6C97wVmCQOBPuTWhkP9rI8QeJp0Jqoc1g,2588
+dirtywork/llm.py,sha256=sHJ4RLau_INaYTXjRLhTYz8dGWSA9m5sE9oY5t_lTJc,3067
+dirtywork/runner.py,sha256=9oSbg3Sfm9oij7U4TR_tnJaBWY4ioeGx3Zs40gftILM,9802
+dirtywork/tools.py,sha256=5j-UVKuGNKtLB7-cy9Qk17c-l16TDxiSmOukLs0lBoA,9167
+dirtywork/transcript.py,sha256=rHQGGVK_Pd5EKcsycSQH0w7P31QrpPhw5B6VW169SDM,707
+dirtywork/workspace.py,sha256=2SBfalZcQa-atTDCFZEQlESASyTIX-rarWKffVJwgbg,2961
+dirtywork-0.2.0.dist-info/licenses/LICENSE,sha256=g6jZ9mmdV6YHbQjPgxGgk8Iqv-vaJRWoh4RY9Wy0srQ,1083
+dirtywork-0.2.0.dist-info/METADATA,sha256=k_J3QstKRVoAPmHq-URQupBkEVdJqIpXJuJHWmHAqos,10596
+dirtywork-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+dirtywork-0.2.0.dist-info/entry_points.txt,sha256=JO9-O2lDQWfLkCuYpgtap3xe2cw1CFp_RSfMv2IrF4k,54
+dirtywork-0.2.0.dist-info/top_level.txt,sha256=wlayGLP6ddtjpfsABOphDSBrBb4lp7dcY84tH3Ra6s8,10
+dirtywork-0.2.0.dist-info/RECORD,,

dirtywork-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dirtywork-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dirtywork = dirtywork.__main__:main

dirtywork-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dirt Simple Solutions, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dirtywork-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dirtywork