@llblab/pi-actors 0.45.1 → 0.46.1

package/fixtures/protocol/recipe-summary.json

@@ -1,6 +1,6 @@
 {
   "id": "music-player",
-  "path": "recipes/music-player.json",
+  "path": "skills/media/recipes/player.json",
   "location": "packaged",
   "active": true,
   "args": ["repo", "command", "source", "loop", "volume", "player", "state_dir"],

package/index.ts

@@ -18,10 +18,11 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   pi.on("session_shutdown", async (event, ctx) =>
     runtime.onSessionShutdown(event.reason, ctx),
   );
-  pi.on("before_agent_start", async (event) =>
+  pi.on("before_agent_start", async (event, ctx) =>
     runtime.beforeAgentStart(
       event.systemPrompt,
       event.systemPromptOptions.skills ?? [],
+      ctx,
     ),
   );
   InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);

package/lib/async-runs.ts

@@ -161,6 +161,7 @@ export interface AsyncRunMeta {
   argv: string[];
   createdAt: string;
   cwd: string;
+  launch_kind?: AsyncRunLaunchSource;
   launch_source?: AsyncRunLaunchSource;
   launch_correlation?: {
     correlation_id?: string;
@@ -259,11 +260,23 @@ function assertNoActiveRunState(stateDir: string): void {
   RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
 
-function resolveRecipeFile(file: string): string {
-  return (
-    RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
-    RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
-    RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot())
+export interface AsyncRunStartOptions {
+  skillContext?: RecipesReferences.ActiveSkillRecipeContext;
+}
+
+function resolveRecipeFile(
+  file: string,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): string {
+  const path = RecipesReferences.resolveRecipeReferencePath(
+    file,
+    cwd,
+    options.skillContext,
+  );
+  if (path) return path;
+  throw new Error(
+    `Recipe reference not found. Use <skill>/<recipe> or an explicit .json/.md file path: ${file}`,
   );
 }
 
@@ -274,13 +287,18 @@ function isMutableUsageRecipeFile(file: string): boolean {
   return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
 }
 
-function readRecipeFile(file: string): AsyncRunStartParams {
-  const path = resolveRecipeFile(file);
+function readRecipeFile(
+  file: string,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): AsyncRunStartParams {
+  const path = resolveRecipeFile(file, cwd, options);
   const raw = RecipesReferences.readRawRecipeConfig(path);
   const includeActorRecipeContext =
     raw?.actor_context !== false && raw?.actor_context !== "off";
   const config = RecipesReferences.readResolvedRecipeConfig(path, [], {
     includeActorRecipeContext,
+    skillContext: options.skillContext,
   });
   if (!config) {
     throw new Error(`Template recipe must define template: ${path}`);
@@ -301,9 +319,13 @@ function getRunIdFromFile(file: string | undefined): string | undefined {
   return name || undefined;
 }
 
-function resolveStartParams(params: AsyncRunStartParams): AsyncRunStartParams {
+function resolveStartParams(
+  params: AsyncRunStartParams,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): AsyncRunStartParams {
   if (!params.file) return params;
-  const fileParams = readRecipeFile(params.file);
+  const fileParams = readRecipeFile(params.file, cwd, options);
   return {
     ...fileParams,
     ...params,
@@ -468,25 +490,15 @@ function prepareStateDirForStart(stateDir: string): void {
 export function startRun(
   params: AsyncRunStartParams,
   cwd: string,
+  options: AsyncRunStartOptions = {},
 ): AsyncRunMeta {
-  const startParams = resolveStartParams(params);
+  const startParams = resolveStartParams(params, cwd, options);
   const resolved = resolveRunTemplate(startParams);
   const run = safeRunId(startParams.run_id);
   const stateDir = resolveStateDir(startParams, run);
   const recipeFile = startParams.file
-    ? resolveRecipeFile(startParams.file)
+    ? resolveRecipeFile(startParams.file, cwd, options)
     : undefined;
-  const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
-  const recipeRelation = recipeFile
-    ? relative(packagedRecipeRoot, recipeFile)
-    : undefined;
-  const packagedRepo =
-    startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
-    recipeRelation &&
-    !recipeRelation.startsWith("..") &&
-    !isAbsolute(recipeRelation)
-      ? dirname(packagedRecipeRoot)
-      : undefined;
   const argSpec = Schema.parseToolArgDeclarationList(startParams.args ?? []);
   if (argSpec.error) throw new Error(argSpec.error);
   const declaredArgs = new Set(argSpec.args);
@@ -498,7 +510,6 @@ export function startRun(
     {
       ...argSpec.defaults,
       ...(startParams.defaults || {}),
-      ...(packagedRepo ? { repo: packagedRepo } : {}),
       ...(startParams.values || {}),
       run_id: run,
       state_dir: stateDir,
@@ -546,7 +557,20 @@ export function startRun(
       startParams.actor_context !== "off";
     const recipeContextRecords =
       recipeFile && includeActorRecipeContext
-        ? RecipesReferences.buildRecipeContextRecords(recipeFile)
+        ? RecipesReferences.buildRecipeContextRecords(
+            recipeFile,
+            options.skillContext,
+          ).map((record, index) =>
+            index === 0 &&
+            startParams.launch_source === "tool" &&
+            record.source_kind === "explicit_file_recipe"
+              ? {
+                  ...record,
+                  logical_reference: record.name,
+                  source_kind: "user_registry_capability" as const,
+                }
+              : record,
+          )
         : undefined;
     if (
       recipeFile &&
@@ -577,7 +601,10 @@ export function startRun(
       createdAt: new Date().toISOString(),
       cwd,
       ...(startParams.launch_source
-        ? { launch_source: startParams.launch_source }
+        ? {
+            launch_kind: startParams.launch_source,
+            launch_source: startParams.launch_source,
+          }
         : {}),
       ...(startParams.launch_correlation
         ? { launch_correlation: startParams.launch_correlation } : {}),

package/lib/automatic-review-runtime.ts

@@ -4,13 +4,14 @@
  * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
  */
 
-import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as DraftSleep from "./draft-sleep.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
 import type * as Pi from "./pi.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import * as ReviewControl from "./review-control.ts";
 import * as ToolReviewScheduler from "./tool-review-scheduler.ts";
 
@@ -27,6 +28,16 @@ export interface AutomaticReviewRuntimeDeps {
   getThinkingLevel(): unknown;
 }
 
+export const PACKAGE_RECIPE_MEMORY_CONTEXT =
+  RecipesReferences.createActiveSkillRecipeContext([
+    {
+      name: "recipe-memory",
+      filePath: fileURLToPath(
+        new URL("../skills/recipe-memory/SKILL.md", import.meta.url),
+      ),
+    },
+  ]);
+
 export function createAutomaticReviewRuntime(
   deps: AutomaticReviewRuntimeDeps,
 ): AutomaticReviewRuntime {
@@ -88,7 +99,7 @@ export function createAutomaticReviewRuntime(
           }
           return AsyncRuns.startRun(
             {
-              file: join(Paths.getPackagedRecipeRoot(), "draft-review.json"),
+              file: "recipe-memory/draft-review",
               launch_source: "tool",
               notification_policy: "silent",
               ownerId: deps.getRunOwnerId(ctx),
@@ -97,6 +108,7 @@ export function createAutomaticReviewRuntime(
               values: { input_path: batch.reviewerInputPath },
             },
             ctx.cwd,
+            { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT },
           );
         },
         process: (state) =>
@@ -113,7 +125,7 @@ export function createAutomaticReviewRuntime(
           }
           return AsyncRuns.startRun(
             {
-              file: join(Paths.getPackagedRecipeRoot(), "tool-review.json"),
+              file: "recipe-memory/tool-review",
               launch_source: "tool",
               notification_policy: "silent",
               ownerId: deps.getRunOwnerId(ctx),
@@ -122,6 +134,7 @@ export function createAutomaticReviewRuntime(
               values: { input_path: batch.reviewerInputPath },
             },
             ctx.cwd,
+            { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT },
           );
         },
         process: (state) =>

package/lib/draft-sleep.ts

@@ -96,7 +96,6 @@ function readState(path: string): DraftSleepState | undefined {
 function defaultActiveTools(recipeRoot: string): DraftReviewActiveTool[] {
   const discovered = RecipesDiscovery.discoverRecipeSources([
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
-    { root: Paths.getPackagedRecipeRoot() },
   ]);
   return [...discovered.active.values()]
     .filter((entry) => existsSync(entry.path))

package/lib/execution.ts

@@ -83,6 +83,7 @@ export interface RegisteredToolExecutionResult {
     command: string;
     fullOutputPath?: string;
     killed: boolean;
+    launch_kind: "tool";
     stderrBytes?: number;
     stderrCapturedBytes?: number;
     stderrFile?: string;
@@ -1136,6 +1137,7 @@ export async function executeRegisteredTool(
       command,
       fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
       killed: result.killed,
+      launch_kind: "tool",
       ...getCaptureDetails(result),
       ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
       ...(executed.failures.length > 0

package/lib/extension-runtime.ts

@@ -9,6 +9,7 @@ import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
 import * as Prompts from "./prompts.ts";
+import * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RunUiRuntime from "./run-ui-runtime.ts";
 import * as Runtime from "./runtime.ts";
@@ -20,6 +21,7 @@ export interface ActorExtensionRuntime {
   beforeAgentStart(
     systemPrompt: string,
     skills: RecipesReferences.ActiveSkillRecipeSource[],
+    ctx: Pi.ExtensionContext,
   ): { systemPrompt: string };
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
@@ -33,7 +35,21 @@ export function createActorExtensionRuntime(
   pi: Pi.ExtensionAPI,
 ): ActorExtensionRuntime {
   let activeRunContext: Pi.ExtensionContext | undefined;
+  const recipeResolutionContextsBySession = new Map<
+    string,
+    RecipeResolution.RecipeResolutionContext
+  >();
   const getRunOwnerId = Pi.getSessionId;
+  const getRecipeResolutionContext = (ctx: Pi.ExtensionContext) => {
+    const sessionId = getRunOwnerId(ctx);
+    const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
+    if (!resolutionContext) {
+      throw new Error(
+        `Recipe resolution context is unavailable for session ${sessionId}.`,
+      );
+    }
+    return resolutionContext;
+  };
   const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
     getActiveContext: () => activeRunContext,
     getRunOwnerId,
@@ -59,6 +75,9 @@ export function createActorExtensionRuntime(
         if (ctx && typeof ctx === "object") {
           nextArgs[4] = {
             ...(ctx as Record<string, unknown>),
+            recipeResolutionContext: getRecipeResolutionContext(
+              ctx as Pi.ExtensionContext,
+            ),
             getThinkingLevel: () => pi.getThinkingLevel(),
           };
         }
@@ -74,6 +93,7 @@ export function createActorExtensionRuntime(
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,
     getActiveTools: () => pi.getActiveTools(),
+    getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       const wrapped = withCurrentThinkingContext(definition);
       actorToolDefinitions.set(wrapped.name, wrapped);
@@ -82,10 +102,22 @@ export function createActorExtensionRuntime(
     reservedToolNames: Tools.RESERVED_TOOL_NAMES,
     setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
   });
-  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+    getResolutionContext: () =>
+      activeRunContext
+        ? getRecipeResolutionContext(activeRunContext)
+        : undefined,
+  });
   return {
-    beforeAgentStart(systemPrompt, skills) {
-      RecipesReferences.setActiveSkillRecipeSources(skills);
+    beforeAgentStart(systemPrompt, skills, ctx) {
+      const sessionId = getRunOwnerId(ctx);
+      const resolutionContext = RecipeResolution.createRecipeResolutionContext(
+        sessionId,
+        ctx.cwd,
+        RecipesReferences.createActiveSkillRecipeContext(skills),
+      );
+      recipeResolutionContextsBySession.set(sessionId, resolutionContext);
+      runtime.loadTools(ctx, resolutionContext);
       return {
         systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
       };
@@ -99,12 +131,18 @@ export function createActorExtensionRuntime(
       if (activeRunContext === ctx) automaticReview.schedule();
     },
     onSessionShutdown(reason, ctx) {
+      recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
       activeRunContext = undefined;
       automaticReview.close();
       recipeReload.close();
       runUiRuntime.shutdown(reason, ctx);
     },
     async onSessionStart(ctx) {
+      const sessionId = getRunOwnerId(ctx);
+      recipeResolutionContextsBySession.set(
+        sessionId,
+        RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd),
+      );
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
       runUiRuntime.close();
@@ -113,7 +151,6 @@ export function createActorExtensionRuntime(
       await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
       if (activeRunContext !== ctx) return;
       automaticReview.start(ctx);
-      runtime.loadTools(ctx);
       runUiRuntime.start(ctx);
       recipeReload.watch(ctx);
     },
@@ -129,6 +166,7 @@ export function createActorExtensionRuntime(
               runtime.getTools(),
               (activeName) => actorToolDefinitions.get(activeName),
             ),
+          getRuntimeToolStatus: runtime.getToolStatus,
           handleRuntimeControl: automaticReview.handleControl,
           registryRuntime: runtime,
           setActiveTools: (toolNames) => pi.setActiveTools(toolNames),

package/lib/inspector.ts

@@ -102,17 +102,51 @@ export function readActorInspectorRecipe(
     !Array.isArray(primary.recipe)
       ? (primary.recipe as Record<string, unknown>)
       : undefined;
-  const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
-    SessionEvidence.redactSessionEvidenceValue(
-      Object.fromEntries(
-        Object.entries(value).filter(
+  const stripPrivateOrigins = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(stripPrivateOrigins);
+    if (!value || typeof value !== "object") return value;
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(
           ([key, entry]) =>
             entry !== undefined &&
             key !== "recipe_dir" &&
-            key !== "skill_dir",
-        ),
-      ),
+            key !== "skill_dir" &&
+            key !== "source_file",
+        )
+        .map(([key, entry]) => [
+          key,
+          key === "actorRecipeContext" && entry && typeof entry === "object"
+            ? stripPrivateOrigins(
+                Object.fromEntries(
+                  Object.entries(entry as Record<string, unknown>).filter(
+                    ([contextKey]) => contextKey !== "file",
+                  ),
+                ),
+              )
+            : stripPrivateOrigins(entry),
+        ]),
+    );
+  };
+  const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
+    SessionEvidence.redactSessionEvidenceValue(
+      stripPrivateOrigins(value),
     ) as Record<string, unknown>;
+  const primarySourceKind =
+    primary?.source_kind === "active_skill_component"
+      ? "active_skill_component"
+      : primary?.source_kind === "user_registry_capability" ||
+          meta.launch_source === "tool"
+        ? "user_registry_capability"
+        : "explicit_file_recipe";
+  const primaryLogicalReference =
+    typeof primary?.logical_reference === "string"
+      ? primary.logical_reference
+      : typeof primary?.name === "string"
+        ? primary.name
+        : typeof meta.recipe === "string"
+          ? meta.recipe
+          : "unknown";
   const launchValues =
     meta.values && typeof meta.values === "object" && !Array.isArray(meta.values)
       ? Object.fromEntries(
@@ -126,10 +160,18 @@ export function readActorInspectorRecipe(
       redactedRecord({
         ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
         depth: entry.depth,
-        file: entry.file,
         import_path: entry.import_path,
-        name: entry.name,
-        qualified_name: entry.qualified_name,
+        logical_reference: entry.logical_reference ?? entry.name,
+        recipe_stem: entry.name,
+        role: entry.role,
+        ...(typeof entry.skill === "string" ? { skill: entry.skill } : {}),
+        source_kind:
+          entry.source_kind === "active_skill_component"
+            ? "active_skill_component"
+            : entry.source_kind === "user_registry_capability" ||
+                (entry.depth === 0 && meta.launch_source === "tool")
+              ? "user_registry_capability"
+              : "explicit_file_recipe",
       }),
     ),
     ...(definition ? { definition: redactedRecord(definition) } : {}),
@@ -137,7 +179,11 @@ export function readActorInspectorRecipe(
     identity: redactedRecord({
       run: meta.run,
       recipe: meta.recipe,
-      recipe_file: meta.recipe_file,
+      recipe_stem: primary?.name ?? meta.recipe,
+      logical_reference: primaryLogicalReference,
+      ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
+      source_kind: primarySourceKind,
+      launch_kind: meta.launch_kind ?? meta.launch_source,
       launch_source: meta.launch_source,
     }),
     launch: redactedRecord({

package/lib/paths.ts

@@ -109,10 +109,3 @@ export function getRecipeRoot(agentDir = getAgentDir()): string {
 export function getRecipeDraftRoot(agentDir = getAgentDir()): string {
   return join(getRecipeRoot(agentDir), "drafts");
 }
-
-export function getPackagedRecipeRoot(): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const compiledRoot = resolve(here, "..", "..", "recipes");
-  if (existsSync(compiledRoot)) return compiledRoot;
-  return resolve(here, "..", "recipes");
-}

package/lib/prompts.ts

@@ -14,7 +14,7 @@ export const REGISTER_TOOL_PROMPT_SNIPPET =
 
 export const REGISTER_TOOL_GUIDELINES = [
   "Use register_tool to wrap trusted local commands, scripts, programs, libraries, or template recipes as persistent pi tools.",
-  "After register_tool succeeds, the new tool is immediately callable and remains available after reload.",
+  "After register_tool succeeds, trust its callable_now and activation result; persisted definitions remain available for admission after reload.",
   '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.",
 ];
@@ -24,14 +24,14 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
 - Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
-- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
+- ~/.pi/agent/recipes/*.json is actor muscle memory: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.
 - Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.
+- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {

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;
@@ -96,7 +141,7 @@ function matchesActorContext(
   context: CommandTemplateActorRecipeContext | undefined,
 ): boolean {
   if (!context) return record.role === "entry";
-  if (context.file && context.file === record.file) return true;
+  if (context.file && context.file === record.source_file) return true;
   if (context.name && context.name === record.name) return true;
   if (context.alias && context.alias === record.alias) return true;
   return false;
@@ -131,7 +176,7 @@ export function formatRecipeContextJsonl(
   context?: CommandTemplateActorRecipeContext,
 ): string {
   return markRecipeContextRecords(records, context)
-    .map((record) => JSON.stringify(record))
+    .map(({ source_file: _sourceFile, ...record }) => JSON.stringify(record))
     .join("\n");
 }