@llblab/pi-actors 0.19.2 → 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`, 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
+- `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,13 @@
 # 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.

package/README.md

@@ -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/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;
@@ -96,6 +99,7 @@ export interface AsyncRunMeta {
   argv: string[];
   createdAt: string;
   cwd: string;
+  launch_source?: AsyncRunLaunchSource;
   ownerId?: string;
   pid: number;
   recipe?: string;
@@ -414,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 } : {}),

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/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.2",
+  "version": "0.19.3",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

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.2
+  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.
 

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.2
+  version: 0.19.3
 ---
 
 # Swarm