@llblab/pi-actors 0.45.1 → 0.46.1

package/dist/lib/registry.js

@@ -8,9 +8,11 @@ import { dirname, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Config from "./config.js";
 import * as ExecutionOutput from "./execution-output.js";
-import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import { withFileMutationLock, writeJsonAtomic, writeTextAtomic, } from "./file-state.js";
 import * as Identity from "./identity.js";
 import * as Paths from "./paths.js";
+import * as RecipesContext from "./recipes-context.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as Schema from "./schema.js";
 function textContent(text) {
@@ -58,21 +60,24 @@ function promoteDraftRecipe(name, input, ctx, deps) {
     if ((existing || existsSync(targetPath)) && !input.update) {
         throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }
-    const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
-    if (!config) {
+    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+    if (!raw) {
         const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
         throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid${reason ? `: ${reason}` : "."}`));
     }
-    const promoted = buildConfig(name, {
+    const authoredRecipe = buildAuthoredRecipe({
         ...input,
-        description: input.description ?? config.description,
-        template: draftPath,
-    }, existing);
-    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+        description: input.description ??
+            (typeof raw.description === "string" ? raw.description : undefined),
+    }, existing, raw);
+    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
+    const candidate = RecipesDiscovery.admitUserRecipe(targetPath, resolutionContext, authoredRecipe);
+    if (!candidate.validated || !candidate.tool) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid: ${candidate.diagnostics.join("; ")}`));
+    }
     mkdirSync(dirname(targetPath), { recursive: true });
-    writeJsonAtomic(targetPath, raw);
-    promoted.template = targetPath;
-    promoted.sourcePath = targetPath;
+    writeJsonAtomic(targetPath, authoredRecipe);
+    const promoted = RecipesDiscovery.admitUserRecipe(targetPath, resolutionContext).tool;
     tools.set(name, promoted);
     deps.registerRuntimeTool(promoted);
     deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
@@ -89,17 +94,10 @@ function promoteDraftRecipe(name, input, ctx, deps) {
         },
     };
 }
-function persistToolRecipe(deps, cfg) {
-    const path = getToolRecipePath(deps, cfg.name);
+function persistToolRecipe(deps, name, recipe) {
+    const path = getToolRecipePath(deps, name);
     mkdirSync(dirname(path), { recursive: true });
-    writeJsonAtomic(path, {
-        description: cfg.description,
-        ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
-        ...(cfg.storedArgs ? { args: cfg.storedArgs } : {}),
-        ...(cfg.storedDefaults ? { defaults: cfg.storedDefaults } : {}),
-        ...(cfg.recipe?.values ? { values: cfg.recipe.values } : {}),
-        template: cfg.template,
-    });
+    writeJsonAtomic(path, recipe);
     return path;
 }
 function deleteTool(name, ctx, deps) {
@@ -130,11 +128,15 @@ function readAuthoritativeStoredTool(deps, name) {
     if (!existsSync(path))
         return { exists: false };
     try {
-        const normalized = Config.normalizeStoredTool(name, JSON.parse(readFileSync(path, "utf8")), deps.reservedToolNames);
+        const bytes = readFileSync(path, "utf8");
+        const recipe = JSON.parse(bytes);
+        const normalized = Config.normalizeStoredTool(name, recipe, deps.reservedToolNames);
         if (!normalized.cfg)
-            return { exists: true };
+            return { bytes, exists: true, recipe };
         return {
+            bytes,
             exists: true,
+            recipe,
             tool: { ...normalized.cfg, sourcePath: path },
         };
     }
@@ -161,7 +163,17 @@ function getInputTemplate(value) {
     }
     throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
 }
-function buildConfig(name, input, existing) {
+function getRegistrationResolutionContext(ctx, deps) {
+    if (ctx &&
+        typeof ctx === "object" &&
+        "recipeResolutionContext" in ctx) {
+        const resolutionContext = ctx.recipeResolutionContext;
+        if (resolutionContext)
+            return resolutionContext;
+    }
+    return RecipesContext.createEmptyRecipeResolutionContext("offline-register-tool", getRecipeRoot(deps));
+}
+function buildAuthoredRecipe(input, existing, existingRecipe) {
     const explicitArgs = input.args === undefined
         ? undefined
         : Schema.parseToolArgDeclarations(input.args);
@@ -175,63 +187,29 @@ function buildConfig(name, input, existing) {
     if (template === null) {
         throw new Error(ExecutionOutput.formatToolText("Tool template cannot be null here."));
     }
-    const finalTemplate = template === undefined || template === "" ? existing?.template : template;
+    const finalTemplate = template === undefined || template === ""
+        ? existingRecipe?.template ?? existing?.template
+        : template;
     if (!finalTemplate) {
         throw new Error(ExecutionOutput.formatToolText("Tool template is required."));
     }
-    const inputRecipe = typeof input.async === "boolean" ? name : undefined;
-    const recipe = inputRecipe
-        ? {
-            name: inputRecipe,
-            ...(typeof input.async === "boolean" ? { async: input.async } : {}),
-            template: finalTemplate,
-            ...(input.values && typeof input.values === "object"
-                ? { values: input.values }
-                : {}),
-        }
-        : template === undefined
-            ? existing?.recipe
-            : undefined;
-    const defaults = explicitArgs?.defaults ?? existing?.storedDefaults ?? {};
-    const storedArgs = explicitArgs
-        ? explicitArgs.declarations
-        : existing?.storedArgs;
-    const storedDefaults = Object.keys(defaults).length > 0 ? defaults : undefined;
-    const recipeTemplate = RecipesReferences.getRecipeTemplate(finalTemplate);
-    const argTemplate = recipeTemplate ?? finalTemplate;
-    const argTemplateConfig = typeof argTemplate === "object" && !Array.isArray(argTemplate)
-        ? {
-            ...argTemplate,
-            ...(storedArgs !== undefined ? { args: storedArgs } : {}),
-            defaults: { ...(argTemplate.defaults ?? {}), ...defaults },
-        }
-        : {
-            args: storedArgs,
-            defaults,
-            template: argTemplate,
-        };
-    const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
-    const argTypes = {
-        ...inferredArgTypes,
-        ...(existing?.argTypes ?? {}),
-        ...(explicitArgs?.argTypes ?? {}),
-    };
-    return {
-        name,
+    const authored = {
+        ...(existingRecipe ?? {}),
         description,
         template: finalTemplate,
-        ...(recipe ? { recipe } : {}),
-        args: RecipesReferences.isRecipeTool(finalTemplate, recipe) &&
-            storedArgs !== undefined
-            ? Schema.getExplicitToolArgNames(storedArgs)
-            : RecipesReferences.isRecipeReference(finalTemplate) && !recipeTemplate
-                ? Schema.getExplicitToolArgNames(storedArgs)
-                : Schema.getToolArgNames(argTemplateConfig),
-        defaults,
-        ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
-        ...(storedArgs !== undefined ? { storedArgs } : {}),
-        ...(storedDefaults !== undefined ? { storedDefaults } : {}),
     };
+    if (typeof input.async === "boolean")
+        authored.async = input.async;
+    if (explicitArgs) {
+        authored.args = explicitArgs.declarations;
+        if (Object.keys(explicitArgs.defaults).length > 0)
+            authored.defaults = explicitArgs.defaults;
+        else
+            delete authored.defaults;
+    }
+    if (input.values && typeof input.values === "object")
+        authored.values = input.values;
+    return authored;
 }
 function executeRegisterToolUnlocked(params, ctx, deps) {
     const input = params;
@@ -262,37 +240,82 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     if (template === undefined && !existing) {
         throw new Error(ExecutionOutput.formatToolText("Tool template is required for new registrations."));
     }
-    const cfg = buildConfig(name, input, existing);
-    let recipePath;
+    const recipePath = getToolRecipePath(deps, name);
+    const authoredRecipe = buildAuthoredRecipe(input, existing, authoritative.recipe);
+    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
+    const candidate = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext, authoredRecipe);
+    if (!candidate.validated || !candidate.tool) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool recipe validation failed: ${candidate.diagnostics.join("; ")}`));
+    }
+    const activeBefore = deps.getActiveTools();
+    let persisted = false;
+    let activation;
+    let cfg;
     try {
-        recipePath = persistToolRecipe(deps, cfg);
+        persistToolRecipe(deps, name, authoredRecipe);
+        persisted = true;
+        const admitted = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext);
+        if (!admitted.validated || !admitted.tool) {
+            throw new Error(`Persisted tool recipe admission failed: ${admitted.diagnostics.join("; ")}`);
+        }
+        cfg = admitted.tool;
+        tools.set(name, cfg);
+        activation = deps.registerRuntimeTool(cfg) ?? undefined;
+        if (activation &&
+            (!activation.host_registered ||
+                !activation.active_tool ||
+                !activation.callable_now)) {
+            throw new Error(`Host activation verification failed: ${JSON.stringify(activation)}`);
+        }
     }
     catch (error) {
-        throw new Error(ExecutionOutput.formatToolText(`Failed to persist tool recipe: ${error instanceof Error ? error.message : String(error)}`));
+        if (persisted) {
+            if (authoritative.bytes !== undefined)
+                writeTextAtomic(recipePath, authoritative.bytes);
+            else if (existsSync(recipePath))
+                unlinkSync(recipePath);
+        }
+        if (existing) {
+            tools.set(name, existing);
+            deps.registerRuntimeTool(existing);
+        }
+        else {
+            tools.delete(name);
+        }
+        deps.setActiveTools(activeBefore);
+        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`));
     }
-    cfg.sourcePath = recipePath;
-    tools.set(name, cfg);
-    deps.registerRuntimeTool(cfg);
-    deps.notify(ctx, `Tool persisted: ${name}`, "info");
-    const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.template === "object" && !Array.isArray(cfg.template)
-        ? cfg.template
-        : { template: cfg.template });
+    deps.notify(ctx, `Tool activated: ${name}`, "info");
+    const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)
+        ? cfg.recipe.template
+        : { template: cfg.recipe?.template ?? cfg.template });
     const warningText = templateWarnings.length > 0
         ? `\nWarnings:\n${templateWarnings.map((warning) => `- ${warning}`).join("\n")}`
         : "";
+    const outcomeText = activation?.callable_now
+        ? `${existing ? "Updated" : "Registered"} and activated tool "${name}"`
+        : `Persisted tool "${name}"; current-session activation is unverified`;
     return {
         content: [
-            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
+            textContent(ExecutionOutput.formatToolText(`${outcomeText} (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
         ],
         details: {
+            active_tool: activation?.active_tool ?? false,
+            activation: activation?.activation ?? "unverified",
             args: cfg.args,
+            callable_now: activation?.callable_now ?? false,
             config: recipePath,
             defaults: cfg.defaults,
+            host_registered: activation?.host_registered ?? false,
+            persisted: true,
+            registry_active: tools.get(name) === cfg,
+            resolved: true,
             ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
             ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
             ...(cfg.template ? { template: cfg.template } : {}),
             ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
             tool: name,
+            validated: true,
         },
     };
 }

package/dist/lib/runtime.d.ts

@@ -6,6 +6,7 @@
 import { watch } from "node:fs";
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
+import type { RecipeResolutionContext } from "./recipes-context.ts";
 import * as ToolsLocal from "./tools-local.ts";
 export interface RuntimeContext {
     hasUI: boolean;
@@ -13,22 +14,46 @@ export interface RuntimeContext {
         notify(message: string, type?: "info" | "warning" | "error"): void;
     };
 }
+export interface RuntimeToolActivation {
+    active_tool: boolean;
+    activation: "current_session" | "unverified";
+    callable_now: boolean;
+    host_registered: boolean;
+}
 export interface ToolRegistryRuntimeDeps {
     configPath: string;
     exec: RegisteredToolExec;
-    packagedRecipeRoot?: string;
     recipeRoot?: string;
     getActiveTools?: () => string[];
+    getAllTools?: () => Array<{
+        name: string;
+    }>;
     registerTool: (definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>) => void;
     reservedToolNames: Set<string>;
     setActiveTools?: (toolNames: string[]) => void;
 }
+export interface RecipeRegistryStatus {
+    active_tool_count: number;
+    last_scan_counts: {
+        active: number;
+        rejected: number;
+        scanned: number;
+    };
+    last_scan_at?: string;
+    registry_generation: number;
+    resolution_generation?: string;
+    watch_status: "closed" | "failed" | "watching_parent" | "watching_root";
+    watched_root: string;
+}
 export interface ToolRegistryRuntime {
+    getStatus(): RecipeRegistryStatus;
+    getToolStatus(name: string): Record<string, unknown> | undefined;
     getToolNameBlocker(name: string): string | undefined;
     getTools(): Map<string, Config.RegisteredTool>;
-    loadTools(ctx: RuntimeContext): void;
+    loadTools(ctx: RuntimeContext, resolutionContext?: RecipeResolutionContext): void;
     notify(ctx: RuntimeContext, message: string, type: "info" | "warning" | "error"): void;
-    registerRuntimeTool(cfg: Config.RegisteredTool): void;
+    registerRuntimeTool(cfg: Config.RegisteredTool): RuntimeToolActivation;
+    setWatchStatus(status: RecipeRegistryStatus["watch_status"]): void;
 }
 export interface RecipeToolReloadWatcher {
     close(): void;
@@ -37,7 +62,8 @@ export interface RecipeToolReloadWatcher {
 export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): ToolRegistryRuntime;
 export interface RecipeToolReloadWatcherDeps {
     exists?: (path: string) => boolean;
+    getResolutionContext?: () => RecipeResolutionContext | undefined;
     recipeRoot?: string;
     watchPath?: typeof watch;
 }
-export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools">, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;
+export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools"> & Partial<Pick<ToolRegistryRuntime, "setWatchStatus">>, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;

package/dist/lib/runtime.js

@@ -7,11 +7,20 @@ import { existsSync, watch } from "node:fs";
 import { basename, dirname } from "node:path";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesUsage from "./recipes-usage.js";
 import * as ToolsLocal from "./tools-local.js";
 export function createAutoToolsRuntime(deps) {
     const tools = new Map();
     const runtimeToolFingerprints = new Map();
     const runtimeTools = new Set();
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    const status = {
+        active_tool_count: 0,
+        last_scan_counts: { active: 0, rejected: 0, scanned: 0 },
+        registry_generation: 0,
+        watch_status: "closed",
+        watched_root: recipeRoot,
+    };
     function notify(ctx, message, type) {
         if (ctx.hasUI)
             ctx.ui.notify(message, type);
@@ -44,13 +53,29 @@ export function createAutoToolsRuntime(deps) {
         const staleSet = new Set(stale);
         deps.setActiveTools(deps.getActiveTools().filter((name) => !staleSet.has(name)));
     }
+    function activationFor(name) {
+        const hostRegistered = deps.getAllTools?.().some((tool) => tool.name === name) ?? false;
+        const activeTool = deps.getActiveTools?.().includes(name) ?? false;
+        return {
+            active_tool: activeTool,
+            activation: hostRegistered && activeTool ? "current_session" : "unverified",
+            callable_now: hostRegistered && activeTool,
+            host_registered: hostRegistered,
+        };
+    }
     function registerRuntimeTool(cfg) {
         const fingerprint = getToolFingerprint(cfg);
-        if (runtimeToolFingerprints.get(cfg.name) === fingerprint)
-            return;
-        deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
-        runtimeTools.add(cfg.name);
-        runtimeToolFingerprints.set(cfg.name, fingerprint);
+        if (runtimeToolFingerprints.get(cfg.name) !== fingerprint) {
+            deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
+            runtimeTools.add(cfg.name);
+            runtimeToolFingerprints.set(cfg.name, fingerprint);
+        }
+        if (deps.getActiveTools && deps.setActiveTools) {
+            deps.setActiveTools([
+                ...new Set([...deps.getActiveTools(), cfg.name]),
+            ]);
+        }
+        return activationFor(cfg.name);
     }
     function isStartupActionableRegistryWarning(warning) {
         if (warning.includes(" shadows "))
@@ -69,7 +94,7 @@ export function createAutoToolsRuntime(deps) {
         const other = warnings.filter((warning) => !shadowed.includes(warning) && !skipped.includes(warning));
         const lines = ["pi-actors recipe registry warning"];
         if (shadowed.length > 0) {
-            lines.push("User recipes override packaged recipes:");
+            lines.push("User recipes shadow lower-priority user sources:");
             lines.push(...shadowed.map((warning) => `• ${warning}`));
         }
         if (skipped.length > 0) {
@@ -82,13 +107,15 @@ export function createAutoToolsRuntime(deps) {
         }
         return `${lines.join("\n")}\n`;
     }
-    function loadTools(ctx) {
+    function loadTools(ctx, resolutionContext) {
         const warnings = [];
-        const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-        const packagedRecipeRoot = deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot();
         const discovered = RecipesDiscovery.discoverRecipeSources([
-            { root: recipeRoot, defaultTool: true, mutableUsage: true },
-            { root: packagedRecipeRoot },
+            {
+                root: recipeRoot,
+                defaultTool: true,
+                mutableUsage: true,
+                resolutionContext,
+            },
         ]);
         warnings.push(...discovered.diagnostics);
         tools.clear();
@@ -111,17 +138,47 @@ export function createAutoToolsRuntime(deps) {
             }
             registerRuntimeTool(cfg);
         }
+        status.active_tool_count = tools.size;
+        status.last_scan_at = new Date().toISOString();
+        status.last_scan_counts = {
+            active: tools.size,
+            rejected: discovered.entries.filter((entry) => entry.invalid).length,
+            scanned: discovered.entries.length,
+        };
+        status.registry_generation += 1;
+        status.resolution_generation = resolutionContext?.generation;
         const startupWarnings = warnings.filter(isStartupActionableRegistryWarning);
         if (startupWarnings.length > 0) {
             notify(ctx, formatRecipeToolWarnings(startupWarnings), "warning");
         }
     }
     return {
+        getStatus: () => ({
+            ...status,
+            last_scan_counts: { ...status.last_scan_counts },
+        }),
+        getToolStatus: (name) => {
+            const cfg = tools.get(name);
+            if (!cfg)
+                return undefined;
+            const usage = cfg.sourcePath
+                ? RecipesUsage.readRecipeUsage(cfg.sourcePath)
+                : undefined;
+            return {
+                ...activationFor(name),
+                launch_kind: usage?.launch_kind,
+                spawn_calls: Number(usage?.spawn_calls ?? 0),
+                tool_calls: Number(usage?.tool_calls ?? 0),
+            };
+        },
         getToolNameBlocker,
         getTools: () => tools,
         loadTools,
         notify,
         registerRuntimeTool,
+        setWatchStatus: (watchStatus) => {
+            status.watch_status = watchStatus;
+        },
     };
 }
 export function createRecipeToolReloadWatcher(runtime, deps = {}) {
@@ -131,6 +188,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
     let rootWatcher;
     let parentWatcher;
     let failureNotified = false;
+    const setWatchStatus = (watchStatus) => runtime.setWatchStatus?.(watchStatus);
     const close = () => {
         const closingRoot = rootWatcher;
         rootWatcher = undefined;
@@ -141,11 +199,13 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = undefined;
+        setWatchStatus("closed");
     };
     const notifyFailure = (ctx) => {
         if (failureNotified)
             return;
         failureNotified = true;
+        setWatchStatus("failed");
         ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
     };
     const scheduleReload = (ctx) => {
@@ -153,7 +213,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = setTimeout(() => {
-            runtime.loadTools(ctx);
+            runtime.loadTools(ctx, deps.getResolutionContext?.());
             ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
         }, 150);
         reloadTimeout.unref?.();
@@ -183,6 +243,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
                 scheduleReload(ctx);
             });
             parentWatcher = watcher;
+            setWatchStatus("watching_parent");
             watcher.on("error", () => {
                 if (parentWatcher !== watcher)
                     return;
@@ -216,6 +277,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
                 scheduleReload(ctx);
             });
             rootWatcher = watcher;
+            setWatchStatus("watching_root");
             watcher.on("error", () => {
                 if (rootWatcher !== watcher)
                     return;

package/dist/lib/tools-inspect.d.ts

@@ -3,11 +3,13 @@
  * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
+import * as Runtime from "./runtime.ts";
 export interface InspectToolDeps<TContext = unknown> {
     getRunStatus?: (runOrDir: string) => Record<string, any>;
     getTool?: (name: string) => any | undefined;
+    getToolStatus?: (name: string) => Record<string, unknown> | undefined;
     listRuns?: () => Array<Record<string, any>>;
-    packagedRecipeRoot?: string;
     recipeRoot?: string;
+    registryStatus?: () => Runtime.RecipeRegistryStatus;
 }
 export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;

package/dist/lib/tools-inspect.js

@@ -4,7 +4,7 @@
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 import { statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as ControlProjection from "./control-projection.js";
 import * as Inspector from "./inspector.js";
@@ -157,7 +157,16 @@ function inspectRuntime(view, input, ctx, deps) {
         return runtimeTriage(ctx, deps);
     throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
 }
-function inspectRecipes(view, deps) {
+function portableSkillRecipePath(file, skill, namespaces) {
+    const root = namespaces[skill]?.[0];
+    if (!root)
+        return `<active-skill:${skill}>`;
+    const relation = relative(root, file);
+    return !relation.startsWith("..") && !isAbsolute(relation)
+        ? `<active-skill:${skill}>/${relation.replaceAll("\\", "/")}`
+        : `<active-skill:${skill}>`;
+}
+function inspectRecipes(view, deps, context) {
     if (view !== "status" &&
         view !== "summary" &&
         view !== "doctor" &&
@@ -171,17 +180,54 @@ function inspectRecipes(view, deps) {
     }
     const discovered = RecipesDiscovery.discoverRecipeSources([
         { root: recipeRoot, defaultTool: true, mutableUsage: true },
-        { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
     ]);
-    const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces();
+    const resolutionContext = context && typeof context === "object" && "recipeResolutionContext" in context
+        ? context.recipeResolutionContext
+        : undefined;
+    const activeSkillContext = resolutionContext?.activeSkills ??
+        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+    const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(activeSkillContext);
+    const skillInventory = RecipesReferences.inventoryActiveSkillRecipeComponents(activeSkillContext);
+    const skillRecipeComponents = skillInventory.components.map((component) => ({
+        identity: component.identity,
+        source_kind: "active_skill_component",
+        skill: component.skill,
+        stem: component.stem,
+        imports: component.imports,
+    }));
+    const skillRecipeComponentDiagnostics = skillInventory.rejected.map((diagnostic) => ({
+        error: diagnostic.reason,
+        ...(diagnostic.file
+            ? {
+                file: portableSkillRecipePath(diagnostic.file, diagnostic.skill, skillRecipeNamespaces),
+            }
+            : {}),
+        skill: diagnostic.skill,
+        ...(diagnostic.stem ? { stem: diagnostic.stem } : {}),
+    }));
+    const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
     const summary = {
-        ...RecipesDiscovery.summarizeDiscovery(discovered),
-        skill_recipe_namespaces: skillRecipeNamespaces,
+        ...discoverySummary,
+        ...(deps.registryStatus
+            ? {
+                ...deps.registryStatus(),
+                watched_root: "~/.pi/agent/recipes",
+            }
+            : {}),
+        active: Array.isArray(discoverySummary.active)
+            ? discoverySummary.active.map((entry) => ({
+                ...entry,
+                source_kind: "user_registry_capability",
+            }))
+            : discoverySummary.active,
+        skill_recipe_components: skillRecipeComponents,
+        skill_recipe_component_diagnostics: skillRecipeComponentDiagnostics,
+        skill_recipe_catalog_partial: skillInventory.partial,
+        active_skill_recipe_identities: Object.keys(skillRecipeNamespaces).sort(),
         skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
             .filter(([, roots]) => roots.length > 1)
-            .map(([name, roots]) => ({
+            .map(([name]) => ({
             name,
-            roots,
             error: `Ambiguous active Skill Recipe namespace ${name}`,
         })),
         drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
@@ -280,6 +326,7 @@ function inspectTool(name, view, deps) {
         throw new Error(`registered tool not found: ${name}`);
     return {
         name,
+        ...(view === "status" ? deps.getToolStatus?.(name) : {}),
         description: tool.description,
         parameters: tool.parameters,
         promptSnippet: tool.promptSnippet,
@@ -316,7 +363,7 @@ export function createInspectToolDefinition(deps = {}) {
                 details = inspectRuntime(view, input, ctx, deps);
             }
             else if (target === "recipes") {
-                details = inspectRecipes(view, deps);
+                details = inspectRecipes(view, deps, ctx);
             }
             else {
                 const run = parseRunTarget(target);

package/dist/lib/tools-local.d.ts

@@ -6,7 +6,9 @@
 import * as ModelContext from "./model-context.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
     cwd: string;
     sessionManager?: {
         getSessionId?: () => string;