@llblab/pi-actors 0.46.0 → 0.47.0

package/AGENTS.md

@@ -2,13 +2,14 @@
 
 ## Meta-Protocol Principles
 
-- `README.md`: human product entrypoint.
-- `AGENTS.md`: durable implementation protocol.
+- `README.md` and `docs/`: human-facing product entrypoint, concepts, and reference.
+- `skills/`: agent-facing operating protocols and Skill-local operational references.
+- injected system prompt: routing-only meta-protocol that selects the owning Skill.
+- `AGENTS.md`, source, and tests: implementation protocol and executable evidence.
 - `BACKLOG.md`: canonical future-only work.
 - `CHANGELOG.md`: completed delivery history.
-- `docs/README.md`: documentation index.
 
-Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
+Do not make normal-use Skills depend on README/docs, do not copy Skill operating manuals into the system prompt, and do not present implementation evidence as the agent operating path. Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
 
 ## Concept
 
@@ -37,7 +38,8 @@ Pi host
      -> lib/inspector*.ts             owner-filtered actor-instance inspection
      -> scripts/*.mjs                 process/service entrypoints
      -> skills/*/recipes/*            Skill-owned Recipe components
-     -> skills/* + docs/*             agent and human guidance
+     -> skills/*                      agent operating protocols
+     -> README.md / docs/*            human product guidance
 ```
 
 `index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.47.0: Agent-Native Actor UX
+
+- `Skill-First Operation`: Replaced the injected product manual with a compact Skill-routing meta-protocol. `actors` is now the decision-first authority for generic Recipe/tool/Run mechanics, capability Skills own capability choice, and `swarm` owns only multi-actor methodology.
+- `Persistent Capability Authoring`: Added explicit, mutually exclusive `register_tool from`, `template`, and `draft` modes; public caller `defaults`; canonical Skill/file resolution; compact direct delegation; inherited descriptions, async contracts, typed args, artifacts, Control, and runtime origins; and removal of public `values`.
+- `Registration Truth UX`: Registration now reports logical source, effective required/optional args, persistence, registry/host/active-tool state, callability, activation boundary, and bounded next actions without raw config or executable template payloads. Failed activation retains rollback guarantees.
+- `Focused Diagnosis`: Added `inspect target=recipes view=doctor identity=<skill>/<recipe>` with active ownership, exact resolvability, partial-catalog state, portable source, generation, rejection, and next actions. Tool status now includes source, effective args, activation boundary, and separate spawn/tool usage.
+- `Capability Protocols`: Rewrote all six Skill descriptions as routing triggers and made Media, Artifacts, Project Work, and Recipe Memory compact agent operating guides. Human installation, product, catalog, development, and release guidance remains independently owned by README/docs.
+- `Swarm Methodology`: Reduced Swarm to overhead admission, decomposition, disjoint ownership, lenses, quorum, conflict evidence, integration, and stop rules; moved deep review/development methods to Skill-local references and delegated all generic Run/Recipe mechanics to `actors`.
+- `Safe Recovery`: Inactive, missing, duplicate, removed, malformed, rejected, partial-catalog, and inactive-tool failures now preserve logical identity, redact physical Skill paths, and teach bounded public diagnosis/retry actions without copied contracts, helper paths, shell evaluation, backgrounding, or spawn substitution.
+- `Journey and Package Evidence`: Added deterministic Journeys A-G, reviewed fresh-agent Journey B evidence, and packed first-session parity for final Skills/prompt/references, `from` registration, source-equivalent schema, same-session activation, focused doctor, actual tool invocation, and unshipped `.agents/` evidence.
+
+## 0.46.1: Registration Truth
+
+- `Live Resolution`: Spawn, registration, registry admission/reload, schema derivation, and Inspect now consume one immutable session Recipe context. Skill-dependent user wrappers reconcile only after Pi supplies active Skills, watcher reloads retain the current generation, and stale session consumers fail closed.
+- `Effective Admission`: One user-Recipe admission path resolves direct delegation before persistence, inheriting async behavior, typed arguments/defaults, artifacts, Control, and runtime origins without copying maintained contracts. Malformed or mistyped wrappers fail before mutation, and failed updates roll back prior bytes, registry state, host definitions, and active tools.
+- `Schema Ownership`: Caller schemas preserve enum, bool, integer, number, path, and array types while centrally excluding runtime-owned inputs such as `recipe_dir`, `skill_dir`, `state_dir`, Trace/run identity, and runtime state roots. The intentional async `run_id` override remains public.
+- `Fail-Soft Catalog`: Active-Skill inventory returns valid components alongside bounded per-component rejections and an explicit partial state. Invalid unrelated Recipes and duplicate namespaces remain diagnosable without poisoning exact resolution of valid components.
+- `Activation and Observability`: Registration reports resolved, validated, persisted, registry, host, active-tool, and callable states from Pi host evidence. Recipe inspection adds generation, scan, watcher, portable-root, and partial-catalog state; tool status reports current activation and separate spawn/tool usage.
+- `Launch Truth and Dogfood`: Spawn and registered-tool launches expose distinct `launch_kind` evidence. Source and packed-package regressions activate `media/player`, quarantine an unrelated stale component, register and invoke a compact `music_player` in the same session, preserve inherited Control/schema, exercise repair reloads and negative cases, and reject shell/copy workarounds.
+
 ## 0.46.0: Skill-Owned Capability Packs
 
 - `Breaking Recipe Grammar`: File-backed identity now comes only from the filename; top-level Recipe `name`, nested Skill identities, JSON/Markdown stem collisions, bare references, and the old `std:` / `skill:` prefixes fail with migration guidance. Composition accepts exact `<active-skill>/<stem>` references or explicit `.json` / `.md` paths, with entry paths based at invocation cwd and relative imports based at their owning Recipe.

package/README.md

@@ -74,6 +74,7 @@ inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
 inspect target=runtime view=status
 inspect target=recipes view=status
+inspect target=recipes view=doctor identity=media/player
 inspect target=tool:my_tool view=status
 ```
 
@@ -81,7 +82,7 @@ A Run exposes exactly `recipe`, `trace`, and `control` views.
 
 ### `register_tool`
 
-Persist a trusted command template or Recipe-backed capability under `~/.pi/agent/recipes`. Registration remains separate from running Control.
+Persist a maintained Recipe with `register_tool name=<tool> from=<skill>/<recipe> defaults={...}`, or register a trusted command through the separate `template` mode. Definitions live under `~/.pi/agent/recipes`. Treat a tool as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
 
 ## Recipe
 

package/dist/lib/async-runs.d.ts

@@ -68,6 +68,7 @@ export interface AsyncRunMeta {
     argv: string[];
     createdAt: string;
     cwd: string;
+    launch_kind?: AsyncRunLaunchSource;
     launch_source?: AsyncRunLaunchSource;
     launch_correlation?: {
         correlation_id?: string;

package/dist/lib/async-runs.js

@@ -326,7 +326,10 @@ export function startRun(params, cwd, options = {}) {
             createdAt: new Date().toISOString(),
             cwd,
             ...(startParams.launch_source
-                ? { launch_source: startParams.launch_source }
+                ? {
+                    launch_kind: startParams.launch_source,
+                    launch_source: startParams.launch_source,
+                }
                 : {}),
             ...(startParams.launch_correlation
                 ? { launch_correlation: startParams.launch_correlation } : {}),

package/dist/lib/execution.d.ts

@@ -72,6 +72,7 @@ export interface RegisteredToolExecutionResult {
         command: string;
         fullOutputPath?: string;
         killed: boolean;
+        launch_kind: "tool";
         stderrBytes?: number;
         stderrCapturedBytes?: number;
         stderrFile?: string;

package/dist/lib/execution.js

@@ -709,6 +709,7 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
             command,
             fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
             killed: result.killed,
+            launch_kind: "tool",
             ...getCaptureDetails(result),
             ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
             ...(executed.failures.length > 0

package/dist/lib/extension-runtime.js

@@ -8,6 +8,7 @@ import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as Pi from "./pi.js";
 import * as Prompts from "./prompts.js";
+import * as RecipeResolution from "./recipes-context.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as RunUiRuntime from "./run-ui-runtime.js";
 import * as Runtime from "./runtime.js";
@@ -16,10 +17,16 @@ import * as Tools from "./tools.js";
 import * as ToolsResponse from "./tools-response.js";
 export function createActorExtensionRuntime(pi) {
     let activeRunContext;
-    const skillContextsBySession = new Map();
+    const recipeResolutionContextsBySession = new Map();
     const getRunOwnerId = Pi.getSessionId;
-    const getSkillContext = (ctx) => skillContextsBySession.get(getRunOwnerId(ctx)) ??
-        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+    const getRecipeResolutionContext = (ctx) => {
+        const sessionId = getRunOwnerId(ctx);
+        const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
+        if (!resolutionContext) {
+            throw new Error(`Recipe resolution context is unavailable for session ${sessionId}.`);
+        }
+        return resolutionContext;
+    };
     const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
         getActiveContext: () => activeRunContext,
         getRunOwnerId,
@@ -44,7 +51,7 @@ export function createActorExtensionRuntime(pi) {
                 if (ctx && typeof ctx === "object") {
                     nextArgs[4] = {
                         ...ctx,
-                        activeSkillRecipeContext: getSkillContext(ctx),
+                        recipeResolutionContext: getRecipeResolutionContext(ctx),
                         getThinkingLevel: () => pi.getThinkingLevel(),
                     };
                 }
@@ -61,6 +68,7 @@ export function createActorExtensionRuntime(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         exec: CommandTemplates.execCommandTemplate,
         getActiveTools: () => pi.getActiveTools(),
+        getAllTools: () => pi.getAllTools(),
         registerTool: (definition) => {
             const wrapped = withCurrentThinkingContext(definition);
             actorToolDefinitions.set(wrapped.name, wrapped);
@@ -69,10 +77,17 @@ export function createActorExtensionRuntime(pi) {
         reservedToolNames: Tools.RESERVED_TOOL_NAMES,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     });
-    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+        getResolutionContext: () => activeRunContext
+            ? getRecipeResolutionContext(activeRunContext)
+            : undefined,
+    });
     return {
         beforeAgentStart(systemPrompt, skills, ctx) {
-            skillContextsBySession.set(getRunOwnerId(ctx), RecipesReferences.createActiveSkillRecipeContext(skills));
+            const sessionId = getRunOwnerId(ctx);
+            const resolutionContext = RecipeResolution.createRecipeResolutionContext(sessionId, ctx.cwd, RecipesReferences.createActiveSkillRecipeContext(skills));
+            recipeResolutionContextsBySession.set(sessionId, resolutionContext);
+            runtime.loadTools(ctx, resolutionContext);
             return {
                 systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
             };
@@ -87,14 +102,15 @@ export function createActorExtensionRuntime(pi) {
                 automaticReview.schedule();
         },
         onSessionShutdown(reason, ctx) {
-            skillContextsBySession.delete(getRunOwnerId(ctx));
+            recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
             activeRunContext = undefined;
             automaticReview.close();
             recipeReload.close();
             runUiRuntime.shutdown(reason, ctx);
         },
         async onSessionStart(ctx) {
-            skillContextsBySession.set(getRunOwnerId(ctx), RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
+            const sessionId = getRunOwnerId(ctx);
+            recipeResolutionContextsBySession.set(sessionId, RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd));
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             activeRunContext = ctx;
             runUiRuntime.close();
@@ -104,7 +120,6 @@ export function createActorExtensionRuntime(pi) {
             if (activeRunContext !== ctx)
                 return;
             automaticReview.start(ctx);
-            runtime.loadTools(ctx);
             runUiRuntime.start(ctx);
             recipeReload.watch(ctx);
         },
@@ -113,6 +128,7 @@ export function createActorExtensionRuntime(pi) {
                 configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
                 getActiveTools: () => pi.getActiveTools(),
                 getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
+                getRuntimeToolStatus: runtime.getToolStatus,
                 handleRuntimeControl: automaticReview.handleControl,
                 registryRuntime: runtime,
                 setActiveTools: (toolNames) => pi.setActiveTools(toolNames),

package/dist/lib/inspector.js

@@ -115,6 +115,7 @@ export function readActorInspectorRecipe(stateDir) {
             logical_reference: primaryLogicalReference,
             ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
             source_kind: primarySourceKind,
+            launch_kind: meta.launch_kind ?? meta.launch_source,
             launch_source: meta.launch_source,
         }),
         launch: redactedRecord({

package/dist/lib/prompts.d.ts

@@ -4,20 +4,21 @@
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
 export declare const REGISTER_TOOL_DESCRIPTION: string;
-export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
+export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors Skill routing:\n- Treat active bundled Skills as the operating authority.\n- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.\n- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.\n- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.\n- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.\n- Treat persistence or registration as distinct from current callability; actors owns activation proof.\n- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.\n- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.\n- README and docs are human-facing references, not the normal agent operating path.\n- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
-    readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
+    readonly from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.";
+    readonly defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.";
+    readonly draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
-    readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
+    readonly template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
     readonly templateNull: "Delete the tool when template is null.";
     readonly args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast";
     readonly update: "Set to true to overwrite an existing tool registration.";
-    readonly values: "Optional default runtime placeholder values for a co-located template recipe.";
 };
 export declare function formatRegisteredToolPromptSnippet(template: unknown): string;
 export declare function formatRecipeToolPromptSnippet(recipe: string, asyncRecipe: boolean): string;

package/dist/lib/prompts.js

@@ -3,41 +3,40 @@
  * Zones: prompts, onboarding, tool schema copy
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
-export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from a command template, template recipe path, or co-located template recipe. " +
-    "Definitions are stored as recipe files under ~/.pi/agent/recipes across reloads. " +
-    "Use update=true to overwrite an existing tool, template=null/empty to delete.";
-export const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
+export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
+    "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+    "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
+export const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
 export const REGISTER_TOOL_GUIDELINES = [
-    "Use register_tool to wrap trusted local commands, scripts, programs, libraries, or template recipes as persistent pi tools.",
-    "After register_tool succeeds, the new tool is immediately callable and remains available after reload.",
+    "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
+    "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
+    "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
     'Set template=null or template="" in register_tool to delete a persisted tool.',
     "Set update=true in register_tool to overwrite an existing tool registration.",
 ];
-export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
-- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
-- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
-- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
-- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
-- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.
-- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
-- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
+- Treat active bundled Skills as the operating authority.
+- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.
+- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.
+- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.
+- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.
+- Treat persistence or registration as distinct from current callability; actors owns activation proof.
+- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.
+- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.
+- README and docs are human-facing references, not the normal agent operating path.
+- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
-    draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
+    from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.",
+    defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
+    draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
-    template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
+    template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.",
     templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
     templateNull: "Delete the tool when template is null.",
     args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
     update: "Set to true to overwrite an existing tool registration.",
-    values: "Optional default runtime placeholder values for a co-located template recipe.",
 };
 export function formatRegisteredToolPromptSnippet(template) {
     const rendered = typeof template === "string" ? template : JSON.stringify(template);

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

@@ -1,10 +1,19 @@
 /**
- * Recipe context prompt assembly.
- * Zones: async runner prompt context, recipe provenance, LLM child launches
- * Owns compact actor recipe context records appended to child-agent prompts.
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
  */
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
+export interface RecipeResolutionContext {
+    readonly activeSkills: RecipesReferences.ActiveSkillRecipeContext;
+    readonly cwd: string;
+    readonly generation: string;
+    readonly sessionId: string;
+}
+export declare function createRecipeResolutionContext(sessionId: string, cwd: string, activeSkills: RecipesReferences.ActiveSkillRecipeContext): RecipeResolutionContext;
+export declare function createEmptyRecipeResolutionContext(sessionId: string, cwd: string): RecipeResolutionContext;
 export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
     you_are_here?: true;
     you_are_here_path?: string;

package/dist/lib/recipes-context.js

@@ -1,10 +1,34 @@
 /**
- * Recipe context prompt assembly.
- * Zones: async runner prompt context, recipe provenance, LLM child launches
- * Owns compact actor recipe context records appended to child-agent prompts.
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
  */
+import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
-import { basename } from "node:path";
+import { basename, resolve } from "node:path";
+import * as RecipesReferences from "./recipes-references.js";
+export function createRecipeResolutionContext(sessionId, cwd, activeSkills) {
+    const normalizedSessionId = sessionId.trim();
+    if (!normalizedSessionId)
+        throw new Error("Recipe resolution session id is required.");
+    const normalizedCwd = resolve(cwd);
+    const generation = createHash("sha256")
+        .update(JSON.stringify({
+        activeSkills: RecipesReferences.getActiveSkillRecipeNamespaces(activeSkills),
+        cwd: normalizedCwd,
+        sessionId: normalizedSessionId,
+    }))
+        .digest("hex");
+    return Object.freeze({
+        activeSkills,
+        cwd: normalizedCwd,
+        generation,
+        sessionId: normalizedSessionId,
+    });
+}
+export function createEmptyRecipeResolutionContext(sessionId, cwd) {
+    return createRecipeResolutionContext(sessionId, cwd, RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
+}
 function commandName(command) {
     return basename(command).toLowerCase();
 }

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

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