@llblab/pi-actors 0.46.0 → 0.47.0

package/lib/runtime.ts

@@ -10,7 +10,10 @@ import { basename, dirname } from "node:path";
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
 import * as Paths from "./paths.ts";
+import type { RecipeResolutionContext } from "./recipes-context.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as RecipesUsage from "./recipes-usage.ts";
 import * as ToolsLocal from "./tools-local.ts";
 
 export interface RuntimeContext {
@@ -20,11 +23,19 @@ export interface RuntimeContext {
   };
 }
 
+export interface RuntimeToolActivation {
+  active_tool: boolean;
+  activation: "current_session" | "unverified";
+  callable_now: boolean;
+  host_registered: boolean;
+}
+
 export interface ToolRegistryRuntimeDeps {
   configPath: string;
   exec: RegisteredToolExec;
   recipeRoot?: string;
   getActiveTools?: () => string[];
+  getAllTools?: () => Array<{ name: string }>;
   registerTool: (
     definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>,
   ) => void;
@@ -32,16 +43,32 @@ export interface ToolRegistryRuntimeDeps {
   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 {
@@ -55,6 +82,14 @@ export function createAutoToolsRuntime(
   const tools = new Map<string, Config.RegisteredTool>();
   const runtimeToolFingerprints = new Map<string, string>();
   const runtimeTools = new Set<string>();
+  const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+  const status: RecipeRegistryStatus = {
+    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: RuntimeContext,
     message: string,
@@ -77,6 +112,25 @@ export function createAutoToolsRuntime(
       template: cfg.template,
     });
   }
+  function registeredToolSource(cfg: Config.RegisteredTool): string {
+    const raw = cfg.sourcePath
+      ? RecipesReferences.readRawRecipeConfig(cfg.sourcePath)
+      : undefined;
+    const template = raw?.template;
+    if (
+      typeof template === "string" &&
+      /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(template)
+    ) {
+      return template;
+    }
+    if (
+      typeof template === "string" &&
+      (template.endsWith(".json") || template.endsWith(".md"))
+    ) {
+      return `<explicit-file:${basename(template)}>`;
+    }
+    return "template";
+  }
   function deactivateMissingRuntimeTools(activeNames: Set<string>): void {
     const stale = [...runtimeTools].filter((name) => !activeNames.has(name));
     if (stale.length === 0) return;
@@ -90,12 +144,30 @@ export function createAutoToolsRuntime(
       deps.getActiveTools().filter((name) => !staleSet.has(name)),
     );
   }
-  function registerRuntimeTool(cfg: Config.RegisteredTool) {
+  function activationFor(name: string): RuntimeToolActivation {
+    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: Config.RegisteredTool): RuntimeToolActivation {
     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: string): boolean {
     if (warning.includes(" shadows ")) return false;
@@ -135,13 +207,21 @@ export function createAutoToolsRuntime(
       lines.push("Other registry diagnostics:");
       lines.push(...other.map((warning) => `• ${warning}`));
     }
+    lines.push("Next: inspect target=recipes view=doctor");
     return `${lines.join("\n")}\n`;
   }
-  function loadTools(ctx: RuntimeContext) {
+  function loadTools(
+    ctx: RuntimeContext,
+    resolutionContext?: RecipeResolutionContext,
+  ) {
     const warnings: string[] = [];
-    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
     const discovered = RecipesDiscovery.discoverRecipeSources([
-      { root: recipeRoot, defaultTool: true, mutableUsage: true },
+      {
+        root: recipeRoot,
+        defaultTool: true,
+        mutableUsage: true,
+        resolutionContext,
+      },
     ]);
     warnings.push(...discovered.diagnostics);
     tools.clear();
@@ -164,28 +244,77 @@ export function createAutoToolsRuntime(
       }
       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;
+      const activation = activationFor(name);
+      const args = RecipesDiscovery.summarizeRegisteredToolArgs(cfg);
+      return {
+        ...activation,
+        activation_boundary: activation.callable_now
+          ? "current_session"
+          : !activation.host_registered
+            ? "host_registration"
+            : "active_tool_set",
+        persisted: Boolean(cfg.sourcePath),
+        registry_active: true,
+        source: registeredToolSource(cfg),
+        required_args: args.required,
+        optional_args: args.optional,
+        next_actions: activation.callable_now
+          ? [`call tool ${name}`]
+          : [
+              `register_tool name=${name} update=true`,
+              `inspect target=tool:${name} view=status`,
+            ],
+        ...(usage?.launch_kind ? { 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 interface RecipeToolReloadWatcherDeps {
   exists?: (path: string) => boolean;
+  getResolutionContext?: () => RecipeResolutionContext | undefined;
   recipeRoot?: string;
   watchPath?: typeof watch;
 }
 
 export function createRecipeToolReloadWatcher(
-  runtime: Pick<ToolRegistryRuntime, "loadTools">,
+  runtime: Pick<ToolRegistryRuntime, "loadTools"> &
+    Partial<Pick<ToolRegistryRuntime, "setWatchStatus">>,
   deps: RecipeToolReloadWatcherDeps = {},
 ): RecipeToolReloadWatcher {
   const pathExists = deps.exists ?? existsSync;
@@ -194,6 +323,8 @@ export function createRecipeToolReloadWatcher(
   let rootWatcher: FSWatcher | undefined;
   let parentWatcher: FSWatcher | undefined;
   let failureNotified = false;
+  const setWatchStatus = (watchStatus: RecipeRegistryStatus["watch_status"]): void =>
+    runtime.setWatchStatus?.(watchStatus);
   const close = (): void => {
     const closingRoot = rootWatcher;
     rootWatcher = undefined;
@@ -203,10 +334,12 @@ export function createRecipeToolReloadWatcher(
     closingParent?.close();
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = undefined;
+    setWatchStatus("closed");
   };
   const notifyFailure = (ctx: RuntimeContext): void => {
     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",
@@ -216,7 +349,7 @@ export function createRecipeToolReloadWatcher(
     failureNotified = false;
     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?.();
@@ -245,6 +378,7 @@ export function createRecipeToolReloadWatcher(
         scheduleReload(ctx);
       });
       parentWatcher = watcher;
+      setWatchStatus("watching_parent");
       watcher.on("error", () => {
         if (parentWatcher !== watcher) return;
         parentWatcher = undefined;
@@ -274,6 +408,7 @@ export function createRecipeToolReloadWatcher(
         scheduleReload(ctx);
       });
       rootWatcher = watcher;
+      setWatchStatus("watching_root");
       watcher.on("error", () => {
         if (rootWatcher !== watcher) return;
         rootWatcher = undefined;

package/lib/tools-inspect.ts

@@ -4,8 +4,8 @@
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 
-import { statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as ControlProjection from "./control-projection.ts";
@@ -13,12 +13,14 @@ import * as Inspector from "./inspector.ts";
 import * as Limits from "./limits.ts";
 import { computeRunControlCapacity } from "./run-evidence-policy.ts";
 import * as Paths from "./paths.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
 import * as RunsTrace from "./runs-trace.ts";
+import * as Runtime from "./runtime.ts";
 import * as RuntimeIdentity from "./runtime-identity.ts";
 import * as RuntimeTriage from "./runtime-triage.ts";
 import * as Schema from "./schema.ts";
@@ -32,8 +34,10 @@ const maybeJsonText = ToolsResponse.maybeJsonText;
 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>>;
   recipeRoot?: string;
+  registryStatus?: () => Runtime.RecipeRegistryStatus;
 }
 
 function runtimeStatus(): Record<string, unknown> {
@@ -191,8 +195,148 @@ function inspectRuntime(
   throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
 }
 
+function portableSkillRecipePath(
+  file: string,
+  skill: string,
+  namespaces: Record<string, string[]>,
+): string {
+  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 portableSkillRecipeDiagnosticReason(
+  diagnostic: RecipesReferences.SkillRecipeComponentDiagnostic,
+  namespaces: Record<string, string[]>,
+): string {
+  let reason = diagnostic.reason;
+  if (diagnostic.file) {
+    reason = reason.replaceAll(
+      diagnostic.file,
+      portableSkillRecipePath(
+        diagnostic.file,
+        diagnostic.skill,
+        namespaces,
+      ),
+    );
+  }
+  for (const root of namespaces[diagnostic.skill] ?? []) {
+    reason = reason.replaceAll(root, `<active-skill:${diagnostic.skill}>`);
+  }
+  return reason;
+}
+
+function inspectRecipeIdentity(
+  identity: string,
+  resolutionContext: RecipeResolution.RecipeResolutionContext | undefined,
+  namespaces: Record<string, string[]>,
+  inventory: RecipesReferences.SkillRecipeComponentInventory,
+  registryStatus: Runtime.RecipeRegistryStatus | undefined,
+): Record<string, unknown> {
+  const match = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.exec(identity);
+  const skill = match?.[1] ?? "";
+  const roots = skill ? namespaces[skill] ?? [] : [];
+  const skillActive = roots.length === 1;
+  const matchingComponent = inventory.components.find(
+    (component) => component.identity === identity,
+  );
+  const matchingRejection = inventory.rejected.find(
+    (diagnostic) =>
+      diagnostic.skill === skill &&
+      (diagnostic.stem === undefined || diagnostic.stem === match?.[2]),
+  );
+  let sourceLocation: string | undefined;
+  let rejectedReason: string | undefined;
+  let resolvable = false;
+  if (!match) {
+    rejectedReason =
+      "Identity must use canonical <skill>/<recipe> syntax.";
+  } else if (roots.length === 0) {
+    rejectedReason = `Active Skill Recipe not found: ${identity}`;
+  } else if (roots.length > 1) {
+    rejectedReason = matchingRejection
+      ? portableSkillRecipeDiagnosticReason(matchingRejection, namespaces)
+      : `Duplicate active Skill identity ${skill}`;
+  } else if (matchingRejection) {
+    rejectedReason = portableSkillRecipeDiagnosticReason(
+      matchingRejection,
+      namespaces,
+    );
+    if (matchingRejection.file) {
+      sourceLocation = portableSkillRecipePath(
+        matchingRejection.file,
+        skill,
+        namespaces,
+      );
+    }
+  } else {
+    try {
+      const file = RecipesReferences.resolveRecipeReferencePath(
+        identity,
+        resolutionContext?.cwd,
+        resolutionContext?.activeSkills,
+      );
+      if (!file || !existsSync(file)) {
+        rejectedReason = `Skill Recipe component not found: ${identity}`;
+      } else {
+        sourceLocation = portableSkillRecipePath(file, skill, namespaces);
+        const recipe = RecipesReferences.readResolvedRecipeConfig(file, [], {
+          skillContext: resolutionContext?.activeSkills,
+        });
+        if (recipe) resolvable = true;
+        else {
+          rejectedReason =
+            RecipesReferences.diagnoseRawRecipeConfigFailure(file) ??
+            `Recipe could not be resolved: ${identity}`;
+        }
+      }
+    } catch (error) {
+      rejectedReason = error instanceof Error ? error.message : String(error);
+    }
+  }
+  const componentStatus = resolvable
+    ? "available"
+    : !match
+      ? "invalid_identity"
+      : roots.length === 0
+        ? "skill_inactive"
+        : roots.length > 1
+          ? "ambiguous_skill"
+          : matchingRejection
+            ? "rejected"
+            : matchingComponent
+              ? "unresolvable"
+              : "missing";
+  return {
+    identity,
+    skill_active: skillActive,
+    resolvable,
+    catalog_partial: inventory.partial,
+    component_status: componentStatus,
+    ...(sourceLocation ? { source_location: sourceLocation } : {}),
+    resolution_generation:
+      resolutionContext?.generation ?? registryStatus?.resolution_generation ?? "unavailable",
+    ...(rejectedReason ? { rejected_reason: rejectedReason } : {}),
+    next_actions: resolvable
+      ? [
+          `spawn recipe=${identity}`,
+          `register_tool name=<tool-name> from=${identity}`,
+        ]
+      : roots.length === 0 && skill
+        ? [
+            `activate Skill ${skill}`,
+            `inspect target=recipes view=doctor identity=${identity}`,
+          ]
+        : ["inspect target=recipes view=imports verbose=true"],
+  };
+}
+
 function inspectRecipes(
   view: string,
+  input: Record<string, unknown>,
   deps: InspectToolDeps,
   context: unknown,
 ): Record<string, unknown> {
@@ -214,37 +358,70 @@ function inspectRecipes(
   const discovered = RecipesDiscovery.discoverRecipeSources([
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
   ]);
-  const skillContext =
-    context && typeof context === "object" && "activeSkillRecipeContext" in context
+  const resolutionContext =
+    context && typeof context === "object" && "recipeResolutionContext" in context
       ? (context as {
-          activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
-        }).activeSkillRecipeContext
+          recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
+        }).recipeResolutionContext
       : undefined;
   const activeSkillContext =
-    skillContext ?? RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+    resolutionContext?.activeSkills ??
+    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
   const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(
     activeSkillContext,
   );
-  let skillRecipeComponents: Array<Record<string, unknown>> = [];
-  const skillRecipeComponentDiagnostics: Array<Record<string, unknown>> = [];
-  try {
-    skillRecipeComponents = RecipesReferences.listActiveSkillRecipeComponents(
-      activeSkillContext,
-    ).map((component) => ({
-      identity: component.identity,
-      source_kind: "active_skill_component",
-      skill: component.skill,
-      stem: component.stem,
-      imports: component.imports,
-    }));
-  } catch (error) {
-    skillRecipeComponentDiagnostics.push({
-      error: error instanceof Error ? error.message : String(error),
-    });
+  const skillInventory =
+    RecipesReferences.inventoryActiveSkillRecipeComponents(activeSkillContext);
+  const registryStatus = deps.registryStatus?.();
+  const identity =
+    typeof input.identity === "string" ? input.identity.trim() : "";
+  if (identity && view !== "doctor") {
+    throw new Error("inspect recipes identity is supported only with view=doctor.");
+  }
+  if (view === "doctor" && identity) {
+    return inspectRecipeIdentity(
+      identity,
+      resolutionContext,
+      skillRecipeNamespaces,
+      skillInventory,
+      registryStatus,
+    );
   }
+  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: portableSkillRecipeDiagnosticReason(
+        diagnostic,
+        skillRecipeNamespaces,
+      ),
+      ...(diagnostic.file
+        ? {
+            file: portableSkillRecipePath(
+              diagnostic.file,
+              diagnostic.skill,
+              skillRecipeNamespaces,
+            ),
+          }
+        : {}),
+      skill: diagnostic.skill,
+      ...(diagnostic.stem ? { stem: diagnostic.stem } : {}),
+    }),
+  );
   const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
   const summary = {
     ...discoverySummary,
+    ...(registryStatus
+      ? {
+          ...registryStatus,
+          watched_root: "~/.pi/agent/recipes",
+        }
+      : {}),
     active: Array.isArray(discoverySummary.active)
       ? discoverySummary.active.map((entry) => ({
           ...(entry as Record<string, unknown>),
@@ -253,6 +430,7 @@ function inspectRecipes(
       : 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)
@@ -366,18 +544,63 @@ function inspectTool(
     throw new Error("inspect tool:<name> supports view=status or view=schema.");
   }
   const tool = deps.getTool?.(name);
-  if (!tool) throw new Error(`registered tool not found: ${name}`);
+  const status = deps.getToolStatus?.(name);
+  if (!tool && !status) {
+    throw new Error(
+      `Registered tool not found: ${name}. Next: inspect target=recipes view=doctor; do not substitute spawn for tool invocation.`,
+    );
+  }
+  if (view === "schema" && !tool) {
+    throw new Error(
+      `Tool "${name}" is registered but its callable schema is unavailable; callable_now=${String(status?.callable_now ?? false)}, activation_boundary=${String(status?.activation_boundary ?? "host_registration")}. Next: inspect target=tool:${name} view=status.`,
+    );
+  }
   return {
     name,
-    description: tool.description,
-    parameters: tool.parameters,
-    promptSnippet: tool.promptSnippet,
+    ...(view === "status" ? status : {}),
+    ...(tool
+      ? {
+          description: tool.description,
+          parameters: tool.parameters,
+          promptSnippet: tool.promptSnippet,
+        }
+      : {}),
   };
 }
 
 function compactResult(target: string, view: string, details: Record<string, unknown>): string {
   if (target === "runtime") return compactRuntime(view, details);
+  if (target === "recipes" && typeof details.identity === "string") {
+    const lines = [
+      `recipes doctor identity=${details.identity} skill_active=${String(details.skill_active)} resolvable=${String(details.resolvable)} catalog_partial=${String(details.catalog_partial)} component_status=${String(details.component_status)}`,
+      ...(details.source_location
+        ? [`source=${String(details.source_location)}`]
+        : []),
+      `resolution_generation=${String(details.resolution_generation)}`,
+      ...(details.rejected_reason
+        ? [`rejected_reason=${String(details.rejected_reason)}`]
+        : []),
+      ...((details.next_actions as unknown[] | undefined) ?? []).map(
+        (action) => `next=${String(action)}`,
+      ),
+    ];
+    return `\n${lines.join("\n")}`;
+  }
   if (target === "recipes") return ToolsResponse.compactRecipeRegistry(details);
+  if (target.startsWith("tool:") && view === "status") {
+    const required = Array.isArray(details.required_args)
+      ? details.required_args.map(String).join(",") || "none"
+      : "unknown";
+    const optional = Array.isArray(details.optional_args)
+      ? details.optional_args.map(String).join(",") || "none"
+      : "unknown";
+    const next = Array.isArray(details.next_actions) && details.next_actions.length > 0
+      ? String(details.next_actions[0])
+      : details.callable_now === true
+        ? `call tool ${target.slice(5)}`
+        : `register_tool name=${target.slice(5)} update=true`;
+    return `\ntool=${target.slice(5)} source=${String(details.source ?? "unknown")} callable_now=${String(details.callable_now ?? false)} activation_boundary=${String(details.activation_boundary ?? "unknown")} required=${required} optional=${optional} launch_kind=${String(details.launch_kind ?? "none")} spawn_calls=${Number(details.spawn_calls ?? 0)} tool_calls=${Number(details.tool_calls ?? 0)} next=${next}`;
+  }
   if (target.startsWith("tool:")) return `\ntool=${target.slice(5)} view=${view}`;
   return `\nrun=${target.slice(4)} view=${view}`;
 }
@@ -392,6 +615,9 @@ export function createInspectToolDefinition<TContext = unknown>(
       "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",
     parameters: Schema.objectSchema(
       {
+        identity: Schema.stringSchema(
+          "Optional canonical <skill>/<recipe> identity for focused Recipe doctor diagnosis.",
+        ),
         lines: Schema.stringSchema("Bounded item count for Trace or recent Controls."),
         source: Schema.stringSchema(
           "Optional Trace source: all, lifecycle, control, process, agent, artifact, or runtime.",
@@ -419,7 +645,7 @@ export function createInspectToolDefinition<TContext = unknown>(
       if (target === "runtime") {
         details = inspectRuntime(view, input, ctx, deps);
       } else if (target === "recipes") {
-        details = inspectRecipes(view, deps, ctx);
+        details = inspectRecipes(view, input, deps, ctx);
       } else {
         const run = parseRunTarget(target);
         if (run) details = inspectRun(run, view, input, ctx, deps);