coderio 0.4.0__py3-none-any.whl

coderio/agent/skill_tool.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from coderio.agent.prompts import ActiveSkills
+from coderio.skills.store import SkillStore
+
+
+class ActivateSkillArgs(BaseModel):
+    name: str = Field(description="Name of the skill to activate.")
+
+
+class ActivateSkillTool:
+    """Tool that activates a skill by name, loading its full playbook into context.
+
+    Spec §2.3 (3): keyword/explicit skill activation. Returns a status string;
+    the actual prompt refresh happens via the on_activate_skill callback in the
+    loop (so the system prompt picks up the newly-active skill body).
+    """
+
+    name = "activate_skill"
+    description = (
+        "Activate a skill by name to load its full playbook into context. "
+        "Use when a task matches a skill's domain and you need its detailed playbook."
+    )
+    args_schema = ActivateSkillArgs
+
+    def __init__(self, store: SkillStore, active: ActiveSkills) -> None:
+        self.store = store
+        self.active = active
+
+    def run(self, name: str) -> str:
+        if not self.store.has(name):
+            return f"Error: skill not found: {name}. Available: {', '.join(self.store.names())}"
+        skill = self.store.get(name)
+        newly = self.active.activate(skill)
+        return f"Activated skill: {name}" if newly else f"Skill already active: {name}"
+
+
+class DeactivateSkillArgs(BaseModel):
+    name: str = Field(description="Name of the active skill to deactivate.")
+
+
+class DeactivateSkillTool:
+    """Tool that deactivates an active skill, dropping its body from context.
+
+    Mirrors ActivateSkillTool. The budget warning in the system prompt points the model at
+    `deactivate_skill` when active skill bodies exceed ~30% of the context budget;
+    without this tool that hint would reference a non-existent tool and the model
+    would get an 'unknown tool' error. After deactivation the prompt is refreshed
+    via the same on_activate_skill callback path (it rebuilds the system prompt
+    from whatever skills remain active).
+    """
+
+    name = "deactivate_skill"
+    description = (
+        "Deactivate an active skill to free context. Use when active skill bodies "
+        "are consuming too much budget and one is no longer needed for the task."
+    )
+    args_schema = DeactivateSkillArgs
+
+    def __init__(self, active: ActiveSkills) -> None:
+        self.active = active
+
+    def run(self, name: str) -> str:
+        removed = self.active.deactivate(name)
+        if not removed:
+            active_names = [s.name for s in self.active.all()]
+            return f"Error: skill not active: {name}. Active skills: {', '.join(active_names) or '(none)'}"
+        return f"Deactivated skill: {name}. Prompt will refresh on next turn."

coderio/agent/state.py

@@ -0,0 +1,144 @@
+"""Explicit agent state machine — observability for execution phases.
+
+Inspired by Step-Realtime-CLI's AgentStateMachine, but unlike theirs (which only
+RECORDS transitions for telemetry), this tracker derives phase from the harness's
+ground-truth signals (writes/verifications/todos) so the displayed phase reflects
+what the agent is actually doing, not just what it claims.
+
+The timeline persists to the session jsonl at turn end (via a system-role
+Message) so a past turn's phase progression can be replayed for debugging.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class AgentState(StrEnum):
+    """Structural phases of a coding-agent turn.
+
+    Derived from harness ground truth (never from model self-report):
+      EXPLORE   — reading code (read_file/grep/list_dir), no writes yet
+      PLAN      — a write happened but no todo list exists (PlanGate signal)
+      IMPLEMENT — writes exist, not yet verified
+      VERIFY    — bash ran a verifying command (test/build/lint)
+      COMPLETE  — turn ended (cleanly or max-rounds)
+    """
+
+    EXPLORE = "explore"
+    PLAN = "plan"
+    IMPLEMENT = "implement"
+    VERIFY = "verify"
+    COMPLETE = "complete"
+
+
+@dataclass
+class StateSnapshot:
+    """One point in the phase timeline."""
+
+    state: AgentState
+    timestamp: str = field(default_factory=lambda: time.strftime("%Y-%m-%dT%H:%M:%S"))
+    step: int = 0  # model round number when the transition fired
+    hint: str = ""  # optional context (e.g. "wrote loader.py", "ran pytest")
+
+    def to_dict(self) -> dict:
+        return {
+            "state": str(self.state),
+            "timestamp": self.timestamp,
+            "step": self.step,
+            "hint": self.hint,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "StateSnapshot":
+        return cls(
+            state=AgentState(d.get("state", "explore")),
+            timestamp=d.get("timestamp", ""),
+            step=d.get("step", 0),
+            hint=d.get("hint", ""),
+        )
+
+
+class AgentStateTracker:
+    """Records the phase timeline for one agent turn.
+
+    Phase is derived: ``derive_phase()`` maps harness state to an AgentState.
+    ``transition()`` is called from Harness.observe / check_termination; if the
+    derived phase matches the current one, nothing is recorded (debounce — a
+    turn that does 10 read_files produces ONE explore snapshot, not ten).
+    """
+
+    def __init__(self) -> None:
+        self._current: AgentState = AgentState.EXPLORE
+        self.timeline: list[StateSnapshot] = []
+
+    @property
+    def current(self) -> AgentState:
+        return self._current
+
+    def derive_phase(
+        self,
+        writes_since_verify: list[str],
+        todos_exist: bool,
+        just_verified: bool,
+    ) -> AgentState:
+        """Map harness ground truth to a phase.
+
+        Called from inside Harness (which has the live state); the tracker does
+        NOT reach into Harness to avoid a circular dependency.
+
+        Args:
+            writes_since_verify: files written but not yet verified (non-empty ⇒ IMPLEMENT)
+            todos_exist: whether a todo list exists (False + first write ⇒ PLAN)
+            just_verified: whether a verifying bash ran this tool call (⇒ VERIFY)
+        """
+        if just_verified:
+            return AgentState.VERIFY
+        if writes_since_verify:
+            # Writes exist without a plan → still in the plan-implicit phase
+            # (PlanGate would nudge here). Once a todo list exists, it's full IMPLEMENT.
+            return AgentState.PLAN if not todos_exist else AgentState.IMPLEMENT
+        return AgentState.EXPLORE
+
+    def transition(self, state: AgentState, step: int = 0, hint: str = "") -> bool:
+        """Record a phase change. No-op if ``state`` equals the current phase
+        (debounce: repeated same-phase observations don't bloat the timeline).
+
+        Returns True if a new snapshot was recorded, False if debounced. Callers
+        that also notify a stream should use this to avoid spamming on_phase_change
+        for repeated same-phase observations.
+        """
+        if state == self._current and self.timeline:
+            return False  # same phase, already recorded — skip
+        self._current = state
+        self.timeline.append(StateSnapshot(state=state, step=step, hint=hint))
+        return True
+
+    def finish(self, step: int = 0, hint: str = "") -> None:
+        """Mark the turn as complete. Always records (even if already COMPLETE)
+        so the final step number is captured for timeline replay."""
+        self._current = AgentState.COMPLETE
+        self.timeline.append(StateSnapshot(state=AgentState.COMPLETE, step=step, hint=hint))
+
+    def to_payload(self) -> list[dict]:
+        """Serialize the timeline for persistence (system-role Message content)."""
+        return [s.to_dict() for s in self.timeline]
+
+    @staticmethod
+    def from_payload(payload: list[dict]) -> "AgentStateTracker":
+        """Reconstruct a timeline from persisted data (for session replay)."""
+        t = AgentStateTracker()
+        for d in payload:
+            snap = StateSnapshot.from_dict(d)
+            t.timeline.append(snap)
+            t._current = snap.state
+        return t
+
+    def summary(self) -> str:
+        """One-line human-readable summary for UI display."""
+        if not self.timeline:
+            return str(self._current)
+        phases = " → ".join(str(s.state) for s in self.timeline)
+        return f"{phases} ({len(self.timeline)} transitions)"

coderio/agent/stream.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class StreamHandler(Protocol):
+    """Abstract streaming UI. CLI/GUI implement these (spec §4.3)."""
+
+    def on_step_start(self, step: int = 1) -> None: ...
+    def on_token(self, text: str) -> None: ...
+    def on_tool_start(
+        self,
+        name: str,
+        args: dict[str, Any],
+        step: int = 1,
+        tool_index: int = 0,
+        tool_total: int = 0,
+    ) -> None: ...
+    def on_tool_end(self, name: str, result: str) -> None: ...
+    def on_finish(self) -> None: ...
+    # Optional hooks (have attr guards in run_step; NullStream implements them too):
+    def on_thinking(self, text: str) -> None: ...  # 'is thinking' indicator
+    def on_truncated(self, stop_reason: str) -> None: ...  # output was cut off
+    # Harness escalation release: the agent claimed completion despite an
+    # unverified write / pending todos, and the gate exhausted its retries.
+    def on_harness_warn(self, message: str) -> None: ...
+    # Harness force-continue: the agent claimed done, but the harness found
+    # unfinished work (unverified writes, pending todos, ungrounded claims) and
+    # is injecting a follow-up demand instead of letting the turn end. Distinct
+    # from on_harness_warn (which fires on ESCALATION RELEASE, after retries
+    # are exhausted). This fires on every force-continue iteration, surfacing
+    # why the agent is still running after the model produced a "final" answer.
+    def on_harness_continue(self, reason: str) -> None: ...
+    # Agent phase change (explore/plan/implement/verify/complete). Fired by the
+    # AgentStateTracker from inside Harness.observe/check_termination. Lets the
+    # UI show the task-level phase alongside the model-activity micro-phase.
+    def on_phase_change(self, state: str, step: int, hint: str) -> None: ...
+    # Turn end summary: the list of files modified this turn (write_file /
+    # edit_file / multi_edit). Lets the UI show a "files changed" summary —
+    # matching the "always show what changed" UX of claude code / zcode.
+    def on_turn_end(self, writes: list[str]) -> None: ...
+    # Todo list updated (deepagents write_todos tool). `todos` is a list of
+    # {content: str, status: "pending"|"in_progress"|"completed"}. The whole
+    # list is replaced each time (not incremental). Lets the UI render a live
+    # todo progress panel.
+    def on_todos_update(self, todos: list[dict]) -> None: ...
+
+
+class NullStream:
+    """Default no-op handler for tests/headless."""
+
+    def on_step_start(self, step: int = 1) -> None:
+        pass
+
+    def on_token(self, text: str) -> None:
+        pass
+
+    def on_tool_start(
+        self,
+        name: str,
+        args: dict[str, Any],
+        step: int = 1,
+        tool_index: int = 0,
+        tool_total: int = 0,
+    ) -> None:
+        pass
+
+    def on_tool_end(self, name: str, result: str) -> None:
+        pass
+
+    def on_finish(self) -> None:
+        pass
+
+    def on_thinking(self, text: str) -> None:
+        pass
+
+    def on_truncated(self, stop_reason: str) -> None:
+        pass
+
+    def on_harness_warn(self, message: str) -> None:
+        pass
+
+    def on_harness_continue(self, reason: str) -> None:
+        pass
+
+    def on_phase_change(self, state: str, step: int, hint: str) -> None:
+        pass
+
+    def on_turn_end(self, writes: list[str]) -> None:
+        pass
+
+    def on_todos_update(self, todos: list[dict]) -> None:
+        pass

coderio/cli/app.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from coderio.config import load_config
+from coderio.config.bootstrap import ensure_user_dirs
+from coderio.skills.store import SkillStore, load_skill_store
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=False,
+    help="coderio — a skill-driven coding agent.",
+)
+
+skills_app = typer.Typer(help="Manage skills (install/list/update).")
+app.add_typer(skills_app, name="skills")
+
+mcp_app = typer.Typer(help="Manage MCP servers (add/list/remove).")
+app.add_typer(mcp_app, name="mcp")
+
+BUNDLED_SKILLS = Path(__file__).resolve().parents[1] / "skills"
+
+
+def _user_skills_dir() -> Path:
+    return Path.home() / ".coderio" / "skills"
+
+
+def _load_store() -> SkillStore:
+    return load_skill_store(BUNDLED_SKILLS, _user_skills_dir(), None)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    resume: str = typer.Option(None, "--resume", help="Resume a session by id."),
+    continue_last: bool = typer.Option(False, "--continue", help="Resume most recent session."),
+    provider: str = typer.Option(None, "--provider", help="Override provider_id."),
+    model: str = typer.Option(None, "--model", help="Override model name."),
+):
+    """coderio — start the interactive TUI or run a subcommand.
+
+    Launches the Textual TUI: foldable thinking (Ctrl+O), scrollable history,
+    slash-command autocomplete. This is the only interactive entry point.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    ensure_user_dirs()
+    from coderio.cli.tui import run_tui
+
+    run_tui(
+        provider_override=provider,
+        model_override=model,
+        resume=resume,
+        continue_last=continue_last,
+    )
+
+
+@skills_app.command("list")
+def skills_list():
+    """List installed skills (bundled + user layers)."""
+    store = _load_store()
+    console = Console()
+    names = store.names()
+    if not names:
+        console.print("No skills installed. Run `coderio skills install`.")
+        raise typer.Exit()
+    console.print("Installed skills:\n" + "\n".join(f"  - {n}" for n in names))
+
+
+@skills_app.command("install")
+def skills_install(
+    repo: str = typer.Option(None, "--repo", help="Git repo URL (default: Lion-Skills)."),
+    force: bool = typer.Option(False, "--force", help="Overwrite non-git target."),
+):
+    """Install/update skills from a git repo (default: Lion-Skills)."""
+    from coderio.cli.skills_cmd import install_skills
+
+    cfg = load_config()
+    repo_url = repo or cfg.skills.repo_url
+    result = install_skills(repo_url, _user_skills_dir(), force=force)
+    console = Console()
+    if result.success:
+        console.print(
+            Panel(
+                f"{result.action.capitalize()}: {len(result.skills)} skills\n"
+                + "\n".join(f"  - {s}" for s in result.skills),
+                title="skills",
+                border_style="green",
+            )
+        )
+    else:
+        console.print(f"[red]Error:[/red] {result.message}")
+        raise typer.Exit(1)
+
+
+@skills_app.command("update")
+def skills_update(
+    repo: str = typer.Option(None, "--repo", help="Git repo URL."),
+):
+    """Update installed skills (git pull)."""
+    skills_install(repo=repo, force=False)
+
+
+# ----------------------------------------------------------- coderio mcp
+
+
+@mcp_app.command("list")
+def mcp_list_cmd():
+    """List configured MCP servers (project + user scope)."""
+    from coderio.cli.mcp_cmd import mcp_list
+
+    console = Console()
+    entries = mcp_list()
+    if not entries:
+        console.print("No MCP servers configured. Add one with [cyan]coderio mcp add <name> --command ...[/cyan]")
+        return
+    # Group by scope for readability.
+    project = [(n, p) for n, s, p in entries if s == "project"]
+    user = [(n, p) for n, s, p in entries if s == "user"]
+    if project:
+        console.print("[bold green]project scope[/bold green] (.mcp.json):")
+        for name, path in project:
+            console.print(f"  - {name}   [dim]{path}[/dim]")
+    if user:
+        console.print("[bold blue]user scope[/bold blue] (~/.coderio/mcp.json):")
+        for name, path in user:
+            console.print(f"  - {name}   [dim]{path}[/dim]")
+
+
+@mcp_app.command("add")
+def mcp_add_cmd(
+    name: str = typer.Argument(..., help="Server name (used as tool-name prefix)."),
+    type: str = typer.Option("stdio", "--type", help="Transport: stdio (default), http, or sse."),
+    command: str = typer.Option(None, "--command", help="stdio: executable to run (e.g. npx)."),
+    url: str = typer.Option(None, "--url", help="http/sse: server endpoint URL."),
+    scope: str = typer.Option("project", "--scope", help="Config scope: project (default) or user."),
+    arg: list[str] = typer.Option(
+        None, "--arg", help="stdio: argument (repeatable, in order). E.g. --arg -y --arg @mcp/server-fs"
+    ),
+):
+    """Add an MCP server to the project (.mcp.json) or user (~/.coderio/mcp.json) config."""
+    from coderio.cli.mcp_cmd import mcp_add
+
+    result = mcp_add(
+        name,
+        server_type=type,
+        command=command,
+        url=url,
+        args=arg,
+        scope=scope,
+    )
+    console = Console()
+    if result.success:
+        console.print(f"[green]{result.action.capitalize()}[/green]: {result.message}")
+    else:
+        console.print(f"[red]Error:[/red] {result.message}")
+        raise typer.Exit(1)
+
+
+@mcp_app.command("remove")
+def mcp_remove_cmd(
+    name: str = typer.Argument(..., help="Server name to remove."),
+    scope: str = typer.Option("project", "--scope", help="Config scope: project (default) or user."),
+):
+    """Remove an MCP server entry (no-op if the name is absent)."""
+    from coderio.cli.mcp_cmd import mcp_remove
+
+    result = mcp_remove(name, scope=scope)
+    console = Console()
+    if result.action == "noop":
+        console.print(f"[yellow]No-op:[/yellow] {result.message}")
+    else:
+        console.print(f"[green]{result.action.capitalize()}[/green]: {result.message}")
+
+
+@app.command("run")
+def run_cmd(
+    task: str = typer.Argument(..., help="Task text for a one-shot headless agent run."),
+    provider: str = typer.Option(None, "--provider", help="Override provider_id."),
+    model: str = typer.Option(None, "--model", help="Override model name."),
+    permission: str = typer.Option(
+        "full",
+        "--permission",
+        "-p",
+        help="Permission tier: full (default, headless can't answer prompts), plan, confirm, auto_edit.",
+    ),
+    session_id: str = typer.Option(None, "--session-id", help="Resume a prior session by id."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Print only the final result."),
+):
+    """One-shot headless agent run (CI / scripting / benchmarks).
+
+    Streams tokens to stdout by default; tool progress goes to stderr. Never
+    prompts interactively — untrusted repo config or missing credentials are
+    hard errors. The command blacklist still applies in full mode.
+    """
+    from coderio.cli.run_cmd import run_headless
+
+    run_headless(
+        task,
+        provider=provider,
+        model=model,
+        permission=permission,
+        session_id=session_id,
+        quiet=quiet,
+    )
+
+
+@app.command("config")
+def config_cmd():
+    """Print current configuration."""
+    cfg = load_config()
+    effective_base_url = cfg.model.base_url
+    if cfg.model.provider_id:
+        from coderio.cli.providers import get_provider
+
+        info = get_provider(cfg.model.provider_id)
+        if info is not None:
+            effective_base_url = info.base_url or "(user-supplied at runtime)"
+    console = Console()
+    console.print(
+        Panel(
+            f"provider_id: {cfg.model.provider_id or '(none)'}"
+            f"\nprovider:    {cfg.model.provider}"
+            f"\nmodel:       {cfg.model.default}"
+            f"\nbase_url:    {effective_base_url}"
+            f"\npermission:  {cfg.tools.permission_mode}"
+            f"\nskills repo: {cfg.skills.repo_url}",
+            title="coderio config",
+            border_style="blue",
+        )
+    )
+
+
+def main_entry() -> None:
+    # Ensure stdout/stderr use UTF-8 on Windows. The default Windows console
+    # encoding (cp1252) can't represent CJK characters in the Rich/Typer output
+    # (Chinese UI strings, skill names), causing UnicodeEncodeError. Reconfiguring
+    # here makes `coderio --help` and `coderio config` work in any locale —
+    # matching the behavior Linux/macOS users get by default.
+    import sys
+
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if stream is not None and hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass  # already reconfigured or unsupported — ignore
+    app()
+
+
+if __name__ == "__main__":
+    main_entry()