@introspection-ai/recipes 0.13.0

package/docs/mcp-auth.md

@@ -0,0 +1,80 @@
+# MCP authentication in recipe sessions
+
+This page covers authentication after capability has been declared and selected.
+Start with [MCP configuration](mcp-configuration.md) for the complete policy and
+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.
+
+## Local OAuth
+
+Local users may declare OAuth on a server in the workspace- or recipe-local
+`.pi/mcp.local.json`:
+
+```json
+{
+  "servers": [
+    {
+      "id": "linear",
+      "transport": "streamable_http",
+      "url": "https://mcp.linear.app/mcp",
+      "auth": "oauth",
+      "oauthClientId": "optional-pre-registered-client-id",
+      "oauthClientSecretEnv": "LINEAR_OAUTH_CLIENT_SECRET",
+      "oauthRedirectUrl": "http://127.0.0.1:8787/callback",
+      "oauthScope": "optional provider-specific scopes"
+    }
+  ]
+}
+```
+
+Only `auth: "oauth"` enables mcporter OAuth for that local definition. Recipe
+startup and the agent-facing `mcp` command use cached credentials only and never
+start a browser flow. A local user completes or refreshes OAuth outside the
+agent session with mcporter directly, using the same server name and OAuth
+settings, then retries the recipe operation. They can use their normal mcporter
+config, or the generated session projection when it exists, for example:
+
+```bash
+npx mcporter auth linear --config .pi/mcporter.json
+```
+
+The session CLI does not accept OAuth URLs, ad-hoc servers, config imports, or
+configuration mutation. A local user configures connectivity outside the agent
+through `.pi/mcp.local.json` or their normal mcporter configuration. The agent
+cannot initiate authentication.
+
+## Hosted bindings
+
+Hosted runtimes 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.
+
+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
+`authentication_required` with action `ask_user_to_authenticate`.
+Deployment-specific credential handling is not part of the agent's
+instructions.
+
+## Agent-facing command boundary
+
+Recipe sessions expose only `mcp search`, `mcp list`, `mcp call`, and `mcp run`.
+Interactive authentication and administrative and
+developer commands (`config`, `vault`, `generate-cli`, `emit-ts`, `record`,
+`replay`, `daemon`, and `serve`) are intentionally unavailable. URL selectors,
+ad-hoc HTTP/stdio transports, config overrides, and persistence flags are also
+rejected. The upstream `--tail-log` call flag is also unavailable because it
+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
+isolation.

package/docs/mcp-configuration.md

@@ -0,0 +1,126 @@
+# 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
+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.json#pi.mcp             agents/*.yaml#mcp
+                              +
+ endpoint from package manifest or local/host binding
+                              ↓
+                     session-local mcp CLI
+```
+
+## 1. Declare the package boundary
+
+`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",
+      "servers": [
+        {
+          "id": "contacts",
+          "required": true,
+          "tools": {
+            "include": ["search_contacts", "get_contact"],
+            "exclude": []
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+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.
+
+## 2. Narrow access for each agent
+
+An agent selects a subset of the package-permitted servers and tools. It cannot
+add capability that the package did not declare.
+
+```yaml
+tools:
+  - bash
+mcp:
+  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.
+
+## 3. Supply endpoint configuration
+
+A referenced MCP manifest can carry a portable configured endpoint and catalog.
+When connectivity varies by environment, provide an endpoint and credential
+references in `.pi/mcp.local.json` for local runs, or through a host binding:
+
+```json
+{
+  "servers": [
+    {
+      "id": "contacts",
+      "transport": "streamable_http",
+      "url": "https://contacts.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${CONTACTS_MCP_TOKEN}"
+      }
+    }
+  ]
+}
+```
+
+The `${CONTACTS_MCP_TOKEN}` reference is resolved from the environment at launch,
+so export it before running the recipe locally:
+
+```bash
+export CONTACTS_MCP_TOKEN='...'
+pi --recipe . --agent agent
+```
+
+Do not commit or distribute `.pi/mcp.local.json`; publish 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.
+
+When the local file is absent, manifest-supplied endpoints remain usable.
+Required servers that need environment-specific bindings fail closed until the
+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:
+
+```bash
+mcp search "contact lookup"
+mcp list contacts.search_contacts --schema
+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.

package/docs/migration.md

@@ -0,0 +1,70 @@
+# Migration to Recipes
+
+The project and npm package are now **Recipes**:
+
+```text
+@introspection-ai/pi-recipes  →  @introspection-ai/recipes
+Pi Recipes                    →  Recipes
+```
+
+The artifact remains **a Recipe**. The package format and focused runtime
+entrypoints remain source-compatible unless noted below.
+
+## Package imports
+
+```diff
+- import { resolveRecipe } from "@introspection-ai/pi-recipes/recipe";
++ import { resolveRecipe } from "@introspection-ai/recipes/recipe";
+
+- import { createRecipeSession } from "@introspection-ai/pi-recipes/session";
++ import { createRecipeSession } from "@introspection-ai/recipes/session";
+```
+
+The same replacement applies to `/run`, `/pi`, `/interactions`, and
+`/test-utils`. The former `/tracing` entrypoint is removed: pass a host-owned
+tracer through `createRecipeSession({ otel })` instead.
+
+## Pi extension
+
+```bash
+pi remove npm:@introspection-ai/pi-recipes
+pi install npm:@introspection-ai/recipes
+```
+
+The Recipe extension factory is now `createRecipesExtension`.
+`createPiRecipesExtension` remains as a deprecated source-compatible alias.
+
+Recipe-owned extensions that still import
+`@introspection-ai/pi-recipes/interactions` are aliased to the current runtime
+while they migrate.
+
+## CLI
+
+The standalone `recipes` executable has been retired. Use:
+
+```bash
+introspection init
+introspection check
+introspection local
+introspection dev
+```
+
+Use ordinary Git and filesystem operations to clone, fork, copy, and publish
+Recipe source.
+
+## Hosting
+
+`serveRecipe` and `@introspection-ai/recipes/serve` are not part of the new
+package. Hosts integrate at `createRecipeSession`; HTTP protocols, persistence,
+auth, and deployment adapters belong to the host.
+
+`runRecipe` remains as the small one-turn convenience above the session API.
+
+## Validation
+
+The root npm package no longer downloads a platform-specific
+`recipe-check` executable. Validation remains available through:
+
+- `introspection check`;
+- the `pi-recipe-check` Rust crate and binary;
+- the `pi-recipe-check` Python package.

package/docs/pi-extension.md

@@ -0,0 +1,97 @@
+# Recipes extension for Pi
+
+The Recipes extension teaches [Pi](https://pi.dev/docs/latest) to load a
+Recipe package with:
+
+```bash
+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.
+
+## Installation
+
+The recommended workflow lets the Introspection CLI provision compatible
+versions:
+
+```bash
+npm install -g @introspection-ai/cli
+introspection init
+introspection local
+```
+
+For direct Pi use:
+
+```bash
+pi install npm:@introspection-ai/recipes
+```
+
+Recipes currently requires Node.js 24 or later and Pi `^0.82`.
+
+## Selection
+
+`--recipe` accepts a local directory:
+
+```bash
+pi --recipe . --agent agent
+pi --recipe ./recipes/research --agent researcher
+```
+
+The extension no longer maintains a separate installed-Recipe store. Git,
+package managers, and ordinary paths own distribution.
+
+The selected path and agent are exposed to Recipe-owned tools as
+`PI_RECIPE_DIR` and `PI_AGENT_NAME`.
+
+## What is loaded
+
+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;
+5. materializes declared MCP bindings from host or local configuration;
+6. exposes only the declared subagents through the shared `agent` tool.
+
+See [Recipe Format](recipe-format.md) for the authored contract and
+[Agent composition](agent-composition.md) for inheritance and selection.
+
+## Local capability bindings
+
+Recipe source may include `.pi/mcp.local.example.json`, but secrets belong in
+the environment or an ignored `.pi/mcp.local.json`. A host may synthesize the
+same bindings in memory.
+
+Bindings are resolved fail-closed for required servers. Optional servers may
+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.
+
+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.
+
+## Validation
+
+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.
+
+## Host parity
+
+The Pi extension and embedded hosts consume the same resolver and session
+semantics. Hosts should run the conformance cases exported from
+`@introspection-ai/recipes/test-utils`.

package/docs/python-bindings-release.md

@@ -0,0 +1,47 @@
+# Python bindings release
+
+The `pi-recipe-check` Rust crate and Python distribution are two artifacts of
+one validator product and always use the same version. The binding's Cargo
+package and dependency on the core must both match the core crate version.
+`scripts/check-recipe-check-versions.mjs` enforces this invariant in CI.
+
+Release Please owns both versions, changelogs, component tags, and GitHub
+releases. Its `linked-versions` plugin advances both components to the same
+version whenever either has a releasable change. The `cargo-workspace` plugin
+keeps the local dependency current, but leaves candidate merging to
+`linked-versions`. A Python-only fix therefore creates a patch release for
+both artifacts, and a core release always includes a matching Python release.
+Routine releases must not bump either Cargo version manually.
+
+When Release Please creates a Python binding release, the release workflow:
+
+1. Builds `abi3` wheels compatible with CPython 3.10 and newer for Linux
+   x86-64 and ARM64, macOS Apple Silicon and Intel, and Windows x86-64.
+2. Builds a source distribution containing the local Rust workspace
+   dependency.
+3. Waits for the matching `pi-recipe-check` crate publication to succeed.
+4. Publishes all Python artifacts to PyPI through trusted publishing.
+
+## One-time PyPI setup
+
+Before the first release, create a pending trusted publisher for the unclaimed
+`pi-recipe-check` project on PyPI with:
+
+- Owner: `introspection-org`
+- Repository: `pi-recipes`
+- Workflow: `release-please.yml`
+- Environment: `publish`
+
+The GitHub `publish` environment should retain its existing deployment
+protection. No long-lived PyPI API token is required.
+
+Local release artifact checks use the locked development environment and the
+same pinned maturin version as CI:
+
+```sh
+uv sync --project bindings/python --locked
+uv run --project bindings/python --locked maturin build --locked --release --out dist \
+  --manifest-path bindings/python/Cargo.toml
+uv run --project bindings/python --locked maturin sdist --out dist \
+  --manifest-path bindings/python/Cargo.toml
+```

package/docs/recipe-evals.md

@@ -0,0 +1,70 @@
+# Recipe eval declarations
+
+A Recipe may pin offline evaluation suites without owning the evaluation
+runner. The declaration makes quality inputs portable and reproducible; a host
+or external tool decides when and where to execute them.
+
+## Registry suite
+
+```json
+{
+  "pi": {
+    "evals": {
+      "suites": [
+        {
+          "name": "smoke",
+          "type": "registry",
+          "dataset": "acme/coding-smoke",
+          "version": "1.2.0"
+        }
+      ]
+    }
+  }
+}
+```
+
+Registry suites MUST pin an exact dataset version. Mutable aliases such as
+`latest` are invalid.
+
+## Git suite
+
+```json
+{
+  "pi": {
+    "evals": {
+      "suites": [
+        {
+          "name": "terminal",
+          "type": "git",
+          "repo": "https://github.com/acme/agent-evals.git",
+          "rev": "4f7c2b0d6d8a...",
+          "dataset": "terminal"
+        }
+      ]
+    }
+  }
+}
+```
+
+Git suites SHOULD pin a commit SHA. The dataset path MUST stay inside the
+checkout.
+
+## Validation
+
+```bash
+introspection check
+```
+
+The validator checks declaration shape, unique suite names, immutable pins,
+safe paths, and supported suite types without cloning or running the suite.
+
+## Runtime boundary
+
+Recipe sessions do not load or execute eval suites. The declaration belongs to
+the portable artifact because it identifies the authored evidence associated
+with that agent. Harbor, CI, Introspection, or another evaluation system may
+adapt that declaration into its own execution model.
+
+The selected Recipe agent remains the source of truth for model and behavior.
+An eval runner MUST make any override explicit rather than silently changing
+the agent under test.

package/docs/recipe-flow.md

@@ -0,0 +1,41 @@
+# 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
+second CLI.
+
+## Create and run locally
+
+```bash
+npm install -g @introspection-ai/cli
+introspection init
+introspection check
+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.
+
+The local path requires no login and no Introspection cloud runtime.
+
+## Run Pi directly
+
+```bash
+pi install npm:@introspection-ai/recipes
+pi --recipe ./my-recipe --agent agent
+```
+
+Recipes are ordinary Git-backed source packages. Clone, fork, or copy them with
+normal Git and filesystem tools. There is no Recipe-specific install store or
+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.
+
+Use Introspection when you want the managed host. Use a host adapter when you
+want to operate the same Recipe on another platform.