toolplane 0.2.0__tar.gz → 0.3.0__tar.gz

{toolplane-0.2.0 → toolplane-0.3.0}/AGENTS.md

@@ -54,6 +54,15 @@ more custom code around it.
   capability envelope.
 - Pyodide+Deno is the opt-in sandbox for package-capable snippets, especially
   pandas/NumPy-style workflows.
+- Monty sessions (`docs/monty-session-spike.md`) persist the live namespace
+  across runs by default (stdio/embedded only): a timed-out run rolls the
+  namespace back via a pre-run snapshot — never remove that snapshot, it is
+  what keeps a cancelled run from poisoning the interpreter
+  (pydantic/monty#533) — and host-side effects are never rolled back.
+- The result store (`save_result`/`load_result`, `docs/result-store-design.md`)
+  persists JSON-shaped data across runs within one process; it never persists
+  interpreters or anything to disk. With sessions on, its remaining jobs are
+  surviving a session reset, crossing backends, and MCP-resource reads.
 - Docker, Modal, E2B, and Blaxel are needed for arbitrary CPython packages,
   native system dependencies, subprocesses, GPUs, remote isolation, or
   long-running jobs.

{toolplane-0.2.0 → toolplane-0.3.0}/Makefile

@@ -27,6 +27,9 @@ examples:
 	$(UV) run --no-project --with-editable . python examples/mcp_stdio_config.py
 	$(UV) run --no-project --with-editable . python examples/multi_server.py
 	$(UV) run --no-project --with-editable . python examples/from_config.py
+	env -u ANTHROPIC_API_KEY -u OPENAI_API_KEY $(UV) run --no-project --with-editable . --with pydantic-ai python examples/as_tool_pydantic_ai.py
+	env -u ANTHROPIC_API_KEY -u OPENAI_API_KEY $(UV) run --no-project --with-editable . --with openai-agents python examples/as_tool_openai_agents.py
+	env -u ANTHROPIC_API_KEY -u OPENAI_API_KEY $(UV) run --no-project --with-editable . --with langchain-core python examples/as_tool_langgraph.py
 
 docs:
 	$(UV) run --no-project --with-editable ".[docs]" mkdocs build --strict --site-dir $(SITE_DIR)

toolplane-0.3.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: toolplane
+Version: 0.3.0
+Summary: A controlled Python code-mode runtime for programmable tool surfaces.
+License: MIT
+Keywords: agents,cli,code-mode,mcp,runtime,tools
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cli-to-py>=0.2
+Requires-Dist: fastmcp>=3.1
+Requires-Dist: pydantic-monty<0.0.19,>=0.0.18
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tomlkit>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<9.7,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# toolplane
+
+[![PyPI version](https://img.shields.io/pypi/v/toolplane)](https://pypi.org/project/toolplane/)
+[![Python versions](https://img.shields.io/pypi/pyversions/toolplane)](https://pypi.org/project/toolplane/)
+[![CI](https://github.com/oneryalcin/toolplane/actions/workflows/ci.yml/badge.svg)](https://github.com/oneryalcin/toolplane/actions/workflows/ci.yml)
+[![Docs](https://github.com/oneryalcin/toolplane/actions/workflows/pages.yml/badge.svg)](https://github.com/oneryalcin/toolplane/actions/workflows/pages.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Define your agent's tool surface **once** — MCP servers, CLI binaries, Python
+functions — and get the same curated, sandboxed Python namespace under every
+agent client you use: Claude Code, Codex, opencode, or your own.
+
+Full documentation: https://oneryalcin.github.io/toolplane/
+
+## Why
+
+Agents are strongest when they use code as the control plane: looping,
+filtering, retrying, and combining tools in one pass instead of bouncing
+through one tool call at a time. Toolplane is the runtime for that:
+
+```text
+discover capabilities -> inspect schemas -> execute Python against a curated namespace
+```
+
+Instead of registering N MCP servers in every agent client (and paying for
+N × dozens of tool schemas in every context window, in every client, with
+every client's different quirks), you register **one** server that exposes
+three meta-tools. Your agent searches for what it needs, reads the exact
+schemas, and writes a snippet:
+
+```python
+# one execute_code call replaces a dozen round-trips
+rows = []
+for repo in ["toolplane", "cli-to-py"]:
+    prs = await github_list_pull_requests(repo=repo, state="merged", limit=25)
+    for pr in prs:
+        rows.append({"repo": repo, "title": pr["title"], "days_open": pr["days_open"]})
+handle = await save_result(rows, label="pr-audit")
+return {"count": len(rows), "handle": handle}
+```
+
+What makes toolplane different from other code-mode runtimes:
+
+- **CLI binaries are first-class, policy-gated capabilities.** `git`, `gh`,
+  `jq` become async Python functions behind an allowlist you control — not a
+  raw shell. No other code-mode runtime ships this lane.
+- **Policy escalates to a human instead of dead-ending.** If a snippet needs
+  a binary outside the allowlist, your agent client shows *you* a form:
+  allow it for this session, or refuse. Declines stick; nothing is ever
+  written back to config. (MCP elicitation; degrades to a plain refusal on
+  clients that can't prompt.)
+- **Safe by default, with zero infrastructure.** The default backend
+  ([Monty](https://github.com/pydantic/monty)) is a sandboxed interpreter
+  with no filesystem or network access — a pure `pip install`, no Docker, no
+  Deno, no daemon.
+- **Engineered for how agents actually behave.** Every dead end emits a
+  signpost (no-match searches say how to browse; policy errors name what is
+  allowed), errors are catchable by builtin type on every backend, and the
+  live namespace manifest (`toolplane://namespace`) never lies about the
+  server's configuration. This surface is certified by cold-start agent
+  sessions, not just unit tests — the design lessons are published in
+  [Agents Don't Find Resources](https://oneryalcin.github.io/toolplane/agents-dont-find-resources/)
+  and the firsthand
+  [MCP Client Capability Matrix](https://oneryalcin.github.io/toolplane/mcp-client-capability-matrix/).
+
+## Quickstart
+
+Set up a config (safe defaults: sandboxed backend, CLI disabled):
+
+```bash
+uvx toolplane init
+uvx toolplane cli allow git
+uvx toolplane mcp add context7 --url https://mcp.context7.com/mcp
+uvx toolplane doctor
+```
+
+Prove it runs — put this in `first.py`:
+
+```python
+v = await git("version")
+return {"ok": v["ok"], "git": v["stdout"].strip()}
+```
+
+```bash
+uvx toolplane run first.py
+```
+
+Then register it with your agent client (use the absolute path to your
+`toolplane.toml`):
+
+```bash
+# Claude Code
+claude mcp add toolplane -- uvx toolplane serve mcp --config /path/to/toolplane.toml
+
+# Codex
+codex mcp add toolplane -- uvx toolplane serve mcp --config /path/to/toolplane.toml
+```
+
+```jsonc
+// opencode (~/.config/opencode/opencode.json)
+{
+  "mcp": {
+    "toolplane": {
+      "type": "local",
+      "command": ["uvx", "toolplane", "serve", "mcp", "--config", "/path/to/toolplane.toml"]
+    }
+  }
+}
+```
+
+Every client now sees the same three tools — `search_capabilities`,
+`get_capability_schemas`, `execute_code` — plus the live manifest resource
+`toolplane://namespace` and a bundled usage skill. Ask your agent to read the
+manifest and go.
+
+## What your agent gets
+
+- **Three meta-tools instead of a tool catalog.** Search is exact-word (an
+  empty query lists everything); schemas come back only for the capabilities
+  the snippet will actually use.
+- **A flat, async Python namespace.** MCP tools as flat functions —
+  `await context7_get_docs(...)` — or canonically as
+  `await call_tool("mcp:context7/get_docs", {...})`; allowlisted CLI
+  binaries as `await git("log", oneline=True, max_count=3)` returning
+  `{'stdout', 'stderr', 'exit_code', 'ok'}`. (Scoped sugar like
+  `context7.get_docs(...)` exists on the non-default backends; the monty
+  default is flat-only — the manifest always shows the shapes that work.)
+- **State between runs, off the context window.** Variables persist across
+  runs like notebook cells (a timed-out run rolls back cleanly;
+  `await reset_session()` starts fresh). For values that must survive a
+  reset or be read as MCP resources: `save_result`/`load_result` for
+  JSON-shaped data, `save_artifact`/`load_artifact` for bytes (CSVs,
+  images, parquet) — on Claude Code, a saved artifact materializes as a
+  real local file.
+- **Errors written for agents, not log files.** The real exception type and
+  message on every backend, catchable by builtin type (`except ValueError`
+  for store failures, `except PermissionError` for CLI policy,
+  `except LookupError` for unknown capabilities) — identically on all three
+  backends.
+
+## Use it as a library
+
+The same runtime embeds directly in Python — register your own functions and
+execute agent-written snippets against them, sandboxed, with no server in
+between:
+
+```python
+from toolplane import Toolplane
+
+runtime = Toolplane()
+
+@runtime.tool(tags={"math"})
+def add(x: int, y: int) -> int:
+    """Add two numbers."""
+    return x + y
+
+result = await runtime.execute("""
+value = await call_tool("add", {"x": 2, "y": 3})
+return value
+""")
+```
+
+And if you already have an agent framework, `as_tool()` packages the whole
+runtime as one `run_code` tool — a plain async function with a generated
+description (compact enough for OpenAI's tool-description cap) that
+pydantic-ai, the OpenAI Agents SDK, and LangChain/LangGraph all accept
+directly. It is sandboxed monty by default: model-authored code never
+inherits the `local_unsafe` dev backend implicitly — that requires an
+explicit `backend="local_unsafe"` opt-in:
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent("anthropic:claude-sonnet-5", tools=[runtime.as_tool()])
+```
+
+MCP servers, explicit CLI wrappers, and scoped Python namespaces register the
+same way — see the [library guide](https://oneryalcin.github.io/toolplane/)
+and [examples](examples/README.md) for the full surface, including
+config-driven setup (`Toolplane.from_config`), the result/artifact stores,
+and runnable `as_tool` examples for all three frameworks.
+
+## Backends
+
+| Backend | Use | Status |
+| --- | --- | --- |
+| `monty` | Default. Sandboxed by construction (no filesystem/network), pure pip install. Flat callable namespace — no classes, no third-party imports. | Active |
+| `pyodide-deno` | Opt-in for package-capable snippets (pandas/NumPy-style) via Pyodide in Deno. | Supported, feature-frozen |
+| `local_unsafe` | In-process execution for development only. | Dev only |
+
+A container backend (real CPython, arbitrary packages) lands when a concrete
+use case needs it. See [Code Mode Backends](docs/code-mode-backends.md) for
+the design record.
+
+## Design goals
+
+- Normalize heterogeneous tools into a Python-first API surface; JSON is the
+  wire format, not the programming model.
+- Keep the exposed runtime curated rather than ambiently powerful; the host
+  decides which capabilities exist and what boundaries apply.
+- Durable policy lives in config; session policy (escalation grants) dies
+  with the process.
+- Canonical capability ids are qualified (`mcp:server/tool`); friendly
+  aliases exist only when unambiguous.
+- Every slice earns its place through behavior, tests, or live certification.
+
+## Development
+
+```bash
+make test
+make examples
+make ci
+make publish-check
+```
+
+Docs: `make docs` / `make docs-serve`. Publishing:
+`PYPI_TOKEN=... make publish` — see the
+[release checklist](docs/development/release-checklist.md).
+
+See [ROADMAP.md](ROADMAP.md) for sequencing and
+[Architecture](docs/architecture.md) for code organization.

toolplane-0.3.0/README.md

@@ -0,0 +1,221 @@
+# toolplane
+
+[![PyPI version](https://img.shields.io/pypi/v/toolplane)](https://pypi.org/project/toolplane/)
+[![Python versions](https://img.shields.io/pypi/pyversions/toolplane)](https://pypi.org/project/toolplane/)
+[![CI](https://github.com/oneryalcin/toolplane/actions/workflows/ci.yml/badge.svg)](https://github.com/oneryalcin/toolplane/actions/workflows/ci.yml)
+[![Docs](https://github.com/oneryalcin/toolplane/actions/workflows/pages.yml/badge.svg)](https://github.com/oneryalcin/toolplane/actions/workflows/pages.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Define your agent's tool surface **once** — MCP servers, CLI binaries, Python
+functions — and get the same curated, sandboxed Python namespace under every
+agent client you use: Claude Code, Codex, opencode, or your own.
+
+Full documentation: https://oneryalcin.github.io/toolplane/
+
+## Why
+
+Agents are strongest when they use code as the control plane: looping,
+filtering, retrying, and combining tools in one pass instead of bouncing
+through one tool call at a time. Toolplane is the runtime for that:
+
+```text
+discover capabilities -> inspect schemas -> execute Python against a curated namespace
+```
+
+Instead of registering N MCP servers in every agent client (and paying for
+N × dozens of tool schemas in every context window, in every client, with
+every client's different quirks), you register **one** server that exposes
+three meta-tools. Your agent searches for what it needs, reads the exact
+schemas, and writes a snippet:
+
+```python
+# one execute_code call replaces a dozen round-trips
+rows = []
+for repo in ["toolplane", "cli-to-py"]:
+    prs = await github_list_pull_requests(repo=repo, state="merged", limit=25)
+    for pr in prs:
+        rows.append({"repo": repo, "title": pr["title"], "days_open": pr["days_open"]})
+handle = await save_result(rows, label="pr-audit")
+return {"count": len(rows), "handle": handle}
+```
+
+What makes toolplane different from other code-mode runtimes:
+
+- **CLI binaries are first-class, policy-gated capabilities.** `git`, `gh`,
+  `jq` become async Python functions behind an allowlist you control — not a
+  raw shell. No other code-mode runtime ships this lane.
+- **Policy escalates to a human instead of dead-ending.** If a snippet needs
+  a binary outside the allowlist, your agent client shows *you* a form:
+  allow it for this session, or refuse. Declines stick; nothing is ever
+  written back to config. (MCP elicitation; degrades to a plain refusal on
+  clients that can't prompt.)
+- **Safe by default, with zero infrastructure.** The default backend
+  ([Monty](https://github.com/pydantic/monty)) is a sandboxed interpreter
+  with no filesystem or network access — a pure `pip install`, no Docker, no
+  Deno, no daemon.
+- **Engineered for how agents actually behave.** Every dead end emits a
+  signpost (no-match searches say how to browse; policy errors name what is
+  allowed), errors are catchable by builtin type on every backend, and the
+  live namespace manifest (`toolplane://namespace`) never lies about the
+  server's configuration. This surface is certified by cold-start agent
+  sessions, not just unit tests — the design lessons are published in
+  [Agents Don't Find Resources](https://oneryalcin.github.io/toolplane/agents-dont-find-resources/)
+  and the firsthand
+  [MCP Client Capability Matrix](https://oneryalcin.github.io/toolplane/mcp-client-capability-matrix/).
+
+## Quickstart
+
+Set up a config (safe defaults: sandboxed backend, CLI disabled):
+
+```bash
+uvx toolplane init
+uvx toolplane cli allow git
+uvx toolplane mcp add context7 --url https://mcp.context7.com/mcp
+uvx toolplane doctor
+```
+
+Prove it runs — put this in `first.py`:
+
+```python
+v = await git("version")
+return {"ok": v["ok"], "git": v["stdout"].strip()}
+```
+
+```bash
+uvx toolplane run first.py
+```
+
+Then register it with your agent client (use the absolute path to your
+`toolplane.toml`):
+
+```bash
+# Claude Code
+claude mcp add toolplane -- uvx toolplane serve mcp --config /path/to/toolplane.toml
+
+# Codex
+codex mcp add toolplane -- uvx toolplane serve mcp --config /path/to/toolplane.toml
+```
+
+```jsonc
+// opencode (~/.config/opencode/opencode.json)
+{
+  "mcp": {
+    "toolplane": {
+      "type": "local",
+      "command": ["uvx", "toolplane", "serve", "mcp", "--config", "/path/to/toolplane.toml"]
+    }
+  }
+}
+```
+
+Every client now sees the same three tools — `search_capabilities`,
+`get_capability_schemas`, `execute_code` — plus the live manifest resource
+`toolplane://namespace` and a bundled usage skill. Ask your agent to read the
+manifest and go.
+
+## What your agent gets
+
+- **Three meta-tools instead of a tool catalog.** Search is exact-word (an
+  empty query lists everything); schemas come back only for the capabilities
+  the snippet will actually use.
+- **A flat, async Python namespace.** MCP tools as flat functions —
+  `await context7_get_docs(...)` — or canonically as
+  `await call_tool("mcp:context7/get_docs", {...})`; allowlisted CLI
+  binaries as `await git("log", oneline=True, max_count=3)` returning
+  `{'stdout', 'stderr', 'exit_code', 'ok'}`. (Scoped sugar like
+  `context7.get_docs(...)` exists on the non-default backends; the monty
+  default is flat-only — the manifest always shows the shapes that work.)
+- **State between runs, off the context window.** Variables persist across
+  runs like notebook cells (a timed-out run rolls back cleanly;
+  `await reset_session()` starts fresh). For values that must survive a
+  reset or be read as MCP resources: `save_result`/`load_result` for
+  JSON-shaped data, `save_artifact`/`load_artifact` for bytes (CSVs,
+  images, parquet) — on Claude Code, a saved artifact materializes as a
+  real local file.
+- **Errors written for agents, not log files.** The real exception type and
+  message on every backend, catchable by builtin type (`except ValueError`
+  for store failures, `except PermissionError` for CLI policy,
+  `except LookupError` for unknown capabilities) — identically on all three
+  backends.
+
+## Use it as a library
+
+The same runtime embeds directly in Python — register your own functions and
+execute agent-written snippets against them, sandboxed, with no server in
+between:
+
+```python
+from toolplane import Toolplane
+
+runtime = Toolplane()
+
+@runtime.tool(tags={"math"})
+def add(x: int, y: int) -> int:
+    """Add two numbers."""
+    return x + y
+
+result = await runtime.execute("""
+value = await call_tool("add", {"x": 2, "y": 3})
+return value
+""")
+```
+
+And if you already have an agent framework, `as_tool()` packages the whole
+runtime as one `run_code` tool — a plain async function with a generated
+description (compact enough for OpenAI's tool-description cap) that
+pydantic-ai, the OpenAI Agents SDK, and LangChain/LangGraph all accept
+directly. It is sandboxed monty by default: model-authored code never
+inherits the `local_unsafe` dev backend implicitly — that requires an
+explicit `backend="local_unsafe"` opt-in:
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent("anthropic:claude-sonnet-5", tools=[runtime.as_tool()])
+```
+
+MCP servers, explicit CLI wrappers, and scoped Python namespaces register the
+same way — see the [library guide](https://oneryalcin.github.io/toolplane/)
+and [examples](examples/README.md) for the full surface, including
+config-driven setup (`Toolplane.from_config`), the result/artifact stores,
+and runnable `as_tool` examples for all three frameworks.
+
+## Backends
+
+| Backend | Use | Status |
+| --- | --- | --- |
+| `monty` | Default. Sandboxed by construction (no filesystem/network), pure pip install. Flat callable namespace — no classes, no third-party imports. | Active |
+| `pyodide-deno` | Opt-in for package-capable snippets (pandas/NumPy-style) via Pyodide in Deno. | Supported, feature-frozen |
+| `local_unsafe` | In-process execution for development only. | Dev only |
+
+A container backend (real CPython, arbitrary packages) lands when a concrete
+use case needs it. See [Code Mode Backends](docs/code-mode-backends.md) for
+the design record.
+
+## Design goals
+
+- Normalize heterogeneous tools into a Python-first API surface; JSON is the
+  wire format, not the programming model.
+- Keep the exposed runtime curated rather than ambiently powerful; the host
+  decides which capabilities exist and what boundaries apply.
+- Durable policy lives in config; session policy (escalation grants) dies
+  with the process.
+- Canonical capability ids are qualified (`mcp:server/tool`); friendly
+  aliases exist only when unambiguous.
+- Every slice earns its place through behavior, tests, or live certification.
+
+## Development
+
+```bash
+make test
+make examples
+make ci
+make publish-check
+```
+
+Docs: `make docs` / `make docs-serve`. Publishing:
+`PYPI_TOKEN=... make publish` — see the
+[release checklist](docs/development/release-checklist.md).
+
+See [ROADMAP.md](ROADMAP.md) for sequencing and
+[Architecture](docs/architecture.md) for code organization.

{toolplane-0.2.0 → toolplane-0.3.0}/ROADMAP.md

@@ -12,7 +12,7 @@ local_unsafe slice
   -> MCP adapter
   -> config-driven runtime setup
   -> Toolplane MCP facade
-  -> Docker/Modal remote backends
+  -> container backend (when a named user needs arbitrary CPython packages)
 ```
 
 The goal is to test the core architecture before building a broad framework
@@ -22,10 +22,12 @@ around it.
 
 ### Execution Backends
 
-- Pyodide+Deno backend for package-capable sandboxed snippets.
-- Docker backend for real CPython, local CLI binaries, and system dependencies.
-- Modal backend for remote package-heavy or longer-running jobs.
-- E2B and Blaxel once the callback bridge and session model are stable.
+- Pyodide+Deno backend for package-capable sandboxed snippets — shipped and
+  feature-frozen: supported as-is, no further edge investment; its use case
+  is served by a container backend when a real user needs it.
+- One container backend (real CPython, arbitrary packages) when a named user
+  asks. Modal/E2B/Blaxel-style remote backends only after that contract is
+  proven — not before.
 
 ### Capability Adapters
 

toolplane-0.3.0/docs/agents-dont-find-resources.md

@@ -0,0 +1,90 @@
+# Agents Don't Find Resources
+
+A design lesson from building toolplane's discovery surface, verified live
+against real agents. It generalizes to any MCP server: **exposing a
+capability is not the same as an agent discovering it.** If you ship a
+resource, a template, or a clever affordance and don't put a plain-text
+pointer to it in a channel the agent already reads, you shipped nothing.
+
+## The experiment that settled it
+
+While building toolplane's namespace manifest (a live MCP resource
+describing every binding an `execute_code` snippet can use), we ran cold
+sessions: a fresh Claude Code agent, the toolplane server connected, a task
+that the manifest would make easy. The agent had the resource-listing tool
+available from turn one.
+
+It never called it. Asked directly afterward — *"if we hadn't told you the
+server exposes resources, would you have discovered them?"* — the agent's
+answer was no. It guessed capability names, misread error text, and
+retried, but at no point did "enumerate the server's resources" enter its
+loop. The capability was present; the behavior wasn't.
+
+That single observation reshaped the whole design: **the resource is the
+payload; the pointer is the feature.**
+
+## The three channels agents actually read
+
+Discovery works only through text that arrives in the agent's context in
+the normal course of work:
+
+1. **Tool descriptions and server instructions** — read once, at session
+   start. This is where standing directives live: toolplane's
+   `execute_code` description says *"Read the toolplane://namespace
+   resource BEFORE writing code — guessing shapes fails."* Cold agents
+   follow it.
+2. **Tool response text on the happy path** — read at the moment of need.
+   When a toolplane snippet saves an artifact, the response carries the
+   handle *and* its resource URI; the agent never has to know that
+   artifacts are enumerable, because the one it needs is already named.
+3. **Error text on the failure path** — the strongest channel, because a
+   failing agent is a searching agent. Every dead end must emit a
+   signpost: toolplane's no-match search reports how many capabilities
+   exist and how to list them; a policy refusal names the allowed
+   binaries; a wrong call shape shows the right one, verbatim, ready to
+   paste.
+
+Listings, templates, and documentation pages are not channels. Claude Code
+doesn't even show templated resource URIs in its listing (see the
+[capability matrix](mcp-client-capability-matrix.md)) — but even where
+listings work, agents don't browse; they act, fail, and read the error.
+
+## The corollary we learned the hard way: signposts can dangle
+
+The doctrine has a failure mode of its own, found when toolplane grew an
+embedded mode (`runtime.as_tool()` — the same runtime as a single tool
+inside pydantic-ai / OpenAI Agents SDK / LangGraph, no MCP anywhere).
+
+A live agent run misremembered a capability name. The error helpfully
+said: *search capabilities with an empty query, or read the
+toolplane://namespace resource.* Neither exists in embedded mode — there
+is no search tool and no resource protocol. The agent obediently tried to
+"search" through the only tool it had, hit a second dead end, and gave up
+on a task it was fully equipped to complete.
+
+So the refined rule: **a signpost must only point at affordances that
+exist in the reader's context — or carry the answer inline.** The fix was
+to make the dead ends self-contained: the unknown-capability error now
+lists the registered names itself; a miss on a CLI binary's name teaches
+the correct call shape in the message; the tool description shows a real
+canonical id instead of a `"canonical:name"` placeholder (which one model
+read literally, inventing `canonical:git`). After the change, the same
+agent completed the same task — the signposts walked it there.
+
+## Design rules, compressed
+
+- Every surface ships with its pointer, in a channel from the list above.
+  A resource without a pointer is dark matter.
+- Every dead end teaches the next move. If an error can be hit by a wrong
+  guess, the message must contain the right guess.
+- Signposts name only what exists *here* — same server, same mode, same
+  policy — or include the answer inline.
+- Deliver concrete URIs in results; never rely on the agent enumerating.
+- Test discovery the only way that counts: a cold agent, a real task, no
+  hints. If it needs a human to say "there's a resource for that," the
+  pointer mesh has a hole.
+
+Everything above was verified against live agents (Claude Code cold
+sessions for the MCP mode; claude-sonnet-5, an OpenAI model, and a
+LangGraph ReAct agent for embedded mode) — the failures described are
+transcripts, not thought experiments.

{toolplane-0.2.0 → toolplane-0.3.0}/docs/architecture.md

@@ -22,7 +22,10 @@ Name the real boundaries early so the code does not collapse into glue:
 - `Schema`: how the agent learns to call something.
 - `Backend`: where code runs.
 - `Bridge`: how sandboxed code calls host capabilities.
-- `Session`: execution state across snippets.
+- `Session`: execution state across snippets. Realized inside the monty
+  backend (persistent namespace, on by default — see the
+  [session spike](monty-session-spike.md) and `[session]` config) rather
+  than as a separate layer: the interpreter that holds the state owns it.
 
 The main rule:
 
@@ -181,7 +184,8 @@ src/toolplane/
     render.py          # brief/detailed/full schema rendering
     json_schema.py     # introspection helpers
 
-  sessions.py          # execution sessions and state
+  # (no sessions.py: session state lives in backends/monty.py — the
+  #  interpreter that holds the namespace owns it)
   errors.py
 ```
 

{toolplane-0.2.0 → toolplane-0.3.0}/docs/code-mode-backends.md

@@ -10,9 +10,13 @@ discover capabilities -> inspect schemas -> execute Python against a curated nam
 
     Monty is the default backend: safe tool orchestration with no external
     dependencies (see the [decision record](monty-default-spike.md)).
-    Pyodide+Deno is the opt-in sandbox for pandas/NumPy-style snippets.
-    Docker, Modal, E2B, and Blaxel are for arbitrary CPython packages,
-    subprocesses, native dependencies, GPUs, or stronger remote isolation.
+    Pyodide+Deno is the opt-in sandbox for pandas/NumPy-style snippets —
+    shipped and **feature-frozen** as of 2026-07: supported as-is, but no
+    further investment in its edges; workloads beyond it are served by a
+    container backend when a concrete user needs one. Docker/Modal/E2B-class
+    backends (arbitrary CPython packages, subprocesses, native dependencies,
+    GPUs, remote isolation) stay design-only until then; the material below
+    about them is a design record, not a commitment.
 
 The execution backend should be swappable. Different workloads need different
 tradeoffs between safety, package support, startup latency, local development