@introspection-ai/recipes 0.13.0

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.js","sourceRoot":"","sources":["../src/test-utils.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionEvent, ExtensionAPI, RegisteredCommand, ToolDefinition } from "@earendil-works/pi-coding-agent";
+export interface MockExtensionAPI extends ExtensionAPI {
+    commands: Map<string, Omit<RegisteredCommand, "name" | "sourceInfo">>;
+    tools: Map<string, ToolDefinition<any, any, any>>;
+    flags: Map<string, {
+        description?: string;
+        type: "boolean" | "string";
+        default?: boolean | string;
+    }>;
+    flagValues: Map<string, boolean | string>;
+    handlers: Map<string, Array<(event: any, ctx: any) => unknown>>;
+    messages: unknown[];
+    sentMessages: Array<{
+        message: any;
+        options?: any;
+    }>;
+    messageRenderers: Map<string, (message: any, options: any, theme: any) => unknown>;
+    sessionName?: string;
+    activeTools: string[];
+    thinkingLevel?: string;
+    model?: unknown;
+    emitExtensionEvent(event: ExtensionEvent, ctx: any): Promise<unknown[]>;
+}
+export declare function createMockExtensionAPI(): MockExtensionAPI;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,iCAAiC,CAAC;AAEzC,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;IACtE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IACrG,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;IAC1C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC;IAChE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IACrD,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzE;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CA8FzD"}

package/dist/testing.js

@@ -0,0 +1,96 @@
+export function createMockExtensionAPI() {
+    const commands = new Map();
+    const tools = new Map();
+    const flags = new Map();
+    const flagValues = new Map();
+    const handlers = new Map();
+    const messages = [];
+    const sentMessages = [];
+    const messageRenderers = new Map();
+    const api = {
+        commands,
+        tools,
+        flags,
+        flagValues,
+        handlers,
+        messages,
+        sentMessages,
+        messageRenderers,
+        activeTools: [],
+        on(event, handler) {
+            const list = handlers.get(event) ?? [];
+            list.push(handler);
+            handlers.set(event, list);
+        },
+        registerTool(tool) {
+            tools.set(tool.name, tool);
+        },
+        registerCommand(name, options) {
+            commands.set(name, options);
+        },
+        registerShortcut() { },
+        registerFlag(name, options) {
+            flags.set(name, options);
+            if (options.default !== undefined && !flagValues.has(name)) {
+                flagValues.set(name, options.default);
+            }
+        },
+        getFlag(name) {
+            return flagValues.get(name);
+        },
+        registerMessageRenderer(customType, renderer) {
+            messageRenderers.set(customType, renderer);
+        },
+        sendMessage(message, options) {
+            messages.push(message);
+            sentMessages.push({ message, options });
+        },
+        sendUserMessage() { },
+        setSessionName(name) {
+            api.sessionName = name;
+        },
+        getSessionName() {
+            return api.sessionName;
+        },
+        setActiveTools(toolNames) {
+            api.activeTools = toolNames;
+        },
+        getActiveTools() {
+            return api.activeTools;
+        },
+        getAllTools() {
+            return [...tools.values()].map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+                sourceInfo: { path: "<test>", source: "test", scope: "temporary", origin: "top-level" },
+            }));
+        },
+        setThinkingLevel(level) {
+            api.thinkingLevel = level;
+        },
+        getThinkingLevel() {
+            return api.thinkingLevel ?? "off";
+        },
+        async setModel(model) {
+            api.model = model;
+            return true;
+        },
+        async emitExtensionEvent(event, ctx) {
+            const results = [];
+            for (const handler of handlers.get(event.type) ?? []) {
+                results.push(await handler(event, ctx));
+            }
+            return results;
+        },
+        events: {
+            emit() { },
+            on() {
+                return () => { };
+            },
+            off() { },
+        },
+    };
+    return api;
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAuBA,MAAM,UAAU,sBAAsB;IACpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0D,CAAC;IACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyC,CAAC;IAC/D,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4F,CAAC;IAClH,MAAM,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoD,CAAC;IAC7E,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,YAAY,GAA2C,EAAE,CAAC;IAChE,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA+D,CAAC;IAChG,MAAM,GAAG,GAAG;QACV,QAAQ;QACR,KAAK;QACL,KAAK;QACL,UAAU;QACV,QAAQ;QACR,QAAQ;QACR,YAAY;QACZ,gBAAgB;QAChB,WAAW,EAAE,EAAE;QACf,EAAE,CAAC,KAAa,EAAE,OAA0C;YAC1D,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACnB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,YAAY,CAAC,IAAmC;YAC9C,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,eAAe,CAAC,IAAY,EAAE,OAAuD;YACnF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,gBAAgB,KAAI,CAAC;QACrB,YAAY,CAAC,IAAY,EAAE,OAAyF;YAClH,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACzB,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3D,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAY;YAClB,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,uBAAuB,CAAC,UAAkB,EAAE,QAA6D;YACvG,gBAAgB,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QACD,WAAW,CAAC,OAAgB,EAAE,OAAiB;YAC7C,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,YAAY,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,eAAe,KAAI,CAAC;QACpB,cAAc,CAAC,IAAY;YACzB,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,cAAc;YACZ,OAAO,GAAG,CAAC,WAAW,CAAC;QACzB,CAAC;QACD,cAAc,CAAC,SAAmB;YAChC,GAAG,CAAC,WAAW,GAAG,SAAS,CAAC;QAC9B,CAAC;QACD,cAAc;YACZ,OAAO,GAAG,CAAC,WAAW,CAAC;QACzB,CAAC;QACD,WAAW;YACT,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACxC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE;aACxF,CAAC,CAAC,CAAC;QACN,CAAC;QACD,gBAAgB,CAAC,KAAa;YAC5B,GAAG,CAAC,aAAa,GAAG,KAAK,CAAC;QAC5B,CAAC;QACD,gBAAgB;YACd,OAAO,GAAG,CAAC,aAAa,IAAI,KAAK,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,KAAc;YAC3B,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,kBAAkB,CAAC,KAAqB,EAAE,GAAQ;YACtD,MAAM,OAAO,GAAc,EAAE,CAAC;YAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;YAC1C,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,EAAE;YACN,IAAI,KAAI,CAAC;YACT,EAAE;gBACA,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;YAClB,CAAC;YACD,GAAG,KAAI,CAAC;SACT;KAC6B,CAAC;IACjC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/docs/agent-composition.md

@@ -0,0 +1,196 @@
+# Agent Composition
+
+A recipe separates behavior into package-wide context and agent-specific
+configuration. Use that separation to share one operating model across a team
+of agents without making every agent identical.
+
+## The Three Layers
+
+| Layer | Scope | Use it for |
+| --- | --- | --- |
+| `package.json#pi` | Entire recipe package | Declaring available agents, extensions, skills, prompts, MCP servers, and evals |
+| `SYSTEM.md` | Every root and delegated agent in the recipe | Shared mission, terminology, policies, and workflow rules |
+| `agents/*.yaml` | One selected agent | Model, tools, selected skills, visible subagents, extension/MCP selection, and role-specific instructions |
+
+`SYSTEM.md` is the shared recipe instruction layer. A root agent and every
+delegated subagent start from the same recipe-level content. Put instructions
+there when they should remain true regardless of which agent is selected.
+
+Each agent's `system_instructions` specializes that shared layer:
+
+```yaml
+system_instructions:
+  mode: append
+  content: |
+    Review the evidence and return a release recommendation.
+```
+
+- `append` adds the agent-specific content after the shared recipe prompt.
+- `replace` intentionally replaces the current prompt, including `SYSTEM.md`.
+
+When a recipe has no `SYSTEM.md`, Pi's normal base prompt is the starting
+prompt. When `SYSTEM.md` exists, it becomes the recipe-wide starting prompt.
+Recipes then applies the selected agent's `system_instructions` mode.
+
+## Derive Agents With `from:`
+
+Use `from:` to derive a named agent from another agent in the same recipe. This
+is useful for model variants, constrained roles, and subagents that share most
+of a base configuration.
+
+```yaml
+# agents/agent.yaml
+name: agent
+description: Main release coordinator
+model:
+  name: anthropic/claude-sonnet-4-6
+  thinking_level: medium
+tools: [read, bash]
+skills: [release-policy]
+subagents: [reviewer]
+extensions:
+  include: [release-tools]
+system_instructions:
+  mode: append
+  content: Coordinate the complete release decision.
+```
+
+```yaml
+# agents/reviewer.yaml
+name: reviewer
+from: agent
+model:
+  thinking_level: high
+tools: [read]
+subagents: []
+system_instructions:
+  mode: append
+  content: Independently review the evidence. Do not make changes.
+```
+
+The derived agent inherits the base model name and selected skill, overrides
+the thinking level and tool allowlist, clears its visible subagents, and uses
+its own specialized instructions. Both agents still receive `SYSTEM.md`.
+
+`from:` chains may contain multiple levels. The referenced name must resolve to
+another agent in the same recipe. Missing bases and cycles are validation
+errors. A filename stem can resolve as an alias for an explicitly named agent,
+but explicit stable `name` values are recommended and required for portable
+child-agent definitions.
+
+Inheritance and delegation are separate. `from: reviewer-base` inherits a
+definition; it does not expose the derived agent for delegation. A root agent
+must still name that agent in its `subagents` list.
+
+## Inheritance Rules
+
+Omission means "inherit" for a derived agent. Declaring a field means
+"override or merge" according to its type.
+
+| Field | Derived-agent behavior |
+| --- | --- |
+| `description` | Child value replaces the base; omission inherits it |
+| `model` | Merges by key; nested stream/provider sections also merge by key |
+| `tools` | Child array replaces the inherited allowlist; `[]` clears it |
+| `skills` | Child array replaces the inherited selection; `[]` clears it |
+| `subagents` | Child array replaces inherited visibility; `[]` clears it |
+| `extensions` | `include` and `exclude` inherit independently; a declared child list replaces that list |
+| `mcp` | Servers merge by id; each server's `include` and `exclude` inherit independently and a declared child list replaces that list |
+| `system_instructions` | The whole child block replaces the inherited block; omission inherits it |
+
+Agent instruction blocks are not concatenated along a `from:` chain. If a
+child declares `system_instructions`, its block replaces the base agent's block.
+The child's `mode: append` applies to the recipe-wide `SYSTEM.md` (or Pi base
+prompt), not to the base agent's instructions. Put truly shared instructions in
+`SYSTEM.md` or a shared skill.
+
+Arrays never merge item by item. This makes capability boundaries reviewable:
+a derived agent that declares `tools: [read]` receives only `read`, not the
+base agent's other tools.
+
+## Model Configuration
+
+Beyond `name` and `thinking_level`, the `model` block accepts request and
+transport tuning and provider routing. Set only what a case needs.
+
+```yaml
+model:
+  name: anthropic/claude-sonnet-4-6
+  thinking_level: medium        # or reasoning_effort (an alias; a conflicting value errors)
+  temperature: 0.2
+  max_tokens: 4096
+  cache_retention: short        # none | short | long
+  timeout_ms: 60000
+  max_retries: 2
+  max_retry_delay_ms: 8000
+  providers:
+    anthropic:
+      betas: [context-1m]
+      context_management: {}
+    openrouter:
+      routing:                  # allow_fallbacks, require_parameters, data_collection,
+        order: [anthropic]      # zdr, order, only, ignore, quantizations, sort, max_price,
+        sort: throughput        # preferred_min_throughput, preferred_max_latency, …
+```
+
+All keys are optional and merge by key along a `from:` chain. Use `reasoning_effort`
+or `thinking_level`, not both with different values.
+
+## Instruction Shorthand
+
+A top-level `prompt:` string on an agent is shorthand for append-mode
+`system_instructions` — the text is appended to `SYSTEM.md` for that agent. Use
+the explicit `system_instructions` block when you need `mode: replace`.
+
+## Resources and Capabilities
+
+The manifest declares what the package can provide; the selected agent narrows
+what is active:
+
+- `package.json#pi.skills` declares physical skill resources. `agent.skills`
+  selects the skill names Pi discovers for that agent.
+- `package.json#pi.extensions` declares recipe-owned extensions.
+  `agent.extensions` filters which declared extensions load.
+- `package.json#pi.mcp` defines the package's upper-bound MCP policy.
+  `agent.mcp` narrows tool access per server.
+- `agent.tools` is the exact allowlist for Pi built-ins and tools registered by
+  loaded recipe extensions.
+- `agent.subagents` controls which other recipe agents are visible through the
+  `agent` tool.
+- Prompt templates declared by the package are recipe resources; they are not
+  specialized through `from:`.
+
+Skill and subagent selection controls prompt exposure and runtime capability,
+not filesystem isolation. All agents run in the same recipe package and current
+workspace. Use sandboxing and external authorization for security boundaries.
+
+## Root Agents and Subagents
+
+An agent selected with `--agent` is a root agent. If its effective `subagents`
+list is non-empty, Recipes enables the `agent` tool and exposes only those
+named agents.
+
+A delegated subagent resolves its own complete effective definition:
+
+1. follow its `from:` chain;
+2. apply its model, tools, skills, extensions, MCP, and instruction overrides;
+3. start from the same recipe `SYSTEM.md` as the root agent; and
+4. append or replace with its effective `system_instructions`.
+
+Delegation is one level deep. A definition may expose subagents when selected
+directly as a root agent, but the same definition does not receive the `agent`
+tool while running as a delegated child.
+
+## Recommended Structure
+
+- Put shared identity, policies, terminology, and workflow invariants in
+  `SYSTEM.md`.
+- Put role-specific duties and response contracts in the relevant agent's
+  `system_instructions`.
+- Put reusable detailed judgment in skills and select only the skills each
+  agent needs.
+- Use `from:` for real variants, not merely to avoid a few repeated lines.
+- Declare narrow tool, extension, MCP, and subagent lists at the point where a
+  role's capability boundary changes.
+- Run `introspection check` after changing inheritance, then prove each important
+  root agent and delegated path in a fresh Pi session.

package/docs/deployment-configuration.md

@@ -0,0 +1,65 @@
+# Deployment configuration
+
+How a recipe declares what its tasks need from the platform that runs them —
+compute resources and scratch disk — and what an implementing platform does
+with those declarations.
+
+This spec is defined here, in Recipes, because it describes *Recipe
+intent*: portable, platform-neutral declarations that any host can honor.
+The validation grammar lives in `pi_recipe_check::resources`
+(`validate_resources`) so every host — the Introspection CLI, a
+platform's manifest validator, wasm/Python bindings — applies identical
+rules with stable diagnostic codes. Platform-specific enforcement (floors,
+caps, billing) is the implementer's job, not part of the grammar.
+
+## Where the declarations live
+
+Recipe *package* contents (`package.json#pi`, `agents/*.yaml`) are
+materialized inside a running sandbox, after the machine that runs them
+already exists — so deployment configuration cannot live there. It lives in
+the host's deployment manifest, the file the platform reads *before*
+provisioning. On Introspection that is the repo-root
+`.introspection/<slug>.yaml` manifest's `runtime:` block:
+
+```yaml
+runtime:
+  resources:
+    requests: { cpu: 500m, memory: 1.5Gi, storage: 10Gi }
+    limits: { cpu: 1500m, memory: 1.5Gi }
+```
+
+## `resources`
+
+Kubernetes-style `requests`/`limits` (`validate_resources`). Grammar:
+`500m` millicores or decimal cores for CPU; bytes with binary
+(`Ki`/`Mi`/`Gi`/`Ti`) or decimal (`k`/`M`/`G`/`T`) suffixes for memory and
+storage (`0.1T` works). Quantities may also be JSON numbers — `cpu: 1.5`
+(cores) or an integer byte count for memory. A request must not exceed its limit.
+
+`storage` is the sandbox scratch-volume size and follows the PVC
+convention (`spec.resources.requests.storage`): request-only — declaring
+it under `limits` is rejected. Whether the scratch volume is persistent
+(survives sandbox teardown for warm restore) or ephemeral stays a
+*deployment* setting on the implementing platform — the recipe only sizes
+it. Future io characteristics (e.g. a storage class) would be siblings in
+the manifest, mirroring how Kubernetes expresses them outside the
+quantity.
+
+## How Introspection implements this
+
+The reference implementation treats every declaration as an **upward
+request** merged onto deployment-configured floors:
+
+- cpu/memory requests: `max(recipe, deployment floor)`, capped by a
+  schedulability guard; limits raise to the resolved request.
+- `requests.storage`: taken as declared — rounded up to whole GiB
+  (smaller scratch bills less; 1Gi is the validated minimum) and capped
+  at 300 GiB; undeclared uses the deployment default (10 GiB). Applied to
+  the sandbox's scratch volume (a persistent PVC when the deployment
+  enables warm storage, ephemeral emptyDir at the same mount path
+  otherwise).
+
+Invalid declarations fail manifest validation at push — a recipe never
+silently spawns with defaults because of a typo. Other platforms may
+choose different enforcement; the declarations and their grammar are the
+portable part.

package/docs/index.md

@@ -0,0 +1,49 @@
+# Recipes documentation
+
+**Recipes is the open package format for complete, portable Pi agents.**
+
+A Recipe keeps the agent-owned layer together as inspectable source. Pi runs
+the agent; a compatible host supplies credentials, isolation, persistence,
+task lifecycle, protocols, and deployment.
+
+## Start here
+
+| Goal | Document |
+| --- | --- |
+| 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 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) |
+
+## Boundary
+
+```text
+Recipe source
+    │
+    ▼
+resolveRecipe()          format interpretation
+    │
+    ▼
+createRecipeSession()    complete live Pi agent
+    │
+    ├── runRecipe()      one-turn convenience
+    │
+    └── 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.
+
+The first-party hosts are:
+
+- the Pi terminal harness through the Recipes extension;
+- Introspection's managed `runtime-agent`.
+
+Other hosts implement the same session contract and can run the host
+conformance suite.

package/docs/interactions.md

@@ -0,0 +1,210 @@
+# 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:
+the local TUI, RPC-driven UIs, headless runs, and hosts that stream tool
+results to a remote frontend and can pause/resume a run.
+
+The module registers no tools. Recipes own their interaction tools — their
+names, schemas, and prompts — and call `askUserQuestion()` or
+`askUserApproval()` from the tool's `execute()`. Those helpers build the
+`details.interrupt` request, local Pi dialog copy, and host metadata. Use raw
+`askUser()` only when a tool needs a lower-level interaction shape.
+
+## Quick start
+
+```ts
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { askUserQuestion } from "@introspection-ai/recipes/interactions";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "ask_user_question",
+    label: "Ask user",
+    description: "Ask the user a clarifying question and wait for the answer.",
+    parameters: Type.Object({
+      question: Type.String(),
+      options: Type.Optional(Type.Array(Type.String())),
+    }),
+    // Required: interaction tools must not run concurrently with other tools,
+    // otherwise a host pause can strand half-finished parallel tool calls.
+    executionMode: "sequential",
+    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+      return await askUserQuestion(
+        {
+          question: params.question,
+          options: params.options,
+        },
+        { toolCallId, ctx, signal }
+      );
+    },
+  });
+}
+```
+
+The helpers always return a finished tool result (`content` + `details`), so
+the tool can return them directly. Pass the tool's own `signal` parameter —
+not `ctx.signal` — so an aborted turn dismisses any open dialog.
+
+## Channel resolution
+
+The interaction helpers pick the best available channel, in order:
+
+1. **`PI_ASK_USER_AUTO_APPROVE`** (env) — headless/CI runs: confirmations
+   resolve `approved`, everything else resolves `declined`. Deterministic and
+   never blocks.
+2. **Interactive UI** (`ctx.hasUI`, TUI and RPC modes) — the built-in dialog
+   walk: a select for fixed options and approvals, a text input otherwise.
+   A caller-provided `interactive` walk replaces the dialogs (return
+   `undefined` to fall through). In RPC mode dialogs get a default timeout
+   (`DEFAULT_RPC_DIALOG_TIMEOUT_MS`, 120s) so a client that never renders
+   them cannot wedge the session; a timed-out or dismissed dialog declines.
+3. **Pause/resume host** (`PI_INTERRUPT_RESUME` env, set by the host) —
+   the tool returns `Awaiting user response.` with a Recipes
+   `details.interrupt` request whose outcome is `awaiting_user`. The host
+   pauses the run, adapts the request to its own UI protocol, and later resumes
+   the run by rewriting this tool result with the response envelope (below).
+   Root sessions only. In-process child agents resolve interactions internally
+   and never emit a pause request.
+4. **Fallback** — the result states that nothing was shown to the user and
+   directs the model to ask in its normal assistant reply. An unrendered
+   question is never treated as declined.
+
+## The interrupt request
+
+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.
+
+| Field | Meaning |
+| --- | --- |
+| `reason` | Open string; well-known: `input_required`, `confirmation`, `tool_call` |
+| `message` | Concise human-readable prompt |
+| `options` | Optional structured answer suggestions: `{ label, value?, description? }[]` |
+| `metadata` | Renderer or tool hints (`kind`, `header`, source tool parameters, …) |
+| `display` | Optional structured display copy for richer local or remote UI |
+| `expiresAt` | Optional ISO-8601 instant after which the host may auto-decline |
+| `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
+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.
+
+## 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
+`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,
+tool-call binding, response schemas, transport events, persistence, and any
+frontend-specific rendering.
+
+## Display data
+
+`message` is the concise prompt every host can show without understanding
+recipe-specific metadata. Keep it meaningful, for example
+`Approve search proposal: Senior product leaders in Sydney?`.
+
+When a tool needs richer approval UI copy, pass card fields to
+`askUserApproval()`:
+
+```ts
+await askUserApproval(
+  {
+    kind: "plan_search",
+    message: "Approve search proposal: Senior product leaders in Sydney?",
+    title: "Senior product leaders in Sydney",
+    body: "Target senior product leaders in Sydney with B2B SaaS or marketplace experience.",
+    sections: [
+      {
+        title: "Starting angles",
+        items: [
+          "Product leadership titles in Sydney",
+          "Growth product leaders in Sydney",
+          "Marketplace product operators",
+        ],
+      },
+    ],
+    metadata: {
+      proposal: "Target senior product leaders in Sydney with B2B SaaS or marketplace experience.",
+    },
+  },
+  { toolCallId, ctx, signal }
+);
+```
+
+Local pi dialogs format the generated display into readable prompt text.
+Remote hosts can adapt the same object into their own UI. Hosts that do not
+understand the structured display can still render `message` and basic
+options.
+
+## Response envelopes (frozen)
+
+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
+without a coordinated protocol change across all hosts.
+
+| Outcome | Envelope |
+| --- | --- |
+| Answered | `Answer: <answer>` |
+| Approved | `Approved.` |
+| Approved with feedback | `Approved. Feedback: <feedback>` |
+| Revision requested | `Revision requested.` |
+| Revision requested with feedback | `Revision requested. Feedback: <feedback>` |
+| Declined | `User declined to answer. Proceed with your best judgment.` |
+| Pending host resume | `Awaiting user response.` |
+
+Declines are **not** tool errors — the model is expected to proceed with its
+best judgment.
+
+## Rules for interaction tools
+
+- **`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.
+- **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
+  custom dialog (`undefined` from a dialog means dismissal *or* abort — only
+  the signal distinguishes them).
+- **Custom UIs are enhancements.** A richer TUI walk goes through the
+  `interactive` option; remote hosts can adapt `metadata` and `display`.
+  Hosts that recognize neither must still work off `reason`, `message`, and
+  `options`.
+- **Child agents cannot ask the user directly.** Inside an in-process child
+  agent run, approvals resolve as approved and questions resolve as declined.
+  Child tools never open UI or interrupt the root session.
+
+## Host checklist (implementing `PI_INTERRUPT_RESUME`)
+
+1. Wrap every in-process child session prompt with
+   `autoResolveInteractions()`. The guard is shared across separately resolved
+   copies of Recipes, so Recipe-owned interaction tools observe the child
+   boundary too.
+2. Watch root-session `tool_execution_end` events for
+   `details.interrupt.outcome.type === "awaiting_user"`.
+3. Convert the Recipes interrupt request into the host UI protocol, pause the run, and
+   persist the host descriptor(s); the pause frame itself is not replayable,
+   so persisted descriptors are the source of truth.
+4. On resume, rewrite the paused tool result's text with the frozen envelope
+   for the user's response and continue the run. Declines (`cancelled`,
+   no payload) use the declined envelope and are not errors.
+5. Set `PI_INTERRUPT_RESUME=1` in the session environment only when all of
+   the above is wired.