localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/tools/append_file.py

@@ -0,0 +1,55 @@
+"""append_file - append content to a text file, creating it when needed."""
+from __future__ import annotations
+
+from .base import ToolContext
+from .write_file import _detect_stub_code
+
+
+SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "append_file",
+        "description": (
+            "Append content to a text file, creating the file and parent "
+            "directories if needed. Use this for section-by-section file "
+            "creation or when adding a later section without an edit anchor."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {
+                    "type": "string",
+                    "description": "Content to append to the end of the file",
+                },
+            },
+            "required": ["path", "content"],
+        },
+    },
+}
+
+
+def execute(ctx: ToolContext, args: dict) -> str:
+    if "path" not in args:
+        return "Error: 'path' argument is required for append_file."
+    if "content" not in args:
+        return "Error: 'content' argument is required for append_file."
+
+    rel_path = str(args["path"])
+    path = ctx.resolve_write_path(rel_path)
+    if path.is_dir():
+        return f"Error: append_file cannot append to directory: {rel_path}"
+    content = str(args.get("content", ""))
+    stub = _detect_stub_code(content, rel_path)
+    if stub:
+        return stub
+
+    created = not path.exists()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = "" if created else path.read_text(errors="replace")
+    separator = "" if not existing or existing.endswith("\n") or content.startswith("\n") else "\n"
+    path.write_text(existing + separator + content)
+    appended_lines = content.count("\n") + (1 if content else 0)
+    total_lines = (existing + separator + content).count("\n") + 1
+    verb = "Created" if created else "Appended"
+    return f"{verb} {rel_path}; added {appended_lines} lines ({total_lines} total lines)"

localcode/tools/background_process.py

@@ -0,0 +1,115 @@
+"""Explicit lifecycle tool for supervised background commands."""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+
+from .base import ToolContext
+from .._subproc_env import clean_env
+from ..process_registry import (
+    ProcessRecord,
+    find_record,
+    load_records,
+    mark_spawned,
+    record_process,
+    refresh_record,
+    save_records,
+    spawned_this_session,
+)
+
+SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "background_process",
+        "description": "Start, poll, list, or stop a supervised background command. Returns a stable process ID and incremental output.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "action": {"type": "string", "enum": ["start", "poll", "list", "stop"]},
+                "command": {"type": "string", "description": "Required for start."},
+                "process_id": {"type": "string", "description": "Required for poll/stop."},
+                "offset": {"type": "integer", "description": "Byte offset for incremental poll output.", "default": 0},
+                "owner": {"type": "string", "description": "Logical owner label.", "default": "agent"},
+            },
+            "required": ["action"],
+        },
+    },
+}
+
+def _status(record: ProcessRecord) -> str:
+    return "stopped" if record.stopped_at else "running"
+
+def execute(ctx: ToolContext, args: dict) -> str:
+    action = str(args.get("action", ""))
+    if action == "list":
+        records = load_records(ctx.repo)
+        if not records:
+            return "No supervised background processes."
+        return "\n".join(f"{r.process_id} {_status(refresh_record(ctx.repo, r.process_id) or r)} owner={r.owner} pid={r.pid} command={r.command}" for r in records[-50:])
+    process_id = str(args.get("process_id", ""))
+    if action in {"poll", "stop"} and not process_id:
+        return f"Error: process_id is required for {action}."
+    if action == "start":
+        command = str(args.get("command", "")).strip()
+        if not command:
+            return "Error: command is required for start."
+        log_dir = ctx.repo / ".localcode" / "process-logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        provisional = ProcessRecord(pid=0, pgid=0, port=0, url="", cwd=str(ctx.repo), kind="background", command=command, log_path="", verified=False, started_at=time.time(), owner=str(args.get("owner", "agent")))
+        log_path = log_dir / f"{provisional.process_id}.log"
+        stream = log_path.open("ab", buffering=0)
+        try:
+            proc = subprocess.Popen(command, cwd=ctx.repo, shell=True, executable="/bin/sh", stdout=stream, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, env=clean_env(), start_new_session=True)
+        finally:
+            stream.close()
+        mark_spawned(proc.pid)
+        provisional.pid = proc.pid
+        provisional.pgid = proc.pid
+        provisional.log_path = str(log_path)
+        record_process(ctx.repo, provisional)
+        return f"Started {provisional.process_id}: status=running pid={proc.pid} owner={provisional.owner} output_offset=0"
+    record = refresh_record(ctx.repo, process_id)
+    if record is None:
+        return f"Error: unknown process_id: {process_id}"
+    if action == "stop":
+        if not record.stopped_at:
+            target = record.pgid or record.pid
+            # Registry records are durable on-disk state. Refuse to signal
+            # any pid this LocalCode process did not spawn — a crafted or
+            # stale record must never drive killpg at an arbitrary pid.
+            if target <= 1 or not (spawned_this_session(record.pid) or spawned_this_session(target)):
+                return (
+                    f"Error: refusing to stop {process_id}: its pid was not "
+                    "started by this session (stop it manually if needed)."
+                )
+            try:
+                os.killpg(target, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            except OSError as exc:
+                return f"Error: could not stop {process_id}: {exc}"
+            records = load_records(ctx.repo)
+            for item in records:
+                if item.process_id == process_id:
+                    item.stopped_at = time.time()
+            save_records(ctx.repo, records)
+        return f"Stopped {process_id}."
+    if action == "poll":
+        offset = max(0, int(args.get("offset", 0)))
+        data = b""
+        try:
+            with Path(record.log_path).open("rb") as handle:
+                handle.seek(offset)
+                data = handle.read(64_000)
+                next_offset = handle.tell()
+        except OSError:
+            next_offset = offset
+        output = data.decode(errors="replace")
+        return f"id={process_id} status={_status(record)} pid={record.pid} next_offset={next_offset}\n{output}".rstrip()
+    return f"Error: unsupported action: {action}"
+
+def is_concurrency_safe(args: dict) -> bool:
+    return str(args.get("action")) in {"poll", "list"}

localcode/tools/base.py

@@ -0,0 +1,168 @@
+"""Shared types for tool modules.
+
+Each tool lives in its own file under src/localcode/tools/ and exports two
+symbols:
+
+  SCHEMA:   dict — the OpenAI-compatible function schema handed to the
+            model. See TOOL_SCHEMAS usage in src/localcode/agent.py.
+
+  execute:  callable (ctx: ToolContext, args: dict) -> str — invoked
+            when the model picks this tool. Returns the result string
+            that's fed back as the `tool` message.
+
+Per-tool files + co-located schema+exec is the minimal-agent / terminal coding tools Agent
+SDK convention. Makes adding a tool a one-file change, keeps description
+next to the code that implements it, and enables per-tool unit tests.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from ..app import LocalCodeApp
+    from ..output import OutputManager
+
+
+@dataclass
+class ToolContext:
+    """Everything a tool might need to do its job.
+
+    Keep this deliberately small — if a tool can be done with just
+    `repo` (Path) and `args` (dict), prefer that. Reach for `app` or
+    `out` only when you need the full agent state or the TUI output
+    manager.
+    """
+    app: "LocalCodeApp"
+    out: "OutputManager"
+
+    @property
+    def repo(self) -> Path:
+        return self.app.repo_root
+
+    @property
+    def check_root(self) -> Path:
+        """Where project checks (ruff/tsc/...) may scan — see app.check_root."""
+        return getattr(self.app, "check_root", None) or self.app.repo_root
+
+    def resolve_path(self, raw: str) -> Path:
+        """Resolve a tool `path` argument, healing corrupted repo prefixes.
+
+        Small quantized models corrupt long absolute paths when they copy
+        them between calls. Observed live (2026-07-13): the model turned the
+        workdir `…/localcode-evals/20260713-024502/tempconv` into
+        `…/localcode-evals/2026-0713-0245-02/tempconv` — hyphens
+        hallucinated into the timestamp — and every subsequent write landed
+        in a phantom tree while the real project stayed empty. Same class of
+        fix as fuzzy old_string matching in edit_file: if an absolute path
+        is NOT under repo_root but its leading components are a near-match
+        of repo_root's (difflib ratio ≥ 0.8 per component), remap that
+        prefix onto the real repo_root. Anything else passes through
+        untouched — reads intentionally have full filesystem access.
+
+        NOTE: this method does NOT contain the path. Write tools must call
+        `resolve_write_path()` instead, which applies the same healing and
+        then refuses anything that lands outside the project root.
+        """
+        p = self.repo / raw
+        try:
+            root = self.repo.resolve()
+            rp = p.resolve()
+            if root == rp or root in rp.parents:
+                return p  # already inside the project — nothing to heal
+            root_parts = root.parts
+            path_parts = rp.parts
+            if len(path_parts) <= len(root_parts):
+                return p
+            import difflib
+            for a, b in zip(root_parts, path_parts):
+                if a == b:
+                    continue
+                if difflib.SequenceMatcher(None, a, b).ratio() < 0.8:
+                    return p  # genuinely different location — respect it
+            healed = root.joinpath(*path_parts[len(root_parts):])
+            try:
+                from ..events import emit as _emit
+                _emit("path_remap", raw=str(raw)[:200], healed=str(healed)[:200])
+            except Exception:
+                pass
+            return healed
+        except Exception:
+            return p
+
+    def resolve_write_path(self, raw: str) -> Path:
+        """Resolve a WRITE target: heal first, then enforce containment.
+
+        Healing runs exactly as it does for reads (small quants mangle long
+        absolute paths, and a mangled path that near-matches repo_root is
+        remapped onto it). Containment is applied to the healed result, so
+        the heal feature keeps working while `/Users/victim/.zshrc`,
+        `../../../etc/hosts`, and a repo-internal symlink pointing outside
+        all raise `PathContainmentError`.
+
+        Escape hatches, in order:
+          * the agent's notebook scratch dir (sanctioned, may live outside
+            the project root), and
+          * paths the USER has explicitly approved this session, recorded on
+            `app._approved_write_paths` — approval is a human decision, so an
+            approved path is never re-blocked here.
+        """
+        from ..paths import PathContainmentError, contain_write_path
+
+        healed = self.resolve_path(raw)
+
+        approved = getattr(self.app, "_approved_write_paths", None)
+        if approved:
+            try:
+                if str(Path(healed).resolve()) in {str(Path(a).resolve()) for a in approved}:
+                    return Path(healed).resolve()
+            except Exception:
+                pass
+
+        try:
+            return contain_write_path(healed, self.repo)
+        except PathContainmentError:
+            # Outside the project — the notebook scratch dir is the one
+            # sanctioned exception. Checked lazily so the common (contained)
+            # case never touches the notebook module.
+            try:
+                from ..notebook import is_within_notebook
+                if is_within_notebook(Path(healed)):
+                    return Path(healed).resolve()
+            except Exception:
+                pass
+            try:
+                from ..events import emit as _emit
+                _emit("write_containment_block", raw=str(raw)[:200],
+                      resolved=str(healed)[:200])
+            except Exception:
+                pass
+            raise
+
+
+@dataclass
+class ToolResult:
+    """Internal typed tool result.
+
+    Tools may continue returning plain strings. The dispatcher normalizes
+    both forms to this type so the agent loop can reason over facts while
+    preserving the exact text sent back to the model/UI.
+    """
+    text: str
+    ok: bool = True
+    facts: dict = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return self.text
+
+
+class ToolModule(Protocol):
+    """Structural type every tool module satisfies."""
+    SCHEMA: dict
+
+    @staticmethod
+    def execute(ctx: ToolContext, args: dict) -> str: ...  # noqa: E704
+
+    @staticmethod
+    def is_concurrency_safe(args: dict) -> bool: ...  # noqa: E704