coderio 0.4.0__py3-none-any.whl

coderio/__init__.py

@@ -0,0 +1,14 @@
+"""coderio: a skill-driven coding agent."""
+
+# Single source of truth for the version is pyproject.toml's [project].version.
+# Read it at runtime via importlib.metadata so __version__ can never drift.
+# Falls back to "0.0.0" only when the package isn't installed (e.g. running
+# directly from a source checkout without `pip install -e .`) — in that case
+# the banner shows "0.0.0", which is obviously wrong rather than silently
+# stale, prompting the developer to install the package.
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("coderio")
+except PackageNotFoundError:  # pragma: no cover - dev-only fallback
+    __version__ = "0.0.0"

coderio/agent/__init__.py

@@ -0,0 +1,5 @@
+from coderio.agent.prompts import build_system_prompt
+from coderio.agent.skill_tool import ActivateSkillTool
+from coderio.agent.stream import NullStream, StreamHandler
+
+__all__ = ["build_system_prompt", "ActivateSkillTool", "StreamHandler", "NullStream"]

coderio/agent/_deepagents_compat.py

@@ -0,0 +1,139 @@
+"""Compatibility layer for deepagents internal APIs.
+
+Centralizes all usage of deepagents internals (non-public APIs) so that:
+1. There's a single file to update when deepagents changes its internals.
+2. Version-specific breakage produces a clear error message instead of a
+   cryptic AttributeError/ImportError deep in a call stack.
+3. Future migration to public APIs (if/when available) is a single-file change.
+
+Current internal dependencies:
+- BASE_AGENT_PROMPT (deepagents.graph): module-level string, monkey-patched
+  to empty to prevent prompt conflicts. Public alternative not yet available.
+- PlanningState.todos state key (langchain.agents.middleware.todo): the graph
+  state field where write_todos persists its output. The key name "todos" is
+  an undocumented implementation detail of langchain's planning middleware —
+  centralized here (TODOS_STATE_KEY + get_state_todos) so a rename upstream
+  only requires updating this one constant instead of scattered state.get()
+  reads across harness_middleware.
+
+The research subagent's tool isolation (_ToolWhitelistMiddleware below) is
+NOT a deepagents internal dependency — it subclasses the public AgentMiddleware
+base and uses the documented ModelRequest.override mechanism. The old
+_ToolExclusionMiddleware (blacklist) was removed in favor of this whitelist
+approach (2026-08-07 report P2-9).
+
+If BASE_AGENT_PROMPT patching fails, we degrade gracefully (the duplicate
+prompt will appear but won't crash).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from langchain.agents.middleware.types import AgentMiddleware
+
+_log = logging.getLogger(__name__)
+
+# Graph state key under which langchain's planning middleware (TodoListMiddleware)
+# persists the todo list. Sourced from langchain.agents.middleware.todo.PlanningState
+# (the "todos: Annotated[NotRequired[list[Todo]], OmitFromInput]" field). This key
+# name is an undocumented implementation detail — if langchain renames it (e.g. to
+# "todo_list"), only this constant needs updating, not every state.get("todos") call.
+TODOS_STATE_KEY = "todos"
+
+
+def get_state_todos(state: Any) -> list | None:
+    """Read the todos list from graph state, dict-or-object agnostic.
+
+    Centralizes the state.get("todos") read so that a key rename upstream
+    produces a single-file fix (update TODOS_STATE_KEY) instead of scattered
+    silent failures across harness_middleware. Returns None when the key is
+    absent (the caller treats None as "no todos to sync").
+    """
+    if hasattr(state, "get"):
+        return state.get(TODOS_STATE_KEY)
+    return getattr(state, TODOS_STATE_KEY, None)
+
+
+def neutralize_base_prompt() -> bool:
+    """Set deepagents' BASE_AGENT_PROMPT to empty string.
+
+    create_deep_agent appends BASE_AGENT_PROMPT after the caller's system_prompt,
+    causing conflicts (e.g. 'explore first' vs 'match effort', macOS path
+    examples vs virtual paths). coderio's prompt covers everything — setting
+    BASE to empty ensures only coderio's prompt reaches the model.
+
+    Returns True if successful, False if the internal API has changed (in
+    which case the duplicate prompt will appear but won't crash).
+    """
+    try:
+        import deepagents.graph as _dg_graph
+
+        if hasattr(_dg_graph, "BASE_AGENT_PROMPT") and _dg_graph.BASE_AGENT_PROMPT:
+            _dg_graph.BASE_AGENT_PROMPT = ""
+            return True
+    except Exception as e:
+        _log.warning("Could not neutralize BASE_AGENT_PROMPT (deepagents API may have changed): %s", e)
+    return False
+
+
+def _tool_name(tool: Any) -> str | None:
+    """Extract the name from a BaseTool or dict tool (mirrors deepagents' helper)."""
+    if isinstance(tool, dict):
+        name = tool.get("name")
+        return name if isinstance(name, str) else None
+    name = getattr(tool, "name", None)
+    return name if isinstance(name, str) else None
+
+
+class _ToolWhitelistMiddleware(AgentMiddleware):
+    """Whitelist-first tool filter — the model only sees tools in ``allowed``.
+
+    Safer than the blacklist approach (``_ToolExclusionMiddleware``) because a
+    new destructive tool added by deepagents in a future version is
+    automatically blocked (it's not in the whitelist). The blacklist would
+    leak it until coderio is updated to exclude the new name.
+
+    Wraps the same ModelRequest.override + filter mechanism as
+    ``_ToolExclusionMiddleware`` but inverts the predicate.
+    """
+
+    def __init__(self, *, allowed: frozenset[str]) -> None:
+        self._allowed = allowed
+
+    def wrap_model_call(self, request, handler):
+        if self._allowed:
+            filtered = [t for t in request.tools if _tool_name(t) in self._allowed]
+            request = request.override(tools=filtered)
+        return handler(request)
+
+    async def awrap_model_call(self, request, handler):
+        if self._allowed:
+            filtered = [t for t in request.tools if _tool_name(t) in self._allowed]
+            request = request.override(tools=filtered)
+        return await handler(request)
+
+
+def make_research_subagent_middleware():
+    """Build the middleware list for the research subagent.
+
+    WHITELIST approach (2026-08-07 report P2-9): the research subagent can
+    ONLY use tools in the explicit read-only set below. This is safer than the
+    old blacklist (exclude write_file/edit_file/execute/write_todos) because
+    any new tool deepagents adds is blocked by default until explicitly
+    allowlisted here.
+
+    Returns a list with a _ToolWhitelistMiddleware. If the deepagents
+    AgentMiddleware base class API is unavailable (very old or very new
+    version), returns an empty list — the subagent will inherit all tools
+    (less safe, but won't crash).
+    """
+    # Read-only tools the research subagent is allowed to use. Add new tools
+    # here ONLY after confirming they're safe for a read-only agent.
+    allowed = frozenset({"read_file", "ls", "glob", "grep", "web_search"})
+    try:
+        return [_ToolWhitelistMiddleware(allowed=allowed)]
+    except Exception as e:  # noqa: BLE001 — AgentMiddleware API may differ
+        _log.warning("Could not build _ToolWhitelistMiddleware: %s", e)
+        return []

coderio/agent/command_review.py

@@ -0,0 +1,140 @@
+"""Command-content review as a deepagents AgentMiddleware.
+
+Sits in the same middleware chain as PermissionMiddleware, AFTER it. While
+PermissionMiddleware decides based on TOOL TYPE + MODE (which tier), this
+middleware inspects the CONTENT of shell commands and network calls — blocking
+destructive patterns (``rm -rf /``, ``mkfs``, fork bombs) regardless of the
+permission mode.
+
+This is NOT a real OS sandbox: a determined model can obfuscate commands to
+bypass regex matching. The goal is to stop accidental/careless destruction,
+which is the vast majority of real-world incidents. See command_policy.py for
+the pattern list and the limitations.
+
+Runs even in FULL mode: safety takes priority over the "FULL = allow
+everything" literal semantics. A user who selects FULL accepts that file edits
+and shell execution happen without prompts, but not that ``rm -rf /`` proceeds
+without even a logged block.
+
+Whitelist interaction: when whitelist_mode is enabled on the policy, commands
+outside the whitelist are flagged. Unlike blacklist (hard block), whitelist
+misses degrade gracefully:
+  - FULL mode: allowed (FULL = explicit trust, user accepted all commands)
+  - CONFIRM/AUTO_EDIT: the whitelist hint is appended to the command result so
+    the user can see it during the (already-triggered) permission prompt. We
+    don't hard-block because PermissionMiddleware already gates execute.
+  - PLAN mode: execute is already blocked by PermissionMiddleware before this
+    middleware runs, so the whitelist check is moot for plan mode.
+"""
+
+from __future__ import annotations
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+# Tools whose CONTENT this middleware inspects. Note deepagents native names.
+_SHELL_TOOL = "execute"
+_NETWORK_TOOLS = frozenset({"web_fetch", "web_search"})
+
+
+def _augment_with_whitelist_note(result, note: str):
+    """Return ``result`` with the whitelist note appended.
+
+    Handles three result shapes the execute tool can return:
+      - str (plain string): return a new string with the note appended.
+      - ToolMessage (deepagents wraps results): mutate .content in-place and return.
+      - ExecuteResponse (deepagents backends): mutate .output in-place and return.
+
+    Returns the (possibly mutated) result so the caller can return it directly.
+    """
+    content = getattr(result, "content", None)
+    if content is not None and isinstance(content, str):
+        result.content = f"{content}\n[whitelist] {note}"
+        return result
+    output = getattr(result, "output", None)
+    if output is not None and isinstance(output, str):
+        result.output = f"{output}\n[whitelist] {note}"
+        return result
+    if isinstance(result, str):
+        return f"{result}\n[whitelist] {note}"
+    # Unknown type — return unchanged (best-effort; note is informational).
+    return result
+
+
+class CommandReviewMiddleware(AgentMiddleware):
+    """Inspects shell commands and network calls against a CommandPolicy.
+
+    Sibling to PermissionMiddleware. Both run in wrap_tool_call; this one is
+    content-focused (regex on the command string), the other is tier-focused
+    (plan/confirm/full mode). Order: PermissionMiddleware first (tier gate),
+    then this (content gate) — so we only inspect commands that already passed
+    the tier check. But the content rules are mode-independent: even FULL mode
+    blocks ``rm -rf /``.
+
+    Optional ``gate`` reference: if provided, whitelist misses use gate.mode to
+    decide behavior (FULL allows, other modes get a hint appended to result).
+    If None (no gate), whitelist misses are logged but not blocked (the policy
+    can't enforce confirmation without the gate).
+    """
+
+    def __init__(self, policy, gate=None) -> None:
+        self.policy = policy
+        self.gate = gate
+
+    def wrap_tool_call(self, request, handler):
+        """Inspect execute/web commands; block if the policy says no."""
+        tc = getattr(request, "tool_call", None) or {}
+        name = tc.get("name", "")
+        args = dict(tc.get("args", {}) or {})
+        tool_call_id = tc.get("id", "")
+
+        if name == _SHELL_TOOL:
+            command = str(args.get("command", ""))
+            # Layer 1: blacklist (hard block, always active).
+            violation = self.policy.check_command(command)
+            if violation:
+                # Surface the reason so the model understands WHY and can
+                # reformulate — e.g. "rm -rf /build" is fine, "rm -rf /" is not.
+                return ToolMessage(
+                    content=f"Blocked by command policy: {violation}. "
+                    "Reformulate the command to avoid the destructive pattern "
+                    "(e.g. target a specific subdirectory, not root/home).",
+                    tool_call_id=tool_call_id,
+                    name=name,
+                )
+            # Layer 2: whitelist (soft — degrade based on gate mode, not hard block).
+            # Unlike the blacklist (which hard-blocks), a whitelist miss is enforced
+            # by the gate's tier semantics:
+            #   - PLAN mode: execute is already blocked by PermissionMiddleware, so
+            #     we won't reach here in production. But if we do (e.g. gate=None),
+            #     we hard-block to stay safe.
+            #   - FULL mode: explicit trust — allow without annotation.
+            #   - CONFIRM/AUTO_EDIT: let the tool run (PermissionMiddleware already
+            #     prompted the user), but APPEND the whitelist hint to the result so
+            #     the model/user sees WHY the command was flagged.
+            whitelist_miss = self.policy.check_whitelist(command)
+            if whitelist_miss:
+                mode = getattr(self.gate, "mode", "confirm") if self.gate is not None else "confirm"
+                if mode == "plan":
+                    return ToolMessage(
+                        content=f"Blocked by whitelist policy (plan mode): {whitelist_miss}",
+                        tool_call_id=tool_call_id,
+                        name=name,
+                    )
+                if mode != "full":
+                    # Non-FULL, non-PLAN: annotate the result. Let the tool execute
+                    # (the user was already prompted by PermissionMiddleware), but
+                    # surface the whitelist note in the result content so the model
+                    # understands the command was outside the trusted set.
+                    result = handler(request)
+                    return _augment_with_whitelist_note(result, whitelist_miss)
+                # FULL mode: fall through to the normal handler(request) below.
+        elif name in _NETWORK_TOOLS and not self.policy.network_allowed:
+            return ToolMessage(
+                content="Blocked: network access is disabled (network_allowed=false "
+                "in config). web_fetch/web_search are unavailable in this session.",
+                tool_call_id=tool_call_id,
+                name=name,
+            )
+
+        return handler(request)