@llblab/pi-actors 0.57.0 → 0.58.0

package/lib/prompts.ts

@@ -7,15 +7,18 @@
 export const REGISTER_TOOL_DESCRIPTION =
   "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
   "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+  "Set expose=false to retain a new template/from Recipe without tool activation. " +
   "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
 
 export const REGISTER_TOOL_PROMPT_SNIPPET =
-  "Register persistent Recipes or command templates as agent-callable tools";
+  "Persist command templates or Recipes with register_tool; use expose=false to retain without tool activation";
 
 export const REGISTER_TOOL_GUIDELINES = [
   "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
   "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
-  "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
+  "Use register_tool expose=false to retain a new named template/from Recipe without activation; update, delete and draft promotion are unsupported in this mode.",
+  "A register_tool retained_recipe receipt with activation=not_requested is deliberate retention, not failed activation; reuse its exact Recipe path through spawn.",
+  "When register_tool requests tool exposure, trust callable_now and activation; persistence alone is not callability.",
   'Set template=null or template="" in register_tool to delete a persisted tool.',
   "Set update=true in register_tool to overwrite an existing tool registration.",
 ];
@@ -42,6 +45,8 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
   draft:
     "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
+  expose:
+    "Set false to retain a new named template/from Recipe in recipes/library without registering or activating a tool. Default true preserves ordinary tool registration. Retained update, delete and draft promotion are unsupported.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
   template:

package/lib/recipes-discovery.ts

@@ -756,6 +756,32 @@ function templatePreview(value: unknown): string | undefined {
     : rendered;
 }
 
+export function inventoryRetainedRecipes(
+  recipeRoot: string,
+  resolutionContext?: RecipeResolutionContext,
+): { recipes: Array<Record<string, unknown>>; diagnostics: string[] } {
+  const discovery = discoverRecipeSources([
+    { root: join(recipeRoot, "library"), resolutionContext },
+  ]);
+  return {
+    recipes: [...discovery.active.values()]
+      .map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        source_kind: "user_retained_recipe",
+        tool: false,
+        invalid: entry.invalid,
+        disabled: entry.disabled,
+        ...(entry.config ? { async: entry.config.async === true } : {}),
+        ...(entry.config?.description ? { description: entry.config.description } : {}),
+        ...(entry.diagnostics.length ? { diagnostics: entry.diagnostics } : {}),
+        ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    diagnostics: discovery.diagnostics,
+  };
+}
+
 export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
     for (let attempt = 0; attempt < 3; attempt += 1) {

package/lib/recipes-references.ts

@@ -16,7 +16,7 @@ import * as Paths from "./paths.ts";
 import * as RecipeControl from "./recipe-control.ts";
 import * as Schema from "./schema.ts";
 
-const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
+export const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
 
 export interface TemplateRecipeImportBinding {

package/lib/recipes-usage.ts

@@ -101,7 +101,7 @@ function readRecipeSource(path: string): { fingerprint: string } | undefined {
 
 function inferRecipeRoot(path: string): string {
   const parent = dirname(resolve(path));
-  return basename(parent) === "drafts" ? dirname(parent) : parent;
+  return ["drafts", "library"].includes(basename(parent)) ? dirname(parent) : parent;
 }
 
 function pathKey(path: string, recipeRoot: string): string {
@@ -112,8 +112,9 @@ function pathKey(path: string, recipeRoot: string): string {
   return relation.replaceAll("\\", "/");
 }
 
-function recipeName(path: string): string {
-  return basename(path).replace(/\.(?:json|md)$/u, "");
+function recipeName(path: string, recipeRoot: string): string {
+  const name = basename(path).replace(/\.(?:json|md)$/u, "");
+  return dirname(resolve(path)) === resolve(recipeRoot, "library") ? `library/${name}` : name;
 }
 
 function lineageFilename(lineageName: string): string {
@@ -232,8 +233,10 @@ function findRelocatedRecipe(
   index: RecipeUsageIndex,
   fingerprint: string,
   recipeRoot: string,
+  newPath: string,
 ): { indexedName: string; path: string; record: RecipeUsageRecord } | undefined {
   const candidates = Object.entries(index.paths).flatMap(([oldPath, indexedName]) => {
+    if (oldPath.startsWith("library/") !== newPath.startsWith("library/")) return [];
     if (existsSync(join(recipeRoot, oldPath))) return [];
     const found = readIndexedLedger(indexedName, recipeRoot);
     return found?.record.fingerprint === fingerprint
@@ -288,7 +291,7 @@ export function ensureRecipeLineage(
       const source = readRecipeSource(path);
       if (!source) return false;
       const key = pathKey(path, recipeRoot);
-      const name = recipeName(path);
+      const name = recipeName(path, recipeRoot);
       const index = readIndex(recipeRoot);
       const indexedName = index.paths[key];
       if (indexedName) {
@@ -392,11 +395,11 @@ export function recordRecipeLaunch(
       if (!source) return false;
       const { fingerprint } = source;
       const key = pathKey(path, recipeRoot);
-      const desiredName = recipeName(path);
+      const desiredName = recipeName(path, recipeRoot);
       const index = readIndex(recipeRoot);
       const relocated = index.paths[key]
         ? undefined
-        : findRelocatedRecipe(index, fingerprint, recipeRoot);
+        : findRelocatedRecipe(index, fingerprint, recipeRoot, key);
       const indexedName = index.paths[key] ?? relocated?.indexedName;
       const found = indexedName
         ? readIndexedLedger(indexedName, recipeRoot)
@@ -436,7 +439,7 @@ export function recordRecipeLaunch(
           former_names: renamed
             ? appendBounded(stored?.former_names ?? [], stored!.lineage_name)
             : relocated
-              ? appendBounded(stored?.former_names ?? [], recipeName(relocated.path))
+              ? appendBounded(stored?.former_names ?? [], recipeName(join(recipeRoot, relocated.path), recipeRoot))
               : stored?.former_names ?? [],
           former_paths: relocated
             ? appendBounded(stored?.former_paths ?? [], relocated.path)
@@ -591,7 +594,7 @@ export function moveRecipeUsage(
       const toKey = pathKey(toPath, recipeRoot);
       const index = readIndex(recipeRoot);
       const oldName = index.paths[fromKey];
-      const newName = recipeName(toPath);
+      const newName = recipeName(toPath, recipeRoot);
       if (!oldName) {
         return index.paths[toKey] === newName && Boolean(readLedger(newName, recipeRoot));
       }

package/lib/registry.ts

@@ -4,8 +4,8 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
@@ -28,6 +28,7 @@ export interface RegisterToolInput {
   name?: string;
   description?: string;
   async?: boolean;
+  expose?: boolean;
   template?: CommandTemplates.CommandTemplateValue | null;
   from?: string;
   defaults?: Record<string, unknown>;
@@ -38,13 +39,16 @@ export interface RegisterToolInput {
 
 export interface RegisterToolResultDetails {
   active_tool?: boolean;
-  activation?: "current_session" | "unverified";
+  activation?: "current_session" | "unverified" | "not_requested";
   activation_boundary?: string;
   args?: string[];
   async?: boolean;
   callable_now?: boolean;
   defaults?: Record<string, string>;
   host_registered?: boolean;
+  kind?: "retained_recipe";
+  recipe?: string;
+  result?: "retained";
   next_actions?: string[];
   optional_args?: string[];
   persisted?: boolean;
@@ -811,12 +815,18 @@ function executeRegisterToolUnlocked<TContext>(
   params: unknown,
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
-): RegisterToolResult {
+): RegisterToolResult | (() => RegisterToolResult) {
   const rawInput =
     params && typeof params === "object"
       ? (params as RegisterToolInput)
       : ({} as RegisterToolInput);
   assertRegisterToolInputModes(rawInput);
+  if (Object.hasOwn(rawInput, "expose")) {
+    const exposure = rawInput.expose;
+    if (typeof exposure !== "boolean") throw new RetainedRecipeRefusal("expose", "expose must be Boolean.");
+    // Select under the existing name reservation; acquire retention locks only after it releases.
+    if (exposure === false) return () => retainRecipe(rawInput, ctx, deps);
+  }
   let input = rawInput;
   if (!input.name) return listTools(deps);
   const name = Identity.normalizeToolName(input.name);
@@ -995,16 +1005,191 @@ function executeRegisterToolUnlocked<TContext>(
   };
 }
 
+class RetainedRecipeRefusal extends Error {
+  readonly reason: string;
+  constructor(field: string, reason: string, cause?: unknown) {
+    super(ExecutionOutput.formatToolText(registryMetadataText({ field, result: reason })), { cause });
+    this.reason = reason;
+  }
+}
+
+function retainedDirectory(path: string) {
+  const stat = lstatSync(path, { bigint: true });
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new RetainedRecipeRefusal("storage", "Retained storage must be a regular non-symlink directory.");
+  }
+  return { path, realpath: realpathSync.native(path), dev: stat.dev, ino: stat.ino };
+}
+
+function recheckRetainedDirectory(frame: ReturnType<typeof retainedDirectory>): void {
+  const current = retainedDirectory(frame.path);
+  if (current.realpath !== frame.realpath || current.dev !== frame.dev || current.ino !== frame.ino) {
+    throw new RetainedRecipeRefusal("storage", "Retained storage identity changed.");
+  }
+}
+
+function retainedSlotAbsent(path: string, ownTargetPublished = false): void {
+  for (const candidate of ownTargetPublished ? [path.replace(/\.json$/u, ".md")] : [path, path.replace(/\.json$/u, ".md")]) {
+    try { lstatSync(candidate); }
+    catch (error) {
+      let code: unknown;
+      try { code = (error as NodeJS.ErrnoException | undefined)?.code; }
+      catch (observationError) { throw new AggregateError([error, observationError], "Retained slot observation failed.", { cause: error }); }
+      if (code === "ENOENT") continue;
+      throw error;
+    }
+    throw new RetainedRecipeRefusal("name", "Retained Recipe already exists; this path is create-only.");
+  }
+}
+
+function retainedFile(path: string) {
+  const stat = lstatSync(path, { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new RetainedRecipeRefusal("storage", "Retained target must be a regular non-symlink file.");
+  }
+  if (stat.size > BigInt(RecipesReferences.MAX_RECIPE_FILE_BYTES)) throw new RetainedRecipeRefusal("storage", "Retained target exceeds the source size limit.");
+  return { dev: stat.dev, ino: stat.ino, size: stat.size, mtime: stat.mtimeNs, ctime: stat.ctimeNs };
+}
+
+function withinRetainedSource(root: string, path: string): boolean {
+  const relation = relative(resolve(root), resolve(path));
+  return relation === "" || (!isAbsolute(relation) && !/^\.\.(?:[\\/]|$)/u.test(relation));
+}
+
+function assertRetainedSourceLifetime(source: string, root: string, field: string): void {
+  const drafts = join(root, "drafts");
+  if (withinRetainedSource(drafts, source) ||
+    (existsSync(drafts) && existsSync(source) && withinRetainedSource(realpathSync.native(drafts), realpathSync.native(source)))) {
+    throw new RetainedRecipeRefusal(field, "Retained creation cannot reference a managed disposable draft.");
+  }
+}
+
+function assertRetainedTemplateLifetimes(value: unknown, path: string, root: string, context: RecipesContext.RecipeResolutionContext): void {
+  if (typeof value === "string") {
+    const source = RecipesReferences.resolveRecipeReferencePath(value, dirname(path), context.activeSkills);
+    if (source) assertRetainedSourceLifetime(source, root, "template");
+  } else if (Array.isArray(value)) {
+    for (const child of value) assertRetainedTemplateLifetimes(child, path, root, context);
+  } else if (value && typeof value === "object") {
+    const node = value as Record<string, unknown>;
+    assertRetainedTemplateLifetimes(node.template, path, root, context);
+    assertRetainedTemplateLifetimes(node.recover, path, root, context);
+  }
+}
+
+function retainRecipe<TContext>(
+  input: RegisterToolInput,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  assertRegisterToolInputModes(input);
+  if (typeof input.name !== "string" || !input.name.trim()) {
+    throw new RetainedRecipeRefusal("name", "Retained creation requires a name.");
+  }
+  const name = Identity.normalizeToolName(input.name);
+  if (!name || deps.reservedToolNames.has(name)) {
+    throw new RetainedRecipeRefusal("name", "Invalid or reserved retained Recipe name.");
+  }
+  const blocker = deps.getToolNameBlocker(name);
+  if (blocker) throw new Error(ExecutionOutput.formatToolText(blocker));
+  if (input.update || Object.hasOwn(input, "draft")) {
+    throw new RetainedRecipeRefusal("expose", "Retained creation does not support update or draft promotion.");
+  }
+  const template = getInputTemplate(input.template);
+  if (template === null || template === "") {
+    throw new RetainedRecipeRefusal("template", "Retained deletion is not supported.");
+  }
+  if (template === undefined && !input.from) {
+    throw new RetainedRecipeRefusal("source", "Retained creation requires template or from.");
+  }
+  const root = resolve(getRecipeRoot(deps)), library = join(root, "library"), path = join(library, `${name}.json`);
+  const context = getRegistrationResolutionContext(ctx, deps);
+  const from = input.from === undefined ? undefined : normalizeFromReference(input.from, context);
+  if (from) {
+    const source = from.endsWith(".json") || from.endsWith(".md") ? from
+      : RecipesReferences.resolveRecipeReferencePath(from, context.cwd, context.activeSkills);
+    if (source) assertRetainedSourceLifetime(source, root, "from");
+  }
+  const authored = buildAuthoredRecipe({ ...input, ...(from ? { from } : {}) }, undefined, undefined);
+  if (!from) assertRetainedTemplateLifetimes(authored.template, path, root, context);
+  const bytes = `${JSON.stringify(authored, null, 2)}\n`;
+  if (Buffer.byteLength(bytes) > RecipesReferences.MAX_RECIPE_FILE_BYTES) {
+    throw new RetainedRecipeRefusal("source", "Retained Recipe exceeds the 1 MiB source limit.");
+  }
+  const candidate = RecipesDiscovery.admitUserRecipe(path, context, authored);
+  if (!candidate.validated || !candidate.tool) {
+    throw new RetainedRecipeRefusal("source", "Retained Recipe admission failed; check the source and caller argument contract.", candidate.diagnostics);
+  }
+  let stage = "storage";
+  try {
+    return withFileMutationLock(root, () => {
+      mkdirSync(root, { recursive: true });
+      const rootFrame = retainedDirectory(root);
+      return withFileMutationLock(library, () => {
+        recheckRetainedDirectory(rootFrame);
+        mkdirSync(library, { recursive: true });
+        const libraryFrame = retainedDirectory(library);
+        const relation = relative(rootFrame.realpath, libraryFrame.realpath);
+        if ((process.platform === "win32" ? relation.toLowerCase() : relation) !== "library") {
+          throw new RetainedRecipeRefusal("storage", "Retained library escapes its Recipe root.");
+        }
+        const recheck = () => { recheckRetainedDirectory(rootFrame); recheckRetainedDirectory(libraryFrame); };
+        return withFileMutationLock(path, () => {
+          recheck(); retainedSlotAbsent(path);
+          stage = "persistence";
+          writeTextAtomic(path, bytes, { exclusive: true, onBeforeReplace: () => { recheck(); retainedSlotAbsent(path); } });
+          stage = "persisted_admission";
+          recheck(); retainedSlotAbsent(path, true);
+          const before = retainedFile(path);
+          if (readFileSync(path, "utf8") !== bytes) throw new RetainedRecipeRefusal("storage", "Persisted retained content changed.");
+          const admitted = RecipesDiscovery.admitUserRecipe(path, context);
+          if (!admitted.validated || !admitted.tool) throw new RetainedRecipeRefusal("source", "Persisted retained Recipe admission failed.", admitted.diagnostics);
+          const after = retainedFile(path);
+          if (Object.keys(before).some(key => before[key as keyof typeof before] !== after[key as keyof typeof after]) ||
+            readFileSync(path, "utf8") !== bytes) throw new RetainedRecipeRefusal("storage", "Persisted retained content changed.");
+          recheck(); retainedSlotAbsent(path, true);
+          stage = "receipt";
+          const args = RecipesDiscovery.summarizeRegisteredToolArgs(admitted.tool);
+          const source = from ? from.endsWith(".json") || from.endsWith(".md") ? `<explicit-file:${basename(from)}>` : from : "template";
+          const recipe = registrySelected("recipe", path), selectedName = registrySelected("tool", name);
+          const selectedSource = registrySelected("source", source);
+          const required = ToolsResponse.selectYamlField("required_args", args.required, REGISTRY_METADATA_BUDGET);
+          const optional = ToolsResponse.selectYamlField("optional_args", args.optional, REGISTRY_METADATA_BUDGET);
+          const facts = { kind: "retained_recipe" as const, result: "retained" as const, persisted: true, resolved: true,
+            validated: true, activation: "not_requested" as const, async: admitted.async };
+          const text = growRegistryDocument(() => ({ ...selectedName.selected, ...facts, ...recipe.selected, ...selectedSource.selected,
+            ...required.selected, ...optional.selected, next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } }),
+            [recipe, selectedName, selectedSource, required, optional]);
+          const result = {
+            content: [textContent(ExecutionOutput.formatToolText(text))],
+            details: { ...facts, tool: name, recipe: path, source, required_args: args.required, optional_args: args.optional,
+              next_actions: ["inspect target=recipes view=summary verbose=true"] },
+          };
+          stage = "release";
+          return result;
+        });
+      });
+    });
+  } catch (error) {
+    const reason = error instanceof RetainedRecipeRefusal ? { reason: error.reason } : {};
+    throw new Error(ExecutionOutput.formatToolText(registryMetadataText({ operation: "retain", stage, result: "unconfirmed",
+      effects: "unknown; inspect retained inventory before retry", ...reason,
+      next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } })), { cause: error });
+  }
+}
+
 export async function executeRegisterTool<TContext>(
   params: unknown,
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
 ): Promise<RegisterToolResult> {
   const input = params as RegisterToolInput;
-  if (!input.name) return executeRegisterToolUnlocked(params, ctx, deps);
-  const name = Identity.normalizeToolName(input.name);
-  if (!name) return executeRegisterToolUnlocked(params, ctx, deps);
-  return withFileMutationLock(getToolRecipePath(deps, name), () =>
-    executeRegisterToolUnlocked(params, ctx, deps),
-  );
+  let result: RegisterToolResult | (() => RegisterToolResult);
+  if (!input.name) result = executeRegisterToolUnlocked(params, ctx, deps);
+  else {
+    const name = Identity.normalizeToolName(input.name);
+    result = !name ? executeRegisterToolUnlocked(params, ctx, deps)
+      : withFileMutationLock(getToolRecipePath(deps, name), () => executeRegisterToolUnlocked(params, ctx, deps));
+  }
+  return typeof result === "function" ? result() : result;
 }