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

local_coding_agent/terminal/_tools.py

@@ -0,0 +1,233 @@
+"""Model-facing terminal tool schemas and handlers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..terminal._manager import TerminalManager
+
+
+# ============================================================================
+# Model-Facing Tool Schemas and Handlers
+# ============================================================================
+
+def get_terminal_tool_schemas() -> list[dict[str, Any]]:
+    """Return JSON schemas for the 6 persistent terminal tools."""
+    return [
+        {
+            "name": "terminal_open",
+            "description": "Create a persistent interactive terminal session (e.g. bash, cmd, REPL) that survives across tool calls.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Unique identifier for this terminal session (e.g. 'main', 'build', 'gdb').",
+                    },
+                    "cwd": {
+                        "type": "string",
+                        "description": "Initial working directory. Defaults to workspace root.",
+                    },
+                    "shell": {
+                        "type": "string",
+                        "description": "Shell or interactive command to launch (e.g. 'bash', 'powershell', 'python -i'). Defaults to system shell.",
+                    },
+                },
+                "required": ["session_id"],
+            },
+        },
+        {
+            "name": "terminal_send",
+            "description": "Send text or commands to a persistent terminal and receive the resulting output delta.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID returned by terminal_open.",
+                    },
+                    "text": {
+                        "type": "string",
+                        "description": "Input text or command line to send.",
+                    },
+                    "wait_ms": {
+                        "type": "integer",
+                        "description": "Milliseconds to wait for output after sending (default 500).",
+                        "default": 500,
+                    },
+                    "submit": {
+                        "type": "boolean",
+                        "description": "Whether to append a newline (Enter) after text (default true).",
+                        "default": True,
+                    },
+                },
+                "required": ["session_id", "text"],
+            },
+        },
+        {
+            "name": "terminal_read",
+            "description": "Read a bounded window from a terminal session's retained output buffer without sending input.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to read from.",
+                    },
+                    "offset": {
+                        "type": "integer",
+                        "description": "Character offset to start reading from (default 0; negative offsets count from end).",
+                        "default": 0,
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of characters to return (default 4096).",
+                        "default": 4096,
+                    },
+                },
+                "required": ["session_id"],
+            },
+        },
+        {
+            "name": "terminal_signal",
+            "description": "Deliver a control signal to the terminal (e.g. SIGINT/Ctrl+C, SIGTERM, SIGKILL).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Target terminal session ID.",
+                    },
+                    "signal": {
+                        "type": "string",
+                        "description": "Signal to deliver ('SIGINT', 'SIGTERM', 'SIGKILL', etc.).",
+                        "enum": ["SIGINT", "SIGTERM", "SIGKILL", "CTRL_C", "SIGBREAK"],
+                    },
+                },
+                "required": ["session_id", "signal"],
+            },
+        },
+        {
+            "name": "terminal_list",
+            "description": "List all active persistent terminal sessions and their current status.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+            },
+        },
+        {
+            "name": "terminal_close",
+            "description": "Close a persistent terminal session and terminate its entire child process tree.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to terminate and close.",
+                    },
+                },
+                "required": ["session_id"],
+            },
+        },
+    ]
+
+
+def execute_terminal_tool(
+    manager: TerminalManager,
+    name: str,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    """Execute a model-facing terminal tool by name with arguments."""
+    if name == "terminal_open":
+        session_id = arguments.get("session_id")
+        if not session_id:
+            return {"ok": False, "error": "session_id is required"}
+        cwd = arguments.get("cwd")
+        shell = arguments.get("shell")
+        try:
+            session = manager.create_session(session_id, cwd=cwd, shell=shell)
+            return {
+                "ok": True,
+                "session_id": session.session_id,
+                "pid": session.pid,
+                "cwd": str(session.cwd),
+                "shell": session.shell_cmd,
+                "status": "running",
+            }
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    elif name == "terminal_send":
+        session_id = arguments.get("session_id")
+        text = arguments.get("text")
+        if not session_id or text is None:
+            return {"ok": False, "error": "session_id and text are required"}
+        wait_ms = int(arguments.get("wait_ms", 500))
+        submit = bool(arguments.get("submit", True))
+        try:
+            output = manager.send_input(session_id, str(text), wait_ms=wait_ms, submit=submit)
+            session = manager.get_session(session_id)
+            return {
+                "ok": True,
+                "session_id": session_id,
+                "output": output,
+                "alive": session.is_alive(),
+                "exit_code": session.exit_code,
+            }
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    elif name == "terminal_read":
+        session_id = arguments.get("session_id")
+        if not session_id:
+            return {"ok": False, "error": "session_id is required"}
+        offset = int(arguments.get("offset", 0))
+        limit = max(0, int(arguments.get("limit", 4096)))
+        try:
+            output = manager.read_buffer(session_id, offset=offset, limit=limit)
+            session = manager.get_session(session_id)
+            return {
+                "ok": True,
+                "session_id": session_id,
+                "output": output,
+                "total_buffer_bytes": len(session.buffer.encode("utf-8")),
+                "offset": offset,
+                "limit": limit,
+            }
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    elif name == "terminal_signal":
+        session_id = arguments.get("session_id")
+        sig = arguments.get("signal")
+        if not session_id or not sig:
+            return {"ok": False, "error": "session_id and signal are required"}
+        try:
+            delivered = manager.send_signal(session_id, str(sig))
+            return {
+                "ok": delivered,
+                "session_id": session_id,
+                "signal": sig,
+                "delivered": delivered,
+            }
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    elif name == "terminal_list":
+        try:
+            sessions = manager.list_sessions()
+            return {"ok": True, "sessions": sessions}
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    elif name == "terminal_close":
+        session_id = arguments.get("session_id")
+        if not session_id:
+            return {"ok": False, "error": "session_id is required"}
+        try:
+            manager.close_session(session_id)
+            return {"ok": True, "session_id": session_id, "closed": True}
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    return {"ok": False, "error": f"Unknown tool: {name}"}

local_coding_agent/terminal/_types.py

@@ -0,0 +1,60 @@
+"""Exceptions and data models for the terminal package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+# ============================================================================
+# Exceptions
+# ============================================================================
+
+class TerminalError(RuntimeError):
+    """Base exception for terminal failures."""
+
+
+class TerminalSessionNotFoundError(TerminalError):
+    """Raised when a requested terminal session does not exist."""
+
+
+class TerminalSessionExistsError(TerminalError):
+    """Raised when creating a session with an ID that is already active."""
+
+
+class TerminalProcessExitedError(TerminalError):
+    """Raised when attempting to interact with a terminal process that has exited."""
+
+
+class TerminalTimeoutError(TerminalError):
+    """Raised when a terminal operation times out."""
+
+
+# ============================================================================
+# Data Models
+# ============================================================================
+
+@dataclass(frozen=True)
+class TerminalSessionInfo:
+    """Snapshot metadata describing a persistent terminal session."""
+
+    session_id: str
+    pid: int
+    alive: bool
+    exit_code: int | None
+    cwd: str
+    shell: str
+    buffer_size: int
+    created_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "pid": self.pid,
+            "alive": self.alive,
+            "exit_code": self.exit_code,
+            "cwd": self.cwd,
+            "shell": self.shell,
+            "buffer_size": self.buffer_size,
+            "created_at": self.created_at,
+        }

local_coding_agent/tool_call_parser.py

@@ -0,0 +1,178 @@
+"""Small-model tool-call emitters -> controller tool_call dicts.
+
+Small local models often cannot emit a proper OpenAI ``tool_calls`` array and
+instead spell a tool call inside their text using one of several ad-hoc
+formats (qwen ``<tool_call>`` JSON, qwen XML ``<function=...>``,
+llama-server ``<|python_tag|>``, mistral ``[TOOL_CALLS]``). This module
+extracts those spans and reshapes them into the SAME dict shape the
+controller's ``_decode_tool_call`` consumes (``{"function": {"name",
+"arguments"}}``), so the controller can promote them into real tool calls.
+
+Standalone on purpose (no controller import) to avoid a circular import; the
+dict shape is duplicated here.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCallExtraction:
+    calls: list[dict[str, Any]] = field(default_factory=list)
+    remaining_text: str = ""
+    formats_detected: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+_FORMATS: list[tuple[str, re.Pattern]] = [
+    ("<tool_call>", re.compile(r"<tool_call>(.*?)</tool_call>", re.S)),
+    ("llama_python_tag", re.compile(r"<\|python_tag\|>(.*?)(?=<|$)", re.S)),
+    ("qwen_xml", re.compile(r"<function=([^>]+)>(.*?)</function>", re.S)),
+    ("mistral_tool_calls", re.compile(r"\[TOOL_CALLS\]\s*(\[[^\]]*\])", re.S)),
+]
+
+# <parameter=K>V</parameter> or <parameter name="K">V</parameter>
+_PARAMETER_RE = re.compile(
+    r"<parameter\s*(?:name=\"([^\"]+)\"|=([^>]+))>(.*?)</parameter>", re.S
+)
+
+
+def _parse_argument(value: str) -> Any:
+    """Parse a qwen-XML parameter value as JSON when possible, else raw string."""
+    try:
+        return json.loads(value)
+    except (TypeError, ValueError):
+        return value
+
+
+def _make_call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    return {"function": {"name": name, "arguments": arguments}}
+
+
+def _matches_allowed(name: str, allowed_names: list[str] | None) -> bool:
+    return not allowed_names or name in allowed_names
+
+
+def _consume(text: str, spans: list[tuple[int, int]]) -> str:
+    """Drop the given [start, end) spans from text, keeping everything else."""
+    if not spans:
+        return text
+    spans = sorted(spans)
+    parts: list[str] = []
+    cursor = 0
+    for start, end in spans:
+        if start > cursor:
+            parts.append(text[cursor:start])
+        cursor = max(cursor, end)
+    parts.append(text[cursor:])
+    return "".join(parts)
+
+
+def _extract_json_calls(
+    text: str,
+    body: str,
+    start: int,
+    end: int,
+    allowed_names: list[str] | None,
+    calls: list[dict[str, Any]],
+    spans: list[tuple[int, int]],
+    is_array: bool,
+    errors: list[str],
+    format_name: str,
+) -> None:
+    """Parse a JSON (object or array) body into calls; consume the span on success."""
+    try:
+        payload = json.loads(body)
+    except (TypeError, ValueError):
+        errors.append(f"{format_name}: malformed JSON tool call")
+        return  # malformed -> span left in remaining_text, no call promoted
+    items = payload if is_array and isinstance(payload, list) else [payload]
+    if not items:
+        return
+    promoted: list[dict[str, Any]] = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            errors.append(f"{format_name}[{index}]: tool call must be an object")
+            continue
+        name = item.get("name")
+        arguments = item.get("arguments")
+        if not isinstance(name, str) or not name or not isinstance(arguments, dict):
+            errors.append(f"{format_name}[{index}]: name and object arguments are required")
+            continue
+        if not _matches_allowed(name, allowed_names):
+            return  # not allowlisted: keep the whole span in remaining text
+        promoted.append(_make_call(name, arguments))
+    if promoted:
+        calls.extend(promoted)
+        spans.append((start, end))
+    elif is_array and isinstance(payload, list) and payload:
+        # array held only invalid items -> consume the span, but retain errors
+        spans.append((start, end))
+
+
+def extract_tool_calls(
+    text: str, allowed_names: list[str] | None = None
+) -> ToolCallExtraction:
+    """Extract small-model tool calls from ``text``.
+
+    Returns a :class:`ToolCallExtraction`. Consumed spans are removed from
+    ``remaining_text``; a call whose name is not in ``allowed_names`` (when
+    provided) is left untouched in the text. Malformed input never raises —
+    worst case an empty ``calls`` list and the original text.
+    """
+    if not isinstance(text, str) or not text.strip():
+        return ToolCallExtraction(remaining_text=text or "", formats_detected=[])
+
+    calls: list[dict[str, Any]] = []
+    spans: list[tuple[int, int]] = []
+    formats_detected: list[str] = []
+    errors: list[str] = []
+
+    for fmt, pattern in _FORMATS:
+        matched = False
+        for m in pattern.finditer(text):
+            matched = True
+            start, end = m.span()
+            if fmt == "<tool_call>":
+                _extract_json_calls(
+                    text, m.group(1), start, end, allowed_names, calls, spans, False,
+                    errors, fmt,
+                )
+            elif fmt == "llama_python_tag":
+                _extract_json_calls(
+                    text, m.group(1), start, end, allowed_names, calls, spans, False,
+                    errors, fmt,
+                )
+            elif fmt == "mistral_tool_calls":
+                _extract_json_calls(
+                    text, m.group(1), start, end, allowed_names, calls, spans, True,
+                    errors, fmt,
+                )
+            elif fmt == "qwen_xml":
+                name = m.group(1).strip()
+                arguments: dict[str, Any] = {}
+                valid = bool(name)
+                for pm in _PARAMETER_RE.finditer(m.group(2)):
+                    key = (pm.group(1) or pm.group(2) or "").strip()
+                    if not key:
+                        continue
+                    arguments[key] = _parse_argument(pm.group(3))
+                if not valid or not _matches_allowed(name, allowed_names):
+                    if not valid:
+                        errors.append(f"{fmt}: tool function name is required")
+                    continue  # missing name -> skipped; not allowed -> kept in text
+                calls.append(_make_call(name, arguments))
+                spans.append((start, end))
+        if matched:
+            formats_detected.append(fmt)
+
+    return ToolCallExtraction(
+        calls=calls,
+        remaining_text=_consume(text, spans),
+        formats_detected=formats_detected,
+        errors=errors,
+    )