@llblab/pi-actors 0.44.0 → 0.45.0

package/dist/lib/tools-local.js

@@ -45,11 +45,16 @@ function shouldAddRuntimeToolUsageHint(error) {
 }
 function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
     const optional = cfg.args.filter((arg) => !required.includes(arg));
+    const exampleDefaults = {
+        ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+        ...cfg.defaults,
+        ...(cfg.recipe?.values ?? {}),
+    };
     const example = {};
     for (const arg of required)
-        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
     for (const arg of optional)
-        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
     if (includeRunId)
         example.run_id = `${cfg.name}-1`;
     const lines = [
@@ -62,6 +67,21 @@ function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
         lines.push(`Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`);
     return lines.join("\n");
 }
+function resolveRecipeToolValues(cfg, callerValues, ctx) {
+    const recipeRuntimeValues = {
+        ...(cfg.recipe?.recipe_dir
+            ? { recipe_dir: cfg.recipe.recipe_dir }
+            : {}),
+        ...(cfg.recipe?.skill_dir ? { skill_dir: cfg.recipe.skill_dir } : {}),
+    };
+    return Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues({
+        ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+        ...cfg.defaults,
+        ...(cfg.recipe?.values ?? {}),
+        ...callerValues,
+        ...recipeRuntimeValues,
+    }, ctx), cfg.argTypes);
+}
 function formatRuntimeToolArgumentError(cfg, error, required, includeRunId) {
     const message = error instanceof Error ? error.message : String(error);
     if (!shouldAddRuntimeToolUsageHint(error))
@@ -87,8 +107,10 @@ export function createRuntimeToolDefinition(cfg, exec) {
             defaults: cfg.defaults,
             template: requiredTemplate,
         };
+    const recipeInlineDefaults = Schema.getExplicitToolArgDefaults(cfg.recipe?.args);
     const requiredArgs = isRecipe && cfg.storedArgs !== undefined
-        ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+        ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg) &&
+            !Object.hasOwn(recipeInlineDefaults, arg)))
         : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
             ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
             : Schema.getRequiredToolArgNames(requiredTemplateConfig);
@@ -137,7 +159,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                         run_id: runId,
                         tool: cfg.name,
                         policy_values: ModelContext.withCurrentModelValues({ ...(cfg.recipe?.values ?? {}), ...values }, ctx),
-                        values: Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues({ ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values }, ctx), cfg.argTypes),
+                        values: resolveRecipeToolValues(cfg, values, ctx),
                     }, ctx.cwd);
                     return {
                         content: [
@@ -150,12 +172,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                     };
                 }
                 if (isRecipe && recipeTemplate) {
-                    const paramsWithDefaults = ModelContext.withCurrentModelValues({
-                        ...(cfg.recipe?.values ?? {}),
-                        ...cfg.defaults,
-                        ...params,
-                    }, ctx);
-                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes), exec, ctx.cwd, signal);
+                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, resolveRecipeToolValues(cfg, params, ctx), exec, ctx.cwd, signal);
                 }
                 return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues(params, ctx), cfg.argTypes), exec, ctx.cwd, signal);
             }

package/dist/lib/tools-spawn.js

@@ -90,8 +90,8 @@ export function createSpawnToolDefinition() {
         parameters: Schema.objectSchema({
             artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned Run."),
             as: Schema.stringSchema("Optional Run identity in exact run:<id> form."),
-            file: Schema.stringSchema("Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes."),
-            recipe: Schema.stringSchema("Alias for file; template recipe JSON file/name to spawn."),
+            file: Schema.stringSchema("Optional template Recipe reference. Supports paths, bare user/adjacent/std names, std:<name>, and skill:<skill>/<recipe>."),
+            recipe: Schema.stringSchema("Alias for file; qualified Skill/std or ordinary Recipe reference to spawn."),
             template: Schema.unionSchema([
                 Schema.stringSchema("Inline command template string"),
                 Schema.arraySchema("Inline command-template sequence or parallel tree"),

package/dist/scripts/release-gates.mjs

@@ -198,7 +198,7 @@ try {
   );
   console.log("[release] zero-warning Recipe QA gate checked");
 
-  const maximumShippedLines = 29_598;
+  const maximumShippedLines = 29_767;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))

package/dist/skills/actors/SKILL.md

@@ -25,11 +25,11 @@ A Run target exposes exactly three inspect views: `recipe`, `trace`, and `contro
 
 ## Recipe
 
-A Recipe defines execution. It may declare args, defaults, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained packaged Recipes over ad hoc wrappers. Use `std:<recipe>` for exact packaged lookup and `skill:<skill>/<recipe-path>` for a component bundled with a Pi-active Skill. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace
 

package/docs/command-templates.md

@@ -53,7 +53,7 @@ Common object fields:
 - `concurrency`: Optional positive integer cap for a `parallel: true` node. Omit it to launch all children at once.
 - `min_successful`: Optional non-negative integer evidence threshold for a `parallel: true` node. Usable branches are successful branches with non-empty stdout; joins include a `parallel_status` header when this is set.
 - `when`: Optional node guard. A false guard skips the node; strings may be `flag`, `!flag`, or `{flag?yes:no}` style expressions.
-- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `request_timeout:int=60000` before persistence.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. `name:type=value` is an optional argument with an inline fallback. Hosts reject duplicate names and conflicting declared/placeholder types rather than selecting one silently.
 - `defaults`: Placeholder default values by name.
 - `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely. Numeric control fields may be literal numbers or placeholders such as `"{timeout_ms}"`.
 - `delay`: Optional wait in milliseconds before starting this node. Default is no delay. It may be a literal number or placeholder.
@@ -104,7 +104,7 @@ With runtime values `{ "text": "hello" }`, argv is:
 ["--text", "hello", "--lang", "ru", "--rate", "+30%"]
 ```
 
-Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+Use `defaults` for visible fallback configuration, `values` for composition binding, and inline defaults for compact local literals. Named resolution uses caller values before composition values, explicit defaults, and inline defaults; the final selected value is type/enum validated. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
 Use `{env??dev}` for fallback values and `{all?--all:}` to map boolean args to optional text.
 

package/docs/recipe-library.md

@@ -45,6 +45,8 @@ Subagent components provide reusable command-template cells for normalization, p
 
 Imports compose these definitions inside one parent Run. They are not independently addressable peers. Parent template flags control sequencing, parallelism, retries, failure scope, recovery, and repeated execution.
 
+Packaged components can be selected exactly as `std:<recipe-name>`. Recipes bundled under a Pi-active Skill are selected as `skill:<skill-name>/<recipe-path>` and receive runtime-owned `{skill_dir}` plus `{recipe_dir}`. Active Skill components are namespaced library entries, never automatic tools; expose one intentionally through a user Recipe wrapper when a direct tool is desired.
+
 ## Utility Recipes
 
 Utilities wrap deterministic local capabilities such as:

package/docs/template-recipes.md

@@ -44,7 +44,7 @@ Fences marked `template`, `command-template`, `json`, or `recipe` can define exe
 Common Recipe fields:
 
 - `name`, `description`, `disabled`;
-- `args`, typed arg declarations, and `defaults`;
+- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
 - `imports` with optional binding defaults/values;
 - `template`;
 - `async`;
@@ -71,7 +71,9 @@ Common Recipe fields:
 }
 ```
 
-Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Resolution enforces Recipe-root priority, file-size/depth bounds, and cycle rejection.
+Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
+
+Bare references preserve user → adjacent → packaged resolution. `std:<name>` selects a packaged Recipe exactly. `skill:<skill-name>/<recipe-path>` selects a component under the `recipes/` tree of a Skill currently active through Pi resource discovery. Skill Recipes never become tools merely by existing, and duplicate active Skill names fail as ambiguous rather than shadowing silently.
 
 Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
 
@@ -102,9 +104,13 @@ Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters
 
 Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
 
+## File Origins
+
+Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+
 ## Context and Provenance
 
-File-backed Runs capture Recipe context records for the entry and imports. The captured bundle explains composition identity and remains generation-local evidence. It does not override the authored task prompt.
+File-backed Runs capture Recipe context records for the entry and imports, including qualified `std:` or `skill:` identity when applicable. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
 
 Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
 
@@ -125,7 +131,7 @@ Resolution fails before launch when required current policy is unavailable. The
 
 ## Resolution and Shadowing
 
-User Recipes under `~/.pi/agent/recipes` take priority over packaged Recipes. An invalid active file blocks fallback and reports both paths. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+User Recipes under `~/.pi/agent/recipes` take priority over adjacent and packaged Recipes for compatible bare lookup. Exact `std:` and `skill:` references bypass that ambiguous space. The active Skill namespace converges from Pi's loaded Skill metadata on startup/reload; pi-actors does not scan ambient Skill roots independently. An invalid active file blocks fallback and reports both paths. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
 
 ## Validation
 

package/docs/tool-registry.md

@@ -61,7 +61,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Wrapping Existing Recipes
 
-Prefer a small user-root wrapper that imports a maintained packaged or skill-owned Recipe by path and delegates by alias. Do not duplicate its executable template, defaults, Control declaration, or artifacts. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Prefer a small user-root wrapper that imports a maintained Recipe by exact `std:<recipe>` or `skill:<skill>/<recipe-path>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/index.ts

@@ -11,6 +11,7 @@ import * as InspectorCommand from "./lib/inspector-command.ts";
 import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Prompts from "./lib/prompts.ts";
+import * as RecipesReferences from "./lib/recipes-references.ts";
 import * as RunUiRuntime from "./lib/run-ui-runtime.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Temp from "./lib/temp.ts";
@@ -98,9 +99,14 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     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<Pi.ExtensionContext>({

package/lib/async-runs.ts

@@ -33,6 +33,7 @@ import {
 import * as Paths from "./paths.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
+import * as Schema from "./schema.ts";
 import {
   resolveArtifactManifest,
   resolveArtifactPaths,
@@ -128,6 +129,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;
@@ -309,7 +312,14 @@ function resolveStartParams(params: AsyncRunStartParams): AsyncRunStartParams {
       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 } : {}),
+    },
   };
 }
 
@@ -477,13 +487,37 @@ export function startRun(
     !isAbsolute(recipeRelation)
       ? dirname(packagedRecipeRoot)
       : undefined;
-  const values = {
-    ...(packagedRepo ? { repo: packagedRepo } : {}),
-    ...(startParams.values || {}),
-    run_id: run,
-    state_dir: stateDir,
-    trace_file: join(stateDir, "trace.jsonl"),
-  };
+  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,
@@ -557,7 +591,7 @@ export function startRun(
       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/lib/config.ts

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

package/lib/inspector.ts

@@ -105,9 +105,22 @@ export function readActorInspectorRecipe(
   const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
     SessionEvidence.redactSessionEvidenceValue(
       Object.fromEntries(
-        Object.entries(value).filter(([, entry]) => entry !== undefined),
+        Object.entries(value).filter(
+          ([key, entry]) =>
+            entry !== undefined &&
+            key !== "recipe_dir" &&
+            key !== "skill_dir",
+        ),
       ),
     ) as Record<string, unknown>;
+  const launchValues =
+    meta.values && typeof meta.values === "object" && !Array.isArray(meta.values)
+      ? Object.fromEntries(
+          Object.entries(meta.values as Record<string, unknown>).filter(
+            ([key]) => key !== "recipe_dir" && key !== "skill_dir",
+          ),
+        )
+      : meta.values;
   return {
     composition: contexts.map((entry) =>
       redactedRecord({
@@ -116,6 +129,7 @@ export function readActorInspectorRecipe(
         file: entry.file,
         import_path: entry.import_path,
         name: entry.name,
+        qualified_name: entry.qualified_name,
       }),
     ),
     ...(definition ? { definition: redactedRecord(definition) } : {}),
@@ -129,7 +143,7 @@ export function readActorInspectorRecipe(
     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/lib/recipes-discovery.ts

@@ -122,6 +122,25 @@ function getRecipeCommandTemplateConfig(
     : config) as CommandTemplates.CommandTemplateConfig;
 }
 
+function getRecipeDiagnosticTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateObjectConfig {
+  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: string,
   config: TemplateRecipeConfig | undefined,
@@ -131,7 +150,7 @@ function getRecipeConfigDiagnostics(
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
   return CommandTemplates.getCommandTemplateWarnings(
-    getRecipeCommandTemplateConfig(config),
+    getRecipeDiagnosticTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
@@ -141,7 +160,7 @@ function getRecipeRiskLabels(
   if (!config) return [];
   const labels = new Set(
     CommandTemplates.getCommandTemplateRiskLabels(
-      getRecipeCommandTemplateConfig(config),
+      getRecipeDiagnosticTemplateConfig(config),
     ),
   );
   if (config.async === true) labels.add("risk.long_running");
@@ -846,9 +865,10 @@ export function toRegisteredTool(
   assertToolSafeRepeatConfig(
     argTemplateConfig,
     explicitArgTypes,
-    cfg.defaults ?? {},
+    { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) },
   );
   const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
   return {
     name: entry.id,
     description,