@llblab/pi-actors 0.46.0 → 0.46.1

package/lib/recipes-context.ts

@@ -1,15 +1,60 @@
 /**
- * Recipe context prompt assembly.
- * Zones: async runner prompt context, recipe provenance, LLM child launches
- * Owns compact actor recipe context records appended to child-agent prompts.
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
  */
 
+import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
-import { basename } from "node:path";
+import { basename, resolve } from "node:path";
 
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
 
+export interface RecipeResolutionContext {
+  readonly activeSkills: RecipesReferences.ActiveSkillRecipeContext;
+  readonly cwd: string;
+  readonly generation: string;
+  readonly sessionId: string;
+}
+
+export function createRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+  activeSkills: RecipesReferences.ActiveSkillRecipeContext,
+): RecipeResolutionContext {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) throw new Error("Recipe resolution session id is required.");
+  const normalizedCwd = resolve(cwd);
+  const generation = createHash("sha256")
+    .update(
+      JSON.stringify({
+        activeSkills: RecipesReferences.getActiveSkillRecipeNamespaces(activeSkills),
+        cwd: normalizedCwd,
+        sessionId: normalizedSessionId,
+      }),
+    )
+    .digest("hex");
+  return Object.freeze({
+    activeSkills,
+    cwd: normalizedCwd,
+    generation,
+    sessionId: normalizedSessionId,
+  });
+}
+
+export function createEmptyRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+): RecipeResolutionContext {
+  return createRecipeResolutionContext(
+    sessionId,
+    cwd,
+    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+  );
+}
+
 export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
   you_are_here?: true;
   you_are_here_path?: string;

package/lib/recipes-discovery.ts

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as ModelContext from "./model-context.ts";
+import type { RecipeResolutionContext } from "./recipes-context.ts";
 import type { TemplateRecipeConfig } from "./recipes-references.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
@@ -29,6 +30,7 @@ export interface DiscoveredRecipe {
   disabled: boolean;
   tool: boolean;
   mutableUsage: boolean;
+  resolutionContext?: RecipeResolutionContext;
   diagnostics: string[];
   riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
   shadows: string[];
@@ -58,6 +60,22 @@ export interface RecipesDiscoverySource {
   file?: string;
   defaultTool?: boolean;
   mutableUsage?: boolean;
+  resolutionContext?: RecipeResolutionContext;
+}
+
+export interface UserRecipeAdmission {
+  args?: string[];
+  argTypes?: RegisteredTool["argTypes"];
+  artifacts?: Record<string, string>;
+  async?: boolean;
+  control?: string[];
+  defaults?: Record<string, unknown>;
+  diagnostics: string[];
+  effectiveRecipe?: TemplateRecipeConfig;
+  identity: string;
+  sourcePath: string;
+  tool?: RegisteredTool;
+  validated: boolean;
 }
 
 function assertToolSafeRepeatConfig(
@@ -185,10 +203,13 @@ function readDiscoveredRecipe(
   priority: number,
   defaultTool = false,
   mutableUsage = false,
+  resolutionContext?: RecipeResolutionContext,
 ): DiscoveredRecipe {
   const id = RecipesReferences.getRecipeIdFromPath(file);
   try {
-    const config = RecipesReferences.readResolvedRecipeConfig(file);
+    const config = RecipesReferences.readResolvedRecipeConfig(file, [], {
+      skillContext: resolutionContext?.activeSkills,
+    });
     const invalid = !config;
     const disabled = config?.disabled === true;
     return {
@@ -203,6 +224,7 @@ function readDiscoveredRecipe(
       disabled,
       tool: defaultTool && !disabled && !invalid,
       mutableUsage,
+      resolutionContext,
       diagnostics: getRecipeConfigDiagnostics(file, config),
       riskLabels: getRecipeRiskLabels(config),
       shadows: [],
@@ -219,6 +241,7 @@ function readDiscoveredRecipe(
       disabled: false,
       tool: false,
       mutableUsage,
+      resolutionContext,
       diagnostics: [
         `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
       ],
@@ -233,6 +256,7 @@ function filesForSource(source: RecipesDiscoverySource): Array<{
   file: string;
   defaultTool: boolean;
   mutableUsage: boolean;
+  resolutionContext?: RecipeResolutionContext;
 }> {
   const defaultTool = source.defaultTool === true;
   const mutableUsage = source.mutableUsage === true;
@@ -243,6 +267,7 @@ function filesForSource(source: RecipesDiscoverySource): Array<{
         file: source.file,
         defaultTool,
         mutableUsage,
+        resolutionContext: source.resolutionContext,
       },
     ];
   return source.root
@@ -251,6 +276,7 @@ function filesForSource(source: RecipesDiscoverySource): Array<{
         file,
         defaultTool,
         mutableUsage,
+        resolutionContext: source.resolutionContext,
       }))
     : [];
 }
@@ -338,8 +364,16 @@ export function discoverRecipeSources(
   sources: RecipesDiscoverySource[],
 ): RecipesDiscoveryResult {
   const entries = sources.flatMap((source, priority) =>
-    filesForSource(source).map(({ root, file, defaultTool, mutableUsage }) =>
-      readDiscoveredRecipe(root, file, priority, defaultTool, mutableUsage),
+    filesForSource(source).map(
+      ({ root, file, defaultTool, mutableUsage, resolutionContext }) =>
+        readDiscoveredRecipe(
+          root,
+          file,
+          priority,
+          defaultTool,
+          mutableUsage,
+          resolutionContext,
+        ),
     ),
   );
   const byId = new Map<string, DiscoveredRecipe[]>();
@@ -836,14 +870,13 @@ export function summarizeDiscovery(
   };
 }
 
-export function toRegisteredTool(
-  entry: DiscoveredRecipe,
-): RegisteredTool | undefined {
-  if (!entry.tool || entry.invalid || entry.disabled || !entry.config)
-    return undefined;
-  const cfg = entry.config;
-  const template = entry.path;
-  const description = cfg.description ?? `Execute template recipe: ${entry.id}`;
+function projectRegisteredTool(
+  identity: string,
+  path: string,
+  cfg: TemplateRecipeConfig,
+  mutableUsage: boolean,
+): RegisteredTool {
+  const description = cfg.description ?? `Execute template recipe: ${identity}`;
   const argTemplate = cfg.template;
   const argTemplateConfig =
     typeof argTemplate === "object" && !Array.isArray(argTemplate)
@@ -867,27 +900,38 @@ export function toRegisteredTool(
     explicitArgTypes,
     { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) },
   );
-  const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
-  Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
+  const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(explicitArgTypes, inferredArgTypes);
+  const effectiveArgTypes = { ...inferredArgTypes, ...explicitArgTypes };
+  const args = Schema.getToolArgNames(argTemplateConfig).filter(
+    (arg) => !RecipesReferences.isRuntimeOwnedRecipeInput(arg),
+  );
+  const callerArgSet = new Set(args);
+  const argTypes = Object.fromEntries(
+    Object.entries(effectiveArgTypes).filter(([arg]) => callerArgSet.has(arg)),
+  );
+  const defaults = Object.fromEntries(
+    Object.entries(cfg.defaults ?? {}).filter(([arg]) => callerArgSet.has(arg)),
+  );
+  const storedArgs = cfg.args?.filter((arg) =>
+    callerArgSet.has(Schema.parseToolArgToken(String(arg)).arg),
+  );
   return {
-    name: entry.id,
+    name: identity,
     description,
-    template,
+    template: path,
     recipe: cfg,
-    args: Schema.getToolArgNames(argTemplateConfig),
+    args,
     defaults: Object.fromEntries(
-      Object.entries(cfg.defaults ?? {}).map(([key, value]) => [
-        key,
-        String(value),
-      ]),
+      Object.entries(defaults).map(([key, value]) => [key, String(value)]),
     ),
     ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
-    ...(entry.mutableUsage ? { sourcePath: entry.path } : {}),
-    ...(cfg.args ? { storedArgs: cfg.args } : {}),
-    ...(cfg.defaults
+    ...(mutableUsage ? { sourcePath: path } : {}),
+    ...(storedArgs ? { storedArgs } : {}),
+    ...(Object.keys(defaults).length > 0
       ? {
           storedDefaults: Object.fromEntries(
-            Object.entries(cfg.defaults).map(([key, value]) => [
+            Object.entries(defaults).map(([key, value]) => [
               key,
               String(value),
             ]),
@@ -896,3 +940,99 @@ export function toRegisteredTool(
       : {}),
   };
 }
+
+function boundedAdmissionDiagnostic(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.length <= 4096 ? message : `${message.slice(0, 4095)}…`;
+}
+
+export function admitUserRecipe(
+  sourcePath: string,
+  resolutionContext: RecipeResolutionContext,
+  authoredRecipe?: Record<string, unknown>,
+  mutableUsage = true,
+): UserRecipeAdmission {
+  const identity = RecipesReferences.getRecipeIdFromPath(sourcePath);
+  try {
+    const effectiveRecipe = RecipesReferences.readResolvedRecipeConfig(
+      sourcePath,
+      [],
+      {
+        ...(authoredRecipe
+          ? { authoredEntry: { path: sourcePath, recipe: authoredRecipe } }
+          : {}),
+        skillContext: resolutionContext.activeSkills,
+      },
+    );
+    if (!effectiveRecipe) {
+      return {
+        diagnostics: [
+          authoredRecipe
+            ? "Recipe must define a valid template."
+            : RecipesReferences.diagnoseRawRecipeConfigFailure(sourcePath) ??
+              "Recipe must define a valid template.",
+        ],
+        identity,
+        sourcePath,
+        validated: false,
+      };
+    }
+    if (effectiveRecipe.disabled === true) {
+      return {
+        diagnostics: ["Recipe is disabled."],
+        effectiveRecipe,
+        identity,
+        sourcePath,
+        validated: false,
+      };
+    }
+    const tool = projectRegisteredTool(
+      identity,
+      sourcePath,
+      effectiveRecipe,
+      mutableUsage,
+    );
+    return {
+      args: tool.args,
+      argTypes: tool.argTypes,
+      artifacts: effectiveRecipe.artifacts,
+      async: effectiveRecipe.async === true,
+      control: effectiveRecipe.control,
+      defaults: effectiveRecipe.defaults,
+      diagnostics: [],
+      effectiveRecipe,
+      identity,
+      sourcePath,
+      tool,
+      validated: true,
+    };
+  } catch (error) {
+    return {
+      diagnostics: [boundedAdmissionDiagnostic(error)],
+      identity,
+      sourcePath,
+      validated: false,
+    };
+  }
+}
+
+export function toRegisteredTool(
+  entry: DiscoveredRecipe,
+): RegisteredTool | undefined {
+  if (!entry.tool || entry.invalid || entry.disabled || !entry.config)
+    return undefined;
+  if (entry.resolutionContext) {
+    return admitUserRecipe(
+      entry.path,
+      entry.resolutionContext,
+      undefined,
+      entry.mutableUsage,
+    ).tool;
+  }
+  return projectRegisteredTool(
+    entry.id,
+    entry.path,
+    entry.config,
+    entry.mutableUsage,
+  );
+}

package/lib/recipes-references.ts

@@ -87,11 +87,34 @@ export interface TemplateRecipeContextRecord {
 }
 
 export interface ReadResolvedRecipeConfigOptions {
+  authoredEntry?: { path: string; recipe: Record<string, unknown> };
   includeActorRecipeContext?: boolean;
   skillContext?: ActiveSkillRecipeContext;
 }
 
-const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
+const RESERVED_AUTHORED_RECIPE_VALUE_NAMES = new Set([
+  "recipe_dir",
+  "skill_dir",
+]);
+
+export const RUNTIME_OWNED_RECIPE_INPUT_NAMES = Object.freeze([
+  "owner_id",
+  "recipe_dir",
+  "run_instance_id",
+  "runtime_state_root",
+  "session_id",
+  "skill_dir",
+  "state_dir",
+  "trace_file",
+]);
+
+const RUNTIME_OWNED_RECIPE_INPUT_SET = new Set(
+  RUNTIME_OWNED_RECIPE_INPUT_NAMES,
+);
+
+export function isRuntimeOwnedRecipeInput(name: string): boolean {
+  return RUNTIME_OWNED_RECIPE_INPUT_SET.has(name);
+}
 
 export interface ActiveSkillRecipeSource {
   name: string;
@@ -149,6 +172,19 @@ export interface ActiveSkillRecipeComponent {
   stem: string;
 }
 
+export interface SkillRecipeComponentDiagnostic {
+  file?: string;
+  reason: string;
+  skill: string;
+  stem?: string;
+}
+
+export interface SkillRecipeComponentInventory {
+  components: ActiveSkillRecipeComponent[];
+  partial: boolean;
+  rejected: SkillRecipeComponentDiagnostic[];
+}
+
 function nestedRecipeFiles(root: string): string[] {
   if (!existsSync(root)) return [];
   return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
@@ -158,20 +194,32 @@ function nestedRecipeFiles(root: string): string[] {
   });
 }
 
-export function listActiveSkillRecipeComponents(
+export function inventoryActiveSkillRecipeComponents(
   context: ActiveSkillRecipeContext,
-): ActiveSkillRecipeComponent[] {
+): SkillRecipeComponentInventory {
   const components: ActiveSkillRecipeComponent[] = [];
+  const rejected: SkillRecipeComponentDiagnostic[] = [];
   for (const [skill, roots] of Object.entries(context.namespaces)) {
-    if (roots.length > 1)
-      throw new Error(`Duplicate active Skill identity ${skill}: ${roots.join(", ")}`);
+    if (roots.length > 1) {
+      rejected.push({
+        reason: `Duplicate active Skill identity ${skill}: ${roots.join(", ")}`,
+        skill,
+      });
+      continue;
+    }
     const root = roots[0];
     if (!root || !existsSync(root)) continue;
     const direct = readdirSync(root, { withFileTypes: true });
     for (const entry of direct.filter((candidate) => candidate.isDirectory())) {
       const nested = nestedRecipeFiles(join(root, entry.name));
-      if (nested.length > 0)
-        throw new Error(`Nested Skill Recipe file is not addressable: ${nested[0]}`);
+      for (const file of nested) {
+        rejected.push({
+          file,
+          reason: `Nested Skill Recipe file is not addressable: ${file}`,
+          skill,
+          stem: getRecipeIdFromPath(file),
+        });
+      }
     }
     const files = direct
       .filter(
@@ -186,30 +234,62 @@ export function listActiveSkillRecipeComponents(
       byStem.set(stem, matches);
     }
     for (const [stem, matches] of [...byStem].sort(([a], [b]) => a.localeCompare(b))) {
-      if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(stem))
-        throw new Error(`Invalid Skill Recipe filename stem: ${stem}`);
-      if (matches.length > 1)
-        throw new Error(`Skill Recipe stem collision: ${skill}/${stem} has both .json and .md files`);
+      if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(stem)) {
+        rejected.push({
+          file: matches[0],
+          reason: `Invalid Skill Recipe filename stem: ${stem}`,
+          skill,
+          stem,
+        });
+        continue;
+      }
+      if (matches.length > 1) {
+        rejected.push({
+          file: matches[0],
+          reason: `Skill Recipe stem collision: ${skill}/${stem} has both .json and .md files`,
+          skill,
+          stem,
+        });
+        continue;
+      }
       const file = matches[0];
-      const raw = readRawRecipeConfig(file);
-      if (!raw || !Object.hasOwn(raw, "template"))
-        throw new Error(`Invalid Skill Recipe component: ${skill}/${stem}`);
-      assertRecipeHasNoDeclaredName(raw);
-      components.push({
-        file,
-        identity: `${skill}/${stem}`,
-        imports: Object.fromEntries(
-          Object.entries(getRecipeImports(raw)).map(([alias, value]) => [
-            alias,
-            getImportFrom(value),
-          ]),
-        ),
-        skill,
-        stem,
-      });
+      try {
+        const raw = readRawRecipeConfig(file);
+        if (!raw || !Object.hasOwn(raw, "template"))
+          throw new Error(`Invalid Skill Recipe component: ${skill}/${stem}`);
+        assertRecipeHasNoDeclaredName(raw);
+        components.push({
+          file,
+          identity: `${skill}/${stem}`,
+          imports: Object.fromEntries(
+            Object.entries(getRecipeImports(raw)).map(([alias, value]) => [
+              alias,
+              getImportFrom(value),
+            ]),
+          ),
+          skill,
+          stem,
+        });
+      } catch (error) {
+        rejected.push({
+          file,
+          reason: error instanceof Error ? error.message : String(error),
+          skill,
+          stem,
+        });
+      }
     }
   }
-  return components;
+  return { components, partial: rejected.length > 0, rejected };
+}
+
+export function listActiveSkillRecipeComponents(
+  context: ActiveSkillRecipeContext,
+): ActiveSkillRecipeComponent[] {
+  const inventory = inventoryActiveSkillRecipeComponents(context);
+  if (inventory.rejected.length > 0)
+    throw new Error(inventory.rejected[0].reason);
+  return inventory.components;
 }
 
 const SKILL_RECIPE_REFERENCE =
@@ -311,7 +391,7 @@ function assertRuntimeRecipeValuesNotDeclared(raw: Record<string, unknown>): voi
   const args = Array.isArray(raw.args)
     ? Schema.getExplicitToolArgNames(raw.args.map(String))
     : [];
-  for (const name of RUNTIME_RECIPE_VALUE_NAMES) {
+  for (const name of RESERVED_AUTHORED_RECIPE_VALUE_NAMES) {
     if (
       args.includes(name) ||
       (isRecord(raw.defaults) && Object.hasOwn(raw.defaults, name)) ||
@@ -1068,6 +1148,46 @@ function getDirectDelegatedRecipe(
   return undefined;
 }
 
+function resolveDirectDelegationArgs(
+  delegated: TemplateRecipeConfig,
+  wrapperArgs: unknown,
+  wrapperDefaults: Record<string, unknown> | undefined,
+): string[] | undefined {
+  if (!Array.isArray(delegated.args))
+    return Array.isArray(wrapperArgs) ? wrapperArgs.map(String) : undefined;
+  const delegatedSpec = Schema.parseToolArgDeclarationList(delegated.args);
+  if (delegatedSpec.error) throw new Error(delegatedSpec.error);
+  const wrapperDeclarations = Array.isArray(wrapperArgs)
+    ? wrapperArgs.map(String)
+    : [];
+  const wrapperSpec = Schema.parseToolArgDeclarationList(wrapperDeclarations);
+  if (wrapperSpec.error) throw new Error(wrapperSpec.error);
+  const declared = new Set(delegatedSpec.args);
+  for (const arg of wrapperSpec.args) {
+    if (!declared.has(arg))
+      throw new Error(`Unknown delegated Recipe argument: ${arg}`);
+  }
+  Schema.assertCompatibleToolArgTypes(
+    delegatedSpec.argTypes,
+    wrapperSpec.argTypes,
+  );
+  assertRecipeDefaultsDeclared(
+    delegated.args,
+    wrapperDefaults,
+    "delegated Recipe default",
+  );
+  Schema.normalizeRuntimeValues(
+    Object.fromEntries(
+      Object.entries(wrapperDefaults ?? {}).filter(
+        ([, value]) =>
+          typeof value !== "string" || !/\{[^{}]+\}/.test(value),
+      ),
+    ),
+    delegatedSpec.argTypes,
+  );
+  return delegated.args;
+}
+
 function expandImportNodes(
   value: CommandTemplateValue,
   imports: Record<string, ImportedRecipe>,
@@ -1157,7 +1277,10 @@ export function readResolvedRecipeConfig(
       `Recipe import depth exceeds limit ${MAX_RECIPE_IMPORT_DEPTH}: ${[...stack, path].join(" -> ")}`,
     );
   }
-  const raw = readRawRecipeConfig(path);
+  const raw =
+    options.authoredEntry?.path === path
+      ? options.authoredEntry.recipe
+      : readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return undefined;
   assertRecipeHasNoDeclaredName(raw);
   RecipeControl.assertRecipeHasNoMailbox(raw);
@@ -1244,10 +1367,15 @@ export function readResolvedRecipeConfig(
         role: stack.length > 0 ? "import" : "entry",
       })
     : expandedTemplate;
-  const mergedDefaults = mergeDefaults(
-    delegated?.defaults,
-    isRecord(substituted.defaults) ? substituted.defaults : undefined,
-  );
+  const wrapperDefaults = isRecord(substituted.defaults)
+    ? substituted.defaults
+    : undefined;
+  const mergedDefaults = mergeDefaults(delegated?.defaults, wrapperDefaults);
+  const effectiveArgs = delegated
+    ? resolveDirectDelegationArgs(delegated, substituted.args, wrapperDefaults)
+    : Array.isArray(substituted.args)
+      ? (substituted.args as string[])
+      : undefined;
   const artifactSource = isRecord(substituted.artifacts)
     ? substituted.artifacts
     : delegated?.artifacts;
@@ -1284,11 +1412,7 @@ export function readResolvedRecipeConfig(
       ? { imports: getRecipeImports(raw) }
       : {}),
     template: templateWithContext,
-    ...(Array.isArray(substituted.args)
-      ? { args: substituted.args as string[] }
-      : Array.isArray(delegated?.args)
-        ? { args: delegated.args }
-        : {}),
+    ...(effectiveArgs ? { args: effectiveArgs } : {}),
     ...(mergedDefaults ? { defaults: mergedDefaults } : {}),
     ...(typeof substituted.parallel === "boolean"
       ? { parallel: substituted.parallel }