@llblab/pi-actors 0.19.1 → 0.19.3

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, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, recipe-persistence suggestions for successful direct inline/ad hoc `spawn` runs that are not already durable user recipes, named recipe `artifacts`, recipe `mailbox` metadata, `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,20 @@
 # Changelog
 
+## 0.19.3: Spawn Recipe Persistence Suggestions
+
+- `[Observability]` Added semi-active recipe persistence suggestions for successful direct `spawn` runs. Inline/ad hoc spawned actors now record `launch_source: "spawn"`, and their successful terminal follow-up asks the agent to offer saving the reusable pattern as a durable recipe/tool under `~/.pi/agent/recipes` without auto-saving.
+- `[Runtime]` Recorded `launch_source` metadata for actor starts so observability can distinguish direct spawns from registered recipe-tool runs and avoid prompting for actors already backed by user-owned recipes.
+- `[Docs/Prompt]` Updated onboarding prompt guidance, README, async-run docs, and project context around ask-first recipe persistence after successful transient actors.
+- `[Tests]` Added regression coverage for successful transient spawn suggestions and suppression when the run already came from a saved user recipe.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.3` for the hotfix release.
+
+## 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
 
@@ -239,7 +239,7 @@ Packaged recipes are building blocks. Copy them into `~/.pi/agent/recipes/` or r
 
 Use a foreground registered tool when the work is short, bounded, and does not need lifecycle.
 
-Use an async recipe or `spawn` when the work is long-running, service-like, parallel, agentic, artifact-producing, or needs later control.
+Use an async recipe or `spawn` when the work is long-running, service-like, parallel, agentic, artifact-producing, or needs later control. If a directly spawned inline/ad hoc actor completes successfully, pi-actors sends the launching agent a follow-up note to offer saving that pattern as a durable recipe/tool under `~/.pi/agent/recipes`; the agent should ask first and never auto-save.
 
 Use `room:<run>` when multiple actors in the same run need shared context, roster discovery, or group-visible progress.
 

package/docs/async-runs.md

@@ -83,7 +83,7 @@ Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the calle
 
 Use ordinary files under the extension temp directory so status tools stay simple and inspectable:
 
-- `run.json`: pid, optional source metadata (`tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir.
+- `run.json`: pid, optional source metadata (`launch_source`, `tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir.
 - `communication.json`: compact actor communication snapshot with self/root/parent, default-room, member, and contact hints for room-aware scripts and agents.
 - `progress.json`: phase, active command count, completed count, failures, and updated time.
 - `events.jsonl`: append-only implementation lifecycle log.
@@ -124,7 +124,7 @@ The core loop is:
    { "recipe": "music-player.json", "as": "run:music" }
    ```
 
-2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically.
+2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. When a directly spawned inline/ad hoc actor completes successfully, the coordinator follow-up tells the agent to offer recipe persistence only as a question to the operator; it must not auto-save.
 
 3. Respond with explicit run-local messages when needed:
 

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

@@ -34,9 +34,12 @@ import * as RecipeUsage from "./recipe-usage.ts";
 
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 
+export type AsyncRunLaunchSource = "spawn" | "tool";
+
 export interface AsyncRunStartParams {
   async?: boolean;
   file?: string;
+  launch_source?: AsyncRunLaunchSource;
   name?: string;
   ownerId?: string;
   run_id?: string;
@@ -59,6 +62,7 @@ export interface AsyncRunStartParams {
   recover?: CommandTemplateValue;
   repeat?: number;
   values?: Record<string, unknown>;
+  actor_context?: boolean | string;
   cwd?: string;
 }
 
@@ -95,6 +99,7 @@ export interface AsyncRunMeta {
   argv: string[];
   createdAt: string;
   cwd: string;
+  launch_source?: AsyncRunLaunchSource;
   ownerId?: string;
   pid: number;
   recipe?: string;
@@ -107,6 +112,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 +202,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 +390,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);
   }
@@ -399,6 +418,7 @@ export function startRun(
     argv: [process.execPath, ...argv],
     createdAt: new Date().toISOString(),
     cwd,
+    ...(startParams.launch_source ? { launch_source: startParams.launch_source } : {}),
     ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
     pid: 0,
     ...(recipe ? { recipe } : {}),
@@ -411,6 +431,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/observability.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -26,9 +26,12 @@ export interface RunObservation {
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
+  launchSource?: AsyncRuns.AsyncRunLaunchSource;
+  recipeFile?: string;
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  tool?: string;
   stateDir?: string;
   status: RunObservedStatus;
   updatedAt?: string;
@@ -57,8 +60,11 @@ export interface RunTransition {
   run: string;
   stateDir?: string;
   artifacts?: Record<string, string>;
+  launchSource?: AsyncRuns.AsyncRunLaunchSource;
+  recipeFile?: string;
   terminalHandled?: boolean;
   to: RunObservedStatus;
+  tool?: string;
 }
 
 export interface RunOutboxEvent {
@@ -132,6 +138,12 @@ function observeRun(stateDir: string): RunObservation | undefined {
       !Array.isArray(status.artifacts)
         ? { artifacts: status.artifacts as Record<string, string> }
         : {}),
+      ...(status.launch_source === "spawn" || status.launch_source === "tool"
+        ? { launchSource: status.launch_source }
+        : {}),
+      ...(typeof status.recipe_file === "string"
+        ? { recipeFile: status.recipe_file }
+        : {}),
       ...(status.terminal_handled ? { terminalHandled: true } : {}),
       ...(typeof status.retire_when === "string"
         ? { retireWhen: status.retire_when }
@@ -139,6 +151,7 @@ function observeRun(stateDir: string): RunObservation | undefined {
       run,
       stateDir,
       status: status.status as RunObservedStatus,
+      ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
       updatedAt: getUpdatedAt(status),
     };
   } catch {
@@ -365,8 +378,11 @@ export function detectRunTransitions(
         run: run.run,
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
+        ...(run.launchSource ? { launchSource: run.launchSource } : {}),
+        ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
         to: run.status,
+        ...(run.tool ? { tool: run.tool } : {}),
       });
     }
     previous.set(run.run, run.status);
@@ -610,11 +626,35 @@ function getRunArtifacts(transition: RunTransition): string[] {
   ];
 }
 
+function isUserRecipeFile(file: string | undefined): boolean {
+  if (!file) return false;
+  const recipeRoot = resolve(Paths.getRecipeRoot());
+  const path = resolve(file);
+  return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
+}
+
+export function shouldSuggestRecipePersistence(
+  transition: RunTransition,
+): boolean {
+  return (
+    transition.to === "done" &&
+    transition.launchSource === "spawn" &&
+    !transition.tool &&
+    !isUserRecipeFile(transition.recipeFile)
+  );
+}
+
+function formatRecipePersistenceSuggestion(transition: RunTransition): string {
+  if (!shouldSuggestRecipePersistence(transition)) return "";
+  return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern looks reusable, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
+  const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.`;
+    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.${persistenceSuggestion}`;
   if (transition.to === "failed")
     return `Run ${transition.run} failed.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail for details.`;
   if (transition.to === "cancelled")

package/lib/prompts.ts

@@ -29,7 +29,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged recipes are lower-priority components, not tools by location.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged recipes are lower-priority components; offer to save successful direct spawn patterns only after confirmation.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;

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/lib/tools.ts

@@ -578,6 +578,7 @@ export function createSpawnToolDefinition<
               : typeof input.recipe === "string"
                 ? input.recipe
                 : undefined,
+          launch_source: "spawn",
           ownerId: getRunOwnerId(ctx),
           run_id: runId,
           state_dir:
@@ -1301,6 +1302,7 @@ export function createRuntimeToolDefinition(
           const meta = AsyncRuns.startRun(
             {
               ...base,
+              launch_source: "tool",
               ownerId: getRunOwnerId(ctx),
               run_id: runId,
               tool: cfg.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "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.3
 ---
 
 # Actors (pi-actors)
@@ -63,6 +63,7 @@ Rules:
 
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
+- When a directly spawned inline/ad hoc actor completes successfully and the follow-up suggests persistence, offer to save it as a recipe/tool; ask before writing `~/.pi/agent/recipes`.
 - Use stable `as` names when you will inspect or message the actor later.
 - `async: true` on the recipe is the detached run switch.
 
@@ -124,7 +125,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 +219,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.3
 ---
 
 # Swarm