@introspection-ai/recipes 0.13.0 → 0.14.1

package/docs/index.md

@@ -10,16 +10,14 @@ task lifecycle, protocols, and deployment.
 
 | Goal | Document |
 | --- | --- |
+| Create, validate, and run a Recipe | [Recipe workflow](recipe-flow.md) |
 | Understand the portable artifact contract | [Recipe Format](recipe-format.md) |
-| Embed a Recipe in a host | [Runtime library](runtime-library.md) |
+| Run a Recipe in your host | [Host API](host-api.md) |
 | Run a Recipe in Pi | [Pi extension](pi-extension.md) |
 | Compose agents and subagents | [Agent composition](agent-composition.md) |
 | Ask for user input across hosts | [Interactions](interactions.md) |
 | Declare capability policy and bindings | [MCP configuration](mcp-configuration.md) |
-| Declare portable resource intent | [Deployment configuration](deployment-configuration.md) |
-| Package quality definitions | [Recipe judges](recipe-judges.md) |
-| Declare offline evaluation suites | [Recipe evals](recipe-evals.md) |
-| Move from the previous package | [Migration](migration.md) |
+| Define portable evaluation judges | [Recipe judges](recipe-judges.md) |
 
 ## Boundary
 
@@ -30,20 +28,17 @@ Recipe source
 resolveRecipe()          format interpretation
     │
     ▼
-createRecipeSession()    complete live Pi agent
+createAgentSession()     complete live Pi agent
     │
-    ├── runRecipe()      one-turn convenience
-    │
-    └── host             tasks, persistence, auth, protocols, deployment
+    └── host              tasks, persistence, auth, protocols, deployment
 ```
 
 Recipes stops at the live session boundary. It does not ship a generic server,
-task store, scheduler, sandbox, or provider-specific deployment adapter.
+task store, scheduler, sandbox, or provider-specific hosting integration.
 
-The first-party hosts are:
+The same contracts power:
 
 - the Pi terminal harness through the Recipes extension;
-- Introspection's managed `runtime-agent`.
+- Node.js hosts through `createAgentSession()`.
 
-Other hosts implement the same session contract and can run the host
-conformance suite.
+Every host can run the exported conformance suite against its integration.

package/docs/interactions.md

@@ -1,7 +1,7 @@
 # Recipe Interactions
 
-`@introspection-ai/recipes/interactions` gives recipe tools one contract for
-asking the user a question or requesting approval that works on every pi host:
+`@introspection-ai/recipes/interactions` gives Recipe tools one contract for
+asking the user a question or requesting approval that works on every Pi host:
 the local TUI, RPC-driven UIs, headless runs, and hosts that stream tool
 results to a remote frontend and can pause/resume a run.
 
@@ -77,7 +77,7 @@ Pi's native tool-result shape is `content` plus arbitrary structured
 `details`. Recipes stores its interaction state at `details.interrupt`.
 A host that supports pause/resume treats
 `details.interrupt.outcome.type === "awaiting_user"` as a pause request.
-Runtime adapters generate their own pause state from this record.
+Hosts generate their own pause state from this record.
 
 | Field | Meaning |
 | --- | --- |
@@ -90,26 +90,26 @@ Runtime adapters generate their own pause state from this record.
 | `outcome` | Local result, or `{ type: "awaiting_user" }` when the host must pause |
 
 Question options are suggestions, not a closed enum. Local Pi shows them in a
-selector plus an `Other` input path, and runtime adapters should preserve that
+selector plus an `Other` input path, and hosts should preserve that
 same custom-answer path unless a specific tool explicitly does something else.
 
 Resume payloads are single-question: `{ answer }` for questions,
 `{ approved, feedback? }` for confirmations. A decline is a resume with
 status `cancelled` and **no payload**. Any host-specific pause/resume state
-should be generated by the host adapter from this request, not authored inside
-recipes.
+should be generated by the host from this request, not authored inside a
+Recipe.
 
 ## AG-UI compatibility
 
 `details.interrupt` is intentionally close to the shape needed by AG-UI-style
-frontends, while remaining Pi-native recipe metadata. A host that deploys
-recipes behind the Agent User Interaction Protocol can map an awaiting
+frontends, while remaining Pi-native Recipe metadata. A host that deploys a
+Recipe behind the Agent User Interaction Protocol can map an awaiting
 `details.interrupt` request into `RUN_FINISHED` with
 `outcome: { type: "interrupt", interrupts: [...] }`, then resume with the
 same `{ answer }`, `{ approved, feedback? }`, or cancelled payloads described
 above.
 
-Recipes should still emit only `details.interrupt`. The host adapter owns ids,
+Recipes should still emit only `details.interrupt`. The host owns ids,
 tool-call binding, response schemas, transport events, persistence, and any
 frontend-specific rendering.
 
@@ -157,7 +157,7 @@ options.
 The envelope is the tool-result text the model sees after the user responds.
 It is a byte-exact wire contract: the local dialog walk and every pause/resume
 host must synthesize identical text for the same outcome,
-so recipes cannot tell where the answer came from. Do not reword these
+so Recipe tools cannot tell where the answer came from. Do not reword these
 without a coordinated protocol change across all hosts.
 
 | Outcome | Envelope |
@@ -178,7 +178,8 @@ best judgment.
 - **`executionMode: "sequential"` is mandatory.** A host pause must never
   race concurrently executing tools.
 - **Prefer the wrappers.** Use `askUserQuestion()` and `askUserApproval()` so
-  recipes do not hand-author interrupt details, reasons, or display metadata.
+  Recipe tools do not hand-author interrupt details, reasons, or display
+  metadata.
 - **Never format envelopes yourself.** Return the helper result as-is; envelope
   authorship must not split across layers.
 - **Thread the tool's `signal`** into the helper and check for aborts after any

package/docs/mcp-auth.md

@@ -7,7 +7,7 @@ endpoint model.
 Recipe MCP authentication follows the endpoint source that made an
 already-approved server reachable: a configured package manifest or a local/host
 binding. Authentication never selects a server or grants tools; the package and
-active/visible-agent selections still determine the final server/tool inventory.
+selected-agent policies still determine the final server/tool inventory.
 
 ## Local OAuth
 
@@ -49,13 +49,13 @@ cannot initiate authentication.
 
 ## Hosted bindings
 
-Hosted runtimes adapt their endpoint and credential systems into the same
+Hosts adapt their endpoint and credential systems into the same
 `.pi/mcp.local.json` shape before starting Recipes. Header values remain
 environment references, so credentials are resolved at runtime rather than
 written into the recipe workspace. Deployment-specific bootstrap, token, and
-egress behavior belongs to the hosting adapter, not this package.
+egress behavior belongs to the host, not this package.
 
-Regardless of where a recipe runs, the agent sees one rule: MCP operations are
+Regardless of where a Recipe runs, the agent sees one rule: MCP operations are
 headless. When authentication is missing, it receives a deployment-neutral
 recovery telling it to ask the user to authenticate the connection outside the
 agent session and then retry; `mcp run --json-errors` reports this as
@@ -75,6 +75,6 @@ reads an absolute local path supplied by an MCP result; server output must not
 choose files for an agent session to read.
 
 This command policy prevents accidental escape from the materialized MCP
-surface. It is not an OS or network sandbox: the enclosing local shell or
-managed runtime remains responsible for filesystem, process, and egress
+surface. It is not an OS or network sandbox: the enclosing local shell or host
+remains responsible for filesystem, process, and egress
 isolation.

package/docs/mcp-configuration.md

@@ -1,31 +1,30 @@
 # MCP configuration
 
 MCP authorization is the intersection of two fail-closed policy gates: the
-package boundary and the subsets selected by the active agent and its visible
-subagents. The authorized server must
+package boundary and the subset selected by an agent. The authorized server must
 also have a reachable endpoint, supplied either by a package-declared MCP
 manifest or by a local/host binding. A binding supplies connectivity; it never
 expands authorization.
 
 ```text
-package policy  ∩  active/visible-agent selections  =  authorized tools
+package policy  ∩  selected-agent policy  =  authorized tools
        package.json#pi.mcp             agents/*.yaml#mcp
                               +
  endpoint from package manifest or local/host binding
                               ↓
-                     session-local mcp CLI
+                 CLI or Pi-registered tools
 ```
 
 ## 1. Declare the package boundary
 
-`package.json#pi.mcp` declares the servers a recipe may use and the maximum
+`package.json#pi.mcp` declares the servers a Recipe may use and the maximum
 tool set available from each one. It can also reference portable MCP manifests.
 
 ```json
 {
   "pi": {
     "mcp": {
-      "manifest": "mcp.json",
+      "manifests": ["mcp.json"],
       "servers": [
         {
           "id": "contacts",
@@ -44,13 +43,12 @@ tool set available from each one. It can also reference portable MCP manifests.
 Prefer exact tool names. `"*"` explicitly permits the package-visible tool set,
 including tools a server may add later; patterns such as `search_*` are invalid.
 
-`manifest` accepts a single path; `manifests` accepts an array, and either the
-`mcp` value or a manifest reference may be given as a string shorthand for a
-single path. A server marked `"required": true` must resolve to a bound endpoint
-at session materialization or the session fails closed rather than starting
-without the capability.
+`manifests` is always an array of Recipe-relative paths or globs. Singular
+`manifest` and string shorthand are invalid. A server marked
+`"required": true` must resolve to a bound endpoint at session materialization
+or the session fails closed rather than starting without the capability.
 
-## 2. Narrow access for each agent
+## 2. Choose an agent mode and narrow access
 
 An agent selects a subset of the package-permitted servers and tools. It cannot
 add capability that the package did not declare.
@@ -59,15 +57,51 @@ add capability that the package did not declare.
 tools:
   - bash
 mcp:
-  contacts:
-    include:
-      - search_contacts
+  mode: cli
+  servers:
+    contacts:
+      include:
+        - search_contacts
 ```
 
 Omitting a server—or the entire agent `mcp` block—means no access. `exclude`
 removes exact names after inclusion and always wins. MCP tools are selected here,
 not in the agent's ordinary `tools` list.
 
+`mode: cli` creates the session-local `mcp` command.
+
+`mode: tools` registers every authorized MCP tool with Pi. Server-local
+`defer` selectors control which authorized tools start hidden from the model;
+`eager` subtracts exceptions from that deferred set:
+
+```yaml
+mcp:
+  mode: tools
+  servers:
+    contacts:
+      include: ["*"]
+      defer: ["*"]
+      eager:
+        - search_contacts
+```
+
+Omit `defer` to expose every authorized tool immediately. Use `defer: ["*"]`
+to hide all authorized tools for a server, then optionally list exact tools in
+`eager` to expose those tools at startup. Both fields accept exact tool names
+or a sole `"*"` selector. `eager` wins when a tool matches both fields, but
+neither field can authorize a tool excluded by `include`/`exclude`.
+
+Deferred tools remain authorized and discoverable. When at least one exists,
+Recipes registers `mcp_search`; calling it searches only the authorized
+deferred catalog and adds matches to Pi's current active tool set for the next
+model request. It never grants access beyond `servers`.
+
+`defer` and `eager` are invalid in CLI mode. An omitted agent `mcp` block
+inherits its base policy. Once a child declares `mcp`, the complete block
+replaces the inherited policy; restate its mode, servers, authorization, and
+activation selectors. This makes external capability changes reviewable at the
+derived agent. Every resolved agent owns its mode independently.
+
 ## 3. Supply endpoint configuration
 
 A referenced MCP manifest can carry a portable configured endpoint and catalog.
@@ -97,12 +131,12 @@ export CONTACTS_MCP_TOKEN='...'
 pi --recipe . --agent agent
 ```
 
-Do not commit or distribute `.pi/mcp.local.json`; publish validation rejects
+Do not commit or distribute `.pi/mcp.local.json`; Recipe validation rejects
 local configuration. Commit `.pi/mcp.local.example.json` when a binding template
-is helpful. A hosted runtime binds its own endpoint and credential system to the
-same shape. A binding overrides a package-manifest endpoint with the same id,
-but a server that the package does not permit, or that none of the active/visible
-agents permit, remains unavailable.
+is helpful. A host binds its own endpoint and credential system to the same
+shape. A binding overrides a package-manifest endpoint with the same id,
+but a server that the package or selected agent does not permit remains
+unavailable.
 
 When the local file is absent, manifest-supplied endpoints remain usable.
 Required servers that need environment-specific bindings fail closed until the
@@ -110,9 +144,10 @@ local Pi environment or embedding host supplies them.
 
 ## Use capabilities from an agent
 
-When the active agent or one of its visible subagents has MCP access, the
-extension creates a session-local `mcp` command from their combined selections.
-Discover narrowly, inspect one schema, then call or compose:
+In CLI mode, Recipes creates a session-local `mcp` command containing only the
+selected agent's authorized tools. Delegating to another agent does not grant
+the parent direct access to that child's MCP capabilities. Discover narrowly,
+inspect one schema, then call or compose:
 
 ```bash
 mcp search "contact lookup"
@@ -122,5 +157,18 @@ mcp call contacts.search_contacts query="Ada Lovelace"
 
 The command is headless and cannot add servers, mutate configuration, or start
 browser authentication. See [MCP authentication](mcp-auth.md) for OAuth and
-hosted binding details, and [Recipes extension](pi-extension.md#mcp) for the
-full runtime contract.
+hosted binding details, and [Recipes extension](pi-extension.md) for the
+full session contract.
+
+In tools mode, each Pi session—including each delegated child session—gets its
+own registered tool catalog and active set. The MCP daemon and mcporter config
+remain private to those wrappers; shell tools do not receive an `mcp` command,
+`MCPORTER_CONFIG`, or MCP session path.
+
+Pi receives each tool's MCP input schema. If the server declares
+`outputSchema`, Recipes retains and validates it locally against successful
+`structuredContent`; providers do not currently receive it as a tool
+declaration field. Text, image, resource, resource-link, audio, and structured
+results are normalized to Pi tool results. Duplicate structured JSON text is
+removed, errors become ordinary failed tool calls, and model-visible text is
+bounded to 50 KiB or 2,000 lines by default.

package/docs/pi-extension.md

@@ -9,7 +9,8 @@ pi --recipe ./path/to/recipe --agent agent
 
 Pi is the harness. The extension resolves the selected Recipe, configures its
 model and tools, loads its skills and extensions, materializes its declared
-capabilities, and registers its subagents.
+capabilities, and registers its subagents. Every launch with `--recipe`
+validates the authored package first.
 
 ## Installation
 
@@ -52,7 +53,7 @@ For the selected agent, the extension:
 1. reads the root `package.json#pi` resource declarations;
 2. resolves the agent YAML, including `from:` inheritance;
 3. selects the model, thinking level, and tool allowlist;
-4. loads selected skills, prompts, and Recipe-owned extensions;
+4. loads selected skills, package prompts, and the complete Recipe extension closure;
 5. materializes declared MCP bindings from host or local configuration;
 6. exposes only the declared subagents through the shared `agent` tool.
 
@@ -71,24 +72,51 @@ remain unavailable. See [MCP configuration](mcp-configuration.md).
 ## Recipe-owned extensions
 
 TypeScript extension sources declared by `package.json#pi.extensions` are
-loaded relative to the Recipe. Agent-level `extensions.include` and
-`extensions.exclude` select which declared extensions participate.
+resolved deterministically and loaded for every Recipe session. This complete
+set is one executable closure; agent YAML only controls which registered tools
+the model may call.
+
+Recipe extensions can import `forAgent`, `forRecipeSession`, and
+`getRecipeSessionContext` from `@introspection-ai/recipes/extensions` for
+session-local conditional behavior:
+
+```ts
+import { forAgent } from "@introspection-ai/recipes/extensions";
+
+export default function reviewerHooks(pi) {
+  forAgent(pi, "reviewer", () => {
+    pi.on("tool_call", reviewPolicy);
+  });
+}
+```
+
+The context distinguishes `root` and `subagent` roles. Conditional behavior is
+not code isolation: the extension module still executes with the Pi process's
+authority. `forAgent` matches the final resolved `agent.name` exactly; `from`
+is configuration inheritance and does not make a derived agent match its
+ancestor's hooks.
 
-Recipe extensions can import runtime helpers from `@introspection-ai/recipes`.
-The loader also aliases the previous `@introspection-ai/pi-recipes` name during
-the migration period so existing Recipe source shares the same runtime state.
+The closure contains every extension declared by the Recipe. It does not claim
+exclusive ownership of the surrounding Pi process: trusted global or project
+extensions already loaded by interactive Pi may still run hooks, providers,
+commands, and other non-tool behavior. Recipe `tools` remains the exact
+model-callable allowlist. Embedded Recipe sessions disable ambient extensions,
+skills, prompt templates, and context files by default.
 
 ## Validation
 
-Run:
+Every `pi --recipe` launch automatically runs the shared Recipe Format
+validator. Invalid Recipes are rendered in Pi and stop the session before any
+model call.
+
+For an explicit manual or CI check, run:
 
 ```bash
 introspection check
 ```
 
-The runtime also performs the minimum validation required to fail safely before
-constructing a session. Static authoring diagnostics remain the CLI validator's
-job.
+Both paths use the same Rust validation core. The binary embedded in the npm
+package is an internal bridge for Pi startup, not a second user-facing CLI.
 
 ## Host parity
 

package/docs/recipe-flow.md

@@ -1,7 +1,7 @@
 # Recipe workflow
 
 The `introspection` CLI owns the developer workflow. The Recipes npm package is
-the format implementation and Pi runtime extension; it does not install a
+the format implementation, Host API, and Pi extension; it does not install a
 second CLI.
 
 ## Create and run locally
@@ -15,10 +15,11 @@ introspection local
 
 `introspection init` scaffolds a Recipe and ensures compatible versions of Pi
 and the Recipes extension are present. `introspection check` runs the Recipe
-Format validator. `introspection local` resolves the repository's local runtime
-manifest and launches Pi with the Recipe path.
+Format validator. `introspection local` resolves the repository's project
+manifest and launches Pi with the Recipe path. Pi automatically runs the same
+validator whenever `--recipe` is present.
 
-The local path requires no login and no Introspection cloud runtime.
+The local path requires no login or Introspection cloud service.
 
 ## Run Pi directly
 
@@ -33,9 +34,8 @@ publish command.
 
 ## Deploy
 
-The Recipe remains unchanged across hosts. A host calls
-`createRecipeSession()` and supplies its own credentials, task lifecycle,
-persistence, isolation, and protocol surface.
+The Recipe remains unchanged across hosts. A long-lived host resolves the Recipe
+once, calls `createAgentSession()`, and supplies its own credentials, task
+lifecycle, persistence, isolation, and protocol surface.
 
-Use Introspection when you want the managed host. Use a host adapter when you
-want to operate the same Recipe on another platform.
+Integrate the Host API with the platform that will operate the Recipe.