@llblab/pi-actors 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.45.0: Skill Recipe Standard Library
+
+- `Recipe Values`: Makes inline argument defaults optional, applies caller > values > defaults > inline precedence across tools, Runs, imports, and delegation, and validates final typed/enum values plus duplicate, unknown-default, and conflicting-type declarations.
+- `Recipe Origins`: Gives file-backed Recipes immutable `{recipe_dir}` and active-Skill Recipes `{skill_dir}` across templates, defaults, artifacts, tools, and Runs while retaining local provenance and hiding machine-local origins from model-facing launch values.
+- `Skill Recipe Library`: Adds exact `std:<name>` and Pi-active `skill:<skill>/<path>` component lookup for imports, delegation, spawn, validation, Inspect diagnostics, captured qualified identity, and installed dist without automatically registering Skill Recipes as tools.
+- `Validation`: Covers source, composed async execution, installed dist, namespace collisions/reload, path redaction, and migrated Skill wrappers while resetting the shipped-line ceiling to the validated 29,767-line release tree.
+
 ## 0.44.0: Bounded Run Evidence
 
 - `Trace`: Bounds each Run to 2,048 events and 4 MiB, atomically retaining the newest suffix with one cumulative `runtime.trace_compacted` marker so discarded history is explicit while terminal, result, execution, and artifact evidence remains authoritative.

package/README.md

@@ -84,7 +84,7 @@ Persist a trusted command template or Recipe-backed capability under `~/.pi/agen
 
 Recipes can declare:
 
-- args and typed defaults;
+- named typed args, inline fallbacks, configuration `defaults`, and composition `values`;
 - imports and command-template composition;
 - retry, failure, recovery, repeat, concurrency, and timeout policy;
 - artifact paths;
@@ -103,6 +103,8 @@ Example controlled Recipe:
 
 Ordinary one-shot Recipes should omit `control`. Recipe imports compose definitions inside one Run; they do not create peer actors.
 
+File-backed Recipes receive immutable `{recipe_dir}`; Recipes under a Pi-active Skill also receive `{skill_dir}`. Use `std:<recipe>` for an exact packaged component and `skill:<skill>/<recipe-path>` for an exact active-Skill component. Skill Recipes are namespaced reusable components and do not become tools automatically.
+
 String command-template leaves execute directly without shell interpretation. Use template arrays for sequencing or an explicit trusted shell/script when shell semantics matter.
 
 ## Trace

package/dist/index.js

@@ -10,6 +10,7 @@ import * as InspectorCommand from "./lib/inspector-command.js";
 import * as Paths from "./lib/paths.js";
 import * as Pi from "./lib/pi.js";
 import * as Prompts from "./lib/prompts.js";
+import * as RecipesReferences from "./lib/recipes-references.js";
 import * as RunUiRuntime from "./lib/run-ui-runtime.js";
 import * as Runtime from "./lib/runtime.js";
 import * as Temp from "./lib/temp.js";
@@ -99,9 +100,12 @@ export default function toolRegistryExtension(pi) {
         runUiRuntime.shutdown(event.reason, ctx);
     });
     InspectorCommand.registerActorInspectorCommand(pi, getRunOwnerId);
-    pi.on("before_agent_start", async (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
-    }));
+    pi.on("before_agent_start", async (event) => {
+        RecipesReferences.setActiveSkillRecipeSources(event.systemPromptOptions.skills ?? []);
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
+        };
+    });
     Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),

package/dist/lib/async-runs.d.ts

@@ -38,6 +38,8 @@ export interface AsyncRunStartParams {
     template?: CommandTemplateValue;
     args?: string[];
     defaults?: Record<string, unknown>;
+    recipe_dir?: string;
+    skill_dir?: string;
     parallel?: boolean;
     concurrency?: number | string;
     min_successful?: number | string;

package/dist/lib/async-runs.js

@@ -12,6 +12,7 @@ import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPol
 import * as Paths from "./paths.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as RecipesUsage from "./recipes-usage.js";
+import * as Schema from "./schema.js";
 import { resolveArtifactPaths, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } from "./runs-control.js";
@@ -151,7 +152,14 @@ function resolveStartParams(params) {
             fileParams.run_id ||
             fileParams.name ||
             getRunIdFromFile(fileParams.file),
-        values: { ...(fileParams.values ?? {}), ...(params.values ?? {}) },
+        values: {
+            ...(fileParams.values ?? {}),
+            ...(params.values ?? {}),
+            ...(fileParams.recipe_dir
+                ? { recipe_dir: fileParams.recipe_dir }
+                : {}),
+            ...(fileParams.skill_dir ? { skill_dir: fileParams.skill_dir } : {}),
+        },
     };
 }
 function readJson(path) {
@@ -249,13 +257,34 @@ export function startRun(params, cwd) {
         !isAbsolute(recipeRelation)
         ? dirname(packagedRecipeRoot)
         : undefined;
-    const values = {
+    const argSpec = Schema.parseToolArgDeclarationList(startParams.args ?? []);
+    if (argSpec.error)
+        throw new Error(argSpec.error);
+    const declaredArgs = new Set(argSpec.args);
+    for (const key of Object.keys(startParams.defaults ?? {})) {
+        if (declaredArgs.size > 0 && !declaredArgs.has(key))
+            throw new Error(`Unknown Recipe default argument: ${key}`);
+    }
+    const values = Schema.normalizeRuntimeValues({
+        ...argSpec.defaults,
+        ...(startParams.defaults || {}),
         ...(packagedRepo ? { repo: packagedRepo } : {}),
         ...(startParams.values || {}),
         run_id: run,
         state_dir: stateDir,
         trace_file: join(stateDir, "trace.jsonl"),
-    };
+    }, argSpec.argTypes);
+    const runtimeTemplate = resolved.template &&
+        typeof resolved.template === "object" &&
+        !Array.isArray(resolved.template)
+        ? {
+            ...resolved.template,
+            defaults: {
+                ...(resolved.template.defaults ?? {}),
+                ...values,
+            },
+        }
+        : resolved.template;
     const modelPolicy = describeCurrentPolicyProvenance({
         defaults: startParams.defaults,
         template: resolved.template,
@@ -312,7 +341,7 @@ export function startRun(params, cwd) {
             state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
-            template: resolved.template,
+            template: runtimeTemplate,
             values,
             model_policy: modelPolicy,
             ...(artifacts ? { artifacts } : {}),

package/dist/lib/config.js

@@ -149,6 +149,7 @@ export function normalizeStoredTool(key, value, reservedToolNames) {
             template: argTemplate,
         };
     const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+    Schema.assertCompatibleToolArgTypes(inferredArgTypes, declarations.argTypes);
     const argTypes = { ...inferredArgTypes, ...declarations.argTypes };
     const cfg = {
         name,

package/dist/lib/inspector.js

@@ -56,7 +56,12 @@ export function readActorInspectorRecipe(stateDir) {
         !Array.isArray(primary.recipe)
         ? primary.recipe
         : undefined;
-    const redactedRecord = (value) => SessionEvidence.redactSessionEvidenceValue(Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)));
+    const redactedRecord = (value) => SessionEvidence.redactSessionEvidenceValue(Object.fromEntries(Object.entries(value).filter(([key, entry]) => entry !== undefined &&
+        key !== "recipe_dir" &&
+        key !== "skill_dir")));
+    const launchValues = meta.values && typeof meta.values === "object" && !Array.isArray(meta.values)
+        ? Object.fromEntries(Object.entries(meta.values).filter(([key]) => key !== "recipe_dir" && key !== "skill_dir"))
+        : meta.values;
     return {
         composition: contexts.map((entry) => redactedRecord({
             ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
@@ -64,6 +69,7 @@ export function readActorInspectorRecipe(stateDir) {
             file: entry.file,
             import_path: entry.import_path,
             name: entry.name,
+            qualified_name: entry.qualified_name,
         })),
         ...(definition ? { definition: redactedRecord(definition) } : {}),
         diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
@@ -76,7 +82,7 @@ export function readActorInspectorRecipe(stateDir) {
         launch: redactedRecord({
             cwd: meta.cwd,
             template: meta.template,
-            values: meta.values,
+            values: launchValues,
             model_policy: meta.model_policy,
             control: meta.control,
             artifacts: meta.artifacts,

package/dist/lib/recipes-discovery.js

@@ -53,17 +53,33 @@ function getRecipeCommandTemplateConfig(config) {
         ? config.template
         : config);
 }
+function getRecipeDiagnosticTemplateConfig(config) {
+    const templateConfig = getRecipeCommandTemplateConfig(config);
+    return typeof templateConfig === "object" && !Array.isArray(templateConfig)
+        ? {
+            ...templateConfig,
+            defaults: {
+                ...(templateConfig.defaults ?? {}),
+                ...(config.defaults ?? {}),
+                ...(config.values ?? {}),
+            },
+        }
+        : {
+            defaults: { ...(config.defaults ?? {}), ...(config.values ?? {}) },
+            template: templateConfig,
+        };
+}
 function getRecipeConfigDiagnostics(file, config) {
     if (!config) {
         const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
         return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
     }
-    return CommandTemplates.getCommandTemplateWarnings(getRecipeCommandTemplateConfig(config)).map((warning) => `Recipe ${file}: ${warning}`);
+    return CommandTemplates.getCommandTemplateWarnings(getRecipeDiagnosticTemplateConfig(config)).map((warning) => `Recipe ${file}: ${warning}`);
 }
 function getRecipeRiskLabels(config) {
     if (!config)
         return [];
-    const labels = new Set(CommandTemplates.getCommandTemplateRiskLabels(getRecipeCommandTemplateConfig(config)));
+    const labels = new Set(CommandTemplates.getCommandTemplateRiskLabels(getRecipeDiagnosticTemplateConfig(config)));
     if (config.async === true)
         labels.add("risk.long_running");
     return [
@@ -652,8 +668,9 @@ export function toRegisteredTool(entry) {
         const parsed = Schema.parseToolArgToken(String(arg));
         return [parsed.arg, parsed.type];
     }));
-    assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, cfg.defaults ?? {});
+    assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) });
     const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+    Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
     return {
         name: entry.id,
         description,

package/dist/lib/recipes-references.d.ts

@@ -40,6 +40,8 @@ export interface TemplateRecipeDefinition {
 }
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
     async?: boolean;
+    recipe_dir?: string;
+    skill_dir?: string;
 }
 export interface TemplateRecipeContextRecord {
     alias?: string;
@@ -47,12 +49,20 @@ export interface TemplateRecipeContextRecord {
     file: string;
     import_path: string[];
     name: string;
+    qualified_name?: string;
     recipe: Record<string, unknown>;
     role: "entry" | "import";
 }
 export interface ReadResolvedRecipeConfigOptions {
     includeActorRecipeContext?: boolean;
 }
+export interface ActiveSkillRecipeSource {
+    name: string;
+    filePath?: string;
+    baseDir?: string;
+}
+export declare function setActiveSkillRecipeSources(skills: ActiveSkillRecipeSource[]): void;
+export declare function getActiveSkillRecipeNamespaces(): Record<string, string[]>;
 export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
 export declare function resolveRecipeReferencePath(value: unknown, currentRecipeRoot?: string): string | undefined;
 export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;

package/dist/lib/recipes-references.js

@@ -5,15 +5,106 @@
  */
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, extname, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as RecipeControl from "./recipe-control.js";
+import * as Schema from "./schema.js";
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
+const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
+const activeSkillRecipeRoots = new Map();
+export function setActiveSkillRecipeSources(skills) {
+    activeSkillRecipeRoots.clear();
+    for (const skill of skills) {
+        const name = skill.name.trim();
+        const skillDir = skill.baseDir
+            ? resolve(skill.baseDir)
+            : skill.filePath
+                ? dirname(resolve(skill.filePath))
+                : undefined;
+        if (!name || !skillDir)
+            continue;
+        const roots = activeSkillRecipeRoots.get(name) ?? new Set();
+        roots.add(resolve(skillDir, "recipes"));
+        activeSkillRecipeRoots.set(name, roots);
+    }
+}
+export function getActiveSkillRecipeNamespaces() {
+    return Object.fromEntries([...activeSkillRecipeRoots.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, roots]) => [name, [...roots].sort()]));
+}
+function qualifiedRecipeNameForFile(file) {
+    const path = resolve(file);
+    const stdRelation = relative(Paths.getPackagedRecipeRoot(), path);
+    if (stdRelation &&
+        !stdRelation.startsWith("..") &&
+        !isAbsolute(stdRelation)) {
+        return `std:${stdRelation.replace(/\.(?:json|md)$/u, "")}`;
+    }
+    for (const [skillName, roots] of activeSkillRecipeRoots) {
+        if (roots.size !== 1)
+            continue;
+        const root = [...roots][0];
+        const relation = relative(root, path);
+        if (relation && !relation.startsWith("..") && !isAbsolute(relation))
+            return `skill:${skillName}/${relation.replaceAll("\\", "/").replace(/\.(?:json|md)$/u, "")}`;
+    }
+    return undefined;
+}
+function qualifiedRecipeCandidates(value) {
+    if (value.startsWith("std:")) {
+        return recipeNameFiles(value.slice(4)).map((file) => resolve(Paths.getPackagedRecipeRoot(), file));
+    }
+    if (!value.startsWith("skill:"))
+        return undefined;
+    const qualified = value.slice(6);
+    const separator = qualified.indexOf("/");
+    if (separator <= 0 || separator === qualified.length - 1)
+        throw new Error(`Invalid Skill Recipe reference: ${value}`);
+    const skillName = qualified.slice(0, separator);
+    const recipeName = qualified.slice(separator + 1);
+    const roots = [...(activeSkillRecipeRoots.get(skillName) ?? [])];
+    if (roots.length === 0)
+        throw new Error(`Active Skill Recipe namespace not found: ${skillName}`);
+    if (roots.length > 1)
+        throw new Error(`Ambiguous active Skill Recipe namespace ${skillName}: ${roots.join(", ")}`);
+    const root = roots[0];
+    return recipeNameFiles(recipeName).map((file) => {
+        const candidate = resolve(root, file);
+        const relation = relative(root, candidate);
+        if (!relation || relation.startsWith("..") || isAbsolute(relation))
+            throw new Error(`Skill Recipe reference escapes its recipes root: ${value}`);
+        return candidate;
+    });
+}
 function hasWhitespace(value) {
     return /\s/.test(value);
 }
+function findOwningSkillDir(recipeFile) {
+    let current = dirname(recipeFile);
+    while (true) {
+        if (existsSync(resolve(current, "SKILL.md")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function assertRuntimeRecipeValuesNotDeclared(raw) {
+    const args = Array.isArray(raw.args)
+        ? Schema.getExplicitToolArgNames(raw.args.map(String))
+        : [];
+    for (const name of RUNTIME_RECIPE_VALUE_NAMES) {
+        if (args.includes(name) ||
+            (isRecord(raw.defaults) && Object.hasOwn(raw.defaults, name)) ||
+            (isRecord(raw.values) && Object.hasOwn(raw.values, name))) {
+            throw new Error(`Recipe runtime value is reserved: ${name}`);
+        }
+    }
+}
 export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
     const trimmed = value.trim();
     const repoRoot = resolve(recipeRoot, "..");
@@ -42,6 +133,9 @@ function recipeNameFiles(value) {
     return [`${trimmed}.json`, `${trimmed}.md`];
 }
 function recipeCandidatePaths(value, currentRecipeRoot) {
+    const qualified = qualifiedRecipeCandidates(value.trim());
+    if (qualified)
+        return qualified;
     if (!isBareRecipeName(value))
         return [resolveRecipePath(value, currentRecipeRoot)];
     const roots = [
@@ -495,11 +589,46 @@ function mergeDefaults(...items) {
     const merged = Object.assign({}, ...items.filter(Boolean));
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
+function assertRecipeDefaultsDeclared(args, defaults, label) {
+    const spec = Schema.parseToolArgDeclarationList(args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    if (spec.args.length === 0)
+        return;
+    const declared = new Set(spec.args);
+    for (const key of Object.keys(defaults ?? {})) {
+        if (!declared.has(key))
+            throw new Error(`Unknown ${label} argument: ${key}`);
+    }
+}
+function assertRecipeArgumentContract(config, label = "Recipe default") {
+    assertRecipeDefaultsDeclared(config.args, config.defaults, label);
+    const spec = Schema.parseToolArgDeclarationList(config.args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    Schema.assertCompatibleToolArgTypes(spec.argTypes, Schema.getTemplateArgTypes({ template: config.template }));
+    const staticValues = Object.fromEntries(Object.entries({ ...config.defaults, ...config.values }).filter(([, value]) => typeof value !== "string" || !/\{[^{}]+\}/.test(value)));
+    Schema.normalizeRuntimeValues(staticValues, spec.argTypes);
+}
+function resolveRecipeValueLayers(args, ...layers) {
+    const spec = Schema.parseToolArgDeclarationList(args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    const merged = mergeDefaults(spec.defaults, ...layers);
+    if (!merged)
+        return undefined;
+    const staticValues = Object.fromEntries(Object.entries(merged).filter(([, value]) => typeof value !== "string" || !/\{[^{}]+\}/.test(value)));
+    return {
+        ...merged,
+        ...Schema.normalizeRuntimeValues(staticValues, spec.argTypes),
+    };
+}
 function applyDefaultsToTemplate(template, defaults, overrides) {
     const cleanOverrides = { ...overrides };
     delete cleanOverrides.name;
     delete cleanOverrides.template;
     delete cleanOverrides.values;
+    delete cleanOverrides.defaults;
     if (typeof template === "object" && !Array.isArray(template)) {
         return {
             ...template,
@@ -537,7 +666,15 @@ function loadDelegatedRecipe(value, currentRecipeFile, stack, options) {
     return config;
 }
 function applyDelegatedRecipeToNode(delegated, overrides = {}) {
-    return applyDefaultsToTemplate(delegated.template, delegated.values, overrides);
+    const nodeDefaults = isRecord(overrides.defaults)
+        ? overrides.defaults
+        : undefined;
+    const nodeValues = isRecord(overrides.values) ? overrides.values : undefined;
+    const values = resolveRecipeValueLayers(delegated.args, delegated.defaults, delegated.values, nodeDefaults, nodeValues, {
+        ...(delegated.recipe_dir ? { recipe_dir: delegated.recipe_dir } : {}),
+        ...(delegated.skill_dir ? { skill_dir: delegated.skill_dir } : {}),
+    });
+    return applyDefaultsToTemplate(delegated.template, values, overrides);
 }
 function expandRecipeDelegations(value, currentRecipeFile, stack, options = {}) {
     if (typeof value === "string") {
@@ -593,7 +730,7 @@ function expandImportNodes(value, imports, options = {}) {
             ? record.defaults
             : undefined;
         const nodeValues = isRecord(record.values) ? record.values : undefined;
-        const defaults = mergeDefaults(imported.defaults, imported.values, nodeDefaults, nodeValues);
+        const defaults = resolveRecipeValueLayers(imported.config.args, imported.defaults, imported.values, nodeDefaults, nodeValues);
         const expanded = applyDefaultsToTemplate(imported.config.template, defaults, record);
         return options.includeActorRecipeContext
             ? withActorRecipeContext(expanded, {
@@ -631,6 +768,8 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     if (!raw || !Object.hasOwn(raw, "template"))
         return undefined;
     RecipeControl.assertRecipeHasNoMailbox(raw);
+    assertRuntimeRecipeValuesNotDeclared(raw);
+    assertRecipeArgumentContract(raw);
     const imports = {};
     for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
         const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
@@ -639,13 +778,18 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             throw new Error(`Recipe import not found: ${alias}`);
         const bindingDefaults = typeof binding === "string" ? undefined : binding.defaults;
         const bindingValues = typeof binding === "string" ? undefined : binding.values;
+        assertRecipeDefaultsDeclared(config.args, bindingDefaults, `Recipe import ${alias} default`);
         imports[alias] = {
             alias,
             file: importPath,
             name: config.name ?? alias,
             config,
             defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
-            values: { ...(bindingValues ?? {}) },
+            values: {
+                ...(bindingValues ?? {}),
+                ...(config.recipe_dir ? { recipe_dir: config.recipe_dir } : {}),
+                ...(config.skill_dir ? { skill_dir: config.skill_dir } : {}),
+            },
         };
     }
     const substituted = substituteImportRefs(raw, imports);
@@ -661,6 +805,17 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             : {})
         : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
     const recipeName = getRecipeIdFromPath(path);
+    const recipeDir = dirname(path);
+    const skillDir = findOwningSkillDir(path);
+    if (!skillDir &&
+        JSON.stringify({
+            artifacts: substituted.artifacts,
+            defaults: substituted.defaults,
+            template: substituted.template,
+            values: substituted.values,
+        }).includes("{skill_dir}")) {
+        throw new Error(`Recipe uses {skill_dir} outside an owning Skill directory: ${path}`);
+    }
     const templateWithContext = options.includeActorRecipeContext
         ? withActorRecipeContext(expandedTemplate, {
             file: path,
@@ -678,6 +833,8 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         : delegated?.control);
     return {
         name: recipeName,
+        recipe_dir: recipeDir,
+        ...(skillDir ? { skill_dir: skillDir } : {}),
         ...(typeof substituted.description === "string" &&
             substituted.description.trim()
             ? { description: substituted.description.trim() }
@@ -765,7 +922,11 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         ...(typeof substituted.repeat === "number"
             ? { repeat: substituted.repeat }
             : {}),
-        ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+        values: {
+            ...(isRecord(substituted.values) ? substituted.values : {}),
+            recipe_dir: recipeDir,
+            ...(skillDir ? { skill_dir: skillDir } : {}),
+        },
         ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
     };
 }
@@ -780,12 +941,14 @@ function collectRecipeContextRecords(file, stack, importPath, alias) {
     const raw = readRawRecipeConfig(path);
     if (!raw || !Object.hasOwn(raw, "template"))
         return [];
+    const qualifiedName = qualifiedRecipeNameForFile(path);
     const record = {
         ...(alias ? { alias } : {}),
         depth: stack.length,
         file: path,
         import_path: importPath,
         name: getRecipeIdFromPath(path),
+        ...(qualifiedName ? { qualified_name: qualifiedName } : {}),
         recipe: raw,
         role: stack.length === 0 ? "entry" : "import",
     };

package/dist/lib/schema.d.ts

@@ -44,14 +44,17 @@ export declare function objectSchema(properties: Record<string, JsonSchema>, req
 export declare function looseObjectSchema(description: string): JsonSchema;
 export declare function parseToolArgToken(value: string): ParsedToolArgToken;
 export declare function parseToolArgDeclarations(value: string): ToolArgSpec;
+export declare function parseToolArgDeclarationList(value: unknown[]): ToolArgSpec;
 export declare function normalizeStoredToolArgDeclarations(argsValue: unknown, defaultsValue: unknown): ToolArgSpec & {
     changed: boolean;
     provided: boolean;
 };
 export declare function formatToolArgs(args: string[]): string;
 export declare function getTemplatePlaceholderNames(config: CommandTemplates.CommandTemplateConfig): string[];
+export declare function assertCompatibleToolArgTypes(...sources: Array<Record<string, ToolArgType> | undefined>): void;
 export declare function getTemplateArgTypes(config: CommandTemplates.CommandTemplateConfig): Record<string, ToolArgType>;
 export declare function getExplicitToolArgNames(args: string[] | undefined): string[];
+export declare function getExplicitToolArgDefaults(args: string[] | string | undefined): Record<string, string>;
 export declare function getToolArgNames(config: CommandTemplates.CommandTemplateConfig): string[];
 export declare function getRequiredToolArgNames(config: CommandTemplates.CommandTemplateConfig): Set<string>;
 export declare function normalizeRuntimeValues(values: Record<string, unknown>, argTypes: Record<string, ToolArgType> | undefined): Record<string, unknown>;

package/dist/lib/schema.js

@@ -147,7 +147,10 @@ function isValidDefault(type, value) {
     }
 }
 export function parseToolArgDeclarations(value) {
-    const source = splitArgDeclarations(value);
+    return parseToolArgDeclarationList(splitArgDeclarations(value));
+}
+export function parseToolArgDeclarationList(value) {
+    const source = value.map(String);
     const seen = new Set();
     const duplicates = new Set();
     const args = [];
@@ -272,6 +275,8 @@ function collectCommandTemplateConfigDeclarations(config, declarations) {
         collectTemplatePlaceholderDeclarations(config, declarations);
         return;
     }
+    if (!config || typeof config !== "object")
+        return;
     if (Array.isArray(config)) {
         for (const step of config)
             collectCommandTemplateConfigDeclarations(step, declarations);
@@ -296,9 +301,30 @@ function getTemplatePlaceholderDeclarations(config) {
 export function getTemplatePlaceholderNames(config) {
     return mergeUnique(getTemplatePlaceholderDeclarations(config).map((item) => item.arg));
 }
+function toolArgTypesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function assertCompatibleToolArgTypes(...sources) {
+    const seen = {};
+    for (const source of sources) {
+        for (const [name, type] of Object.entries(source ?? {})) {
+            const previous = seen[name];
+            if (previous && !toolArgTypesEqual(previous, type)) {
+                throw new Error(`Conflicting argument type for ${name}: ${canonicalArgDeclaration(name, previous)} vs ${canonicalArgDeclaration(name, type)}`);
+            }
+            seen[name] = type;
+        }
+    }
+}
 export function getTemplateArgTypes(config) {
     const argTypes = {};
     for (const declaration of getTemplatePlaceholderDeclarations(config)) {
+        const previous = argTypes[declaration.arg];
+        if (previous &&
+            declaration.type.kind !== "string" &&
+            !toolArgTypesEqual(previous, declaration.type)) {
+            throw new Error(`Conflicting argument type for ${declaration.arg}: ${canonicalArgDeclaration(declaration.arg, previous)} vs ${declaration.declaration}`);
+        }
         if (declaration.type.kind !== "string")
             argTypes[declaration.arg] = declaration.type;
     }
@@ -307,6 +333,13 @@ export function getTemplateArgTypes(config) {
 export function getExplicitToolArgNames(args) {
     return mergeUnique((args ?? []).map((item) => parseToolArgToken(String(item)).arg));
 }
+export function getExplicitToolArgDefaults(args) {
+    const declarations = typeof args === "string" ? splitArgDeclarations(args) : (args ?? []);
+    return Object.fromEntries(declarations
+        .map((item) => parseToolArgToken(String(item)))
+        .filter((item) => item.defaultValue !== undefined)
+        .map((item) => [item.arg, item.defaultValue]));
+}
 export function getToolArgNames(config) {
     const normalizedConfig = CommandTemplates.normalizeCommandTemplateConfig(config);
     const declaredArgs = Array.isArray(normalizedConfig.args)

package/dist/lib/tools-inspect.js

@@ -12,6 +12,7 @@ import * as Limits from "./limits.js";
 import { computeRunControlCapacity } from "./run-evidence-policy.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as ReviewDiagnostics from "./review-diagnostics.js";
 import * as RunsControls from "./runs-controls.js";
 import * as RunControlDelivery from "./runs-control-delivery.js";
@@ -172,8 +173,17 @@ function inspectRecipes(view, deps) {
         { root: recipeRoot, defaultTool: true, mutableUsage: true },
         { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
     ]);
+    const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces();
     const summary = {
         ...RecipesDiscovery.summarizeDiscovery(discovered),
+        skill_recipe_namespaces: skillRecipeNamespaces,
+        skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
+            .filter(([, roots]) => roots.length > 1)
+            .map(([name, roots]) => ({
+            name,
+            roots,
+            error: `Ambiguous active Skill Recipe namespace ${name}`,
+        })),
         drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
     };
     return {