@llblab/pi-actors 0.19.1 → 0.19.2

package/AGENTS.md

@@ -39,7 +39,7 @@
 
 - `Knowledge surface separation`: pi-actors has distinct knowledge surfaces with different context-entry behavior: injected prompt is always present and should stay a tiny bootstrap/reminder; packaged `actors` skill is auto-matched by name/description and should signal that its body is the highest-density practical guide for operating the extension plus the shortest navigator to bundled recipes; packaged `swarm` skill is auto-matched for multi-agent methodology, strategies, standards, and portable examples; README is the human entrypoint explaining concept, rhythm, benefits, and scenarios but is not automatically in context; `/docs` are detailed transportable standards read on demand; `AGENTS.md` is project context and architectural constraints for agents changing the repo | Trigger: Editing prompt copy, README, docs, skills, or project context | Action: Keep each surface on its own wave, avoid duplicating prompt and skill headers, keep the actors skill recipe navigator compact and concrete, avoid duplicating scenario catalogs or changelog narratives in the actors skill, avoid turning the prompt into docs, keep multi-agent methodology in swarm-oriented guidance rather than the actors skill, keep packaged extension skill metadata versions synchronized with `package.json` version, and avoid extra colons in skill frontmatter scalar lines because skill formatters treat them poorly
 - `Tool registry is executable muscle memory`: `~/.pi/agent/recipes/*.json` is the persistent user tool surface by location: every recipe in that agent root is automatically registered as an agent tool across sessions, and `register_tool` creates/updates/deletes recipe files there under the hood | Trigger: Any runtime registration, recipe discovery, migration, docs, skill, prompt, or recipe authoring work | Action: Treat the directory like `MEMORY.md` for executable habits; preserve filename identity, atomic writes, explicit operator-gated migration paths, and never author a recipe-owned `tool` property in repository recipes, docs, or fixtures; packaged/ad hoc recipes outside the agent root are components, not tools
-- `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, named recipe `artifacts`, recipe `mailbox` metadata, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, `template` recipe references, recipe-layer `imports`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
+- `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, named recipe `artifacts`, recipe `mailbox` metadata, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, `template` recipe references, recipe-layer `imports`, file-backed async recipe JSONL context bundles for child `pi -p` actors with raw entry/import recipes and `"you_are_here": true`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
 - `Template recipe graph`: The valid execution chain is `tool → template → recipe → run → template`; file-backed and co-located recipes are storage variants of that chain | Trigger: Adding registry bindings, recipes, docs, or runtime shortcuts | Action: Keep command templates synchronous and portable, use `async: true` as the detached run switch, require every recipe to own `template` directly, and reject cyclic shortcuts such as recipe-owned `tool`
 - `Layer boundary discipline`: Command-template evolution must be separated from template-recipe configuration and async-run lifecycle configuration | Trigger: Adding syntax, placeholders, imports, async controls, or docs | Action: Put portable execution graph semantics in `docs/command-templates.md`, recipe storage/import/default/reference behavior in `docs/template-recipes.md`, and detached lifecycle/state/IPC behavior in `docs/async-runs.md`; type imported recipes as command-template-shaped recipe definitions, not async-run instances

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.19.2: Actor Recipe Context Bundle
+
+- `[Actor Context]` Added a recipe context bundle for file-backed async recipes. The runtime now collects the raw authored entry recipe and resolved imports into deterministic JSONL records with filename-derived `name`, import alias/path metadata, role/depth, and raw recipe JSON so spawned LLM actors can understand the workflow composition behind their prompt.
+- `[Actor Context]` Annotated command-template leaves with actor recipe context and appends the JSONL bundle to child `pi -p` prompts. The recipe record that launched the current child receives `"you_are_here": true` plus path metadata, enabling actors to give advisory feedback on their own recipe/composition fit; recipes can opt out with `"actor_context": false` / `"off"` when a minimal prompt is required.
+- `[Tests]` Added coverage for raw recipe context record generation, import identity, `you_are_here` JSONL marking, prompt injection for `pi -p`, execution-time context propagation, async-run persistence, and recipe opt-out behavior.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.2` for the hotfix release.
+
 ## 0.19.1: Actor Inspector Hotfix
 
 - `[Actor Inspector]` Fixed the live communications roster and row numbering controls after real swarm usage. `/actors-inspector-toggle <rows>` now keeps the room preview cap aligned with the requested row count, current-run sequence numbers are assigned before row limiting so the visible tail keeps its full-log positions, and roster role labels use concise `name/role` text instead of slugifying full role descriptions.

package/README.md

@@ -159,7 +159,7 @@ The terminal actor inspector is hidden by default. When opened without an explic
 /actors-inspect 3
 ```
 
-The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, and an inline roster summary in the form `role/name` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. `/actors-inspect <number>` opens the selected row as a full-message view; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. `/actors-inspect <number>` opens the selected row as a full-message view; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
 
 ## Registry Model
 
@@ -218,7 +218,7 @@ Templates support:
 - Retries, recovery, failure policy, delays, and guarded execution;
 - Async run values such as `{run_id}`, `{state_dir}`, `{actor_address}`, `{default_room}`, and `{communication_file}`.
 
-The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. The run actor owns detached lifecycle, state, messages, cancellation, and inspection.
+The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
 
 ## Recipe Library
 

package/docs/template-recipes.md

@@ -137,6 +137,22 @@ Use recipe-level `mailbox` to document the semantic messages a recipe actor acce
 
 `mailbox` is contract metadata, not transport configuration. It should name semantic message types, not transport commands, file paths, or CLI fragments.
 
+## Actor Recipe Context
+
+File-backed async recipes automatically build a bounded recipe context bundle for child LLM actor launches. The bundle is appended to child `pi -p` prompts as JSONL: each line is one recipe/context record containing filename-derived `name`, source file, role/depth, import path/alias, and the raw authored recipe JSON. The record whose command-template node launched the current child is marked with `"you_are_here": true` and path metadata.
+
+This context is provenance, not the task instruction. The authored prompt remains authoritative; the bundle explains the recipe/composition tree that produced the launch. A child actor can use it to give advisory feedback on whether its recipe, imports, mailbox metadata, and role boundaries fit the task, without needing a separate hand-written workflow explanation. Recipes that require a minimal child prompt may opt out:
+
+```json
+{
+  "async": true,
+  "actor_context": false,
+  "template": "pi -p --model {model} {prompt}"
+}
+```
+
+`"actor_context": "off"` is equivalent. Bundle generation uses the same recipe file-size and import-depth safety limits as normal recipe loading.
+
 ## Actor Message Delivery
 
 Recipes do not declare a second event-delivery policy. A running actor emits addressed messages such as `command.done`, `run.done`, or `checkpoint.needs_input`; the coordinator/runtime decides whether a message stays diagnostic, becomes a notification, or re-enters the agent context. This keeps recipe metadata focused on the actor contract:

package/lib/actor-recipe-context.ts

@@ -0,0 +1,108 @@
+/**
+ * Actor recipe context prompt helpers.
+ * Zones: async runner prompt context, recipe provenance, LLM child launches
+ */
+
+import { basename } from "node:path";
+
+import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import type { TemplateRecipeContextRecord } from "./recipe-references.ts";
+
+export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
+  you_are_here?: true;
+  you_are_here_path?: string;
+}
+
+function commandName(command: string): string {
+  return basename(command).toLowerCase();
+}
+
+function isPiCommand(command: string): boolean {
+  return commandName(command) === "pi";
+}
+
+function findPrintPromptIndex(args: string[]): number | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if ((arg === "-p" || arg === "--print") && index + 1 < args.length) {
+      return index + 1;
+    }
+  }
+  return undefined;
+}
+
+function matchesActorContext(
+  record: TemplateRecipeContextRecord,
+  context: CommandTemplateActorRecipeContext | undefined,
+): boolean {
+  if (!context) return record.role === "entry";
+  if (context.file && context.file === record.file) return true;
+  if (context.name && context.name === record.name) return true;
+  if (context.alias && context.alias === record.alias) return true;
+  return false;
+}
+
+function contextPath(
+  record: TemplateRecipeContextRecord,
+  context: CommandTemplateActorRecipeContext | undefined,
+): string {
+  return record.import_path.join(".") || context?.path || record.name;
+}
+
+export function markRecipeContextRecords(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): MarkedRecipeContextRecord[] {
+  let marked = false;
+  const result = records.map((record) => {
+    if (marked || !matchesActorContext(record, context)) return record;
+    marked = true;
+    return {
+      ...record,
+      you_are_here: true as const,
+      you_are_here_path: contextPath(record, context),
+    };
+  });
+  return result;
+}
+
+export function formatRecipeContextJsonl(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): string {
+  return markRecipeContextRecords(records, context)
+    .map((record) => JSON.stringify(record))
+    .join("\n");
+}
+
+export function buildRecipeContextPromptBlock(
+  records: TemplateRecipeContextRecord[],
+  context?: CommandTemplateActorRecipeContext,
+): string {
+  const jsonl = formatRecipeContextJsonl(records, context);
+  if (!jsonl) return "";
+  return [
+    "Actor recipe context bundle follows as JSONL.",
+    'Each line is one recipe/context record; `"you_are_here": true` marks the recipe node that launched this actor.',
+    "Use this as workflow/composition context, while the task prompt remains authoritative.",
+    "```jsonl",
+    jsonl,
+    "```",
+  ].join("\n");
+}
+
+export function appendRecipeContextToPiArgs(
+  command: string,
+  args: string[],
+  records: TemplateRecipeContextRecord[] | undefined,
+  context?: CommandTemplateActorRecipeContext,
+): string[] {
+  if (!records || records.length === 0 || !isPiCommand(command)) return args;
+  const promptIndex = findPrintPromptIndex(args);
+  if (promptIndex === undefined) return args;
+  const block = buildRecipeContextPromptBlock(records, context);
+  if (!block) return args;
+  const next = [...args];
+  next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
+  return next;
+}

package/lib/async-runs.ts

@@ -59,6 +59,7 @@ export interface AsyncRunStartParams {
   recover?: CommandTemplateValue;
   repeat?: number;
   values?: Record<string, unknown>;
+  actor_context?: boolean | string;
   cwd?: string;
 }
 
@@ -107,6 +108,7 @@ export interface AsyncRunMeta {
   values: Record<string, unknown>;
   artifacts?: Record<string, string>;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
+  recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
 }
 
@@ -196,17 +198,25 @@ function isMutableUsageRecipeFile(file: string): boolean {
 
 function readRecipeFile(file: string): AsyncRunStartParams {
   const path = resolveRecipeFile(file);
-  const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-  if (Object.hasOwn(raw, "tool")) {
+  const raw = RecipeReferences.readRawRecipeConfig(path);
+  if (raw && Object.hasOwn(raw, "tool")) {
     throw new Error(
       `Template recipe cannot define tool; use template in ${path}`,
     );
   }
-  const config = RecipeReferences.readResolvedRecipeConfig(path);
+  const includeActorRecipeContext =
+    raw?.actor_context !== false && raw?.actor_context !== "off";
+  const config = RecipeReferences.readResolvedRecipeConfig(path, [], {
+    includeActorRecipeContext,
+  });
   if (!config) {
     throw new Error(`Template recipe must define template: ${path}`);
   }
-  return { ...(config as AsyncRunStartParams), file: path };
+  return {
+    ...(config as AsyncRunStartParams),
+    file: path,
+    ...(includeActorRecipeContext ? {} : { actor_context: false }),
+  };
 }
 
 function getRunIdFromFile(file: string | undefined): string | undefined {
@@ -376,6 +386,11 @@ export function startRun(
     ? resolveRecipeFile(startParams.file)
     : undefined;
   const recipe = startParams.name || getRunIdFromFile(recipeFile);
+  const includeActorRecipeContext =
+    startParams.actor_context !== false && startParams.actor_context !== "off";
+  const recipeContextRecords = recipeFile && includeActorRecipeContext
+    ? RecipeReferences.buildRecipeContextRecords(recipeFile)
+    : undefined;
   if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
     RecipeUsage.recordRecipeLaunch(recipeFile);
   }
@@ -411,6 +426,9 @@ export function startRun(
     values,
     ...(artifacts ? { artifacts } : {}),
     ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+    ...(recipeContextRecords && recipeContextRecords.length > 0
+      ? { recipe_context_records: recipeContextRecords }
+      : {}),
     ...(startParams.retire_when === "children_terminal"
       ? { retire_when: "children_terminal" as const }
       : {}),

package/lib/command-templates.ts

@@ -10,7 +10,16 @@ import { isAbsolute, resolve } from "node:path";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
+export interface CommandTemplateActorRecipeContext {
+  alias?: string;
+  file?: string;
+  name?: string;
+  path?: string;
+  role?: string;
+}
+
 export interface CommandTemplateObjectConfig {
+  actorRecipeContext?: CommandTemplateActorRecipeContext;
   label?: string;
   parallel?: boolean;
   when?: boolean | string;

package/lib/execution.ts

@@ -10,6 +10,7 @@ import { formatFailureOutput, formatOutput, formatToolText } from "./output.ts";
 import * as Schema from "./schema.ts";
 
 export interface ToolExecOptions {
+  actorRecipeContext?: CommandTemplates.CommandTemplateActorRecipeContext;
   cwd?: string;
   signal?: AbortSignal;
   stdin?: string;
@@ -331,6 +332,7 @@ async function executeRetriableTemplateConfig(
   signal: AbortSignal | undefined,
   stdin: string | undefined,
   isRoot: boolean,
+  actorRecipeContext: CommandTemplates.CommandTemplateActorRecipeContext | undefined,
 ): Promise<TemplateExecution> {
   const maxAttempts = normalizeRetry(normalized.retry, {
     ...(inherited.defaults ?? {}),
@@ -358,6 +360,7 @@ async function executeRetriableTemplateConfig(
       signal,
       stdin,
       isRoot,
+      actorRecipeContext,
     );
     mergeExecution(aggregate, executed);
     aggregate.result = executed.result;
@@ -376,6 +379,7 @@ async function executeRetriableTemplateConfig(
       signal,
       executed.result.stdout,
       false,
+      actorRecipeContext,
     );
     mergeExecution(aggregate, recovered);
     if (recovered.result.code === 0) continue;
@@ -403,6 +407,7 @@ async function executeTemplateConfig(
   signal: AbortSignal | undefined,
   stdin: string | undefined,
   isRoot: boolean,
+  inheritedActorRecipeContext: CommandTemplates.CommandTemplateActorRecipeContext | undefined,
 ): Promise<TemplateExecution> {
   const normalized = CommandTemplates.normalizeCommandTemplateConfig(config);
   const normalizedDefaults = CommandTemplates.resolveInheritedDefaultReferences(
@@ -420,6 +425,7 @@ async function executeTemplateConfig(
       ? { defaults: mergeDefaults(inherited.defaults, normalizedDefaults) }
       : {}),
   };
+  const actorRecipeContext = normalized.actorRecipeContext ?? inheritedActorRecipeContext;
   const controlValues = { ...(context.defaults ?? {}), ...params };
   await applyDelay(normalized.delay, controlValues, signal);
   if (
@@ -464,6 +470,7 @@ async function executeTemplateConfig(
       signal,
       stdin,
       isRoot,
+      actorRecipeContext,
     );
   }
   if (
@@ -479,6 +486,7 @@ async function executeTemplateConfig(
       signal,
       stdin,
       isRoot,
+      actorRecipeContext,
     );
   }
   if (
@@ -495,6 +503,7 @@ async function executeTemplateConfig(
       signal,
       stdin,
       false,
+      actorRecipeContext,
     );
   }
   if (!Array.isArray(normalized.template)) {
@@ -506,6 +515,7 @@ async function executeTemplateConfig(
       { emptyMessage: "Tool template produced an empty command." },
     );
     const result = await exec(invocation.command, invocation.args, {
+      ...(actorRecipeContext ? { actorRecipeContext } : {}),
       cwd,
       signal,
       stdin,
@@ -549,6 +559,7 @@ async function executeTemplateConfig(
           signal,
           stdin,
           false,
+          actorRecipeContext,
         ),
       ),
     );
@@ -640,6 +651,7 @@ async function executeTemplateConfig(
       signal,
       nextStdin,
       false,
+      actorRecipeContext,
     );
     branches.push(...executed.branches);
     commands.push(...executed.commands);
@@ -699,6 +711,7 @@ async function executeTemplateSteps(
     signal,
     undefined,
     true,
+    undefined,
   );
 }
 

package/lib/recipe-references.ts

@@ -70,6 +70,20 @@ interface ImportedRecipe {
   values: Record<string, unknown>;
 }
 
+export interface TemplateRecipeContextRecord {
+  alias?: string;
+  depth: number;
+  file: string;
+  import_path: string[];
+  name: string;
+  recipe: Record<string, unknown>;
+  role: "entry" | "import";
+}
+
+export interface ReadResolvedRecipeConfigOptions {
+  includeActorRecipeContext?: boolean;
+}
+
 function hasWhitespace(value: string): boolean {
   return /\s/.test(value);
 }
@@ -218,7 +232,7 @@ function getRecipeCommandTemplate(
   return normalizeRecipeTemplate({ ...envelope, template });
 }
 
-function readRawRecipeConfig(
+export function readRawRecipeConfig(
   path: string,
 ): Record<string, unknown> | undefined {
   if (!existsSync(path)) return undefined;
@@ -437,14 +451,25 @@ function applyDefaultsToTemplate(
   } as CommandTemplates.CommandTemplateObjectConfig;
 }
 
+function withActorRecipeContext(
+  value: CommandTemplateValue,
+  context: CommandTemplates.CommandTemplateActorRecipeContext,
+): CommandTemplateValue {
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return { ...value, actorRecipeContext: context };
+  }
+  return { actorRecipeContext: context, template: value };
+}
+
 function expandImportNodes(
   value: CommandTemplateValue,
   imports: Record<string, ImportedRecipe>,
+  options: ReadResolvedRecipeConfigOptions = {},
 ): CommandTemplateValue {
   if (typeof value === "string") return value;
   if (Array.isArray(value)) {
     return value.map(
-      (item) => expandImportNodes(item, imports) as CommandTemplateConfig,
+      (item) => expandImportNodes(item, imports, options) as CommandTemplateConfig,
     );
   }
   const record = value as Record<string, unknown>;
@@ -465,7 +490,16 @@ function expandImportNodes(
       nodeDefaults,
       nodeValues,
     );
-    return applyDefaultsToTemplate(imported.config.template, defaults, record);
+    const expanded = applyDefaultsToTemplate(imported.config.template, defaults, record);
+    return options.includeActorRecipeContext
+      ? withActorRecipeContext(expanded, {
+          alias: imported.alias,
+          file: imported.file,
+          name: imported.name,
+          path: imported.alias,
+          role: "import",
+        })
+      : expanded;
   }
   if (Array.isArray(record.template)) {
     return {
@@ -475,6 +509,7 @@ function expandImportNodes(
           expandImportNodes(
             item as CommandTemplateValue,
             imports,
+            options,
           ) as CommandTemplateConfig,
       ),
     } as CommandTemplates.CommandTemplateObjectConfig;
@@ -485,6 +520,7 @@ function expandImportNodes(
       template: expandImportNodes(
         record.template as CommandTemplateValue,
         imports,
+        options,
       ),
     } as CommandTemplates.CommandTemplateObjectConfig;
   }
@@ -494,6 +530,7 @@ function expandImportNodes(
 export function readResolvedRecipeConfig(
   file: string,
   stack: string[] = [],
+  options: ReadResolvedRecipeConfigOptions = {},
 ): TemplateRecipeConfig | undefined {
   const path = resolveRecipePath(
     file,
@@ -512,7 +549,7 @@ export function readResolvedRecipeConfig(
   const imports: Record<string, ImportedRecipe> = {};
   for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
     const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
-    const config = readResolvedRecipeConfig(importPath, [...stack, path]);
+    const config = readResolvedRecipeConfig(importPath, [...stack, path], options);
     if (!config) throw new Error(`Recipe import not found: ${alias}`);
     const bindingDefaults =
       typeof binding === "string" ? undefined : binding.defaults;
@@ -533,9 +570,18 @@ export function readResolvedRecipeConfig(
   >;
   const template = getRecipeCommandTemplate(substituted);
   if (!template) return undefined;
-  const expandedTemplate = expandImportNodes(template, imports);
+  const expandedTemplate = expandImportNodes(template, imports, options);
+  const recipeName = getRecipeIdFromPath(path);
+  const templateWithContext = options.includeActorRecipeContext
+    ? withActorRecipeContext(expandedTemplate, {
+        file: path,
+        name: recipeName,
+        path: recipeName,
+        role: stack.length > 0 ? "import" : "entry",
+      })
+    : expandedTemplate;
   return {
-    name: getRecipeIdFromPath(path),
+    name: recipeName,
     ...(typeof substituted.description === "string" &&
     substituted.description.trim()
       ? { description: substituted.description.trim() }
@@ -554,7 +600,7 @@ export function readResolvedRecipeConfig(
     ...(Object.keys(imports).length > 0
       ? { imports: getRecipeImports(raw) }
       : {}),
-    template: expandedTemplate,
+    template: templateWithContext,
     ...(Array.isArray(substituted.args)
       ? { args: substituted.args as string[] }
       : {}),
@@ -635,6 +681,49 @@ export function readResolvedRecipeConfig(
   };
 }
 
+function collectRecipeContextRecords(
+  file: string,
+  stack: string[],
+  importPath: string[],
+  alias?: string,
+): TemplateRecipeContextRecord[] {
+  const path = resolveRecipePath(
+    file,
+    stack.length > 0 ? dirname(stack.at(-1)!) : Paths.getRecipeRoot(),
+  );
+  if (stack.includes(path)) {
+    throw new Error(`Cyclic recipe import: ${[...stack, path].join(" -> ")}`);
+  }
+  if (stack.length >= MAX_RECIPE_IMPORT_DEPTH) {
+    throw new Error(
+      `Recipe import depth exceeds limit ${MAX_RECIPE_IMPORT_DEPTH}: ${[...stack, path].join(" -> ")}`,
+    );
+  }
+  const raw = readRawRecipeConfig(path);
+  if (!raw || !Object.hasOwn(raw, "template")) return [];
+  const record: TemplateRecipeContextRecord = {
+    ...(alias ? { alias } : {}),
+    depth: stack.length,
+    file: path,
+    import_path: importPath,
+    name: getRecipeIdFromPath(path),
+    recipe: raw,
+    role: stack.length === 0 ? "entry" : "import",
+  };
+  const imports = getRecipeImports(raw);
+  const children = Object.entries(imports).flatMap(([childAlias, binding]) => {
+    const importFile = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
+    return collectRecipeContextRecords(importFile, [...stack, path], [...importPath, childAlias], childAlias);
+  });
+  return [record, ...children];
+}
+
+export function buildRecipeContextRecords(
+  file: string,
+): TemplateRecipeContextRecord[] {
+  return collectRecipeContextRecords(file, [], []);
+}
+
 export function getRecipeTemplate(
   value: unknown,
 ): CommandTemplateValue | undefined {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

package/scripts/async-runner.mjs

@@ -21,6 +21,7 @@ if (!stateDir) {
 }
 const { executeRegisteredTool } = await import("../lib/execution.ts");
 const { execCommandTemplate } = await import("../lib/command-templates.ts");
+const { appendRecipeContextToPiArgs } = await import("../lib/actor-recipe-context.ts");
 const { writeJsonAtomic } = await import("../lib/file-state.ts");
 const runPath = join(stateDir, "run.json");
 const progressPath = join(stateDir, "progress.json");
@@ -90,10 +91,16 @@ function progressRunning() {
 }
 async function observedExec(command, args, options) {
   const commandDetail = formatCommandDetail(command, args);
+  const execArgs = appendRecipeContextToPiArgs(
+    command,
+    args,
+    meta.recipe_context_records,
+    options?.actorRecipeContext,
+  );
   activeSubagents += 1;
   event("command.start", { activeSubagents, command: commandDetail });
   progressRunning();
-  const result = await execCommandTemplate(command, args, options);
+  const result = await execCommandTemplate(command, execArgs, options);
   activeSubagents = Math.max(0, activeSubagents - 1);
   completedSubagents += 1;
   if (result.code !== 0) {

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.19.1
+  version: 0.19.2
 ---
 
 # Actors (pi-actors)
@@ -124,7 +124,7 @@ Actor inspector commands:
 - `/actors-inspector-filter all|room|direct|broadcast|mention <text>`: narrow table previews without changing room/run state.
 - `/actors-inspect <number>`: open one visible row as a full-message view.
 
-The table is compact and optimistic by default: bounded body previews, capped noisy room rows, and an inline roster summary in the form `role/name` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded body previews, capped noisy room rows, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 
@@ -218,8 +218,9 @@ Rules:
 5. Declare `mailbox` for actors that accept or emit meaningful messages.
 6. Declare `artifacts` for durable outputs the coordinator should inspect.
 7. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-8. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-9. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+8. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
+9. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+10. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
 
 Priority for same-id recipes:
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.19.1
+  version: 0.19.2
 ---
 
 # Swarm