stcode 0.0.1a0__py3-none-any.whl

stcode/core/daemon/workspace.py

@@ -0,0 +1,88 @@
+"""Daemon workspace operations for explicit client requests."""
+
+import asyncio
+import contextlib
+import os
+import signal
+import subprocess
+from pathlib import Path
+from typing import Any
+
+FILE_LIMIT = 2000
+
+
+def list_files(root: Path, limit: int = FILE_LIMIT) -> list[str]:
+    """Workspace paths for `@`, relative to `root`, newest convention first: git."""
+    try:
+        finished = subprocess.run(
+            ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+            cwd=root,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        if finished.returncode == 0 and finished.stdout:
+            # -z disables Git's C-style quoting and preserves whitespace in names.
+            paths = finished.stdout.rstrip(b"\0").split(b"\0")
+            return sorted({os.fsdecode(path) for path in paths})[:limit]
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return _walk(root, limit)
+
+
+def _walk(root: Path, limit: int) -> list[str]:
+    """Every file under `root`, dot-directories skipped and bounded.
+
+    Bounded because this runs on a directory nobody vetted: a home directory, or a
+    workspace with a 40,000-file build output in it, must not turn typing `@` into a
+    minute of walking.
+    """
+    found: list[str] = []
+    for current, directories, filenames in os.walk(root):
+        directories[:] = [name for name in directories if not name.startswith(".")]
+        for filename in filenames:
+            if filename.startswith("."):
+                continue
+            found.append(str(Path(current, filename).relative_to(root)))
+            if len(found) >= limit:
+                return sorted(found)
+    return sorted(found)
+
+
+async def run_shell(command: str, cwd: Path, timeout: float) -> dict[str, Any]:
+    """Run a user command in the session workspace; reap its group on timeout/close."""
+    timeout = max(1.0, min(120.0, timeout))
+    process = await asyncio.create_subprocess_shell(
+        command, cwd=cwd, stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT,
+        start_new_session=True,
+    )
+    # Drain continuously but bound the retained output, including single huge lines.
+    output = bytearray()
+    truncated = False
+
+    async def drain() -> None:
+        nonlocal truncated
+        assert process.stdout is not None
+        while chunk := await process.stdout.read(65536):
+            remaining = max(0, 1024 * 1024 - len(output))
+            output.extend(chunk[:remaining])
+            truncated |= len(chunk) > remaining
+        await process.wait()
+
+    pump = asyncio.create_task(drain())
+    timed_out = False
+    try:
+        await asyncio.wait_for(asyncio.shield(pump), timeout)
+    except asyncio.TimeoutError:
+        timed_out = True
+    finally:
+        if not pump.done():
+            with contextlib.suppress(ProcessLookupError):
+                os.killpg(process.pid, signal.SIGKILL)
+            await pump
+    text = output.decode("utf-8", errors="replace").rstrip()
+    if truncated:
+        text += "\n… output truncated at 1 MiB"
+    return {"output": text, "exit_code": 124 if timed_out else process.returncode,
+            "timed_out": timeout if timed_out else None}

stcode/core/harness/__init__.py

@@ -0,0 +1,81 @@
+"""
+Harness — the tools, prompts, and skills an agent works with.
+
+    harness = await Harness.create(cwd=project_root, approval_mode="auto-edit")
+    system  = harness.system_prompt()
+    tools   = harness.tool_definitions()
+    result  = await harness.invoke("read", {"path": "src/main.py"})
+
+* `tools/base.py` — `@tool`, and `Runtime[T]`, the parameter the model cannot see.
+* `tools/schema.py` — signature + docstring → JSON Schema.
+* `approvals.py` — the permission vocabulary and the mode policy.
+* `context.py` — `HarnessContext`, the workspace state tools share.
+* `tools/registry.py` — which tools exist and which an agent may see.
+* `skills/` — `SKILL.md` discovery, loaded on demand.
+* `prompts/` — the plan and execute prompts, and the sub-agent briefing.
+* `mcp.py` — external tool servers, adapted to the same `Tool` interface.
+* `harness.py` — the facade that composes all of it.
+"""
+
+from stcode.core.harness.approvals import (
+    APPROVAL_MODES,
+    DEFAULT_APPROVAL_MODE,
+    ApprovalMode,
+    ToolPermission,
+    is_forbidden,
+    requires_approval,
+)
+from stcode.core.harness.context import HarnessContext, TodoItem
+from stcode.core.harness.harness import Harness, read_project_instructions
+from stcode.core.harness.mcp import MCPManager, MCPServerConfig, load_mcp_config
+from stcode.core.harness.prompts import PromptMode, build_system_prompt, mode_for
+from stcode.core.harness.skills import Skill, SkillRegistry
+from stcode.core.harness.tools import (
+    BUILTIN_TOOLS,
+    MAIN_TOOLS,
+    READ_ONLY_TOOLS,
+    WORKER_TOOLS,
+    ApprovalRequest,
+    Question,
+    Runtime,
+    Tool,
+    ToolError,
+    ToolRegistry,
+    ToolResult,
+    to_tool_definition,
+    tool,
+)
+
+__all__ = [
+    "APPROVAL_MODES",
+    "BUILTIN_TOOLS",
+    "DEFAULT_APPROVAL_MODE",
+    "MAIN_TOOLS",
+    "READ_ONLY_TOOLS",
+    "WORKER_TOOLS",
+    "ApprovalMode",
+    "ApprovalRequest",
+    "Harness",
+    "HarnessContext",
+    "MCPManager",
+    "MCPServerConfig",
+    "PromptMode",
+    "Question",
+    "Runtime",
+    "Skill",
+    "SkillRegistry",
+    "TodoItem",
+    "Tool",
+    "ToolError",
+    "ToolPermission",
+    "ToolRegistry",
+    "ToolResult",
+    "build_system_prompt",
+    "is_forbidden",
+    "load_mcp_config",
+    "mode_for",
+    "read_project_instructions",
+    "requires_approval",
+    "to_tool_definition",
+    "tool",
+]

stcode/core/harness/approvals.py

@@ -0,0 +1,85 @@
+"""
+Approval modes — how much the agent may do without asking.
+
+The vocabulary is `core/configs.py`'s; this module owns what each mode permits.
+
+`ToolPermission` and the policy below are the enforcement half: a tool declares its
+class of side effect once, at definition, and this module — not the tool — decides
+whether that class runs unattended under the current mode.
+"""
+
+from __future__ import annotations
+
+from stcode.core.common.compat import StrEnum
+from stcode.core.configs import APPROVAL_MODES, ApprovalMode  # noqa: F401 — re-exported
+
+DEFAULT_APPROVAL_MODE: ApprovalMode = "suggest"
+
+
+class ToolPermission(StrEnum):
+    """What class of side effect a tool has — the axis approval modes gate on.
+
+    Declared once at definition; the policy below decides what it means under the
+    current mode. Tools never test the mode themselves — one that knows about
+    `full-auto` will eventually disagree with the next one about what it means.
+    """
+
+    READ = "read"
+    """Observes the workspace and nothing else. Safe in every mode, `plan` included."""
+
+    WRITE = "write"
+    """Mutates the filesystem. The thing `plan` exists to forbid."""
+
+    EXECUTE = "execute"
+    """Runs an arbitrary command or arbitrary Python. Strictly wider than WRITE — a
+    shell can write files, and it can also delete the repository."""
+
+    NETWORK = "network"
+    """Leaves the machine. Gated separately from WRITE because the risk is disclosure,
+    not corruption: the workspace survives, its contents may not stay private."""
+
+    INTERACTIVE = "interactive"
+    """Asks the human something. Always allowed — a mode that blocks the agent from
+    asking permission-shaped questions has the gate backwards."""
+
+
+# Which permissions run unattended, which ask, and which are refused outright.
+#
+# The ordering is about *workspace mutation*: each mode adds one class to the previous —
+# nothing, then writes, then arbitrary execution. NETWORK is orthogonal (the risk is
+# disclosure, not corruption), so it is gated on its own rather than wedged in.
+_UNATTENDED: dict[ApprovalMode, frozenset[ToolPermission]] = {
+    "plan": frozenset({ToolPermission.READ, ToolPermission.INTERACTIVE}),
+    "suggest": frozenset({ToolPermission.READ, ToolPermission.INTERACTIVE}),
+    "auto-edit": frozenset(
+        {
+            ToolPermission.READ,
+            ToolPermission.INTERACTIVE,
+            ToolPermission.WRITE,
+            ToolPermission.NETWORK,
+        }
+    ),
+    "full-auto": frozenset(ToolPermission),
+}
+
+_FORBIDDEN: dict[ApprovalMode, frozenset[ToolPermission]] = {
+    # `plan` is a research mode: a mid-plan "may I write this file?" prompt would
+    # defeat it rather than enforce it. Network is not refused — it only mutates what
+    # the agent knows — but it asks, because egress is a disclosure to authorise.
+    "plan": frozenset({ToolPermission.WRITE, ToolPermission.EXECUTE}),
+}
+
+
+def requires_approval(mode: ApprovalMode, permission: ToolPermission) -> bool:
+    """Whether a tool of this permission class must ask the human before running."""
+    return permission not in _UNATTENDED.get(mode, _UNATTENDED[DEFAULT_APPROVAL_MODE])
+
+
+def is_forbidden(mode: ApprovalMode, permission: ToolPermission) -> bool:
+    """Whether this mode refuses the tool outright, with no prompt to offer.
+
+    Distinct from `requires_approval`: "ask first" is a pause a human can resolve, while
+    this is a capability the mode does not have. The agent needs to know which it hit —
+    retrying a forbidden tool is never going to work.
+    """
+    return permission in _FORBIDDEN.get(mode, frozenset())

stcode/core/harness/context.py

@@ -0,0 +1,260 @@
+"""
+Harness context — the workspace state built-in tools share, and the `T` in `Runtime[T]`.
+
+`Runtime` carries one call's plumbing (who, when, may-I). This carries what the
+*session* knows: where it is rooted, what it may write to, what it has read, what it
+plans next. The split is what lets another agent define its own context and reuse the
+same `@tool` machinery.
+
+Two invariants live here rather than in the tools that depend on them, because a rule
+enforced in four places will soon be enforced in three:
+
+**Path scope.** Two sub-agents must never write the same file. Scope is assigned at
+spawn and checked in `ensure_writable`.
+
+**Read before overwrite.** `write` to an existing file requires this session to have
+read it. Clobbering a file the agent never looked at is its most expensive mistake, and
+it cannot be detected afterwards — the old contents are simply gone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable, Literal
+
+from pydantic import BaseModel, Field
+
+from stcode.core.configs import ToolConfig
+from stcode.core.harness.errors import ToolError
+
+if TYPE_CHECKING:  # pragma: no cover - import cycle at runtime, fine for type checkers
+    from stcode.core.harness.skills import SkillRegistry
+    from stcode.core.harness.tools.shell import BackgroundShell
+    from stcode.core.repl import PyREPL
+
+TodoStatus = Literal["pending", "in_progress", "completed"]
+
+DEFAULT_IGNORED_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "node_modules",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "dist",
+        "build",
+        ".next",
+        "target",
+    }
+)
+"""Skipped when no `.gitignore` is available. Not a security boundary — a deliberate
+`read(".venv/...")` still works. It exists so `ls` and `glob` answer the question the
+agent meant to ask."""
+
+
+# These field descriptions end up in a tool's JSON Schema, so they are written for the
+# model: short, imperative, no rationale. Two phrasings because the UI shows the
+# participle while an item runs — deriving one from the other in English does not
+# survive contact with real task names.
+class TodoItem(BaseModel):
+    """A single task in the plan."""
+
+    content: str = Field(description="The task, in the imperative: 'Add the retry test'.")
+    status: TodoStatus = Field(default="pending", description="Where this task stands.")
+    active_form: str = Field(
+        default="",
+        description="The same task in the present participle, shown while it runs: "
+        "'Adding the retry test'.",
+    )
+
+    def render(self) -> str:
+        mark = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}[self.status]
+        return f"{mark} {self.content}"
+
+
+@dataclass
+class HarnessContext:
+    """What the built-in tools know about this session's workspace."""
+
+    cwd: Path = field(default_factory=Path.cwd)
+    """Root for every relative path a tool is given, and the default search root."""
+
+    scope: tuple[Path, ...] = ()
+    """Paths this agent may write to. Empty means all of `cwd` — the main agent's
+    normal state. A sub-agent gets a narrower tuple at spawn."""
+
+    read_files: dict[Path, float] = field(default_factory=dict)
+    """Absolute path -> mtime at last read. Feeds the read-before-overwrite check, and
+    lets `edit` notice a file that changed underneath it."""
+
+    todos: list[TodoItem] = field(default_factory=list)
+    session_ctx: dict[str, Any] = field(default_factory=dict)
+    """Knowledge shared down into sibling sub-agents — the in-process twin of the
+    REPL's `session_ctx`."""
+
+    shells: dict[str, "BackgroundShell"] = field(default_factory=dict)
+    """Background processes started by `bash(..., background=True)`, by shell id."""
+
+    skills: "SkillRegistry | None" = None
+
+    repl: "PyREPL | None" = None
+    """The session's persistent Python REPL. Attached by `Harness.create` and lazy —
+    the subprocess waits for the first cell. Read by the `repl` tool and by
+    `Harness.invoke`, which pushes elided payloads into its `tool_out`.
+
+    None for a sub-agent and for `load_repl=False`. When None, the elision hint drops
+    back to "ask for a narrower range" — `tool_out` is then unreachable."""
+
+    git: str = ""
+    """Branch, status and recent commits. Sampled once at `Harness.create` and never
+    refreshed: the system prompt is the cached prefix, and re-sampling per turn would
+    invalidate it every turn. A turn needing current state runs `git status`."""
+
+    env: dict[str, str] = field(default_factory=dict)
+    """Extra environment for spawned processes, layered over `os.environ`."""
+
+    tool_config: ToolConfig = field(default_factory=ToolConfig)
+    """The complete `[tools]` configuration, including service credentials."""
+
+    # ---- paths ----
+
+    def resolve(self, path: str | Path) -> Path:
+        """Absolute, `~`-expanded, and rooted at `cwd` when relative.
+
+        Not `Path.resolve()`: it follows symlinks, so a repo under a symlinked home
+        would fail its own scope check for paths the user legitimately typed. Only `..`
+        is normalised — the part that matters for escaping a scope.
+        """
+        candidate = Path(os.path.expanduser(str(path)))
+        if not candidate.is_absolute():
+            candidate = self.cwd / candidate
+        return Path(os.path.normpath(candidate))
+
+    def in_scope(self, path: str | Path) -> bool:
+        target = self.resolve(path)
+        roots: Iterable[Path] = self.scope or (self.cwd,)
+        return any(target == root or root in target.parents for root in roots)
+
+    def ensure_writable(self, path: str | Path) -> Path:
+        """Resolve `path` and refuse it if this agent has no business writing there."""
+        target = self.resolve(path)
+        if self.in_scope(target):
+            return target
+        allowed = ", ".join(str(p) for p in (self.scope or (self.cwd,)))
+        raise ToolError(
+            f"{target} is outside this agent's write scope ({allowed}). Another agent "
+            "owns that path — report what needs changing there instead of editing it."
+        )
+
+    def note_read(self, path: Path) -> None:
+        try:
+            self.read_files[path] = path.stat().st_mtime
+        except OSError:
+            self.read_files[path] = 0.0
+
+    def has_read(self, path: Path) -> bool:
+        return path in self.read_files
+
+    def changed_since_read(self, path: Path) -> bool:
+        """Whether `path` changed since this session read it.
+
+        Guards against editing from a stale mental model — someone else's save, or a
+        sibling agent that should not have been in there at all.
+        """
+        seen = self.read_files.get(path)
+        if seen is None:
+            return False
+        try:
+            return path.stat().st_mtime > seen
+        except OSError:
+            return False
+
+    # ---- todos ----
+
+    def render_todos(self) -> str:
+        if not self.todos:
+            return "(no todos)"
+        return "\n".join(item.render() for item in self.todos)
+
+    # ---- process environment ----
+
+    def process_env(self) -> dict[str, str]:
+        return {**os.environ, **self.env}
+
+
+class TodoList(BaseModel):
+    """Wrapper so `todo_write` takes one well-named argument rather than a bare list."""
+
+    items: list[TodoItem] = Field(default_factory=list)
+
+
+# ---- repository state ------------------------------------------------------------
+
+GIT_TIMEOUT = 5.0
+"""Past this, the repo is large enough or the filesystem slow enough that blocking
+startup is the wrong trade. The prompt loses a section; `git status` still works."""
+
+_GIT_QUERIES = (
+    ("Branch", ("rev-parse", "--abbrev-ref", "HEAD")),
+    ("Status", ("status", "--short", "--branch")),
+    ("Recent commits", ("log", "-5", "--oneline", "--no-decorate")),
+)
+
+
+async def git_context(cwd: Path) -> str:
+    """Branch, working-tree status and the last five commits, as a prompt section.
+
+    Sampled once and never refreshed: it is the highest quality-per-line addition to
+    the prompt, and re-running it per turn would move the prompt and undo the caching.
+
+    Returns "" outside a repository or without `git`. A missing section is correct
+    here, not an error — plenty of work happens outside a checkout.
+    """
+    async def run(arguments: tuple[str, ...]) -> str:
+        try:
+            process = await asyncio.create_subprocess_exec(
+                "git", "-C", str(cwd), *arguments,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+                stdin=asyncio.subprocess.DEVNULL,
+            )
+            stdout, _ = await asyncio.wait_for(process.communicate(), GIT_TIMEOUT)
+        except (OSError, asyncio.TimeoutError):
+            return ""
+        if process.returncode != 0:
+            return ""
+        return stdout.decode("utf-8", errors="replace").strip()
+
+    if not await run(("rev-parse", "--is-inside-work-tree")):
+        return ""
+
+    sections = await asyncio.gather(*(run(arguments) for _, arguments in _GIT_QUERIES))
+    lines = ["Repository:"]
+    for (label, _), output in zip(_GIT_QUERIES, sections):
+        if not output:
+            continue
+        if "\n" in output:
+            lines.append(f"{label}:")
+            lines += [f"  {line}" for line in output.splitlines()[:12]]
+        else:
+            lines.append(f"{label}: {output}")
+    return "\n".join(lines) if len(lines) > 1 else ""
+
+
+__all__ = [
+    "DEFAULT_IGNORED_DIRS",
+    "GIT_TIMEOUT",
+    "HarnessContext",
+    "TodoItem",
+    "TodoList",
+    "TodoStatus",
+    "git_context",
+]

stcode/core/harness/errors.py

@@ -0,0 +1,40 @@
+"""
+Tool failures — the vocabulary for something going wrong.
+
+A leaf module: `context.py` raises these and `tools/base.py` catches them, so putting
+them in either would make a cycle. The agent loop reacts differently to each:
+
+* `ToolError` — the tool worked, and the answer is "no, because…".
+* `ToolDenied` — a human said no. Could go the other way next time.
+* `ToolForbidden` — the mode lacks this capability. Retrying cannot help.
+* `ToolCancelled` / `ToolTimeout` — did not finish. An interrupt means the user wants
+  something else; a timeout means narrow the request.
+
+A bug *inside* a tool is none of these: logged with its traceback, summarised for the
+model. A stack frame is not advice.
+"""
+
+from __future__ import annotations
+
+
+class ToolError(Exception):
+    """A tool failed in a way the model should read and react to."""
+
+
+class ToolDenied(ToolError):
+    """The human was asked to approve this call and said no."""
+
+
+class ToolForbidden(ToolError):
+    """The current approval mode does not have this capability at all."""
+
+
+class ToolCancelled(ToolError):
+    """The session was interrupted while this tool was running."""
+
+
+class ToolTimeout(ToolError):
+    """The tool exceeded its time budget."""
+
+
+__all__ = ["ToolCancelled", "ToolDenied", "ToolError", "ToolForbidden", "ToolTimeout"]