@introspection-ai/recipes 0.18.0 → 0.19.0

package/docs/agent-composition.md

@@ -42,8 +42,8 @@ of a base configuration.
 # agents/agent.yaml
 name: agent
 description: Main release coordinator
-model:
-  name: anthropic/claude-sonnet-4-6
+ai:
+  model: anthropic/claude-sonnet-4-6
   thinking_level: medium
 tools: [read, bash]
 skills: [release-policy]
@@ -57,7 +57,7 @@ system_instructions:
 # agents/reviewer.yaml
 name: reviewer
 from: agent
-model:
+ai:
   thinking_level: high
 tools: [read]
 subagents: []
@@ -87,7 +87,8 @@ Omission means "inherit" for a derived agent. Declaring a field means
 | Field | Derived-agent behavior |
 | --- | --- |
 | `description` | Child value replaces the base; omission inherits it |
-| `model` | Merges by key when `name` is omitted; declaring `model.name` starts a fresh model configuration |
+| `ai` | Merges by key when `model` is omitted; declaring `ai.model` starts a fresh AI configuration |
+| `session` | Merges by key; nested settings objects merge recursively |
 | `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 |
@@ -104,8 +105,8 @@ 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 settings merge only while the child omits `model.name`. Declaring
-`model.name` starts a fresh model configuration, even when restating the same
+AI settings merge only while the child omits `ai.model`. Declaring
+`ai.model` starts a fresh AI configuration, even when restating the same
 identity, so
 provider routing, headers, retries, cache policy, and transport tuning cannot
 silently cross model boundaries.
@@ -116,33 +117,56 @@ boundary. Restate every server and selector the child may use. `mcp: { servers:
 Each resolved root or child agent may select its own mode; each live session
 receives only that selected agent's MCP policy.
 
-## Model Configuration
+## AI and Session Configuration
 
-Beyond `name` and `thinking_level`, the `model` block accepts request and
-transport tuning and provider routing. Set only what a case needs.
+The `ai` block selects the model and carries request/provider configuration.
+The `session` block controls portable Pi session behavior. Set only what a case
+needs.
 
 ```yaml
-model:
-  name: anthropic/claude-sonnet-4-6
+ai:
+  model: anthropic/claude-sonnet-4-6
   thinking_level: medium
-  temperature: 0.2
-  max_tokens: 4096
-  cache_retention: short        # none | short | long
-  timeout_ms: 60000
-  max_retries: 2
-  max_retry_delay_ms: 8000
+  options:
+    temperature: 0.2
+    max_tokens: 4096
+    cache_retention: short
+    timeout_ms: 60000
   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, …
+      routing:                  # forwarded opaquely to OpenRouter
+        order: [anthropic]
+        only: [anthropic]
+        allow_fallbacks: true
+session:
+  steering_mode: one-at-a-time
+  follow_up_mode: one-at-a-time
+  tool_execution: parallel
+  retry:
+    enabled: true
+    max_retries: 2
 ```
 
-All model settings except the fully resolved `name` are optional and merge by
-key along a `from:` chain until a child explicitly declares `model.name`.
+`ai.options` accepts current and future Pi request options using snake_case;
+Recipes converts only the option names to Pi camelCase. Its safe outer envelope
+is validated, while provider maps and nested option payloads remain opaque. All
+AI settings except the fully resolved model are optional and merge by key along
+a `from:` chain until a child explicitly declares `ai.model`.
+
+The former `model:` block remains readable for existing Recipes. New Recipes
+should use `ai:`; mixing both blocks in one agent is a validation error.
+
+`session` covers the managed runtime's portable model-independent policy:
+steering and follow-up queues, tool execution, retry (including provider
+retry), compaction, and image handling. Pi settings for UI presentation, shell
+and filesystem authority, package loading, persistence, networking, analytics,
+telemetry, and model defaults remain host-owned or belong under `ai`.
+Unlike transparent AI payloads, every nested `session` key, type, enum, and
+numeric range is checked by the Recipe validator. Interactive tree navigation
+and branch summaries are not part of the managed runtime contract.
 
 ## Resources and Capabilities
 

package/docs/pi-extension.md

@@ -120,6 +120,12 @@ package is an internal bridge for Pi startup, not a second user-facing CLI.
 
 ## 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`.
+The Pi extension and embedded hosts consume the same resolver. Embedded Recipe
+sessions apply `ai.options` and `session` directly to the live Pi agent and a
+session-local settings manager. Pi's current extension API exposes model and
+thinking selection but not request defaults, payload hooks, or session-policy
+setters, so `pi --recipe` fails closed when it cannot reproduce authored
+behavior instead of silently ignoring it. Use the embedded Recipe session API
+for those Recipes until Pi exposes the required setters. Hosts should run the
+conformance
+cases exported from `@introspection-ai/recipes/test-utils`.

package/docs/recipe-format.md

@@ -90,9 +90,15 @@ Recipe MUST contain at least one agent.
 ```yaml
 name: agent
 description: Produce a sourced research brief.
-model:
-  name: openrouter/anthropic/claude-sonnet-4.5
+ai:
+  model: openrouter/anthropic/claude-sonnet-4.5
   thinking_level: high
+  options:
+    max_tokens: 4096
+session:
+  steering_mode: one-at-a-time
+  follow_up_mode: one-at-a-time
+  tool_execution: parallel
 tools: [read, bash]
 skills: [research]
 subagents: [reviewer]
@@ -111,15 +117,45 @@ This is its
 stable identity for selection, subagent references, artifacts, and telemetry;
 the filename has no semantic meaning.
 
-Every fully resolved agent MUST also define `model.name` as
+Every fully resolved agent MUST also define `ai.model` as
 `<provider>/<model_id>`. The model may be declared directly or inherited with
-`from`.
+`from`. The legacy `model.name` form remains accepted for backwards
+compatibility, but an agent MUST NOT declare both `ai` and `model`.
 
 All remaining agent fields are optional. Omitted `tools`, `skills`, and
-`subagents` resolve to empty lists. Omitted `model.thinking_level` preserves the
+`subagents` resolve to empty lists. Omitted `ai.thinking_level` preserves the
 provider or session default. Omitted agent instructions preserve `SYSTEM.md`
 when present, or Pi's normal base prompt otherwise.
 
+Recipe-authored configuration uses `snake_case`. `ai.options` is normalized at
+the Pi boundary to Pi's camelCase request options, so newly added Pi request
+options do not require a Recipe schema release. Nested option values and
+`ai.providers.openrouter.routing` are opaque provider data and are not renamed
+or field-allowlisted. Host-owned request controls (`api_key`, `headers`, hooks,
+fetch, environment, abort signals, telemetry, and session identity) are
+rejected.
+
+The checker validates the provider envelope: OpenRouter `routing` and
+Anthropic `context_management` must be objects, and Anthropic `betas` must be
+non-empty strings. Fields inside the routing and context-management objects
+remain transparent provider payloads.
+
+The checker does not predict live provider compatibility inside those
+transparent payloads. For example, OpenRouter's `require_parameters` policy
+depends on the parameters emitted by the selected model adapter and the
+capabilities of currently available endpoints. Recipes preserves the authored
+value; endpoint compatibility must be verified against the provider.
+
+`session` owns portable Pi session behavior. Queue modes accept `all` or
+`one-at-a-time`; `tool_execution` accepts `parallel` or `sequential`. The
+`retry`, `compaction`, and `images` use the managed runtime's corresponding Pi
+settings with snake_case keys and are applied to a session-local settings
+manager, leaving host settings unmodified. Their nested keys, types, enums, and
+integer ranges are closed and validated. Interactive tree navigation and
+branch summaries, UI, shell, resource loading, persistence, networking,
+analytics, telemetry, and model-default settings are
+not portable session policy and remain host-owned or belong under `ai`.
+
 `tools` MUST NOT contain `agent`. The host materializes that session-generated
 tool for a root session whose effective `subagents` list is non-empty.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/recipes",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "The open format for vertical agents, built on Pi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -75,10 +75,10 @@
     ]
   },
   "dependencies": {
-    "@introspection-sdk/introspection-pi": "^0.15.0",
+    "@introspection-sdk/introspection-pi": "^0.19.1",
     "@opentelemetry/api": "^1.9.1",
     "ajv": "^8.20.0",
-    "mcporter": "0.12.3",
+    "mcporter": "0.13.0",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
@@ -89,10 +89,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.83.0",
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
+    "@earendil-works/pi-agent-core": "0.84.1",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "^26.1.2",
     "esbuild": "^0.28.1",
     "typebox": "^1.0.56",

package/dist/mcp-chunks/call-arguments-LU3W6D3K.js

@@ -1,13 +0,0 @@
-import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
-import {
-  parseCallArguments
-} from "./chunk-PIIYJR44.js";
-import "./chunk-BV56DXPW.js";
-import "./chunk-BNV3TPE4.js";
-import "./chunk-LQQEYD76.js";
-import "./chunk-M3TPODXI.js";
-import "./chunk-YVZKMV5H.js";
-import "./chunk-LRKZP7DJ.js";
-export {
-  parseCallArguments
-};