@llblab/pi-actors 0.45.1 → 0.46.1

package/dist/lib/recipes-context.js

@@ -1,10 +1,34 @@
 /**
- * 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 * as RecipesReferences from "./recipes-references.js";
+export function createRecipeResolutionContext(sessionId, cwd, activeSkills) {
+    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, cwd) {
+    return createRecipeResolutionContext(sessionId, cwd, RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
+}
 function commandName(command) {
     return basename(command).toLowerCase();
 }
@@ -78,7 +102,7 @@ export function findPiPrintPromptIndex(args) {
 function matchesActorContext(record, context) {
     if (!context)
         return record.role === "entry";
-    if (context.file && context.file === record.file)
+    if (context.file && context.file === record.source_file)
         return true;
     if (context.name && context.name === record.name)
         return true;
@@ -105,7 +129,7 @@ export function markRecipeContextRecords(records, context) {
 }
 export function formatRecipeContextJsonl(records, context) {
     return markRecipeContextRecords(records, context)
-        .map((record) => JSON.stringify(record))
+        .map(({ source_file: _sourceFile, ...record }) => JSON.stringify(record))
         .join("\n");
 }
 export function buildRecipeContextPromptBlock(records, context) {

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

@@ -5,6 +5,7 @@
  */
 import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
+import type { RecipeResolutionContext } from "./recipes-context.ts";
 import type { TemplateRecipeConfig } from "./recipes-references.ts";
 export interface DiscoveredRecipe {
     id: string;
@@ -18,6 +19,7 @@ export interface DiscoveredRecipe {
     disabled: boolean;
     tool: boolean;
     mutableUsage: boolean;
+    resolutionContext?: RecipeResolutionContext;
     diagnostics: string[];
     riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
     shadows: string[];
@@ -44,6 +46,21 @@ 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;
 }
 export declare function hasBroadWindowsWriteAcl(icaclsOutput: string): boolean;
 export declare function discoverRecipeSources(sources: RecipesDiscoverySource[]): RecipesDiscoveryResult;
@@ -52,4 +69,5 @@ export declare function createRecipeIntegrityManifest(result: RecipesDiscoveryRe
 export declare function getShadowedLaunchDiagnostic(result: RecipesDiscoveryResult, id: string): Record<string, unknown> | undefined;
 export declare function listDraftRecipes(root: string): Array<Record<string, unknown>>;
 export declare function summarizeDiscovery(result: RecipesDiscoveryResult): Record<string, unknown>;
+export declare function admitUserRecipe(sourcePath: string, resolutionContext: RecipeResolutionContext, authoredRecipe?: Record<string, unknown>, mutableUsage?: boolean): UserRecipeAdmission;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipes-discovery.js

@@ -94,10 +94,12 @@ function getRecipeRiskLabels(config) {
         "risk.platform_specific",
     ].filter((label) => labels.has(label));
 }
-function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
+function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false, resolutionContext) {
     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 {
@@ -112,6 +114,7 @@ function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutable
             disabled,
             tool: defaultTool && !disabled && !invalid,
             mutableUsage,
+            resolutionContext,
             diagnostics: getRecipeConfigDiagnostics(file, config),
             riskLabels: getRecipeRiskLabels(config),
             shadows: [],
@@ -129,6 +132,7 @@ function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutable
             disabled: false,
             tool: false,
             mutableUsage,
+            resolutionContext,
             diagnostics: [
                 `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
             ],
@@ -147,6 +151,7 @@ function filesForSource(source) {
                 file: source.file,
                 defaultTool,
                 mutableUsage,
+                resolutionContext: source.resolutionContext,
             },
         ];
     return source.root
@@ -155,6 +160,7 @@ function filesForSource(source) {
             file,
             defaultTool,
             mutableUsage,
+            resolutionContext: source.resolutionContext,
         }))
         : [];
 }
@@ -222,7 +228,7 @@ function getRecipeRootDiagnostics(sources) {
     return diagnostics;
 }
 export function discoverRecipeSources(sources) {
-    const entries = sources.flatMap((source, priority) => filesForSource(source).map(({ root, file, defaultTool, mutableUsage }) => readDiscoveredRecipe(root, file, priority, defaultTool, mutableUsage)));
+    const entries = sources.flatMap((source, priority) => filesForSource(source).map(({ root, file, defaultTool, mutableUsage, resolutionContext }) => readDiscoveredRecipe(root, file, priority, defaultTool, mutableUsage, resolutionContext)));
     const byId = new Map();
     for (const entry of entries) {
         const bucket = byId.get(entry.id) ?? [];
@@ -647,12 +653,8 @@ export function summarizeDiscovery(result) {
         integrity_manifest: createRecipeIntegrityManifest(result),
     };
 }
-export function toRegisteredTool(entry) {
-    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, path, cfg, mutableUsage) {
+    const description = cfg.description ?? `Execute template recipe: ${identity}`;
     const argTemplate = cfg.template;
     const argTemplateConfig = typeof argTemplate === "object" && !Array.isArray(argTemplate)
         ? {
@@ -669,24 +671,27 @@ export function toRegisteredTool(entry) {
         return [parsed.arg, parsed.type];
     }));
     assertToolSafeRepeatConfig(argTemplateConfig, 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),
-        defaults: Object.fromEntries(Object.entries(cfg.defaults ?? {}).map(([key, value]) => [
-            key,
-            String(value),
-        ])),
+        args,
+        defaults: Object.fromEntries(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]) => [
+                storedDefaults: Object.fromEntries(Object.entries(defaults).map(([key, value]) => [
                     key,
                     String(value),
                 ])),
@@ -694,3 +699,71 @@ export function toRegisteredTool(entry) {
             : {}),
     };
 }
+function boundedAdmissionDiagnostic(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length <= 4096 ? message : `${message.slice(0, 4095)}…`;
+}
+export function admitUserRecipe(sourcePath, resolutionContext, authoredRecipe, mutableUsage = true) {
+    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) {
+    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/dist/lib/recipes-references.d.ts

@@ -12,7 +12,6 @@ export interface TemplateRecipeImportBinding {
 }
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 export interface TemplateRecipeDefinition {
-    name?: string;
     description?: string;
     disabled?: boolean;
     imports?: Record<string, TemplateRecipeImport>;
@@ -39,6 +38,7 @@ export interface TemplateRecipeDefinition {
     usage?: Record<string, unknown>;
 }
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
+    name?: string;
     async?: boolean;
     recipe_dir?: string;
     skill_dir?: string;
@@ -46,31 +46,64 @@ export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
 export interface TemplateRecipeContextRecord {
     alias?: string;
     depth: number;
-    file: string;
     import_path: string[];
+    logical_reference: string;
     name: string;
-    qualified_name?: string;
     recipe: Record<string, unknown>;
     role: "entry" | "import";
+    skill?: string;
+    source_file: string;
+    source_kind: "active_skill_component" | "explicit_file_recipe" | "user_registry_capability";
 }
 export interface ReadResolvedRecipeConfigOptions {
+    authoredEntry?: {
+        path: string;
+        recipe: Record<string, unknown>;
+    };
     includeActorRecipeContext?: boolean;
+    skillContext?: ActiveSkillRecipeContext;
 }
+export declare const RUNTIME_OWNED_RECIPE_INPUT_NAMES: readonly string[];
+export declare function isRuntimeOwnedRecipeInput(name: string): 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;
+export interface ActiveSkillRecipeContext {
+    readonly namespaces: Readonly<Record<string, readonly string[]>>;
+}
+export declare function createActiveSkillRecipeContext(skills: ActiveSkillRecipeSource[]): ActiveSkillRecipeContext;
+export declare const EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT: ActiveSkillRecipeContext;
+export declare function getActiveSkillRecipeNamespaces(context: ActiveSkillRecipeContext): Record<string, string[]>;
+export interface ActiveSkillRecipeComponent {
+    file: string;
+    identity: string;
+    imports: Record<string, string>;
+    skill: string;
+    stem: string;
+}
+export interface SkillRecipeComponentDiagnostic {
+    file?: string;
+    reason: string;
+    skill: string;
+    stem?: string;
+}
+export interface SkillRecipeComponentInventory {
+    components: ActiveSkillRecipeComponent[];
+    partial: boolean;
+    rejected: SkillRecipeComponentDiagnostic[];
+}
+export declare function inventoryActiveSkillRecipeComponents(context: ActiveSkillRecipeContext): SkillRecipeComponentInventory;
+export declare function listActiveSkillRecipeComponents(context: ActiveSkillRecipeContext): ActiveSkillRecipeComponent[];
+export declare function resolveRecipePath(value: string, baseDir?: string): string;
+export declare function resolveRecipeReferencePath(value: unknown, baseDir?: string, context?: ActiveSkillRecipeContext): string | undefined;
+export declare function getRecipePath(value: unknown, baseDir?: string, context?: ActiveSkillRecipeContext): string | undefined;
 export declare function diagnoseRawRecipeConfigFailure(path: string): string | undefined;
 export declare function readRawRecipeConfig(path: string): Record<string, unknown> | undefined;
 export declare function getRecipeIdFromPath(file: string): string;
 export declare function readResolvedRecipeConfig(file: string, stack?: string[], options?: ReadResolvedRecipeConfigOptions): TemplateRecipeConfig | undefined;
-export declare function buildRecipeContextRecords(file: string): TemplateRecipeContextRecord[];
+export declare function buildRecipeContextRecords(file: string, context?: ActiveSkillRecipeContext): TemplateRecipeContextRecord[];
 export declare function getRecipeTemplate(value: unknown): CommandTemplateValue | undefined;
 export declare function isRecipeReference(value: unknown): boolean;
 export declare function isAsyncRecipeReference(value: unknown): boolean;