@llblab/pi-actors 0.34.1 → 0.35.0

package/BACKLOG.md

@@ -53,24 +53,6 @@ No open hotfix items.
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-### M-18 Draft Recipe Promotion UX
-
-- Priority: High.
-- Status: Planned.
-- Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
-- Why now: Draft recipes under `~/.pi/agent/recipes/drafts` are replayable but intentionally not active tools, and the two-stage memory model needs an explicit operator-gated promotion path.
-- Direction:
-  - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
-  - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
-  - Run recipe validation/doctor before writing and expose collision/shadowing diagnostics.
-  - Preserve draft files unless deletion is explicitly requested.
-  - Prefer extending existing registry/tool surfaces over adding a new public noun.
-- Acceptance:
-  - Draft recipes remain non-tools until promotion.
-  - Promotion writes atomically and never auto-promotes.
-  - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
-  - Docs explain draft memory vs active tool memory in one compact section.
-
 ### M-19 Recipe Doctor Risk Labels v2
 
 - Priority: Medium.
@@ -154,7 +136,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-18 Draft Recipe Promotion UX.
-Then: M-19 Recipe Doctor Risk Labels v2.
+Next milestone: M-19 Recipe Doctor Risk Labels v2.
+Then: M-20 Runtime Recipe Triage.
 Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
 ```

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.35.0: Draft Recipe Promotion UX
+
+- `[Recipes]` Completed M-18 Draft Recipe Promotion UX: `inspect target=recipes view=summary verbose=true` now exposes draft timestamps, fingerprints, validation state, source run when known, and template previews, while `register_tool name=<tool> draft=<path>` promotes a validated draft into active recipe memory without deleting the draft and rejects collisions unless `update=true` is explicit.
+
 ## 0.34.1: Message Delivery Outcome Hotfix
 
 - `[Dogfood]` Added a deterministic actor-worker stale-claim smoke covering an intentionally claimed branch inbox record; the worker now reports stale claim counts in both `worker-status.json` and its awaiting-assignment room event without adding auto-recovery or scheduler policy.

package/README.md

@@ -207,7 +207,8 @@ Rules:
 - User recipes override same-name lower-priority recipes;
 - Same-id JSON recipes shadow Markdown recipes in the same priority layer;
 - Packaged recipes are standard-library components, not automatically installed operator policy;
-- `register_tool` creates, updates, lists, or deletes user recipe files through the normal agent interface.
+- Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools;
+- `register_tool` creates, updates, lists, deletes, or explicitly promotes draft recipe files through the normal agent interface.
 
 Example foreground tool:
 
@@ -226,6 +227,14 @@ register_tool name=docs_review \
   args="scope:path,model:string"
 ```
 
+Promote a successful captured draft only after an explicit operator decision:
+
+```text
+register_tool name=docs_review draft=~/.pi/agent/recipes/drafts/spawned-run.json
+```
+
+Promotion validates the draft, writes `~/.pi/agent/recipes/<name>.json`, preserves the draft, and rejects collisions unless `update=true` is supplied.
+
 Inspect the discovered registry:
 
 ```text

package/dist/lib/prompts.d.ts

@@ -10,6 +10,7 @@ export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local
 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 async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
     readonly state_dir: "Optional async run state directory for a co-located template recipe.";
     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.";

package/dist/lib/prompts.js

@@ -30,6 +30,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 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.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
     state_dir: "Optional async run state directory for a co-located template recipe.",
     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.",

package/dist/lib/recipes-discovery.js

@@ -425,14 +425,39 @@ export function getShadowedLaunchDiagnostic(result, id) {
         reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
     };
 }
+function templatePreview(value) {
+    const rendered = typeof value === "string"
+        ? value
+        : value === undefined
+            ? undefined
+            : JSON.stringify(value);
+    return rendered && rendered.length > 120
+        ? `${rendered.slice(0, 117)}...`
+        : rendered;
+}
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
         const id = RecipesReferences.getRecipeIdFromPath(path);
+        const bytes = readFileSync(path);
+        const stat = statSync(path);
         const config = RecipesReferences.readRawRecipeConfig(path);
+        const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+        const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+        const sourceRun = String(config?.description ?? "").match(/spawn run ([^\s]+)/)?.[1];
+        const preview = templatePreview(config?.template);
         return {
             id,
             path,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength,
+            created_at: stat.birthtime.toISOString(),
+            modified_at: stat.mtime.toISOString(),
+            valid: Boolean(resolved),
+            diagnostics,
             ...(config?.description ? { description: config.description } : {}),
+            ...(sourceRun ? { source_run: sourceRun } : {}),
+            ...(config?.async !== undefined ? { async: config.async } : {}),
+            ...(preview ? { template_preview: preview } : {}),
         };
     });
 }

package/dist/lib/registry.d.ts

@@ -11,6 +11,7 @@ export interface RegisterToolInput {
     async?: boolean;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue | null;
+    draft?: string;
     args?: string;
     update?: boolean;
     values?: Record<string, unknown>;
@@ -20,6 +21,8 @@ export interface RegisterToolResultDetails {
     async?: boolean;
     config?: string;
     defaults?: Record<string, string>;
+    draft?: string;
+    promoted?: boolean;
     recipeName?: string;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue;

package/dist/lib/registry.js

@@ -4,7 +4,7 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as ExecutionOutput from "./execution-output.js";
 import { writeJsonAtomic } from "./file-state.js";
@@ -32,6 +32,62 @@ function getRecipeRoot(deps) {
 function getToolRecipePath(deps, name) {
     return join(getRecipeRoot(deps), `${name}.json`);
 }
+function assertDraftPath(deps, draft) {
+    const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+    const path = resolve(draft);
+    const relation = relative(draftRoot, path);
+    if (relation === "" ||
+        relation.startsWith("..") ||
+        resolve(relation) === relation) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`));
+    }
+    if (!existsSync(path)) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+    }
+    return path;
+}
+function promoteDraftRecipe(name, input, ctx, deps) {
+    const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+    const targetPath = getToolRecipePath(deps, name);
+    const tools = deps.getTools();
+    const existing = tools.get(name);
+    const conflict = deps.getExternalToolConflict(name);
+    if (conflict)
+        throw new Error(ExecutionOutput.formatToolText(conflict));
+    if ((existing || existsSync(targetPath)) && !input.update) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+    if (!config) {
+        const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid${reason ? `: ${reason}` : "."}`));
+    }
+    const promoted = buildConfig(name, {
+        ...input,
+        description: input.description ?? config.description,
+        template: draftPath,
+    }, existing);
+    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeJsonAtomic(targetPath, raw);
+    promoted.template = targetPath;
+    promoted.sourcePath = targetPath;
+    tools.set(name, promoted);
+    deps.registerRuntimeTool(promoted);
+    deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`)),
+        ],
+        details: {
+            args: promoted.args,
+            config: targetPath,
+            draft: draftPath,
+            promoted: true,
+            tool: name,
+        },
+    };
+}
 function persistToolRecipe(deps, cfg) {
     const path = getToolRecipePath(deps, cfg.name);
     mkdirSync(dirname(path), { recursive: true });
@@ -173,6 +229,9 @@ export async function executeRegisterTool(params, ctx, deps) {
     if (deps.reservedToolNames.has(name)) {
         throw new Error(ExecutionOutput.formatToolText(`Reserved tool name: ${name}`));
     }
+    if (typeof input.draft === "string" && input.draft.trim()) {
+        return promoteDraftRecipe(name, input, ctx, deps);
+    }
     const templateProvided = Object.hasOwn(input, "template");
     const template = getInputTemplate(input.template);
     if (templateProvided && (template === null || template === ""))

package/dist/lib/tools-register.js

@@ -24,6 +24,7 @@ export function createRegisterToolDefinition(deps) {
             args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
             async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
             description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
+            draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
             name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
             state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
             template: unionSchema([

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.34.1
+  version: 0.35.0
 ---
 
 # Actors (pi-actors)

package/dist/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.34.1
+  version: 0.35.0
 ---
 
 # Swarm

package/docs/tool-registry.md

@@ -10,7 +10,7 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 
 - `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
-- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
+- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one with `register_tool name=<tool_name> draft=<draft_path>` or by manually moving/copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths, timestamps, fingerprints, validation state, source run when known, descriptions, and template previews for explicit replay or promotion.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
@@ -51,7 +51,7 @@ register_tool name=call_subagent \
   template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
-Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding.
+Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding. To promote a captured draft, pass `name` plus `draft` with a path under `~/.pi/agent/recipes/drafts`; promotion validates the draft before writing `~/.pi/agent/recipes/<name>.json`, preserves the draft file, rejects name collisions unless `update=true`, and leaves shadowing evidence visible through `inspect target=recipes view=summary` or `view=doctor`.
 
 `template` may also be a standard command-template sequence for multi-step tools. Timeout is disabled by default; add explicit positive `timeout` values when individual steps should fail closed:
 

package/lib/prompts.ts

@@ -38,6 +38,8 @@ 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.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
   state_dir:

package/lib/recipes-discovery.ts

@@ -574,14 +574,43 @@ export function getShadowedLaunchDiagnostic(
   };
 }
 
+function templatePreview(value: unknown): string | undefined {
+  const rendered =
+    typeof value === "string"
+      ? value
+      : value === undefined
+        ? undefined
+        : JSON.stringify(value);
+  return rendered && rendered.length > 120
+    ? `${rendered.slice(0, 117)}...`
+    : rendered;
+}
+
 export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
     const id = RecipesReferences.getRecipeIdFromPath(path);
+    const bytes = readFileSync(path);
+    const stat = statSync(path);
     const config = RecipesReferences.readRawRecipeConfig(path);
+    const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+    const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+    const sourceRun = String(config?.description ?? "").match(
+      /spawn run ([^\s]+)/,
+    )?.[1];
+    const preview = templatePreview(config?.template);
     return {
       id,
       path,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      size: bytes.byteLength,
+      created_at: stat.birthtime.toISOString(),
+      modified_at: stat.mtime.toISOString(),
+      valid: Boolean(resolved),
+      diagnostics,
       ...(config?.description ? { description: config.description } : {}),
+      ...(sourceRun ? { source_run: sourceRun } : {}),
+      ...(config?.async !== undefined ? { async: config.async } : {}),
+      ...(preview ? { template_preview: preview } : {}),
     };
   });
 }

package/lib/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
@@ -22,6 +22,7 @@ export interface RegisterToolInput {
   async?: boolean;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue | null;
+  draft?: string;
   args?: string;
   update?: boolean;
   values?: Record<string, unknown>;
@@ -32,6 +33,8 @@ export interface RegisterToolResultDetails {
   async?: boolean;
   config?: string;
   defaults?: Record<string, string>;
+  draft?: string;
+  promoted?: boolean;
   recipeName?: string;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue;
@@ -95,6 +98,93 @@ function getToolRecipePath<TContext>(
   return join(getRecipeRoot(deps), `${name}.json`);
 }
 
+function assertDraftPath<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  draft: string,
+): string {
+  const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+  const path = resolve(draft);
+  const relation = relative(draftRoot, path);
+  if (
+    relation === "" ||
+    relation.startsWith("..") ||
+    resolve(relation) === relation
+  ) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`,
+      ),
+    );
+  }
+  if (!existsSync(path)) {
+    throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+  }
+  return path;
+}
+
+function promoteDraftRecipe<TContext>(
+  name: string,
+  input: RegisterToolInput,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+  const targetPath = getToolRecipePath(deps, name);
+  const tools = deps.getTools();
+  const existing = tools.get(name);
+  const conflict = deps.getExternalToolConflict(name);
+  if (conflict) throw new Error(ExecutionOutput.formatToolText(conflict));
+  if ((existing || existsSync(targetPath)) && !input.update) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Tool "${name}" already registered. Use update=true to overwrite.`,
+      ),
+    );
+  }
+  const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+  if (!config) {
+    const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft recipe is invalid${reason ? `: ${reason}` : "."}`,
+      ),
+    );
+  }
+  const promoted = buildConfig(
+    name,
+    {
+      ...input,
+      description: input.description ?? config.description,
+      template: draftPath,
+    },
+    existing,
+  );
+  const raw = RecipesReferences.readRawRecipeConfig(draftPath)!;
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeJsonAtomic(targetPath, raw);
+  promoted.template = targetPath;
+  promoted.sourcePath = targetPath;
+  tools.set(name, promoted);
+  deps.registerRuntimeTool(promoted);
+  deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+  return {
+    content: [
+      textContent(
+        ExecutionOutput.formatToolText(
+          `${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`,
+        ),
+      ),
+    ],
+    details: {
+      args: promoted.args,
+      config: targetPath,
+      draft: draftPath,
+      promoted: true,
+      tool: name,
+    } as RegisterToolResultDetails & Record<string, unknown>,
+  };
+}
+
 function persistToolRecipe<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
   cfg: Config.RegisteredTool,
@@ -284,6 +374,9 @@ export async function executeRegisterTool<TContext>(
       ExecutionOutput.formatToolText(`Reserved tool name: ${name}`),
     );
   }
+  if (typeof input.draft === "string" && input.draft.trim()) {
+    return promoteDraftRecipe(name, input, ctx, deps);
+  }
   const templateProvided = Object.hasOwn(input, "template");
   const template = getInputTemplate(input.template);
   if (templateProvided && (template === null || template === ""))

package/lib/tools-register.ts

@@ -36,6 +36,7 @@ export function createRegisterToolDefinition<TContext>(
         description: stringSchema(
           Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description,
         ),
+        draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
         name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
         state_dir: stringSchema(
           Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.34.1
+  version: 0.35.0
 ---
 
 # Actors (pi-actors)

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.34.1
+  version: 0.35.0
 ---
 
 # Swarm