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

local_coding_agent/task.py

@@ -0,0 +1,90 @@
+"""Task envelope shared by the controller and bounded repository tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class TaskEnvelope:
+    id: str
+    goal: str
+    files: tuple[str, ...]
+    context: str = ""
+    constraints: tuple[str, ...] = ()
+    checks: tuple[str, ...] = ()
+    acceptance: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.id, str) or not self.id.strip():
+            raise ValueError("task field 'id' must be a non-empty string")
+        if not isinstance(self.goal, str) or not self.goal.strip():
+            raise ValueError("task field 'goal' must be a non-empty string")
+        if isinstance(self.files, str) or not isinstance(self.files, (tuple, list)) or not self.files:
+            raise ValueError("task field 'files' must not be empty")
+        for raw_path in self.files:
+            if not isinstance(raw_path, str) or not raw_path or "\x00" in raw_path:
+                raise ValueError("task files must contain valid relative paths")
+            if (
+                raw_path.startswith("/")
+                or raw_path.startswith("\\")
+                or (len(raw_path) >= 2 and raw_path[1] == ":" and raw_path[0].isalpha())
+            ):
+                raise ValueError(f"task file must be relative and inside workspace: {raw_path!r}")
+            path = Path(raw_path)
+            if path.is_absolute() or path.drive or path.root or ".." in path.parts:
+                raise ValueError(f"task file must be relative and inside workspace: {raw_path!r}")
+
+        # A frozen dataclass does not make an incoming list immutable.  Keep the
+        # envelope stable after validation so service-level fingerprints and the
+        # controller always observe the same allowlist and checks.
+        object.__setattr__(self, "files", tuple(self.files))
+        object.__setattr__(self, "constraints", tuple(self.constraints))
+        object.__setattr__(self, "checks", tuple(self.checks))
+        object.__setattr__(self, "acceptance", tuple(self.acceptance))
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "TaskEnvelope":
+        def strings(name: str) -> tuple[str, ...]:
+            raw = value.get(name, ())
+            if isinstance(raw, str) or not isinstance(raw, (list, tuple)):
+                raise ValueError(f"task field '{name}' must be a list of strings")
+            if not all(isinstance(item, str) and item for item in raw):
+                raise ValueError(f"task field '{name}' must contain non-empty strings")
+            return tuple(raw)
+
+        identifier = value.get("id")
+        goal = value.get("goal")
+        context = value.get("context", "")
+        if not isinstance(identifier, str) or not identifier.strip():
+            raise ValueError("task field 'id' must be a non-empty string")
+        if not isinstance(goal, str) or not goal.strip():
+            raise ValueError("task field 'goal' must be a non-empty string")
+        if not isinstance(context, str):
+            raise ValueError("task field 'context' must be a string")
+        files = strings("files")
+        if not files:
+            raise ValueError("task field 'files' must not be empty")
+        return cls(
+            id=identifier,
+            goal=goal,
+            files=files,
+            context=context,
+            constraints=strings("constraints"),
+            checks=strings("checks"),
+            acceptance=strings("acceptance"),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "goal": self.goal,
+            "files": list(self.files),
+            "context": self.context,
+            "constraints": list(self.constraints),
+            "checks": list(self.checks),
+            "acceptance": list(self.acceptance),
+        }
+

local_coding_agent/task_store.py

@@ -0,0 +1,142 @@
+"""Durable storage abstraction for task delegation state and recovery."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Mapping, Protocol
+
+
+@dataclass(frozen=True)
+class TaskRecord:
+    """A durable record representing a delegated task and its terminal outcome."""
+
+    task_id: str
+    caller_id: str
+    request_id: str
+    workspace_ref: str
+    model_profile: str
+    state: str
+    created_at: str
+    updated_at: str
+    result: dict[str, Any] | None = None
+    error: dict[str, Any] | None = None
+    fingerprint: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> TaskRecord:
+        return cls(
+            task_id=str(data["task_id"]),
+            caller_id=str(data["caller_id"]),
+            request_id=str(data["request_id"]),
+            workspace_ref=str(data["workspace_ref"]),
+            model_profile=str(data["model_profile"]),
+            state=str(data["state"]),
+            created_at=str(data.get("created_at", "")),
+            updated_at=str(data.get("updated_at", "")),
+            result=dict(data["result"]) if isinstance(data.get("result"), Mapping) else None,
+            error=dict(data["error"]) if isinstance(data.get("error"), Mapping) else None,
+            fingerprint=str(data.get("fingerprint", "")),
+        )
+
+
+class TaskStore(Protocol):
+    """Protocol for persisting and recovering delegation tasks across restarts."""
+
+    def save(self, record: TaskRecord) -> None: ...
+
+    def get(self, task_id: str) -> TaskRecord | None: ...
+
+    def list(
+        self,
+        caller_id: str | None = None,
+        status: str | None = None,
+        limit: int = 100,
+    ) -> list[TaskRecord]: ...
+
+    def delete(self, task_id: str) -> bool: ...
+
+
+class JsonFileTaskStore:
+    """Thread-safe, filesystem-backed JSON task store with atomic writes."""
+
+    def __init__(self, directory: str | Path) -> None:
+        self._dir = Path(directory)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        self._cache: dict[str, TaskRecord] = {}
+        self._load_and_recover()
+
+    def _load_and_recover(self) -> None:
+        """Scan directory, recover existing task files, and mark interrupted tasks."""
+        with self._lock:
+            for path in self._dir.glob("*.json"):
+                try:
+                    content = path.read_text(encoding="utf-8")
+                    data = json.loads(content)
+                    record = TaskRecord.from_dict(data)
+                    # If previous process crashed while task was running/queued
+                    if record.state in {"queued", "working"}:
+                        record = TaskRecord(
+                            task_id=record.task_id,
+                            caller_id=record.caller_id,
+                            request_id=record.request_id,
+                            workspace_ref=record.workspace_ref,
+                            model_profile=record.model_profile,
+                            state="interrupted",
+                            created_at=record.created_at,
+                            updated_at=record.updated_at,
+                            result=record.result,
+                            error={"kind": "process_interrupted", "message": "task was interrupted by server restart"},
+                            fingerprint=record.fingerprint,
+                        )
+                        self._write_file(record)
+                    self._cache[record.task_id] = record
+                except (json.JSONDecodeError, KeyError, OSError):
+                    continue
+
+    def _write_file(self, record: TaskRecord) -> None:
+        target = self._dir / f"{record.task_id}.json"
+        temp = self._dir / f"{record.task_id}.tmp"
+        data = json.dumps(record.as_dict(), ensure_ascii=False, indent=2)
+        temp.write_text(data, encoding="utf-8")
+        temp.replace(target)
+
+    def save(self, record: TaskRecord) -> None:
+        with self._lock:
+            self._write_file(record)
+            self._cache[record.task_id] = record
+
+    def get(self, task_id: str) -> TaskRecord | None:
+        with self._lock:
+            return self._cache.get(task_id)
+
+    def list(
+        self,
+        caller_id: str | None = None,
+        status: str | None = None,
+        limit: int = 100,
+    ) -> list[TaskRecord]:
+        with self._lock:
+            records = list(self._cache.values())
+            if caller_id is not None:
+                records = [r for r in records if r.caller_id == caller_id]
+            if status is not None:
+                records = [r for r in records if r.state == status]
+            return records[:limit]
+
+    def delete(self, task_id: str) -> bool:
+        with self._lock:
+            if task_id in self._cache:
+                del self._cache[task_id]
+                target = self._dir / f"{task_id}.json"
+                if target.exists():
+                    target.unlink()
+                return True
+            return False

local_coding_agent/tasks.py

@@ -0,0 +1,240 @@
+"""MCP Tasks extension (``io.modelcontextprotocol/tasks``) for async delegation.
+
+The 2026-07-28 stateless protocol moved long-running work into the Tasks
+extension (SEP-2663). This module is the server side of that extension: it
+declares the extension identifier, serves the ``tasks/get``, ``tasks/update``
+and ``tasks/cancel`` methods, and intercepts ``tools/call`` so a
+``delegate_code`` invocation can return a ``CreateTaskResult``
+(``resultType: "task"``) instead of blocking.
+
+The extension does not own policy, validation or result state. It is a thin
+wire adapter over a :class:`~local_coding_agent.worker_pool.BoundedWorkerPool`,
+which is the bounded in-memory reservation for a task handle.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from .worker_pool import BoundedWorkerPool
+
+try:
+    from pydantic import BaseModel, ConfigDict, Field
+
+    from mcp.server.context import ServerRequestContext
+    from mcp.server.extension import Extension, MethodBinding
+    from mcp.types import (
+        CallToolRequestParams,
+        CallToolResult,
+        CancelTaskRequestParams,
+        GetTaskRequestParams,
+        INVALID_PARAMS,
+        TextContent,
+    )
+    from mcp.shared.exceptions import MCPError
+
+    _MCP_AVAILABLE = True
+except ImportError:  # pragma: no cover - mcp/pydantic is an optional dependency
+    _MCP_AVAILABLE = False
+
+TASKS_IDENTIFIER = "io.modelcontextprotocol/tasks"
+
+_POOL_STATE_TO_TASK = {
+    "queued": "working",
+    "working": "working",
+    "completed": "completed",
+    # A restarted process cannot safely replay without the original request
+    # envelope. The worker pool exposes an interrupted terminal result, and
+    # Tasks carries it as a completed response with isError=true.
+    "interrupted": "completed",
+    # Controller/tool failures are CallToolResult(isError=true), not JSON-RPC
+    # failures; SEP-2663 keeps those tasks in the completed state.
+    "failed": "completed",
+    "cancelled": "cancelled",
+}
+
+_DEFAULT_TTL_MS = 30 * 60 * 1000
+_DEFAULT_POLL_INTERVAL_MS = 2000
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _client_declared_tasks(ctx: ServerRequestContext[Any, Any]) -> bool:
+    """True when the client declared the tasks extension in its capabilities."""
+
+    try:
+        capabilities = ctx.session.client_capabilities
+    except AttributeError:  # pragma: no cover - defensive against SDK drift
+        return False
+    declared = capabilities.extensions if capabilities is not None else None
+    return bool(declared and TASKS_IDENTIFIER in declared)
+
+
+def task_dict(pool: BoundedWorkerPool, caller_id: str, task_id: str) -> dict[str, Any]:
+    """Render a pool snapshot as the modern (SEP-2663) flat Task wire shape.
+
+    The wire shape is the flat ``Task`` from the ext-tasks schema: ``taskId``,
+    ``status``, ``statusMessage``, ``createdAt``, ``lastUpdatedAt``, ``ttlMs``
+    and optional ``pollIntervalMs``, with a terminal ``result``/``error``.
+    """
+
+    snapshot = pool.get(caller_id, task_id)
+    _raise_if_unknown(snapshot, task_id)
+    status = _POOL_STATE_TO_TASK.get(snapshot.get("status"), "working")
+    created_at = snapshot.get("created_at") or _now_iso()
+    updated_at = snapshot.get("updated_at") or created_at
+    task: dict[str, Any] = {
+        "taskId": task_id,
+        "status": status,
+        "createdAt": created_at,
+        "lastUpdatedAt": updated_at,
+        "ttlMs": _DEFAULT_TTL_MS,
+        "pollIntervalMs": _DEFAULT_POLL_INTERVAL_MS,
+    }
+    if status == "completed":
+        task["result"] = _call_tool_result(snapshot.get("result") or {})
+    return task
+
+
+def _raise_if_unknown(snapshot: Mapping[str, Any], task_id: str) -> None:
+    error = snapshot.get("error")
+    if isinstance(error, Mapping) and error.get("kind") == "unknown_job":
+        raise MCPError(
+            code=INVALID_PARAMS,
+            message=f"unknown taskId: {task_id}",
+        )
+
+
+def _call_tool_result(result: Mapping[str, Any]) -> dict[str, Any]:
+    """Convert controller-owned result data to the original CallToolResult shape."""
+
+    value = dict(result)
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": json.dumps(value, ensure_ascii=False, sort_keys=True),
+            }
+        ],
+        "isError": value.get("status") == "failed",
+        "structuredContent": value,
+    }
+
+
+if _MCP_AVAILABLE:
+
+    class UpdateTaskParams(BaseModel):
+        """Params for ``tasks/update`` (SEP-2663): responses to input requests."""
+
+        model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+        task_id: str = Field(alias="taskId")
+        input_responses: dict[str, Any] | None = Field(alias="inputResponses", default=None)
+
+    class TasksExtension(Extension):
+        """Server side of ``io.modelcontextprotocol/tasks`` over a worker pool."""
+
+        identifier = TASKS_IDENTIFIER
+
+        def __init__(
+            self,
+            pool: BoundedWorkerPool,
+            *,
+            caller_id: str,
+            ttl_ms: int = _DEFAULT_TTL_MS,
+            poll_interval_ms: int = _DEFAULT_POLL_INTERVAL_MS,
+        ) -> None:
+            self._pool = pool
+            self._caller_id = caller_id
+            self._ttl_ms = ttl_ms
+            self._poll_interval_ms = poll_interval_ms
+
+        def methods(self) -> list[MethodBinding]:
+            return [
+                MethodBinding("tasks/get", GetTaskRequestParams, self._handle_get),
+                MethodBinding("tasks/cancel", CancelTaskRequestParams, self._handle_cancel),
+                MethodBinding("tasks/update", UpdateTaskParams, self._handle_update),
+            ]
+
+        async def intercept_tool_call(
+            self,
+            params: CallToolRequestParams,
+            ctx: ServerRequestContext[Any, Any],
+            call_next,
+        ) -> Any:
+            """Short-circuit ``delegate_code`` into a task when the client opted in.
+
+            A client that did not declare the extension falls through to the
+            synchronous handler, so the server never returns a task handle to a
+            client that cannot handle it.
+            """
+
+            if params.name != "delegate_code":
+                return await call_next(ctx)
+            if not _client_declared_tasks(ctx):
+                return await call_next(ctx)
+            try:
+                from .service import DelegationRequest
+                from .task import TaskEnvelope
+
+                arguments = params.arguments or {}
+                request = DelegationRequest(
+                    request_id=arguments.get("request_id"),
+                    workspace_ref=arguments.get("workspace_ref"),
+                    model_profile=arguments.get("model_profile"),
+                    task=TaskEnvelope.from_mapping(arguments.get("task") or {}),
+                )
+            except (TypeError, ValueError):
+                # Invalid arguments must report the same synchronous policy failure
+                # as the non-task path; fall through to the real handler.
+                return await call_next(ctx)
+            snapshot = self._pool.submit(self._caller_id, request)
+            if snapshot.get("status") == "failed":
+                error = snapshot.get("error") or {}
+                return CallToolResult(
+                    content=[TextContent(type="text", text=str(error))],
+                    is_error=True,
+                )
+            return {
+                "resultType": "task",
+                "taskId": snapshot["job_id"],
+                "status": _POOL_STATE_TO_TASK.get(snapshot.get("status"), "working"),
+                "createdAt": snapshot.get("created_at") or _now_iso(),
+                "lastUpdatedAt": snapshot.get("updated_at") or _now_iso(),
+                "ttlMs": self._ttl_ms,
+                "pollIntervalMs": self._poll_interval_ms,
+            }
+
+        async def _handle_get(
+            self,
+            ctx: ServerRequestContext[Any, Any],
+            params: GetTaskRequestParams,
+        ) -> dict[str, Any]:
+            task = task_dict(self._pool, self._caller_id, params.task_id)
+            task["resultType"] = "complete"
+            return task
+
+        async def _handle_cancel(
+            self,
+            ctx: ServerRequestContext[Any, Any],
+            params: CancelTaskRequestParams,
+        ) -> dict[str, Any]:
+            snapshot = self._pool.cancel(self._caller_id, params.task_id)
+            _raise_if_unknown(snapshot, params.task_id)
+            return {"resultType": "complete"}
+
+        async def _handle_update(
+            self,
+            ctx: ServerRequestContext[Any, Any],
+            params: UpdateTaskParams,
+        ) -> dict[str, Any]:
+            snapshot = self._pool.get(self._caller_id, params.task_id)
+            _raise_if_unknown(snapshot, params.task_id)
+            # MVP has no `input_required` flow: delegate_code never surfaces
+            # input requests, so tasks/update only acknowledges. Responses to
+            # unknown or already-satisfied keys are ignored per the spec.
+            return {"resultType": "complete"}

local_coding_agent/terminal/__init__.py

@@ -0,0 +1,35 @@
+"""Persistent PTY Terminal Seam & Interactive Process Control (R26).
+
+Adapted from DeepSeek Harness @deepseek-ai/dsh-terminal and @deepseek-ai/dsh-tool-terminal.
+Provides persistent background interactive shell / process sessions, non-blocking I/O drainers,
+circular scrollback buffers, cross-platform signal propagation, and robust process tree cleanup.
+"""
+
+from __future__ import annotations
+
+from ..terminal._process import kill_process_tree
+from ..terminal._session import TerminalSession
+from ..terminal._types import (
+    TerminalError,
+    TerminalProcessExitedError,
+    TerminalSessionExistsError,
+    TerminalSessionInfo,
+    TerminalSessionNotFoundError,
+    TerminalTimeoutError,
+)
+from ..terminal._manager import TerminalManager
+from ..terminal._tools import execute_terminal_tool, get_terminal_tool_schemas
+
+__all__ = [
+    "TerminalError",
+    "TerminalManager",
+    "TerminalProcessExitedError",
+    "TerminalSession",
+    "TerminalSessionExistsError",
+    "TerminalSessionInfo",
+    "TerminalSessionNotFoundError",
+    "TerminalTimeoutError",
+    "execute_terminal_tool",
+    "get_terminal_tool_schemas",
+    "kill_process_tree",
+]

local_coding_agent/terminal/_manager.py

@@ -0,0 +1,156 @@
+"""Registry and lifecycle manager for persistent terminal sessions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import threading
+from typing import Any, Mapping, Sequence
+
+from ..terminal._session import TerminalSession
+from ..terminal._types import (
+    TerminalError,
+    TerminalSessionExistsError,
+    TerminalSessionNotFoundError,
+)
+
+
+# ============================================================================
+# TerminalManager
+# ============================================================================
+
+class TerminalManager:
+    """Registry and lifecycle manager for multiple persistent terminal sessions."""
+
+    def __init__(
+        self,
+        workspace_root: str | Path | None = None,
+        *,
+        default_max_buffer: int = 1_048_576,
+        strict_workspace: bool = False,
+    ) -> None:
+        self.workspace_root = (
+            Path(workspace_root).resolve() if workspace_root else Path.cwd()
+        )
+        self.default_max_buffer = default_max_buffer
+        self.strict_workspace = strict_workspace
+        self._sessions: dict[str, TerminalSession] = {}
+        self._lock = threading.Lock()
+
+    def create_session(
+        self,
+        session_id: str,
+        cwd: str | Path | None = None,
+        shell: str | Sequence[str] | None = None,
+        *,
+        max_buffer_bytes: int | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> TerminalSession:
+        """Create and start a new interactive persistent terminal session."""
+        session_id = str(session_id).strip()
+        if not session_id:
+            raise TerminalError("session_id must be a non-empty string")
+
+        if cwd is not None:
+            raw_cwd = Path(cwd)
+            if raw_cwd.is_absolute():
+                target_cwd = raw_cwd.resolve()
+            else:
+                target_cwd = (self.workspace_root / raw_cwd).resolve()
+        else:
+            target_cwd = self.workspace_root
+
+        if self.strict_workspace:
+            try:
+                target_cwd.relative_to(self.workspace_root)
+            except ValueError as e:
+                raise TerminalError(
+                    f"Path traversal denied: working directory '{target_cwd}' is outside workspace root '{self.workspace_root}'"
+                ) from e
+
+        with self._lock:
+            existing = self._sessions.get(session_id)
+            if existing is not None:
+                if existing.is_alive():
+                    raise TerminalSessionExistsError(
+                        f"Terminal session '{session_id}' already exists and is active"
+                    )
+                # Cleanup dead session before replacing
+                existing.close()
+                del self._sessions[session_id]
+
+            buf_limit = max_buffer_bytes or self.default_max_buffer
+
+            session = TerminalSession(
+                session_id=session_id,
+                cwd=target_cwd,
+                shell=shell,
+                max_buffer_bytes=buf_limit,
+                env=env,
+            )
+            self._sessions[session_id] = session
+            return session
+
+    def get_session(self, session_id: str) -> TerminalSession:
+        """Retrieve an existing terminal session by ID."""
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if session is None:
+                raise TerminalSessionNotFoundError(
+                    f"Terminal session '{session_id}' not found"
+                )
+            return session
+
+    def send_input(
+        self,
+        session_id: str,
+        text: str,
+        wait_ms: int = 500,
+        submit: bool = True,
+    ) -> str:
+        """Send input to an identified session and collect response output slice."""
+        session = self.get_session(session_id)
+        return session.send_input(text, wait_ms=wait_ms, submit=submit)
+
+    def read_buffer(
+        self,
+        session_id: str,
+        offset: int = 0,
+        limit: int = 4096,
+    ) -> str:
+        """Read a slice from the session's retained output buffer."""
+        session = self.get_session(session_id)
+        return session.read_buffer(offset=offset, limit=limit)
+
+    def send_signal(self, session_id: str, sig: str) -> bool:
+        """Deliver a signal to the identified session."""
+        session = self.get_session(session_id)
+        return session.send_signal(sig)
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """List summary info for all tracked terminal sessions."""
+        with self._lock:
+            return [s.snapshot().to_dict() for s in self._sessions.values()]
+
+    def close_session(self, session_id: str) -> None:
+        """Shut down and unregister a terminal session."""
+        with self._lock:
+            session = self._sessions.pop(session_id, None)
+        if session is not None:
+            session.close()
+
+    def close_all(self) -> None:
+        """Shut down and clean up all active terminal sessions."""
+        with self._lock:
+            sessions = list(self._sessions.values())
+            self._sessions.clear()
+        for s in sessions:
+            try:
+                s.close()
+            except Exception:
+                pass
+
+    def __enter__(self) -> TerminalManager:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close_all()