@introspection-ai/recipes 0.13.0

package/docs/recipe-format.md

@@ -0,0 +1,186 @@
+# Recipe Format
+
+**Status:** Open format, version 1  
+**Reference implementation:** `@introspection-ai/recipes`  
+**Validator:** `pi-recipe-check`
+
+The Recipe Format is a Git-native package contract for complete Pi agents. It
+defines the agent-owned inputs that a compatible host must interpret the same
+way. It does not define deployment infrastructure or a network protocol.
+
+The key words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.
+
+## Compatibility scope
+
+A conforming Recipe is **Pi-native and host-portable**:
+
+- it MUST produce the same resolved agent configuration in compatible Pi hosts;
+- it MUST NOT depend on an Introspection-managed runtime;
+- it MAY declare host requirements that a particular host cannot satisfy;
+- a host MUST fail closed when a required capability cannot be bound.
+
+This format does not claim interoperability with non-Pi agent harnesses.
+
+## Package root
+
+A Recipe MUST be a directory containing `package.json`. The manifest MUST have:
+
+```json
+{
+  "name": "acme-research",
+  "version": "1.0.0",
+  "description": "Research an account and produce a sourced brief.",
+  "pi": {
+    "agents": ["agents/*.yaml"],
+    "skills": ["skills/**/SKILL.md"],
+    "extensions": ["extensions/*.ts"],
+    "prompts": ["prompts/*.md"]
+  }
+}
+```
+
+`name` is the package identity. `version` is distribution metadata and defaults
+to `0.0.0` when omitted for compatibility. `description` is human-facing.
+
+Resource paths:
+
+- MUST be relative to the package root;
+- MUST NOT traverse outside the package;
+- MAY be files, directories, or supported glob patterns;
+- are resolved deterministically in lexical order.
+
+Unknown top-level `package.json` fields retain normal npm semantics. Unknown
+Recipe fields inside supported `pi` structures are validation errors unless a
+later format version explicitly defines them.
+
+## Agents
+
+`pi.agents` declares YAML agent definitions. A resolved Recipe MUST contain at
+least one agent.
+
+```yaml
+name: agent
+description: Produce a sourced research brief.
+model:
+  name: openrouter/anthropic/claude-sonnet-4.5
+  thinking_level: high
+tools: [read, bash]
+skills: [research]
+subagents: [reviewer]
+extensions:
+  include: [citations]
+system_instructions:
+  mode: append
+  content: Verify every material claim.
+```
+
+An agent MAY inherit from another named agent with `from`. Inheritance MUST be
+acyclic. Child fields override inherited scalar fields; documented collection
+fields use the merge or replacement behavior in
+[Agent composition](agent-composition.md).
+
+Every fully resolved agent MUST define:
+
+- `model.name` as `<provider>/<model_id>`;
+- `model.thinking_level`;
+- `tools`;
+- `system_instructions`.
+
+Omitted `skills` and `subagents` resolve to empty lists.
+
+The default agent is named `agent`. If no `agent` exists, a host MAY select the
+only declared agent. When multiple agents exist without `agent`, the caller
+MUST select one explicitly.
+
+## Instructions, skills, prompts, and extensions
+
+`SYSTEM.md`, when present, is package-wide instruction source. Agent
+`system_instructions.mode` determines whether agent instructions append to or
+replace the current prompt.
+
+Skills follow the [Agent Skills](https://agentskills.io) directory convention
+and are selected from the resources declared by `pi.skills`.
+
+Prompt templates are declared by `pi.prompts`.
+
+Recipe-owned Pi extensions are declared by `pi.extensions`. An agent MAY select
+declared extensions with `extensions.include` and `extensions.exclude`. A host
+MUST NOT load undeclared Recipe extension source.
+
+## Tools, subagents, and capabilities
+
+`tools` is an allowlist. A host MUST expose no undeclared Pi or extension tool
+through this field.
+
+`subagents` names agents the selected agent may invoke. A host MUST expose only
+those resolved definitions through the shared `agent` tool. How child work is
+scheduled or isolated belongs to the host.
+
+The `pi.mcp` package block declares capability servers and package-level tool
+policy. Agent `mcp` blocks narrow those declarations. Credentials and concrete
+endpoint bindings MUST NOT be required in distributable Recipe source. A host
+MUST reject an unbound required server before the session begins.
+
+See [MCP configuration](mcp-configuration.md) for the complete authored and
+binding grammar.
+
+## Quality and resource intent
+
+Recipe-owned judge YAML expresses portable quality definitions. Hosts MAY use
+those definitions online or offline, but MUST preserve their authored identity
+and semantics.
+
+`pi.evals` MAY pin external evaluation suites. The format records the pin; an
+evaluation runner remains an external tool.
+
+Portable resource intent is declared under the documented runtime resource
+grammar. A host decides whether it can satisfy that intent and MUST report
+unsupported required resources rather than silently weakening them.
+
+## Host responsibilities
+
+The Recipe Format owns:
+
+- package and agent interpretation;
+- instruction composition;
+- model and tool selection;
+- skill, prompt, and extension selection;
+- subagent visibility;
+- capability policy;
+- quality definitions and resource intent.
+
+The host owns:
+
+- credentials and secret resolution;
+- workspaces and filesystem isolation;
+- task and process lifecycle;
+- persistence and recovery;
+- scheduling and concurrency enforcement;
+- network protocols and user authentication;
+- telemetry export policy;
+- deployment.
+
+Those host concerns MUST NOT become mandatory Recipe source fields.
+
+## Conformance
+
+There are two conformance layers:
+
+1. `pi-recipe-check` validates authored package snapshots without executing
+   them.
+2. `@introspection-ai/recipes/test-utils` verifies that a host constructs and
+   disposes Recipe sessions with the required semantics.
+
+A host SHOULD run both layers in CI.
+
+## Evolution
+
+The format follows additive evolution while version 1 is active:
+
+- new optional fields MAY be added;
+- existing field meaning MUST NOT change incompatibly;
+- required fields MUST NOT be added without a new major format version;
+- hosts MUST ignore only extension points explicitly documented as open.
+
+The implementation package follows SemVer independently. Package version and
+format version are not the same thing.

package/docs/recipe-judges.md

@@ -0,0 +1,152 @@
+# Recipe judge definitions
+
+Recipe judges are optional, recipe-owned LLM grading definitions. Author them
+as direct children of `judges/` using a lowercase `.yaml` or `.yml` extension:
+
+```text
+my-recipe/
+  judges/
+    helpful.yaml
+```
+
+Nested files such as `judges/calibration/helpful.yaml` are not judge sources.
+The standalone `recipe-check` binary, `introspection check`, and in-memory
+bindings discover the same direct-child set and return the same validation
+result. Recipes without judge sources have no judge diagnostics or
+`resources.judges` count.
+
+## Ownership boundary
+
+`pi-recipe-check` owns the portable authored YAML specification and its static,
+file-oriented diagnostics. The I/O-free `check_recipe_files` core is the common
+validation path used by the filesystem checker, npm CLI, serialized snapshot
+API, and Python binding.
+
+The Introspection judge engine owns runtime evaluation: applicability
+execution, conversation assembly and transcript protection, model request
+construction, retries, verdict normalization, and evaluation identity. Runtime
+implementations should consume or remain explicitly compatible with the
+authored specification defined here; new authored fields must land in this
+checker and its contract tests rather than being introduced only in a runtime
+parser.
+
+The Rust checker and Python binding return a `Report` containing diagnostics
+and, when judges exist, a `resources.judges` source count. The report does not
+contain a normalized judge definition, `judge_id`, `definition_hash`, or
+registry projection. Migrating project-scoped registry projection away from
+the runtime parser is a separate platform change and must not add project or
+tenant context to this portable API.
+
+## Definition shape
+
+The minimal definition is:
+
+```yaml
+judge: helpful
+
+instructions: |
+  Determine whether the assistant answered the user correctly.
+
+llm:
+  model: gpt-5
+```
+
+`judge`, `instructions`, and `llm.model` are required and non-empty. Judge names
+must be unique across all judge files in one recipe. `llm.provider` defaults to
+`openai` at runtime.
+
+The canonical expanded definition is:
+
+```yaml
+judge: helpful
+description: Did the assistant answer correctly?
+
+on:
+  - event: message
+    match:
+      role: assistant
+
+instructions: |
+  Determine whether the assistant answered the user correctly.
+
+llm:
+  provider: openai
+  model: gpt-5
+  request:
+    temperature: 0
+    max_tokens: 1024
+    reasoning_effort: medium
+  transport:
+    timeout_ms: 60000
+    max_retries: 2
+    max_retry_delay_ms: 5000
+  local:
+    base_url: https://api.openai.com/v1
+    api_key_env: OPENAI_API_KEY
+```
+
+Unknown fields are errors at every level. The obsolete top-level `model:`
+block is rejected.
+
+### LLM settings
+
+- `provider` is a 1-64 byte lowercase slug containing ASCII letters, digits,
+  and hyphens. The portable checker does not restrict it to managed platform
+  providers because custom slugs can be used with an explicit local endpoint.
+- `model` is a trimmed, non-empty string of at most 255 bytes.
+- `request.temperature` is a finite number from 0 through 2 and defaults to 0.
+- `request.max_tokens` is an integer from 1 through 131072 when present;
+  explicit `null` is treated as omitted.
+- `request.reasoning_effort` is a 1-64 byte lowercase slug containing ASCII
+  letters and hyphens; explicit `null` is treated as omitted.
+- `transport.timeout_ms` is an integer from 1 through 600000 and defaults to
+  60000.
+- `transport.max_retries` is an integer from 0 through 10 and defaults to 0.
+- `transport.max_retry_delay_ms` is an integer from 0 through 60000 and
+  defaults to 5000.
+- `local` requires both `base_url` and `api_key_env`. The URL must be HTTP(S),
+  have a host, contain no embedded credentials, query, or fragment, and use
+  HTTPS unless it targets `localhost`, `127.0.0.1`, or `::1`. `api_key_env` is
+  an environment-variable name, not a credential value.
+
+Transport and local settings affect execution but not authored grading
+identity. The platform judge engine remains responsible for applying defaults,
+building requests, and enforcing runtime routing.
+
+## Applicability
+
+`on` is optional. Omission, an empty mapping, or an empty list makes the judge
+applicable to every conversation selected for judging. Otherwise it is an
+OR-list of matchers. Supported events are `message`, `tool`, and `feedback`;
+fields within one `match` mapping are ANDed by the runtime engine.
+
+```yaml
+on:
+  - event: message
+    match:
+      role: user
+      text: /refund|invoice/i
+  - event: tool
+    match:
+      name: shell
+      args.command: /pytest/i
+  - event: feedback
+    match:
+      sentiment: negative
+```
+
+Match keys are non-empty field paths. Regex literals use Rust regex syntax and
+support unique `i`, `m`, `s`, and `u` flags. `environment`, `runtime_group`, and
+paths ending in `pattern_id` are platform-owned and cannot appear as authored
+match fields. The runtime engine owns dotted-path traversal and actual gate
+evaluation.
+
+## Diagnostics
+
+Invalid recipe content is reported through the normal `Report`/`Diagnostic`
+model. Judge diagnostics use stable `judge.*` codes, recipe-relative source
+paths, useful help text, and deterministic ordering. YAML syntax failures use
+`judge.yaml_malformed` and include a 1-based source span when the parser
+provides one. Invalid definitions do not raise a separate content exception in
+the Python binding; they return `Report(valid=False, ...)` like other recipe
+errors.

package/docs/runtime-library.md

@@ -0,0 +1,171 @@
+# Runtime library
+
+The Recipes runtime library turns Recipe source into a live Pi agent. It is a
+library boundary, not a hosting framework.
+
+## The embedding ladder
+
+```text
+resolveRecipe()          read and resolve the portable package
+    │
+    ▼
+createRecipeSession()    construct the complete live Pi session
+    │
+    └── runRecipe()      execute one turn and dispose
+```
+
+Hosts should use the lowest layer that preserves their control.
+
+## `resolveRecipe`
+
+```ts
+import { resolveRecipe } from "@introspection-ai/recipes/recipe";
+
+const recipe = resolveRecipe({
+  recipeDir,
+  agentName,
+});
+```
+
+The result contains the selected agent, visible subagents, model settings,
+tools, MCP policy, skills, prompts, extensions, and system-prompt composition.
+It does not create a model client or start a session.
+
+## `createRecipeSession`
+
+```ts
+import { createRecipeSession } from "@introspection-ai/recipes/session";
+
+const handle = await createRecipeSession({
+  recipeDir,
+  agentName,
+  cwd: workspaceDir,
+  credentials,
+  modelOverride,
+  mcpBindings,
+  eventBus,
+  customTools,
+  extensionFactories,
+  runController,
+  agentToolOptions,
+  settingsManager,
+  sessionManager,
+  additionalSkillPaths,
+  skillPaths,
+  systemPrompt,
+  onDiagnostics,
+  onEvent,
+  otel: {
+    tracer,
+    meter,
+    meta: { conversationId },
+    runSpans: false,
+    getParentContext: () => currentTurnContext,
+  },
+});
+```
+
+This is the primary host integration point. It:
+
+- resolves the Recipe and selected agent;
+- resolves model credentials fail-closed;
+- materializes required MCP bindings fail-closed;
+- loads Recipe skills, prompts, and extensions;
+- registers the shared subagent tool;
+- creates and binds the Pi `AgentSession`;
+- returns one idempotent `dispose()` boundary.
+
+The returned `RecipeSessionHandle` exposes:
+
+- `session` — Pi prompt, steer, follow-up, abort, messages, and events;
+- `recipe` — the resolved portable definition;
+- `runs` — the subagent run controller;
+- `dispose()` — child, session, instrumentation, and MCP cleanup.
+
+Host injection is intentional. A managed host can supply durable session state,
+cross-process subagent execution, inline endpoint bindings, platform
+extensions, its own settings, an event bus, host tools, and a
+gateway-decorated model without reimplementing Recipe semantics. The Recipe
+continues to own model configuration and tool selection; host seams replace
+transport and materialized resources, not the portable definition.
+
+Default MCP materialization leases the supplied `env` object until the handle
+is disposed and restores its prior MCP/PATH state afterward. Concurrent
+materialized sessions must receive separate environment objects. A host that
+materializes one process-wide MCP runtime instead passes `mcpMode: "inherit"`
+to its sessions, as runtime-agent does.
+
+## `runRecipe`
+
+```ts
+import { runRecipe } from "@introspection-ai/recipes/run";
+
+const result = await runRecipe({
+  recipeDir,
+  cwd: workspaceDir,
+  prompt,
+  timeoutMs: 120_000,
+});
+```
+
+`runRecipe` creates one session, executes one prompt, returns the transcript and
+final text, and always disposes. It is suitable for tests, cron jobs, and queue
+workers that do not need a durable conversational host.
+
+## Inspection
+
+```ts
+import { inspectRecipe } from "@introspection-ai/recipes/inspect";
+
+const requirements = inspectRecipe(recipeDir);
+```
+
+Inspection derives agents, providers, expected credential variables, required
+and optional MCP servers, and resource counts without creating a session.
+
+## OpenTelemetry
+
+Pass a tracer through `otel` to attach the JS SDK's OpenTelemetry GenAI
+semantic-convention instrumentation to the session. Recipes derives default
+agent identity from the resolved package and generates a conversation id when
+the host does not provide one. The default in-process subagent controller
+inherits that conversation id while each child derives its own Recipe agent
+identity. Injected run controllers own their child-session instrumentation.
+
+Recipes does not create or register an OTel provider, processor, exporter, or
+global context manager. The host owns that pipeline and its content policy. A
+standalone host can therefore use the same standard OTLP exporter for
+Braintrust, Langfuse, an OTel Collector, or another compatible backend. A host
+that needs structure-only infrastructure traces can wrap that exporter with
+`GenAiContentScrubbingExporter` from
+`@introspection-sdk/introspection-pi`.
+
+Short-lived hosts must flush their own provider after `runRecipe` completes;
+long-lived hosts should flush and shut it down with the host lifecycle.
+
+## Host conformance
+
+```ts
+import { hostConformanceCases } from "@introspection-ai/recipes/test-utils";
+
+for (const testCase of hostConformanceCases(myHostAdapter)) {
+  it(testCase.name, testCase.run);
+}
+```
+
+Passing the suite means the host is using the same session construction
+contract as Pi and Introspection. Protocol behavior, persistence, tenancy, and
+deployment remain host-specific and require their own tests.
+
+## Deliberate non-features
+
+The package does not provide:
+
+- an HTTP server or wire protocol;
+- a task database or task state machine;
+- a scheduler or queue;
+- sandbox or tenant isolation;
+- a deployment CLI;
+- provider-specific hosting adapters.
+
+Those layers compose above `createRecipeSession`.

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@introspection-ai/recipes",
+  "version": "0.13.0",
+  "description": "The open package format for complete, portable Pi agents.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "vendor/mcp-client",
+    "docs",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/introspection-org/pi-recipes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/introspection-org/pi-recipes/issues"
+  },
+  "homepage": "https://github.com/introspection-org/pi-recipes#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./interactions": {
+      "types": "./dist/interactions.d.ts",
+      "import": "./dist/interactions.js"
+    },
+    "./pi-extension": {
+      "types": "./dist/pi-extension.d.ts",
+      "import": "./dist/pi-extension.js"
+    },
+    "./pi": {
+      "types": "./dist/agent-tool.d.ts",
+      "import": "./dist/agent-tool.js"
+    },
+    "./recipe": {
+      "types": "./dist/recipe/resolve.d.ts",
+      "import": "./dist/recipe/resolve.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "import": "./dist/run.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils.d.ts",
+      "import": "./dist/test-utils.js"
+    },
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "import": "./dist/inspect.js"
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.js"
+    ]
+  },
+  "dependencies": {
+    "@introspection-sdk/introspection-pi": "^0.13.0",
+    "@opentelemetry/api": "^1.9.1",
+    "mcporter": "0.12.3",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "^0.82.0",
+    "@earendil-works/pi-ai": "^0.82.0",
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.82.0",
+    "@earendil-works/pi-ai": "0.82.0",
+    "@earendil-works/pi-coding-agent": "0.82.0",
+    "@earendil-works/pi-tui": "0.82.0",
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.28.1",
+    "typebox": "^1.0.56",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "pnpm build:ts && pnpm build:native",
+    "build:ts": "rm -rf dist && tsc && node scripts/build-mcp-daemon.mjs",
+    "build:native": "cargo build --release -p pi-mcp-client && node scripts/package-mcp-client.mjs",
+    "bench:mcp-client": "pnpm build:ts && cargo build --release -p pi-mcp-client && node scripts/benchmark-mcp-client.mjs",
+    "typecheck": "node scripts/check-recipe-check-versions.mjs && tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "pnpm build:ts && cargo test -p pi-mcp-client -p pi-recipe-check && cargo build -p pi-mcp-client && MCP_CLIENT_BIN=target/debug/mcp-client node scripts/package-mcp-client.mjs && vitest run",
+    "pack:check": "pnpm pack --dry-run --json | node scripts/check-npm-pack.mjs",
+    "clean": "rm -rf dist .turbo node_modules target vendor/mcp-client"
+  }
+}