local-coding-agent 1.1.0__py3-none-any.whl

local_coding_agent/speculative_racing.py

@@ -0,0 +1,85 @@
+"""Speculative Multi-Drafting & Model Racing Engine (R19).
+
+Coordinates concurrent speculative drafts across model clients and worker pools,
+accepting the first passing candidate and cancelling competing workers to boost
+first-attempt success rates with low latency.
+"""
+
+from __future__ import annotations
+
+import queue
+from concurrent.futures import ThreadPoolExecutor
+from threading import Event
+from typing import Any, Callable, Sequence
+
+
+class SpeculativeRacer:
+    """Coordinates racing between multiple speculative task drafts."""
+
+    def run(
+        self,
+        runners: Sequence[Callable[[Event], dict[str, Any]]],
+        *,
+        cancel_event: Event | None = None,
+    ) -> dict[str, Any]:
+        if not runners:
+            return {"status": "failed", "error": "no runners provided"}
+
+        if cancel_event is not None and cancel_event.is_set():
+            return {"status": "failed", "error": "cancelled"}
+
+        result_queue: queue.Queue[tuple[int, dict[str, Any]]] = queue.Queue()
+        local_cancels: list[Event] = [Event() for _ in runners]
+
+        def _worker_wrapper(idx: int, runner_fn: Callable[[Event], dict[str, Any]]) -> None:
+            runner_cancel = local_cancels[idx]
+            try:
+                if cancel_event is not None and cancel_event.is_set():
+                    runner_cancel.set()
+                res = runner_fn(runner_cancel)
+                result_queue.put((idx, res))
+            except Exception as exc:
+                result_queue.put((idx, {"status": "failed", "error": str(exc)}))
+
+        executor = ThreadPoolExecutor(max_workers=len(runners))
+        try:
+            for i, runner in enumerate(runners):
+                executor.submit(_worker_wrapper, i, runner)
+
+            completed_count = 0
+            fallback_result: dict[str, Any] | None = None
+
+            while completed_count < len(runners):
+                if cancel_event is not None and cancel_event.is_set():
+                    for ev in local_cancels:
+                        ev.set()
+                    return {"status": "failed", "error": "cancelled"}
+
+                try:
+                    idx, result = result_queue.get(timeout=0.05)
+                    completed_count += 1
+                except queue.Empty:
+                    continue
+
+                if result.get("status") == "accepted":
+                    # Winner found! Cancel all remaining racers
+                    for j, ev in enumerate(local_cancels):
+                        if j != idx:
+                            ev.set()
+                    audit = result.get("audit")
+                    if isinstance(audit, list):
+                        audit.append({
+                            "event": "speculative_race_winner",
+                            "draft_index": idx,
+                            "total_drafts": len(runners),
+                        })
+                    return result
+
+                if fallback_result is None:
+                    fallback_result = result
+
+            return fallback_result or {"status": "failed", "error": "no result"}
+        finally:
+            for ev in local_cancels:
+                ev.set()
+            executor.shutdown(wait=False, cancel_futures=True)

local_coding_agent/spill.py

@@ -0,0 +1,258 @@
+"""Tool Output Spill Store for bounding model context size.
+
+Adapted from DeepSeek Harness @deepseek-ai/dsh-spill and @deepseek-ai/dsh-spill-policy.
+Manages session-scoped artifact persistence for oversized tool outputs with
+path-traversal protection and secure permissions.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_MAX_BYTES: int = 30 * 1024  # 30KB
+DEFAULT_MAX_LINES: int = 1000
+
+
+@dataclass(frozen=True)
+class SpillRef:
+    """Descriptor for a persisted tool output spill artifact."""
+
+    locator: str
+    bytes: int
+    lines: int
+    preview_head: str
+    preview_tail: str
+    retrieval_hint: str
+
+
+class SpillStore:
+    """Session-scoped storage backend for oversized tool outputs."""
+
+    def __init__(self, root_dir: Path | str | None = None) -> None:
+        if root_dir is None:
+            self.root_dir = (Path.cwd() / ".local_agent" / "spill").resolve()
+        else:
+            self.root_dir = Path(root_dir).resolve()
+
+    def _sanitize_session_id(self, session_id: str) -> str:
+        """Derive a safe, injective directory segment from an untrusted session ID."""
+        if not session_id or session_id in (".", ".."):
+            return "session_default"
+        # Remove path separators and traversal tokens
+        cleaned = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id).strip(".")
+        if not cleaned:
+            cleaned = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:16]
+        return f"session_{cleaned}"
+
+    def _sanitize_file_name(self, name: str) -> str:
+        """Derive a safe filename without path separators."""
+        base_name = Path(name).name
+        cleaned = re.sub(r"[^A-Za-z0-9_.-]", "_", base_name).strip(".")
+        return cleaned or "output.txt"
+
+    def _get_session_dir(self, session_id: str) -> Path:
+        """Get the absolute session directory and assert it stays within root_dir."""
+        safe_seg = self._sanitize_session_id(session_id)
+        session_path = (self.root_dir / safe_seg).resolve()
+        try:
+            session_path.relative_to(self.root_dir)
+        except ValueError as err:
+            raise ValueError(f"Path traversal detected for session_id '{session_id}'") from err
+        return session_path
+
+    def save_text(
+        self,
+        session_id: str,
+        content: str,
+        source_tool: str = "tool",
+        suggested_name: str = "output.txt",
+    ) -> SpillRef:
+        """Persist text content to a session-scoped spill file and return a SpillRef."""
+        session_dir = self._get_session_dir(session_id)
+        session_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if os.name != "nt":
+            try:
+                os.chmod(session_dir, 0o700)
+            except OSError:
+                pass
+
+        safe_name = self._sanitize_file_name(suggested_name)
+        file_id = uuid.uuid4().hex[:12]
+        target_file = (session_dir / f"{file_id}_{safe_name}").resolve()
+
+        try:
+            target_file.relative_to(self.root_dir)
+        except ValueError as err:
+            raise ValueError(f"Path traversal detected for target file '{target_file}'") from err
+
+        encoded = content.encode("utf-8")
+        byte_count = len(encoded)
+
+        # Split preserving newlines for accurate reconstruction
+        raw_lines = content.splitlines(keepends=True)
+        line_count = len(raw_lines)
+
+        # Write securely with exclusive creation / owner-only permissions (0600 on POSIX)
+        flags = os.O_CREAT | os.O_WRONLY | os.O_TRUNC
+        if hasattr(os, "O_EXCL"):
+            flags |= os.O_EXCL
+        fd = os.open(str(target_file), flags, 0o600)
+        with open(fd, "wb") as f:
+            f.write(encoded)
+
+        if os.name != "nt":
+            try:
+                os.chmod(target_file, 0o600)
+            except OSError:
+                pass
+
+        # Build head & tail previews (up to 20 lines each)
+        preview_limit = 20
+        preview_head = "".join(raw_lines[:preview_limit])
+        preview_tail = "".join(raw_lines[-preview_limit:])
+
+        locator = target_file.as_posix()
+        retrieval_hint = f"read_spill(locator='{locator}', offset_line=0, limit_lines=1000)"
+
+        return SpillRef(
+            locator=locator,
+            bytes=byte_count,
+            lines=line_count,
+            preview_head=preview_head,
+            preview_tail=preview_tail,
+            retrieval_hint=retrieval_hint,
+        )
+
+    def read_spill(self, locator: str, offset_line: int = 0, limit_lines: int = 1000) -> str:
+        """Read a slice of lines from a persisted spill artifact."""
+        target_path = Path(locator).resolve()
+        try:
+            target_path.relative_to(self.root_dir)
+        except ValueError as err:
+            raise ValueError(
+                f"Path traversal detected: locator '{locator}' is outside spill root '{self.root_dir}'"
+            ) from err
+
+        if not target_path.is_file():
+            raise FileNotFoundError(f"Spill artifact not found: {locator}")
+
+        if offset_line < 0:
+            offset_line = 0
+        if limit_lines < 0:
+            limit_lines = 0
+
+        with open(target_path, "r", encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+
+        selected = lines[offset_line : offset_line + limit_lines]
+        return "".join(selected)
+
+    def maybe_spill(
+        self,
+        session_id: str,
+        content: str,
+        source_tool: str = "tool",
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        max_lines: int = DEFAULT_MAX_LINES,
+    ) -> tuple[bool, str, SpillRef | None]:
+        """Check content against byte and line thresholds, spilling if exceeded.
+
+        Returns:
+            (spilled: bool, resulting_message: str, ref: SpillRef | None)
+        """
+        encoded_len = len(content.encode("utf-8"))
+        raw_lines = content.splitlines(keepends=True)
+        line_count = len(raw_lines)
+
+        if encoded_len <= max_bytes and line_count <= max_lines:
+            return False, content, None
+
+        ref = self.save_text(
+            session_id=session_id,
+            content=content,
+            source_tool=source_tool,
+            suggested_name=f"{source_tool}_output.txt",
+        )
+
+        omitted_lines = max(0, line_count - 40)
+        notice = (
+            f"[OUTPUT TRUNCATED & SPILLED TO STORE]\n"
+            f"Tool '{source_tool}' produced {ref.bytes} bytes ({ref.lines} lines), "
+            f"exceeding limits ({max_bytes} bytes / {max_lines} lines).\n"
+            f"Full output was saved to locator: {ref.locator}\n\n"
+            f"--- BEGIN PREVIEW (HEAD) ---\n"
+            f"{ref.preview_head.rstrip()}\n"
+            f"--- END PREVIEW (HEAD) ---\n"
+            f"... [{omitted_lines} lines omitted] ...\n"
+            f"--- BEGIN PREVIEW (TAIL) ---\n"
+            f"{ref.preview_tail.rstrip()}\n"
+            f"--- END PREVIEW (TAIL) ---\n\n"
+            f"Retrieval guidance: {ref.retrieval_hint}"
+        )
+
+        return True, notice, ref
+
+
+# Global default instance & convenience helpers
+_DEFAULT_SPILL_STORE: SpillStore | None = None
+
+
+def get_default_spill_store() -> SpillStore:
+    """Retrieve or lazily initialize the default SpillStore instance."""
+    global _DEFAULT_SPILL_STORE
+    if _DEFAULT_SPILL_STORE is None:
+        _DEFAULT_SPILL_STORE = SpillStore()
+    return _DEFAULT_SPILL_STORE
+
+
+def save_text(
+    session_id: str,
+    content: str,
+    source_tool: str = "tool",
+    suggested_name: str = "output.txt",
+) -> SpillRef:
+    """Save text content to the default spill store."""
+    return get_default_spill_store().save_text(
+        session_id=session_id,
+        content=content,
+        source_tool=source_tool,
+        suggested_name=suggested_name,
+    )
+
+
+def read_spill(locator: str, offset_line: int = 0, limit_lines: int = 1000) -> str:
+    """Read a slice of lines from a spill locator."""
+    # Check if locator is under an explicit custom root or default root
+    store = get_default_spill_store()
+    target_path = Path(locator).resolve()
+    try:
+        target_path.relative_to(store.root_dir)
+        return store.read_spill(locator, offset_line, limit_lines)
+    except ValueError:
+        # Fall back to resolving within locator's parent spill directory
+        parent_dir = target_path.parent
+        custom_store = SpillStore(root_dir=parent_dir.parent)
+        return custom_store.read_spill(locator, offset_line, limit_lines)
+
+
+def maybe_spill(
+    session_id: str,
+    content: str,
+    source_tool: str = "tool",
+    max_bytes: int = DEFAULT_MAX_BYTES,
+    max_lines: int = DEFAULT_MAX_LINES,
+) -> tuple[bool, str, SpillRef | None]:
+    """Check content against thresholds using the default spill store."""
+    return get_default_spill_store().maybe_spill(
+        session_id=session_id,
+        content=content,
+        source_tool=source_tool,
+        max_bytes=max_bytes,
+        max_lines=max_lines,
+    )

local_coding_agent/stats.py

@@ -0,0 +1,255 @@
+"""Minimal, stdlib-only statistics collector for delegation runs.
+
+This is a lightweight observability seam: it counts outcomes and accumulates
+latencies without any third-party dependency, and can optionally append one
+JSONL record per terminal result. It is harness-agnostic — anything that
+produces a controller/service result can feed it.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Any, Mapping
+
+
+class DelegationStats:
+    """Thread-safe counters and latency aggregates over delegation results."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._started_ns = time.monotonic_ns()
+        self.total = 0
+        self.by_status: dict[str, int] = {}
+        self.by_model: dict[str, int] = {}
+        self.by_error_kind: dict[str, int] = {}
+        self.latency_count = 0
+        self.latency_total_ns = 0
+        self.latency_min_ns: int | None = None
+        self.latency_max_ns: int | None = None
+        self.tool_calls = 0
+        self.model_calls = 0
+
+    def record(
+        self,
+        result: Mapping[str, Any],
+        *,
+        model: str | None = None,
+        latency_ns: int | None = None,
+    ) -> None:
+        with self._lock:
+            self.total += 1
+            status = str(result.get("status", "unknown"))
+            self.by_status[status] = self.by_status.get(status, 0) + 1
+            if model:
+                self.by_model[model] = self.by_model.get(model, 0) + 1
+            error = result.get("error")
+            if isinstance(error, Mapping) and error.get("kind"):
+                kind = str(error["kind"])
+                self.by_error_kind[kind] = self.by_error_kind.get(kind, 0) + 1
+            audit = result.get("audit")
+            if isinstance(audit, (list, tuple)):
+                for event in audit:
+                    if isinstance(event, Mapping):
+                        name = event.get("event")
+                        if name == "tool_call":
+                            self.tool_calls += 1
+                        elif name == "model_request":
+                            self.model_calls += 1
+            if latency_ns is not None and latency_ns >= 0:
+                self.latency_count += 1
+                self.latency_total_ns += latency_ns
+                self.latency_min_ns = (
+                    latency_ns
+                    if self.latency_min_ns is None
+                    else min(self.latency_min_ns, latency_ns)
+                )
+                self.latency_max_ns = (
+                    latency_ns
+                    if self.latency_max_ns is None
+                    else max(self.latency_max_ns, latency_ns)
+                )
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            elapsed_s = (time.monotonic_ns() - self._started_ns) / 1_000_000_000
+            latency_avg_ns = (
+                self.latency_total_ns / self.latency_count if self.latency_count else None
+            )
+            return {
+                "elapsed_seconds": round(elapsed_s, 3),
+                "total": self.total,
+                "by_status": dict(self.by_status),
+                "by_model": dict(self.by_model),
+                "by_error_kind": dict(self.by_error_kind),
+                "model_calls": self.model_calls,
+                "tool_calls": self.tool_calls,
+                "latency": {
+                    "count": self.latency_count,
+                    "avg_ms": (
+                        round(latency_avg_ns / 1_000_000, 3)
+                        if latency_avg_ns is not None
+                        else None
+                    ),
+                    "min_ms": (
+                        round(self.latency_min_ns / 1_000_000, 3)
+                        if self.latency_min_ns is not None
+                        else None
+                    ),
+                    "max_ms": (
+                        round(self.latency_max_ns / 1_000_000, 3)
+                        if self.latency_max_ns is not None
+                        else None
+                    ),
+                },
+            }
+
+
+class JsonlStatsSink:
+    """Append one JSON line per record to a UTF-8 file for later inspection."""
+
+    _write_lock = threading.Lock()  # class-level: one lock across all sink instances/process threads.
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def write(self, record: Mapping[str, Any]) -> None:
+        with self._write_lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(dict(record), ensure_ascii=False) + "\n")
+
+
+class TimedDelegationStats:
+    """Convenience wrapper that times a delegate call and records the result."""
+
+    def __init__(
+        self,
+        stats: DelegationStats,
+        *,
+        sink: JsonlStatsSink | None = None,
+    ) -> None:
+        self.stats = stats
+        self.sink = sink
+
+    def __call__(
+        self,
+        delegate,
+        caller_id: str,
+        request,
+        *,
+        model: str | None = None,
+    ) -> Mapping[str, Any]:
+        started = time.monotonic_ns()
+        result = delegate(caller_id, request)
+        latency_ns = time.monotonic_ns() - started
+        self.stats.record(result, model=model, latency_ns=latency_ns)
+        if self.sink is not None:
+            record = {
+                "ts": time.time(),
+                "caller_id": caller_id,
+                "request_id": getattr(request, "request_id", None),
+                "model": model,
+                "status": result.get("status"),
+                "error_kind": (
+                    result.get("error", {}).get("kind")
+                    if isinstance(result.get("error"), Mapping)
+                    else None
+                ),
+                "latency_ms": round(latency_ns / 1_000_000, 3),
+            }
+            self.sink.write(record)
+        return result
+
+
+def default_stats_path() -> Path:
+    """Shared cross-process stats journal location (relative to the cwd)."""
+    return Path(".local-run") / "stats.jsonl"
+
+
+def append_stats(
+    path: str | Path,
+    result: Mapping[str, Any],
+    *,
+    model: str | None = None,
+    latency_ns: int | None = None,
+) -> None:
+    """Append one slim, replayable delegation record. Never raises."""
+    error = result.get("error")
+    record = {
+        "ts": time.time(),
+        "model": model,
+        "status": result.get("status"),
+        "error": {"kind": error.get("kind")} if isinstance(error, Mapping) and error.get("kind") else None,
+        "latency_ms": round(latency_ns / 1_000_000, 3) if latency_ns is not None else None,
+    }
+    try:
+        JsonlStatsSink(path).write(record)
+    except OSError:
+        pass  # ponytail: telemetry must never break a delegation.
+
+
+def load_stats(path: str | Path, *, max_records: int = 2000) -> DelegationStats:
+    """Rebuild aggregate stats by replaying the JSONL journal written by append_stats."""
+    stats = DelegationStats()
+    try:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return stats
+    for line in lines[-max_records:]:
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(rec, dict):
+            continue
+        latency_ms = rec.get("latency_ms")
+        stats.record(
+            rec,
+            model=rec.get("model"),
+            latency_ns=int(latency_ms * 1_000_000) if isinstance(latency_ms, (int, float)) else None,
+        )
+    return stats
+
+
+def merge_stats_snapshots(base: Mapping[str, Any], overlay: Mapping[str, Any]) -> dict[str, Any]:
+    """Merge two DelegationStats.snapshot() dicts (counters summed, latency combined)."""
+    merged = dict(base)
+
+    def _sum_latency(a: Mapping[str, Any], b: Mapping[str, Any]) -> dict[str, Any]:
+        count = (a.get("count") or 0) + (b.get("count") or 0)
+        total_ns = 0.0
+        minimums, maximums = [], []
+        for part in (a, b):
+            if part.get("count"):
+                total_ns += part["avg_ms"] * part["count"] * 1_000_000
+            if part.get("min_ms") is not None:
+                minimums.append(part["min_ms"])
+            if part.get("max_ms") is not None:
+                maximums.append(part["max_ms"])
+        if not count:
+            return {"count": 0, "avg_ms": None, "min_ms": None, "max_ms": None}
+        avg_ns = total_ns / count
+        return {
+            "count": count,
+            "avg_ms": round(avg_ns / 1_000_000, 3),
+            "min_ms": min(minimums) if minimums else None,
+            "max_ms": max(maximums) if maximums else None,
+        }
+
+    for key in ("total", "model_calls", "tool_calls"):
+        if key in base or key in overlay:
+            merged[key] = base.get(key, 0) + overlay.get(key, 0)
+    # elapsed_seconds is intentionally dropped: journal-replay uptime and
+    # server uptime measure different clocks; summing or max-ing misleads.
+    merged.pop("elapsed_seconds", None)
+    for key in ("by_status", "by_model", "by_error_kind"):
+        counts = dict(base.get(key) or {})
+        for name, value in (overlay.get(key) or {}).items():
+            counts[name] = counts.get(name, 0) + value
+        if key in base or key in overlay:
+            merged[key] = counts
+    merged["latency"] = _sum_latency(base.get("latency") or {}, overlay.get("latency") or {})
+    return merged