@introspection-ai/recipes 0.13.0 → 0.14.1

package/dist/testing.js

@@ -1,96 +0,0 @@
-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

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

package/docs/deployment-configuration.md

@@ -1,65 +0,0 @@
-# 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/migration.md

@@ -1,70 +0,0 @@
-# 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/python-bindings-release.md

@@ -1,47 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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/runtime-library.md

@@ -1,171 +0,0 @@
-# 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`.