@llblab/pi-actors 0.48.0 → 0.48.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.48.1: Persistent Skill Composition
+
+- `Persistent Skill Composition`: Made `register_tool from=<skill>/<recipe>` use Pi's authoritative active-session Skill snapshot across every admitted Skill location and activate synchronous or asynchronous tools from the resolved effective contract. Compact user Recipes retain logical delegation without copied contracts, absolute helper paths, symlinks, or ambient runtime re-resolution.
+
 ## 0.48.0: Host-Coordinated Swarms
 
 - `Coordinator And Swarm Methodology`: Defined gatewayless host coordination with companion transports as presence only; the coordinator accepts declarative outcomes, creates explicit Runs, stays available, and owns integration/final validation. Reasoning is role-allocated: bounded authors default off, independent reviewers/integrators use medium, and the coordinator selects evidence-worthy fanout. Swarm retains overhead admission, disjoint ownership, isolation, mutation freeze, and event/timer observation.

package/dist/lib/extension-runtime.js

@@ -127,6 +127,9 @@ export function createActorExtensionRuntime(pi) {
             Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
                 configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
                 getActiveTools: () => pi.getActiveTools(),
+                getRecipeResolutionContext: () => activeRunContext
+                    ? getRecipeResolutionContext(activeRunContext)
+                    : undefined,
                 getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
                 getRuntimeToolStatus: runtime.getToolStatus,
                 handleRuntimeControl: automaticReview.handleControl,

package/dist/lib/registry.d.ts

@@ -5,6 +5,7 @@
  */
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
+import * as RecipesContext from "./recipes-context.ts";
 export interface RegisterToolInput {
     name?: string;
     description?: string;
@@ -55,6 +56,7 @@ export interface RegisterToolRuntimeDeps<TContext> {
     recipeRoot?: string;
     getToolNameBlocker: (name: string) => string | undefined;
     getTools: () => Map<string, Config.RegisteredTool>;
+    getRecipeResolutionContext?: () => RecipesContext.RecipeResolutionContext | undefined;
     getActiveTools: () => string[];
     notify: (ctx: TContext, message: string, type: "info" | "warning" | "error") => void;
     registerRuntimeTool: (cfg: Config.RegisteredTool) => RuntimeActivation | void;

package/dist/lib/registry.js

@@ -233,9 +233,10 @@ function getInputTemplate(value) {
     throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
 }
 function getRegistrationResolutionContext(ctx, deps) {
-    if (ctx &&
-        typeof ctx === "object" &&
-        "recipeResolutionContext" in ctx) {
+    const runtimeContext = deps.getRecipeResolutionContext?.();
+    if (runtimeContext)
+        return runtimeContext;
+    if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
         const resolutionContext = ctx.recipeResolutionContext;
         if (resolutionContext)
             return resolutionContext;
@@ -415,15 +416,18 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     let persisted = false;
     let activation;
     let cfg;
+    let transactionStage = "persist";
     try {
         persistToolRecipe(deps, name, authoredRecipe);
         persisted = true;
+        transactionStage = "persisted_admission";
         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);
+        transactionStage = "runtime_activation";
         activation = deps.registerRuntimeTool(cfg) ?? undefined;
         if (activation &&
             (!activation.host_registered ||
@@ -447,7 +451,7 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
             tools.delete(name);
         }
         deps.setActiveTools(activeBefore);
-        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`));
+        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`));
     }
     deps.notify(ctx, `Tool activated: ${name}`, "info");
     const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)

package/dist/lib/tools-local.js

@@ -93,8 +93,9 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const paramSchema = {};
     const required = [];
     const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
-    const isAsyncRecipe = cfg.recipe?.async === true ||
-        RecipesReferences.isAsyncRecipeReference(cfg.template);
+    const isAsyncRecipe = cfg.recipe
+        ? cfg.recipe.async === true
+        : RecipesReferences.isAsyncRecipeReference(cfg.template);
     const recipeTemplate = cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
     const requiredTemplate = recipeTemplate ?? cfg.template;
     const requiredTemplateConfig = typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
@@ -112,7 +113,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const requiredArgs = isRecipe && cfg.storedArgs !== undefined
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg) &&
             !Object.hasOwn(recipeInlineDefaults, arg)))
-        : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+        : !cfg.recipe && RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
             ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
             : Schema.getRequiredToolArgNames(requiredTemplateConfig);
     for (const arg of cfg.args) {

package/dist/lib/tools.d.ts

@@ -14,6 +14,7 @@ export interface ActorToolDefinition {
 export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext> {
     configPath: string;
     getActiveTools: () => string[];
+    getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
     getRuntimeTool: (name: string) => unknown;
     getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;

package/dist/lib/tools.js

@@ -30,6 +30,7 @@ export function createCoreActorToolDefinitions(deps) {
             getActiveTools: deps.getActiveTools,
             getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
             getTools: deps.registryRuntime.getTools,
+            getRecipeResolutionContext: deps.getRecipeResolutionContext,
             notify: deps.registryRuntime.notify,
             registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
             reservedToolNames: RESERVED_TOOL_NAMES,

package/dist/skills/actors/SKILL.md

@@ -52,7 +52,7 @@ direct delegation ≠ named import composition
 Run Control ≠ actor chat
 ```
 
-A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool` creates or updates a persistent user tool. A tool is callable in the current session only when activation evidence says `callable_now: true`.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 

package/dist/skills/actors/references/persistent-tools.md

@@ -28,6 +28,8 @@ register_tool
 
 `from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
 
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
 ## Prove registration

package/docs/tool-registry.md

@@ -73,7 +73,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Specializing Existing Recipes
 
-Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. The stored user Recipe remains compact direct delegation; it does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. Pi supplies one authoritative active-session Skill snapshot across global, project, package, settings, CLI, and extension-contributed locations. Registration resolves the source from that snapshot, stores only the logical direct-delegation reference plus caller specialization, and activates the tool from the already-resolved effective contract without ambient re-resolution. It does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`; symlinks and absolute helper paths are not substitutes. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/lib/extension-runtime.ts

@@ -160,6 +160,10 @@ export function createActorExtensionRuntime(
         Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
           configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
           getActiveTools: () => pi.getActiveTools(),
+          getRecipeResolutionContext: () =>
+            activeRunContext
+              ? getRecipeResolutionContext(activeRunContext)
+              : undefined,
           getRuntimeTool: (name) =>
             Tools.resolveActiveRuntimeTool(
               name,

package/lib/registry.ts

@@ -73,6 +73,7 @@ export interface RegisterToolRuntimeDeps<TContext> {
   recipeRoot?: string;
   getToolNameBlocker: (name: string) => string | undefined;
   getTools: () => Map<string, Config.RegisteredTool>;
+  getRecipeResolutionContext?: () => RecipesContext.RecipeResolutionContext | undefined;
   getActiveTools: () => string[];
   notify: (
     ctx: TContext,
@@ -422,11 +423,9 @@ function getRegistrationResolutionContext<TContext>(
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
 ): RecipesContext.RecipeResolutionContext {
-  if (
-    ctx &&
-    typeof ctx === "object" &&
-    "recipeResolutionContext" in ctx
-  ) {
+  const runtimeContext = deps.getRecipeResolutionContext?.();
+  if (runtimeContext) return runtimeContext;
+  if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
     const resolutionContext = (ctx as {
       recipeResolutionContext?: RecipesContext.RecipeResolutionContext;
     }).recipeResolutionContext;
@@ -697,9 +696,11 @@ function executeRegisterToolUnlocked<TContext>(
   let persisted = false;
   let activation: RuntimeActivation | undefined;
   let cfg: Config.RegisteredTool;
+  let transactionStage = "persist";
   try {
     persistToolRecipe(deps, name, authoredRecipe);
     persisted = true;
+    transactionStage = "persisted_admission";
     const admitted = RecipesDiscovery.admitUserRecipe(
       recipePath,
       resolutionContext,
@@ -711,6 +712,7 @@ function executeRegisterToolUnlocked<TContext>(
     }
     cfg = admitted.tool;
     tools.set(name, cfg);
+    transactionStage = "runtime_activation";
     activation = deps.registerRuntimeTool(cfg) ?? undefined;
     if (
       activation &&
@@ -737,7 +739,7 @@ function executeRegisterToolUnlocked<TContext>(
     deps.setActiveTools(activeBefore);
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`,
       ),
     );
   }

package/lib/tools-local.ts

@@ -147,9 +147,9 @@ export function createRuntimeToolDefinition(
   const paramSchema: Record<string, JsonSchema> = {};
   const required: string[] = [];
   const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
-  const isAsyncRecipe =
-    cfg.recipe?.async === true ||
-    RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const isAsyncRecipe = cfg.recipe
+    ? cfg.recipe.async === true
+    : RecipesReferences.isAsyncRecipeReference(cfg.template);
   const recipeTemplate =
     cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
   const requiredTemplate = recipeTemplate ?? cfg.template!;
@@ -177,7 +177,7 @@ export function createRuntimeToolDefinition(
               !Object.hasOwn(recipeInlineDefaults, arg),
           ),
         )
-      : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+      : !cfg.recipe && RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
   for (const arg of cfg.args) {

package/lib/tools.ts

@@ -24,6 +24,7 @@ export interface CoreActorToolDefinitionDeps<
 > {
   configPath: string;
   getActiveTools: () => string[];
+  getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
   getRuntimeTool: (name: string) => unknown;
   getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
   handleRuntimeControl?: (
@@ -68,6 +69,7 @@ export function createCoreActorToolDefinitions<
       getActiveTools: deps.getActiveTools,
       getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
       getTools: deps.registryRuntime.getTools,
+      getRecipeResolutionContext: deps.getRecipeResolutionContext,
       notify: deps.registryRuntime.notify,
       registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
       reservedToolNames: RESERVED_TOOL_NAMES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.48.0",
+  "version": "0.48.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -52,7 +52,7 @@ direct delegation ≠ named import composition
 Run Control ≠ actor chat
 ```
 
-A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool` creates or updates a persistent user tool. A tool is callable in the current session only when activation evidence says `callable_now: true`.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 

package/skills/actors/references/persistent-tools.md

@@ -28,6 +28,8 @@ register_tool
 
 `from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
 
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
 ## Prove registration