pcode 0.1.0__py3-none-any.whl

pcode/extension_guide.md

@@ -0,0 +1,311 @@
+# Writing a pcode extension
+
+An extension is one Python file that defines `setup(pcode)`. pcode imports it
+when the agent starts and again on `/reload`, calls `setup`, and wires whatever
+it registered into the agent and the terminal.
+
+## Where to put it
+
+| Location | Scope | Loads |
+| --- | --- | --- |
+| `~/.config/pcode/extensions/<name>.py` (or `$XDG_CONFIG_HOME/pcode/extensions/`) | user, every workspace | always |
+| `<workspace>/.pcode/extensions/<name>.py` | this project | only once the user trusts the repository (launch prompt, or `project_extensions on`) |
+| `/config set extension_dirs DIR:DIR` | extra directories | always |
+| `src/pcode/extensions/` (shipped with pcode) | bundled defaults | always |
+
+A directory with `__init__.py` works too, for multi-file extensions. Names
+starting with `_` or `.` are skipped. When two directories hold the same name,
+the project one wins, then user, then configured, then bundled. That is how a
+bundled default is replaced: a user file named `web_research.py` overrides the
+shipped web search and fetch tools, and one whose `setup` does nothing removes
+them. The bundled files are ordinary extensions and worth reading as examples.
+
+After writing or changing an extension, run `/reload` (or tell the user to). It
+rebuilds the agent around the current conversation and prints each extension's
+status; a broken one is reported with its error and line and contributes
+nothing, and the session keeps working. `/extensions` lists the current state.
+
+## Turning one on and off
+
+`/extensions` lists every extension found, where it came from, and what it
+contributed (or why it did not). `/extensions off NAME` stops it loading at all
+and `/extensions on NAME` brings it back; either reloads the session and is
+remembered in the `extensions_off` / `extensions_on` preferences. This works for
+bundled extensions too, so `/extensions off web_research` removes the shipped web
+tools without writing a replacement file.
+
+An extension that should ship opt-in says so at module level:
+
+```python
+DEFAULT_ENABLED = False  # Discovered and listed, but loads only after /extensions on <name>
+```
+
+pcode still imports the module to read that flag, so keep import-time work
+cheap; `setup` does not run until the user turns it on.
+
+## The API
+
+```python
+from pcode.ext import ExtensionAPI
+
+
+def setup(pcode: ExtensionAPI) -> None: ...
+```
+
+`pcode.name` is the file stem, `pcode.workspace` the resolved workspace path.
+`pcode.session_dir` is the resolved session-storage root, honoring `--session-dir`,
+`PCODE_SESSION_DIR`, and the default state directory.
+
+### Tools the model can call
+
+```python
+@pcode.tool
+def ticket_status(ticket_id: str) -> str:
+    """Look up a ticket's title and status."""
+    return subprocess.run(["tk", "show", ticket_id], capture_output=True, text=True).stdout
+```
+
+The docstring is the description the model sees; the type hints become the
+schema (this is Pydantic AI's `Agent.tool_plain`). `async def` works. Raise
+`pydantic_ai.ModelRetry("...")` to send the model a correction instead of a
+result.
+
+### Extra instructions
+
+```python
+pcode.instructions("Always run `make lint` before declaring a change finished.")
+```
+
+Keep this text fixed for the life of the session. It sits in the cached prompt
+prefix, so anything that changes between requests (time, git status) breaks
+caching on every turn. Read changing state inside a tool or hook instead.
+
+### Hooks on the agent lifecycle
+
+`pcode.hooks.on.<name>` are Pydantic AI's `Hooks` decorators. The ones worth
+knowing:
+
+```python
+from pydantic_ai import ModelRetry
+
+
+@pcode.hooks.on.before_tool_execute
+async def guard(ctx, *, call, tool_def, args):
+    """Runs before every tool call; return args (possibly modified) or raise to block."""
+    if tool_def.name == "shell" and "rm -rf" in str(args.get("command", "")):
+        pcode.ui.notify(f"Blocked: {args['command']}", "warning")
+        raise ModelRetry("Destructive command blocked by the rm-guard extension.")
+    return args
+
+
+@pcode.hooks.on.after_tool_execute
+async def log(ctx, *, call, tool_def, args, result):
+    """Runs after; return the result (possibly modified)."""
+    return result
+
+
+@pcode.hooks.on.before_model_request
+async def before(ctx, request_context):
+    return request_context
+
+
+@pcode.hooks.on.after_run
+async def done(ctx, *, result):
+    return result
+```
+
+Other hook names: `before_run`, `before_model_request`, `after_model_request`,
+`before_tool_validate`, `after_tool_validate`, `tool_execute` (wrap: receives
+`handler` and must call it), `tool_execute_error`, `event` (every stream
+event), `prepare_tools` (filter or rewrite the tool definitions the model
+sees). Each must return what it was given unless it means to change it.
+
+Tool names in this agent: `read_file`, `write_file`, `edit_file`, `list_files`,
+`grep`, `shell`, `write_plan`, `delegate_task`, plus any MCP or extension tools.
+
+### Slash commands
+
+```python
+def standup(argument: str) -> None:
+    log = subprocess.run(
+        ["git", "log", "--since=yesterday", "--oneline"], capture_output=True, text=True
+    )
+    pcode.ui.notify(log.stdout or "No commits since yesterday.")
+
+
+pcode.register_command("/standup", "Summarize commits since yesterday", standup)
+pcode.register_command(
+    "/mode",
+    "Set a mode",
+    set_mode,
+    arguments=("fast", "careful"),
+    argument_descriptions={"fast": "Skip verification", "careful": "Verify every step"},
+)
+```
+
+Pass `complete_paths=True` to Tab-complete the argument (after any leading
+`--option` words) as a file or directory path.
+
+Handlers run on the terminal's event loop, so keep them quick. Raise
+`ValueError("message")` to show a usage error. A name pcode already uses is
+reported and skipped. Commands cannot send a prompt to the model; to do that,
+write a skill (`SKILL.md`) instead.
+
+### Sub-agents
+
+```python
+from pydantic_ai import Agent
+
+reviewer = Agent(name="reviewer", description="Review a diff for bugs", instructions="...")
+pcode.subagent(reviewer, timeout_seconds=600)
+```
+
+The agent is listed beside the worker under `delegate_task`. Leave its model
+unset to run on the session's model; keyword options are Harness `SubAgent`
+fields (`usage_limits`, `timeout_seconds`, `max_calls`). Give it capabilities
+of its own; the parent's tools are not inherited.
+
+Without an explicit `usage_limits` the delegate gets its own uncapped request
+counter, so a long delegation cannot exhaust the turn, and it has no timeout.
+Pass `usage_limits=UsageLimits(request_limit=N)` or `timeout_seconds` to bound
+it; either returns a steering message and discards the delegate's result.
+Overriding it with `None` shares the parent's counter, where the library's
+50-request default aborts the run.
+
+The built-in worker shares the parent's workspace by default. Isolated delegation
+requires both `worktree=on` and `worker_isolation=on` in the active workspace's
+effective preferences; `worker_isolation` defaults to `off`. With both on, default
+delegation creates an isolated checkout, while explicit `shared` remains available.
+Specialized delegates registered here remain shared and cannot request isolated
+mode because pcode cannot reconstruct their tools.
+
+For isolated workers, pcode re-runs each successfully loaded extension's `setup`
+with the child's `pcode.workspace` and `pcode.is_worker=True` (false for the
+parent). Treat setup as per-agent initialization: do not assume it runs only once
+per terminal, and register child-owned resources with `on_close`. If an extension
+borrows a process-global resource, only its parent setup should register that
+resource's closer (`if not pcode.is_worker`). The bundled browser follows this
+rule: workers may use the session browser but must not close it on return.
+Setup, tool calls, and close hooks all run with the child's shell-job registry.
+The child retains the parent's effective preferences and session storage root. Only child resources are closed afterward; child slash commands
+and reload requests are not installed in the parent's UI. A failed child setup
+fails that delegation rather than silently dropping tools or guardrails.
+
+Programmatic callers should pass `load_extensions(...).capabilities` unchanged
+when creating the agent. This list-compatible collection preserves the factories
+needed to bind extensions to another workspace; flattening it to a plain list
+loses that provenance, and isolated delegation then refuses the unsafe rebind.
+
+To give a delegate a task plan that also shows in the Tasks widget beneath its
+`delegate_task` row, use pcode's planning capability rather than Harness's:
+
+```python
+from pcode.planning import IdentifiedPlanning
+
+reviewer = Agent(name="reviewer", description="...", capabilities=[IdentifiedPlanning()])
+```
+
+It is Harness `Planning` with guidance that tells the model the user watches
+the plan, plus an announcement of the plan after each planning call; the plan
+itself stays private to the delegate's run. A plain Harness `Planning()` works
+for the delegate but never reaches the widget.
+
+### Notices and lifecycle
+
+`pcode.ui.notify(text, level="info" | "warning" | "error")` prints a transient
+line in the transcript. Safe to call from tools, hooks, and commands.
+
+`pcode.ui.request_reload()` asks for `/reload` once the terminal is idle, for a
+command that changes what `setup` contributes (see the bundled `browser.py`,
+whose `/browser launch` adds tools). Mid-turn it waits for the turn to end, so
+the running turn keeps the tools it started with. It raises `ValueError` without
+a live model session, so call it before changing state. State that must survive the reload cannot live in the
+extension module, which is re-imported.
+
+`@pcode.on_close` registers an `async` function run when the terminal exits,
+for a process or connection a tool started.
+
+### Anything else
+
+```python
+pcode.add_capability(SomeCapability(...))
+```
+
+Any Pydantic AI `AbstractCapability` subclass, or a Harness capability, can be
+added directly. This is the full power of the system; the helpers above are
+shortcuts to it. The capability gets `id="ext.<name>"` if it has none, so
+`/status` can attribute its prompt cost.
+
+## Rules of thumb
+
+- Do import work inside functions when it is slow or optional; `setup` runs on
+  every start and reload.
+- Do not start background processes or threads in `setup`; start them lazily
+  from the tool or command that needs them.
+- Extensions run with the user's full permissions, in-process. There is no
+  sandbox.
+- Standard library and everything pcode depends on (`pydantic_ai`,
+  `pydantic_ai_harness`, `rich`, `httpx`) are importable. Other packages are
+  not unless installed into pcode's environment.
+- Test the file imports cleanly before `/reload`: `python -c "import runpy;
+  runpy.run_path('path/to/ext.py')"` catches syntax errors early.
+
+## Pydantic AI reference
+
+The helpers above wrap Pydantic AI directly, so for anything this guide only
+names (hook signatures, `RunContext`, `ModelRetry`, capability classes, building
+an `Agent` for a sub-agent) read Pydantic AI's docs rather than working from
+memory. Read them at the installed version, not `main`; the website tracks
+unreleased APIs:
+
+```sh
+python -c "from importlib.metadata import version; print(version('pydantic-ai-slim'))"
+```
+
+With that version as `vX.Y.Z`, fetch
+`https://raw.githubusercontent.com/pydantic/pydantic-ai/vX.Y.Z/docs/<topic>.md`
+for `hooks`, `tools`, `tools-advanced`, `toolsets`, or `agent`, and
+`docs/capabilities/overview.md` or `docs/capabilities/custom.md` for
+capabilities (there is no `capabilities.md`). The installed source is beside
+this file's package (`import pydantic_ai; pydantic_ai.__file__`) and wins when
+a doc disagrees. Harness capabilities (`pydantic_ai_harness`) live in the same
+repository and release: their docs are under `docs/harness/<name>.md` at the
+same `vX.Y.Z` tag. Every Harness capability reads and writes through the run's
+workspace (`ctx.workspace`); pcode attaches a `LocalWorkspace` on the session's
+directory.
+
+## Complete example
+
+`~/.config/pcode/extensions/protect_env.py`:
+
+```python
+"""Refuse to edit secret files and offer a /secrets command to list them."""
+
+from fnmatch import fnmatch
+
+from pydantic_ai import ModelRetry
+
+PROTECTED = (".env", ".env.*", "*.pem", "*.tfvars")
+EDIT_TOOLS = {"write_file", "edit_file"}
+
+
+def setup(pcode):
+    def protected(path: str) -> bool:
+        name = path.rsplit("/", 1)[-1]
+        return any(fnmatch(name, pattern) for pattern in PROTECTED)
+
+    @pcode.hooks.on.before_tool_execute
+    async def guard(ctx, *, call, tool_def, args):
+        if tool_def.name in EDIT_TOOLS and protected(str(args.get("path", ""))):
+            pcode.ui.notify(f"Refused to edit {args['path']}", "warning")
+            raise ModelRetry(f"{args['path']} holds secrets; ask the user to edit it.")
+        return args
+
+    pcode.instructions("Never write to .env, key, or tfvars files; ask the user instead.")
+
+    pcode.register_command(
+        "/secrets",
+        "Show which file patterns are write-protected",
+        lambda _: pcode.ui.notify("Protected: " + ", ".join(PROTECTED)),
+    )
+```

pcode/extensions/browser.py

@@ -0,0 +1,284 @@
+"""A real Chrome the model can drive, with the user logging in by hand.
+
+Off by default and per conversation: `/browser launch` or `/browser attach`
+adds Harness's eighteen Playwright tools plus `browser_open` and
+`browser_tabs`, and a `browser` sub-agent that runs multi-step flows without
+the page text landing in the parent's context. `/browser off` closes it and
+removes the tools.
+
+The browser is the user's own Chrome, started with a debugging port and a
+profile of its own that keeps logins between pcode sessions; `/browser attach`
+joins the Chrome the user already has open instead (see `pcode.browser`).
+The window is visible on purpose: a sign-in page is left to the user, who logs
+in there and says so in the next message, and the user sees what the model
+does with that session afterwards. There is no sandbox around it beyond the address bar: a
+page the model reads can tell it to do things with the user's login, which is
+the trade-off of turning this on.
+
+The state itself lives in `pcode.browser`, since `/reload` re-imports this file.
+Copy this file to `~/.config/pcode/extensions/browser.py` to change defaults;
+an empty `setup` removes the feature.
+"""
+
+import asyncio
+
+from pcode.browser import REMOTE_DEBUGGING_PAGE, STATE, show_remote_debugging_toggle
+
+DELEGATE_INSTRUCTIONS = (
+    "A `browser` sub-agent shares the same browser window and login. Delegate to it "
+    "when a browsing task takes several steps and you only need the outcome (find a "
+    "value, verify a flow works, reproduce a bug), so page text stays out of this "
+    "conversation. Drive the browser yourself for a single check or a screenshot, "
+    "and whenever a page needs the user to sign in."
+)
+
+LOGIN_INSTRUCTIONS = {
+    "attach": (
+        "This is the user's own Chrome: every site they are signed in to is already "
+        "signed in here, so just `navigate`."
+    ),
+    "own": (
+        "The browser profile persists between conversations, so a site the user logged "
+        "in to before is still logged in; just `navigate`."
+    ),
+}
+
+SIGN_IN_INSTRUCTIONS = (
+    "When a page turns out to be a sign-in page, never type credentials. Call "
+    "`browser_open` so the window is in front, then end your turn asking the user to "
+    "log in there and tell you when they are done; continue from the same page when "
+    "they do."
+)
+
+SUBAGENT_INSTRUCTIONS = (
+    "You drive a real browser through the tools available to you and report back "
+    "concisely: what you found, what worked, what failed, and the final URL. Do not "
+    "narrate each step. If a page needs a login that is not present, stop and say so "
+    "rather than guessing credentials; the parent will ask the user."
+)
+
+
+def _spawn(coroutine) -> None:
+    """Run a coroutine on the terminal's loop, or inline when there is none (tests)."""
+    try:
+        asyncio.get_running_loop().create_task(coroutine)
+    except RuntimeError:
+        asyncio.run(coroutine)
+
+
+async def _start(pcode) -> None:
+    """Have Chrome up and the session armed, reporting a launch to the user."""
+    await STATE.arm()
+    if note := await STATE.ensure_chrome():
+        pcode.ui.notify(note)
+
+
+async def _replace_lost_page(session, page) -> bool:
+    """Give the session a live tab after the user closed `page` or the browser.
+
+    Harness keeps pointing at the last page it had once that page closes, so a
+    later call would fail on it forever. Returns False when `page` is still
+    open, so an unrelated failure is reported rather than abandoning a live tab.
+    """
+    from playwright.async_api import Error as PlaywrightError
+
+    browser = session._browser
+    connected = browser is not None and browser.is_connected()
+    if connected and not page.is_closed():
+        return False
+    if connected and session._context is not None:
+        try:
+            # Same context, so the login survives; the Chromium fallback would
+            # lose its cookies to a reconnect.
+            await session.open_tab()
+            return True
+        except PlaywrightError:
+            pass  # The context went with the window; reconnect below.
+    # The connection is gone: forget its pages so the next navigate reconnects.
+    session.page = None
+    session.pages = []
+    return True
+
+
+def _capability(pcode, toolset):
+    """The browser tools, the open and login tools, and their guidance, sharing one session."""
+    from playwright.async_api import Error as PlaywrightError
+    from pydantic_ai.capabilities import Capability
+    from pydantic_ai_harness.playwright import BrowserUnavailableError, PlaywrightBrowser
+
+    browser_tools = set(toolset.tools) | {"browser_open", "browser_tabs"}
+
+    async def browser_tabs() -> str:
+        """List every tab open in the browser, including the user's own, as title and URL.
+
+        The `tabs` tool covers only tabs this session opened; this one also shows
+        what the user already has open, which tells you which sites and
+        accounts they use (their mail, their issue tracker) so you can open the
+        right URL in your own tab. Read only: act through `navigate`.
+        """
+        await _start(pcode)
+        try:
+            tabs = await STATE.list_tabs()
+        except (PlaywrightError, BrowserUnavailableError):
+            STATE.session.launch_error = None  # Allow another attempt after a failed launch.
+            return (
+                "Could not list browser tabs: the browser is unavailable or did not respond. "
+                "Check /browser status and remote debugging; if needed, use /browser off "
+                "then /browser attach to reconnect."
+            )
+        mine = {page.url for page in STATE.session.pages}
+        lines = []
+        for title, url in tabs:
+            ours = " (yours)" if url in mine else ""
+            lines.append(f"- {title or '(untitled)'}{ours}: {url}")
+        return "\n".join(lines) or "No tabs are open."
+
+    async def browser_open() -> str:
+        """Bring the browser window to the front, opening it first if needed.
+
+        The current page stays as it is. Use it to show the user a page that
+        needs them, such as a sign-in page, before asking them to act there.
+        """
+        await _start(pcode)
+        session = STATE.session
+        for _ in range(2):
+            if session.page is None:
+                result = await toolset.navigate("about:blank")
+                if session.page is None:
+                    return f"The browser could not be opened: {result}"
+            page = session.page
+            try:
+                await page.bring_to_front()
+            except PlaywrightError as error:
+                if not await _replace_lost_page(session, page):
+                    return f"Could not bring the browser to the front: {error}"
+                continue
+            return f"The browser window is in front, showing {page.url}."
+        return (
+            "Could not bring the browser to the front: its window keeps closing. Check "
+            "/browser status; if needed, use /browser off then /browser launch or attach."
+        )
+
+    class Browser(Capability):
+        async def before_tool_execute(self, ctx, *, call, tool_def, args):
+            # Chrome starts on the first browser tool, for the parent and the
+            # sub-agent alike, on the loop the tools run on.
+            if tool_def.name in browser_tools:
+                await _start(pcode)
+            return args
+
+    guidance = PlaywrightBrowser(
+        headless=False, block_private_addresses=False, max_content_tokens=2500
+    ).get_instructions()(None)
+    return Browser(
+        id="browser",
+        toolsets=[toolset],
+        tools=[browser_open, browser_tabs],
+        instructions="\n".join(
+            (
+                guidance,
+                LOGIN_INSTRUCTIONS["attach" if STATE.attach else "own"],
+                SIGN_IN_INSTRUCTIONS,
+            )
+        ),
+    )
+
+
+def _subagent(pcode, toolset):
+    from pydantic_ai import Agent
+
+    return Agent(
+        name="browser",
+        description=(
+            "Drive the shared browser window through a multi-step task and report the "
+            "outcome; the login the user made is already there"
+        ),
+        instructions=SUBAGENT_INSTRUCTIONS,
+        capabilities=[_capability(pcode, toolset)],
+    )
+
+
+def setup(pcode) -> None:
+    def turn_on() -> None:
+        pcode.ui.request_reload()  # Waits out a running turn; refuses with no live session.
+        STATE.enabled = True
+        pcode.ui.notify(
+            "Browser tools on for this conversation. Pages the model reads can act on "
+            "whatever you log in to there."
+        )
+
+    def browser(argument: str) -> None:
+        argument = argument.strip() or "status"
+        if argument == "launch":
+            if STATE.session is not None:
+                raise ValueError("A browser is already open; /browser off first.")
+            turn_on()
+            STATE.open()
+            _spawn(_launch())
+        elif argument == "attach":
+            if STATE.session is not None:
+                raise ValueError("A browser is already open; /browser off first.")
+            STATE.attach = True
+            try:
+                STATE.open()
+            except ValueError:
+                STATE.attach = False
+                if show_remote_debugging_toggle():
+                    pcode.ui.notify(
+                        f"Opened {REMOTE_DEBUGGING_PAGE} in your Chrome. Turn the switch on, "
+                        "then run /browser attach again."
+                    )
+                    return
+                raise
+            if not STATE.enabled:
+                try:
+                    turn_on()
+                except ValueError:
+                    # Refused (no live session): leave nothing half-open behind.
+                    _spawn(STATE.close())
+                    raise
+            pcode.ui.notify(
+                f"Joining your browser at {STATE.cdp_url}: the model can act as every account "
+                "you are signed in to there. A new tab opens on first use.",
+                "warning",
+            )
+        elif argument == "off":
+            if not STATE.enabled:
+                raise ValueError("The browser is already off.")
+            pcode.ui.request_reload()
+            # The reload's `setup` closes it: a running turn keeps the tools until then.
+            STATE.enabled = False
+            pcode.ui.notify("Browser off; it closes as its tools leave.")
+        else:
+            pcode.ui.notify(f"Browser {STATE.describe()}. /browser launch|attach|off.")
+
+    async def _launch() -> None:
+        try:
+            await _start(pcode)
+            await STATE.toolset.navigate("about:blank")
+        except Exception as error:  # noqa: BLE001 - a failed launch is a notice, not a crash.
+            pcode.ui.notify(f"Browser launch failed: {error}", "error")
+
+    pcode.register_command(
+        "/browser",
+        "A real browser the model can drive; `launch` opens Chrome, `attach` joins yours",
+        browser,
+        arguments=("launch", "attach", "off", "status"),
+        argument_descriptions={
+            "launch": "Open pcode's own Chrome window, with its own logins",
+            "attach": "Join Chrome, Chromium, or Edge, logins included; needs remote debugging on",
+            "off": "Close the browser and remove the tools",
+            "status": "Show which browser is in use and where it is",
+        },
+    )
+    # Workers borrow the session browser, not ownership of its process/connection.
+    if not pcode.is_worker:
+        pcode.on_close(STATE.close)
+    if not STATE.enabled:
+        if not pcode.is_worker and STATE.session is not None:
+            _spawn(STATE.close())  # `/browser off`, now that no agent holds the tools.
+        return
+    toolset = STATE.open()
+    pcode.add_capability(_capability(pcode, toolset))
+    pcode.instructions(DELEGATE_INSTRUCTIONS)
+    pcode.subagent(_subagent(pcode, toolset), timeout_seconds=900)