@introspection-ai/recipes 0.13.0 → 0.14.1

package/dist/session.js

@@ -1,137 +1,123 @@
 import { randomUUID } from "node:crypto";
-import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
-import { getEnvApiKey, getModel } from "@earendil-works/pi-ai/compat";
-import { createAgentSessionFromServices, createAgentSessionServices, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { rm } from "node:fs/promises";
+import { getModel } from "@earendil-works/pi-ai/compat";
+import { createBashToolDefinition, createAgentSessionFromServices, createAgentSessionServices, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { instrumentSession, } from "@introspection-sdk/introspection-pi";
-import { createAgentTool } from "./agent-tool.js";
+import { createAgentTool } from "./agents.js";
 import { clearMcpCatalogPreload, preloadMcpCatalogs, } from "./mcp-catalog.js";
-import { configureMcpLocalConfigPath, isolateMcpEnvironment, materializeMcpSession, materializeSessionMcpCli, restoreMcpEnvironment, resolveAgentMcpSelections, snapshotMcpEnvironment, stopMcpDaemon, } from "./mcp.js";
-import { expectedProviderEnvVars } from "./provider-env.js";
+import { createIsolatedMcpEnvironment, configureMcpLocalConfigPath, isolateMcpEnvironment, materializeMcpSession, materializeSessionMcpCli, readMcpSessionConfig, restoreMcpEnvironment, resolveAgentMcpSelections, snapshotMcpEnvironment, stopMcpDaemon, } from "./mcp.js";
+import { createMcpToolSet } from "./mcp-tools.js";
+import { assertRecipeModelTransport, RecipeCredentialError, RecipeModelError, RecipeModelTransportError, resolveRecipeCredentials, } from "./model-binding.js";
 import { loadRecipeExtensionFactory } from "./recipe-extensions.js";
-import { applyRecipeAgentModelConfigToModel, applyRecipeAgentModelConfigToSession, } from "./recipe-model.js";
-import { resolveRecipe } from "./recipe/resolve.js";
+import { bindRecipeExtensionFactory, createRecipeExtensionRegistrationRegistry, recipeExtensionToolAllowlist, } from "./extensions.js";
+import { applyRecipeAgentModelConfigToModel, applyRecipeAgentModelConfigToSession, cloneModelForRecipe, } from "./recipe-model.js";
 export { expectedProviderEnvVars } from "./provider-env.js";
-/** The session model's provider has no resolvable credential. */
-export class RecipeCredentialError extends Error {
-    provider;
-    expectedEnvVars;
-    name = "RecipeCredentialError";
-    constructor(provider, 
-    /** Env vars that would satisfy the provider, most conventional first. */
-    expectedEnvVars) {
-        super(`No credential for model provider "${provider}": set ${expectedEnvVars.join(" or ")}, or pass a CredentialStore via credentials`);
-        this.provider = provider;
-        this.expectedEnvVars = expectedEnvVars;
+export { RecipeCredentialError, RecipeModelError, RecipeModelTransportError, };
+function schemaChildPosition(position, key) {
+    if (position === "schema-map")
+        return "schema";
+    if (position === "literal")
+        return "literal";
+    if (key === "properties" ||
+        key === "patternProperties" ||
+        key === "$defs" ||
+        key === "definitions" ||
+        key === "dependentSchemas") {
+        return "schema-map";
     }
-}
-/** The recipe's model spec does not resolve to a known model. */
-export class RecipeModelError extends Error {
-    modelSpec;
-    name = "RecipeModelError";
-    constructor(modelSpec) {
-        super(`Recipe model is not available: ${modelSpec}`);
-        this.modelSpec = modelSpec;
+    if (key === "default" ||
+        key === "const" ||
+        key === "examples" ||
+        key === "enum") {
+        return "literal";
     }
+    return "schema";
 }
-function parseModelSpec(spec) {
-    const slash = spec.indexOf("/");
-    if (slash < 0) {
-        throw new Error(`Invalid recipe model "${spec}" - expected "<provider>/<model_id>"`);
+function stripAdditionalProperties(value, position = "schema") {
+    if (value === null || typeof value !== "object")
+        return value;
+    const clone = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    for (const key of Reflect.ownKeys(value)) {
+        if (position === "schema" && key === "additionalProperties")
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor)
+            continue;
+        if ("value" in descriptor) {
+            descriptor.value = stripAdditionalProperties(descriptor.value, schemaChildPosition(position, key));
+        }
+        Object.defineProperty(clone, key, descriptor);
     }
-    const provider = spec.slice(0, slash);
-    const modelId = spec.slice(slash + 1);
-    const lookupProvider = provider === "gemini" ? "google" : provider;
-    return { provider, modelId, lookupProvider };
+    return clone;
 }
 /**
- * Ambient-credential providers resolve from their own SDK chain (AWS
- * profiles, ADC); `getEnvApiKey` reports them as "<authenticated>".
- */
-const AMBIENT_CREDENTIAL_SENTINEL = "<authenticated>";
-/**
- * Resolve credentials fail-closed against the session's own `env`, never the
- * ambient process env: explicit store → per-provider env keys → error.
+ * Gemini rejects JSON Schema's `additionalProperties` keyword in tool
+ * declarations. Normalize the final Recipe toolset after host tools and the
+ * shared agent tool have been registered so every host gets the same behavior.
  */
-async function resolveCredentialStore(lookupProvider, opts) {
-    if (opts.credentials) {
-        const stored = await opts.credentials.read(lookupProvider);
-        if (!stored) {
-            throw new RecipeCredentialError(lookupProvider, expectedProviderEnvVars(lookupProvider));
-        }
-        return opts.credentials;
-    }
-    const env = opts.env ?? process.env;
-    const store = new InMemoryCredentialStore();
-    const apiKey = getEnvApiKey(lookupProvider, env) ??
-        env[`${lookupProvider.toUpperCase().replace(/-/g, "_")}_API_KEY`];
-    if (!apiKey) {
-        throw new RecipeCredentialError(lookupProvider, expectedProviderEnvVars(lookupProvider));
-    }
-    if (apiKey !== AMBIENT_CREDENTIAL_SENTINEL) {
-        await store.modify(lookupProvider, async () => ({
-            type: "api_key",
-            key: apiKey,
-        }));
+function normalizeSessionToolsForModel(session, model) {
+    const isGemini = [model.id, model.name].some((value) => value?.toLowerCase().includes("gemini"));
+    if (!isGemini)
+        return;
+    const mutableSession = session;
+    for (const tool of mutableSession.agent?.state?.tools ?? []) {
+        tool.parameters = stripAdditionalProperties(tool.parameters);
     }
-    // Ambient-credential providers (Bedrock, Vertex ADC) keep an empty store;
-    // the pi-ai provider resolves its own credential chain at stream time.
-    return store;
 }
 function scopedMcpSelections(recipe) {
-    return [recipe.agent, ...recipe.subagents.values()].flatMap((agent) => resolveAgentMcpSelections(agent.mcp));
+    return resolveAgentMcpSelections(recipe.mcp);
 }
 const leasedMcpEnvironments = new WeakSet();
 export class RecipeMcpEnvironmentInUseError extends Error {
     name = "RecipeMcpEnvironmentInUseError";
     constructor() {
-        super("This environment already belongs to a live materialized Recipe MCP session; use a separate env object per concurrent session or let the host materialize MCP once and pass mcpMode: \"inherit\"");
-    }
-}
-/**
- * Everything `createRecipeSession` fail-closes on, without creating a
- * session or starting MCP: recipe resolution, model lookup, credentials.
- * Hosts with a boot phase (the serve layer) run this once to fail fast.
- */
-export async function preflightRecipeSession(opts) {
-    const recipe = resolveRecipe({
-        recipeDir: opts.recipeDir,
-        ...(opts.agentName ? { agentName: opts.agentName } : {}),
-    });
-    const modelSpec = opts.model ?? recipe.modelSpec;
-    const { lookupProvider, modelId } = parseModelSpec(modelSpec);
-    const credentialProvider = opts.modelOverride?.provider ?? lookupProvider;
-    const credentials = await resolveCredentialStore(credentialProvider, opts);
-    const modelRuntime = await ModelRuntime.create({
-        credentials,
-        modelsPath: null,
-    });
-    const model = opts.modelOverride ??
-        modelRuntime.getModel(lookupProvider, modelId) ??
-        getModel(lookupProvider, modelId);
-    if (!model) {
-        throw new RecipeModelError(modelSpec);
+        super("This environment already belongs to a live materialized Recipe MCP session; use a separate env object per concurrent session or let the host materialize MCP once and pass mcpProvisioning: \"host\"");
     }
-    return recipe;
 }
 /**
  * Materialize the session MCP runtime for a recipe scope into `env` at
- * `cwd`. Exposed for hosts that materialize once per process (the serve
- * layer) and create their sessions with `mcpMode: "inherit"`.
+ * `cwd`. Exposed for hosts that materialize once per process and create their
+ * sessions with `mcpProvisioning: "host"`.
  */
 export async function materializeRecipeSessionMcp(recipe, cwd, env, opts = {}) {
-    return configureSessionMcp(recipe, cwd, env, {
-        recipeDir: recipe.recipeDir,
-        ...opts,
-    }, false);
-}
-async function configureSessionMcp(recipe, cwd, env, opts, leaseEnvironment) {
     const selections = scopedMcpSelections(recipe);
-    if (opts.mcpMode === "inherit")
-        return { materialized: false };
     if (selections.length === 0)
         return { materialized: false };
-    const snapshot = leaseEnvironment ? snapshotMcpEnvironment(env) : undefined;
-    if (leaseEnvironment) {
+    if (opts.mcpBindingsPath) {
+        env.PI_RECIPES_MCP_LOCAL_CONFIG = opts.mcpBindingsPath;
+    }
+    else if (!opts.mcpBindings) {
+        configureMcpLocalConfigPath({ cwd, recipeDir: recipe.recipeDir, env });
+    }
+    if (recipe.mcp?.mode === "cli") {
+        await materializeSessionMcpCli({ cwd, env });
+    }
+    await materializeMcpSession({
+        cwd,
+        manifest: recipe.manifest,
+        agentMcp: selections,
+        env,
+        ...(opts.mcpBindings ? { localConfig: opts.mcpBindings } : {}),
+    });
+    return { materialized: true };
+}
+async function configureSessionMcp(recipe, cwd, env, opts, activation) {
+    const selections = scopedMcpSelections(recipe);
+    if (selections.length === 0) {
+        return { available: false, materialized: false };
+    }
+    const mode = recipe.mcp?.mode ?? "cli";
+    const hostProvisioned = opts.mcpProvisioning === "host";
+    const mcpCwd = opts.mcpRuntimeDir ?? cwd;
+    const snapshot = !hostProvisioned && mode === "cli"
+        ? snapshotMcpEnvironment(env)
+        : undefined;
+    let runtimeEnv = env;
+    let privateDirectory;
+    let privateMcporterConfigPath;
+    if (snapshot) {
         if (leasedMcpEnvironments.has(env)) {
             throw new RecipeMcpEnvironmentInUseError();
         }
@@ -139,46 +125,87 @@ async function configureSessionMcp(recipe, cwd, env, opts, leaseEnvironment) {
         isolateMcpEnvironment(env);
     }
     const release = async () => {
-        if (!snapshot)
+        if (hostProvisioned)
             return;
-        try {
-            clearMcpCatalogPreload(env);
-            await stopMcpDaemon(env);
+        clearMcpCatalogPreload(runtimeEnv);
+        await stopMcpDaemon(runtimeEnv);
+        if (privateDirectory) {
+            await rm(privateDirectory, { recursive: true, force: true });
         }
-        finally {
+        if (snapshot) {
             restoreMcpEnvironment(env, snapshot);
             leasedMcpEnvironments.delete(env);
         }
     };
     try {
-        if (opts.mcpBindingsPath) {
-            env.PI_RECIPES_MCP_LOCAL_CONFIG = opts.mcpBindingsPath;
+        if (!hostProvisioned && mode === "tools") {
+            const isolated = await createIsolatedMcpEnvironment(env);
+            runtimeEnv = isolated.env;
+            privateDirectory = isolated.directory;
+            privateMcporterConfigPath = isolated.mcporterConfigPath;
         }
-        else if (!opts.mcpBindings) {
-            configureMcpLocalConfigPath({ cwd, recipeDir: recipe.recipeDir, env });
+        let session;
+        if (hostProvisioned) {
+            session = readMcpSessionConfig(cwd, runtimeEnv);
         }
-        const [cliResult, sessionResult] = await Promise.allSettled([
-            materializeSessionMcpCli({ cwd, env }),
-            materializeMcpSession({
-                cwd,
+        else {
+            if (opts.mcpBindingsPath) {
+                runtimeEnv.PI_RECIPES_MCP_LOCAL_CONFIG = opts.mcpBindingsPath;
+            }
+            else if (!opts.mcpBindings) {
+                configureMcpLocalConfigPath({
+                    cwd,
+                    recipeDir: recipe.recipeDir,
+                    env: runtimeEnv,
+                });
+            }
+            if (mode === "cli") {
+                await materializeSessionMcpCli({ cwd: mcpCwd, env: runtimeEnv });
+            }
+            session = await materializeMcpSession({
+                cwd: mcpCwd,
                 manifest: recipe.manifest,
                 agentMcp: selections,
-                env,
+                env: runtimeEnv,
                 ...(opts.mcpBindings ? { localConfig: opts.mcpBindings } : {}),
-            }),
-        ]);
-        if (cliResult.status === "rejected")
-            throw cliResult.reason;
-        if (sessionResult.status === "rejected")
-            throw sessionResult.reason;
-        const session = sessionResult.value;
+                ...(privateMcporterConfigPath
+                    ? { mcporterConfigPath: privateMcporterConfigPath }
+                    : {}),
+            });
+        }
+        if (mode === "tools") {
+            const catalogs = session.servers.length > 0
+                ? await preloadMcpCatalogs({
+                    env: runtimeEnv,
+                    allowPartial: true,
+                })
+                : [];
+            const materialized = createMcpToolSet({
+                session,
+                catalogs,
+                mcp: recipe.mcp,
+                env: runtimeEnv,
+                activation,
+            });
+            return {
+                available: true,
+                materialized: !hostProvisioned,
+                tools: materialized.tools,
+                initialActiveToolNames: materialized.initialActiveToolNames,
+                ...(materialized.searchToolName
+                    ? { searchToolName: materialized.searchToolName }
+                    : {}),
+                release,
+            };
+        }
         if (session.servers.length > 0) {
             // Warm tool catalogs in the background; sessions work without the warmup.
-            void preloadMcpCatalogs({ env }).catch(() => { });
+            void preloadMcpCatalogs({ env: runtimeEnv }).catch(() => { });
         }
         return {
-            materialized: true,
-            ...(snapshot ? { release } : {}),
+            available: true,
+            materialized: !hostProvisioned,
+            release,
         };
     }
     catch (error) {
@@ -186,42 +213,49 @@ async function configureSessionMcp(recipe, cwd, env, opts, leaseEnvironment) {
         throw error;
     }
 }
-export async function createRecipeSession(opts) {
-    const recipe = resolveRecipe({
-        recipeDir: opts.recipeDir,
-        ...(opts.agentName ? { agentName: opts.agentName } : {}),
-    });
+async function createSessionForAgent(recipe, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const env = opts.env ?? process.env;
+    const recipeExtensionContext = Object.freeze({
+        recipe: Object.freeze({ name: recipe.manifest.name }),
+        agent: Object.freeze({ name: recipe.name }),
+        session: Object.freeze({
+            role: opts.sessionRole,
+        }),
+    });
     const otel = opts.otel
         ? {
             ...opts.otel,
             meta: {
                 conversationId: opts.otel.meta?.conversationId ?? randomUUID(),
                 agentId: opts.otel.meta?.agentId ??
-                    `${recipe.manifest.name}/${recipe.agentName}`,
-                agentName: opts.otel.meta?.agentName ?? recipe.agentName,
+                    `${recipe.manifest.name}/${recipe.name}`,
+                agentName: opts.otel.meta?.agentName ?? recipe.name,
             },
         }
         : undefined;
     // Model + credentials, fail-closed before any MCP runtime starts.
-    const modelSpec = opts.model ?? recipe.modelSpec;
-    const { lookupProvider, modelId } = parseModelSpec(modelSpec);
+    const modelSpec = recipe.modelSpec;
+    const { lookupProvider, modelId } = assertRecipeModelTransport(modelSpec, opts.modelOverride);
     const credentialProvider = opts.modelOverride?.provider ?? lookupProvider;
-    const credentials = await resolveCredentialStore(credentialProvider, opts);
+    const credentials = opts.credentialsResolved && opts.credentials
+        ? opts.credentials
+        : await resolveRecipeCredentials({
+            provider: credentialProvider,
+            env,
+            ...(opts.modelOverride ? { model: opts.modelOverride } : {}),
+            ...(opts.credentials ? { credentials: opts.credentials } : {}),
+        });
     const modelRuntime = await ModelRuntime.create({ credentials, modelsPath: null });
-    const model = opts.modelOverride ??
-        modelRuntime.getModel(lookupProvider, modelId) ??
-        getModel(lookupProvider, modelId);
-    if (!model) {
-        throw new RecipeModelError(modelSpec);
-    }
-    applyRecipeAgentModelConfigToModel(model, recipe.modelConfig);
-    const mcp = await configureSessionMcp(recipe, cwd, env, opts, true);
+    let model;
     let session;
-    let runs;
+    let agentRuns;
     let unsubscribe;
     let detachInstrumentation;
+    const mcp = await configureSessionMcp(recipe, cwd, env, opts, {
+        getActiveTools: () => session?.getActiveToolNames() ?? [],
+        setActiveTools: (names) => session?.setActiveToolsByName(names),
+    });
     const cleanup = async () => {
         try {
             unsubscribe?.();
@@ -230,13 +264,9 @@ export async function createRecipeSession(opts) {
             // Continue releasing the remaining session-owned resources.
         }
         unsubscribe = undefined;
-        if (runs) {
+        if (agentRuns) {
             try {
-                for (const run of runs.list()) {
-                    if (run.status !== "closed") {
-                        await runs.close(run.agent_run_id).catch(() => { });
-                    }
-                }
+                await agentRuns.shutdown();
             }
             catch {
                 // Child teardown is best-effort; the session still disposes.
@@ -270,83 +300,182 @@ export async function createRecipeSession(opts) {
         // Recipe extensions load through the shared jiti loader; host extensions
         // append after them, matching the Pi extension host's ordering.
         const inlineExtensions = [];
+        const recipeRegistrations = createRecipeExtensionRegistrationRegistry();
+        for (const toolName of [
+            "read",
+            "bash",
+            "edit",
+            "write",
+            "grep",
+            "find",
+            "ls",
+            ...(opts.customTools ?? []).map((tool) => tool.name),
+            ...(recipe.subagents.size > 0 && opts.runController !== null
+                ? ["agent"]
+                : []),
+        ]) {
+            recipeRegistrations.claim("tool", toolName, "<host>");
+        }
         for (const extensionPath of recipe.extensionPaths) {
-            inlineExtensions.push(await loadRecipeExtensionFactory(recipe.recipeDir, extensionPath));
+            inlineExtensions.push(bindRecipeExtensionFactory(await loadRecipeExtensionFactory(recipe.recipeDir, extensionPath), recipeExtensionContext, recipeRegistrations, extensionPath, recipeExtensionToolAllowlist(recipe.tools, recipe.subagents.size > 0 && opts.runController !== null, [
+                ...(mcp.tools?.map((tool) => tool.name) ?? []),
+                ...(mcp.searchToolName ? [mcp.searchToolName] : []),
+            ])));
         }
         inlineExtensions.push(...(opts.extensionFactories ?? []));
+        const settingsManager = opts.settingsManager ?? SettingsManager.create(cwd, recipe.recipeDir);
         const services = await createAgentSessionServices({
             cwd,
             agentDir: recipe.recipeDir,
             modelRuntime,
-            settingsManager: opts.settingsManager ?? SettingsManager.create(cwd, recipe.recipeDir),
+            settingsManager,
             resourceLoaderOptions: {
                 eventBus: opts.eventBus,
+                noExtensions: true,
                 noSkills: true,
+                noPromptTemplates: true,
+                noContextFiles: true,
                 additionalSkillPaths: [
-                    ...(opts.skillPaths ?? recipe.skillPaths),
+                    ...(opts.materializedSkillPaths ?? recipe.skillPaths),
                     ...(opts.additionalSkillPaths ?? []),
                 ],
-                additionalPromptTemplatePaths: recipe.promptPaths,
+                additionalPromptTemplatePaths: [...recipe.promptPaths],
                 extensionFactories: inlineExtensions,
                 systemPromptOverride: (base) => {
                     const resolved = recipe.systemPromptOverride(base);
-                    return opts.systemPrompt ? opts.systemPrompt(resolved ?? "") : resolved;
+                    return opts.transformSystemPrompt
+                        ? opts.transformSystemPrompt(resolved ?? "")
+                        : resolved;
                 },
             },
         });
         opts.onDiagnostics?.(services.diagnostics);
+        const extensionLoadErrors = services.resourceLoader.getExtensions().errors;
+        const fatalDiagnostics = services.diagnostics.filter((diagnostic) => diagnostic.type === "error");
+        if (fatalDiagnostics.length > 0 || extensionLoadErrors.length > 0) {
+            throw new Error(`Recipe extension startup failed:\n${[
+                ...extensionLoadErrors.map(({ path, error }) => `- ${path}: ${error}`),
+                ...fatalDiagnostics.map((diagnostic) => `- ${diagnostic.message}`),
+            ]
+                .join("\n")}`);
+        }
+        const selectedModel = opts.modelOverride ??
+            services.modelRuntime.getModel(lookupProvider, modelId) ??
+            modelRuntime.getModel(lookupProvider, modelId) ??
+            getModel(lookupProvider, modelId);
+        if (!selectedModel) {
+            throw new RecipeModelError(modelSpec);
+        }
+        model = cloneModelForRecipe(selectedModel);
+        applyRecipeAgentModelConfigToModel(model, recipe.modelConfig);
         // Subagents: the shared `agent` tool against an injected or in-process
         // controller. `runController: null` disables delegation outright.
         const wantsSubagents = recipe.subagents.size > 0 && opts.runController !== null;
         if (opts.runController) {
-            runs = opts.runController;
+            agentRuns = opts.runController;
         }
         else {
             const { createInProcessRunController, inertRunController } = await import("./run-controller.js");
-            runs = wantsSubagents
+            agentRuns = wantsSubagents
                 ? createInProcessRunController({
-                    recipeDir: recipe.recipeDir,
+                    recipe: opts.recipe,
                     cwd,
                     env,
                     ...(opts.credentials ? { credentials: opts.credentials } : {}),
-                    concurrency: opts.subagentLimits?.concurrency,
+                    concurrency: opts.inProcessRunController?.concurrency,
                     ...(otel ? { otel } : {}),
                 })
                 : inertRunController();
         }
-        const tools = wantsSubagents
-            ? recipe.tools
-            : recipe.tools.filter((tool) => tool !== "agent");
+        const tools = [
+            ...recipe.tools,
+            ...(wantsSubagents ? ["agent"] : []),
+        ];
+        const mcpToolNames = mcp.tools?.map((tool) => tool.name) ?? [];
+        const recipeExtensionToolNames = new Set(services.resourceLoader
+            .getExtensions()
+            .extensions.flatMap((extension) => [...extension.tools.keys()]));
+        const occupiedToolNames = new Set([
+            ...tools,
+            ...(opts.customTools ?? []).map((tool) => tool.name),
+            ...(wantsSubagents ? ["agent"] : []),
+        ]);
+        const collisions = mcpToolNames.filter((name) => occupiedToolNames.has(name) || recipeExtensionToolNames.has(name));
+        if (collisions.length > 0) {
+            throw new Error(`Recipe MCP tool name collision: ${collisions.join(", ")}`);
+        }
+        const selectedToolNames = [...tools, ...mcpToolNames];
+        const environmentBash = (recipe.mcp?.mode ?? "cli") === "cli" &&
+            mcp.available &&
+            env !== process.env &&
+            tools.includes("bash") &&
+            !(opts.customTools ?? []).some((tool) => tool.name === "bash")
+            ? createBashToolDefinition(cwd, {
+                commandPrefix: settingsManager.getShellCommandPrefix(),
+                shellPath: settingsManager.getShellPath(),
+                spawnHook: (context) => ({
+                    ...context,
+                    env: { ...context.env, ...env },
+                }),
+            })
+            : undefined;
         const customTools = [
+            ...(environmentBash ? [environmentBash] : []),
             ...(opts.customTools ?? []),
             ...(wantsSubagents
-                ? [createAgentTool(runs, recipe.subagents, opts.agentToolOptions)]
+                ? [
+                    createAgentTool(agentRuns, recipe.subagents, opts.agentToolOptions),
+                ]
                 : []),
+            ...(mcp.tools ?? []),
         ];
         const created = await createAgentSessionFromServices({
             services,
             sessionManager: opts.sessionManager ?? SessionManager.inMemory(cwd),
             model,
-            ...(opts.thinkingLevel ?? recipe.thinkingLevel
-                ? { thinkingLevel: (opts.thinkingLevel ?? recipe.thinkingLevel) }
+            ...(recipe.thinkingLevel
+                ? { thinkingLevel: recipe.thinkingLevel }
                 : {}),
-            tools,
+            tools: selectedToolNames,
             customTools,
         });
         session = created.session;
+        normalizeSessionToolsForModel(session, model);
         applyRecipeAgentModelConfigToSession(session, recipe.modelConfig);
         await session.bindExtensions({});
+        const registered = new Set(session.getAllTools().map((tool) => tool.name));
+        const missingDeclaredTools = selectedToolNames.filter((name) => !registered.has(name));
+        if (missingDeclaredTools.length > 0) {
+            throw new Error(`Recipe agent "${recipe.name}" declares unavailable tool(s): ${missingDeclaredTools.join(", ")}`);
+        }
+        if (mcp.tools) {
+            const missingRegistered = mcpToolNames.filter((name) => !registered.has(name));
+            if (missingRegistered.length > 0) {
+                throw new Error(`Pi did not register Recipe MCP tool(s): ${missingRegistered.join(", ")}`);
+            }
+            const activeTools = [
+                ...tools,
+                ...(mcp.initialActiveToolNames ?? []),
+                ...(mcp.searchToolName ? [mcp.searchToolName] : []),
+            ];
+            session.setActiveToolsByName(activeTools);
+            const applied = new Set(session.getActiveToolNames());
+            const missing = activeTools.filter((name) => !applied.has(name));
+            if (missing.length > 0) {
+                throw new Error(`Pi did not activate Recipe tool(s): ${missing.join(", ")}`);
+            }
+        }
         unsubscribe = opts.onEvent ? session.subscribe(opts.onEvent) : undefined;
         detachInstrumentation = otel
             ? instrumentSession(session, otel).detach
             : undefined;
         const liveSession = session;
-        const liveRuns = runs;
+        const liveRuns = agentRuns;
         let disposed = false;
         return {
             session: liveSession,
-            recipe,
-            runs: liveRuns,
+            agent: recipe,
+            agentRuns: liveRuns,
             async dispose() {
                 if (disposed)
                     return;
@@ -360,4 +489,14 @@ export async function createRecipeSession(opts) {
         throw error;
     }
 }
+export async function createAgentSession(opts) {
+    return createSessionForAgent(opts.recipe.selectAgent(opts.agentName), {
+        ...opts,
+        sessionRole: "root",
+    });
+}
+/** @internal Construct a child with Recipes-owned lifecycle state. */
+export async function createAgentSessionInternal(opts) {
+    return createSessionForAgent(opts.recipe.selectAgent(opts.agentName), opts);
+}
 //# sourceMappingURL=session.js.map