@llblab/pi-actors 0.31.0 → 0.33.0

package/dist/lib/tools.js

@@ -168,8 +168,9 @@ function compactAsyncRunStatus(value) {
         tokens.push(`code=${String(result.code)}`);
     if (result.killed === true)
         tokens.push("killed=true");
-    if (status.candidate_recipe)
-        tokens.push(`candidate_recipe=${String(status.candidate_recipe)}`);
+    const draftRecipe = status.draft_recipe;
+    if (draftRecipe)
+        tokens.push(`draft_recipe=${String(draftRecipe)}`);
     const nextActions = actorRunNextActions(run);
     if (nextActions.length > 0)
         tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
@@ -357,6 +358,15 @@ function compactArtifactPath(value) {
     const record = asRecord(value);
     return String(record.path ?? "<missing>");
 }
+function artifactNextActions(run, artifacts) {
+    const id = String(run ?? "").trim();
+    if (!id || Object.keys(artifacts).length === 0)
+        return [];
+    return [
+        `inspect target=run:${id} view=artifacts verbose=true`,
+        `inspect target=run:${id} view=messages`,
+    ];
+}
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
     const artifacts = asRecord(status.artifacts);
@@ -375,7 +385,11 @@ function compactActorFiles(status) {
             .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
             .join(",")}`
         : "";
-    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
+    const nextActions = artifactNextActions(run, artifacts);
+    const nextText = nextActions.length
+        ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
 }
 function summarizeOtherSessions(currentSession, allRuns) {
     const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
@@ -490,13 +504,47 @@ function compactRecipeDoctor(summary) {
     }
     for (const item of remediations.slice(0, 8)) {
         const action = compactPreview(item.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
-        const blocked = item.blocked_candidate
-            ? ` blocked=${compactPreview(item.blocked_candidate, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
+        const blocked = item.blocked_fallback
+            ? ` blocked=${compactPreview(item.blocked_fallback, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
             : "";
         lines.push(`${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`);
     }
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    if (nextActions.length > 0)
+        lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
     return `\n${lines.join("\n")}`;
 }
+function recipeRegistryNextActions(summary, view) {
+    const actions = [];
+    const drafts = Array.isArray(summary.drafts)
+        ? summary.drafts
+        : [];
+    const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
+    const diagnostics = Array.isArray(summary.diagnostics)
+        ? summary.diagnostics.length
+        : 0;
+    const topAction = asRecord(summary.top_action);
+    if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
+        actions.push("inspect target=recipes view=doctor");
+    }
+    if (view === "doctor" && typeof topAction.action === "string") {
+        actions.push(String(topAction.action));
+    }
+    if (drafts.length > 0) {
+        actions.push("inspect target=recipes view=summary verbose=true");
+        const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
+        if (firstPath)
+            actions.push(`spawn file=${firstPath}`);
+    }
+    return [...new Set(actions)].slice(0, 4);
+}
+function compactNextActions(actions) {
+    return actions.length
+        ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+}
 function compactRecipeRegistry(summary) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
     const shadowed = Array.isArray(summary.shadowed)
@@ -509,13 +557,37 @@ function compactRecipeRegistry(summary) {
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
-    const candidates = Array.isArray(summary.candidates)
-        ? summary.candidates.length
-        : 0;
+    const drafts = Array.isArray(summary.drafts) ? summary.drafts.length : 0;
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations.length
         : 0;
-    return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+function actorMessageNextActions(message, result) {
+    const actions = [];
+    const address = ActorMessages.parseActorAddress(message.to);
+    if (result.delivery_error || result.sent === false) {
+        if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=status`);
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+        else if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+            actions.push(`inspect target=run:${address.value} view=status`);
+        }
+    }
+    if (result.queued === true) {
+        if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+        }
+        else if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+    }
+    return [...new Set(actions)].slice(0, 3);
 }
 function compactActorMessageResult(message, result) {
     const tokens = [
@@ -548,6 +620,11 @@ function compactActorMessageResult(message, result) {
     if (result.delivery_error) {
         tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
     }
+    const nextActions = Array.isArray(result.next_actions)
+        ? result.next_actions
+        : actorMessageNextActions(message, result);
+    if (nextActions.length > 0)
+        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
     return `\n${tokens.join(" ")}`;
 }
 function maybeJsonText(value, verbose, compact) {
@@ -621,10 +698,10 @@ function shadowedRecipeLaunchDiagnostic(recipe) {
     ]);
     return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
 }
-function candidateRecipeName(run) {
+function draftRecipeName(run) {
     return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
 }
-function candidateRecipeDefaults(values) {
+function draftRecipeDefaults(values) {
     const ignored = new Set([
         "actor_address",
         "communication_file",
@@ -635,21 +712,21 @@ function candidateRecipeDefaults(values) {
     const defaults = Object.fromEntries(Object.entries(values).filter(([key]) => !ignored.has(key)));
     return Object.keys(defaults).length > 0 ? defaults : undefined;
 }
-function writeSpawnCandidateRecipe(input, meta) {
+function writeSpawnDraftRecipe(input, meta) {
     if (process.env.NODE_TEST_CONTEXT &&
-        process.env.PI_ACTORS_ENABLE_SPAWN_CANDIDATES_IN_TEST !== "1")
+        process.env.PI_ACTORS_ENABLE_SPAWN_DRAFTS_IN_TEST !== "1")
         return undefined;
     if (input.template === undefined ||
         input.file !== undefined ||
         input.recipe !== undefined)
         return undefined;
-    const root = Paths.getRecipeCandidateRoot();
+    const root = Paths.getRecipeDraftRoot();
     mkdirSync(root, { recursive: true });
-    const path = join(root, candidateRecipeName(String(meta.run)));
-    const defaults = candidateRecipeDefaults(meta.values);
+    const path = join(root, draftRecipeName(String(meta.run)));
+    const defaults = draftRecipeDefaults(meta.values);
     const recipe = {
         async: true,
-        description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+        description: `Draft recipe captured from spawn run ${String(meta.run)}`,
         ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
         ...(defaults ? { defaults } : {}),
         template: input.template,
@@ -662,7 +739,7 @@ function enhanceSpawnRecipeError(error, recipe) {
     if (!diagnostic)
         return error instanceof Error ? error : new Error(String(error));
     const original = error instanceof Error ? error.message : String(error);
-    return Object.assign(new Error(`${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_candidate=${diagnostic.blocked_candidate} hint=${diagnostic.hint}`), {
+    return Object.assign(new Error(`${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_fallback=${diagnostic.blocked_fallback} hint=${diagnostic.hint}`), {
         ...diagnostic,
         original_error: original,
     });
@@ -783,11 +860,11 @@ export function createSpawnToolDefinition() {
             catch (error) {
                 throw enhanceSpawnRecipeError(error, recipe);
             }
-            const candidateRecipe = writeSpawnCandidateRecipe(input, meta);
+            const draftRecipe = writeSpawnDraftRecipe(input, meta);
             const nextActions = actorRunNextActions(meta.run);
             const details = {
                 ...meta,
-                ...(candidateRecipe ? { candidate_recipe: candidateRecipe } : {}),
+                ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
                 next_actions: nextActions,
             };
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -814,15 +891,29 @@ function requireContextSessionId(ctx, actor) {
     }
     return sessionId;
 }
+function sessionMismatchError(input) {
+    const ownerSession = input.expectedSession ?? "none";
+    const currentSession = input.currentSession ?? "none";
+    const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+    const hintTarget = input.expectedSession
+        ? `session:${input.expectedSession}`
+        : "session:all";
+    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
+        current_session: input.currentSession,
+        hint: `inspect target=${hintTarget} view=status`,
+        owner_session: input.expectedSession,
+        reason: "session_mismatch",
+        run: input.run,
+        target: input.target,
+    });
+}
 function assertRunAccessibleToContext(runId, ctx) {
     const status = AsyncRuns.getRunStatus(runId);
     const sessionId = getContextSessionId(ctx);
     if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-        throw Object.assign(new Error(`run:${runId} reason=session_mismatch owner_session=${status.ownerId} current_session=${sessionId} hint=inspect_session:${status.ownerId}`), {
-            current_session: sessionId,
-            hint: `inspect target=session:${status.ownerId} view=status`,
-            owner_session: status.ownerId,
-            reason: "session_mismatch",
+        throw sessionMismatchError({
+            currentSession: sessionId,
+            expectedSession: String(status.ownerId),
             run: runId,
         });
     }
@@ -835,13 +926,13 @@ export function createInspectToolDefinition(deps = {}) {
     return {
         name: "inspect",
         label: "Inspect",
-        description: "Intentionally inspect an actor at decision points, after follow-ups, or during diagnosis instead of polling. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
+        description: "Intentionally inspect actors at decision points, after follow-ups, or during diagnosis instead of polling. Core targets are run:<id> and tool:<name>; advanced targets include branch:<run>/<branch>, room:<run>, coordinator, session:<id>, and session:all.",
         parameters: objectSchema({
             lines: stringSchema("Line count for tail/messages views. Default 40."),
             status: stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-            target: stringSchema("Actor address to inspect, e.g. run:<id>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>."),
+            target: stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
             verbose: booleanSchema("Return full JSON instead of compact text where available."),
-            view: stringSchema("Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or contacts."),
+            view: stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
         }, ["target", "view"]),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
@@ -863,9 +954,13 @@ export function createInspectToolDefinition(deps = {}) {
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
                 const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-                const summary = {
+                const summaryBase = {
                     ...RecipeDiscovery.summarizeDiscovery(discovered),
-                    candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
+                    drafts: RecipeDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+                };
+                const summary = {
+                    ...summaryBase,
+                    next_actions: recipeRegistryNextActions(summaryBase, view),
                 };
                 return {
                     content: [
@@ -1084,7 +1179,11 @@ export function createInspectToolDefinition(deps = {}) {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
                     const details = artifactManifest
-                        ? { ...status, artifact_manifest: artifactManifest }
+                        ? {
+                            ...status,
+                            artifact_manifest: artifactManifest,
+                            next_actions: artifactNextActions(status.run ?? runId, asRecord(status.artifacts)),
+                        }
                         : status;
                     return {
                         content: [
@@ -1139,7 +1238,7 @@ export function createActorMessageToolDefinition(deps = {}) {
     return {
         name: "message",
         label: "Message",
-        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
+        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
         parameters: objectSchema({
             body: unionSchema([
                 stringSchema("Message body. For run:<id>, this is the run-local command line."),
@@ -1151,7 +1250,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             metadata: looseObjectSchema("Optional structured metadata for routing or domain hints."),
             reply_to: stringSchema("Optional message id this message replies to."),
             summary: stringSchema("Optional short human-facing summary."),
-            to: stringSchema("Destination actor address, e.g. run:<id>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>."),
+            to: stringSchema("Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>."),
             type: stringSchema("Semantic message type, e.g. control.approve or checkpoint.needs_scope."),
             verbose: booleanSchema("Return full JSON instead of compact text."),
         }, ["to", "type"]),
@@ -1266,10 +1365,20 @@ export function createActorMessageToolDefinition(deps = {}) {
                 const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
                 if (address.kind === "session") {
                     if (!senderStatus.ownerId) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got no owner.`);
+                        throw sessionMismatchError({
+                            currentSession: undefined,
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                     if (senderStatus.ownerId !== address.value) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`);
+                        throw sessionMismatchError({
+                            currentSession: String(senderStatus.ownerId),
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                 }
                 result = AsyncRuns.appendRunOutboxEvent(sender.value, {
@@ -1291,14 +1400,18 @@ export function createActorMessageToolDefinition(deps = {}) {
             else {
                 throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
             }
+            const nextActions = actorMessageNextActions(message, result);
+            const resultWithNext = nextActions.length
+                ? { ...result, next_actions: nextActions }
+                : result;
             return {
                 content: [
                     {
                         type: "text",
-                        text: maybeJsonText({ message, result }, input.verbose === true, compactActorMessageResult(message, result)),
+                        text: maybeJsonText({ message, result: resultWithNext }, input.verbose === true, compactActorMessageResult(message, resultWithNext)),
                     },
                 ],
-                details: { message, result },
+                details: { message, result: resultWithNext },
             };
         },
     };

package/dist/scripts/conformance.mjs

@@ -1,33 +1,49 @@
 #!/usr/bin/env node
 
 /**
- * Internal conformance runner shim.
+ * Internal conformance runner.
  *
- * Runtime logic lives in lib/conformance.ts and is compiled to
- * dist/lib/conformance.js for installed JS-only packages.
+ * This script is intentionally standalone package/release glue rather than a
+ * lib domain: it only selects regression suites and formats their summary.
  */
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const conformanceSuites = [
+  "tests/protocol-examples.test.ts",
+  "tests/recipe-discovery.test.ts",
+  "tests/registry.test.ts",
+  "tests/runtime-registry.test.ts",
+  "tests/async-runs.test.ts",
+  "tests/actor-rooms.test.ts",
+  "tests/tools.test.ts",
+];
 
 function packageRoot() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function mainModulePath() {
-  const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "conformance.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "conformance.ts");
-}
+const result = spawnSync(
+  process.execPath,
+  ["--experimental-strip-types", "--test", ...conformanceSuites],
+  { cwd: packageRoot(), encoding: "utf8", stdio: "pipe" },
+);
 
-const { runConformance } = await import(pathToFileURL(mainModulePath()).href);
-const report = runConformance(packageRoot());
+const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+const summary = output
+  .split("\n")
+  .filter((line) =>
+    /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line),
+  )
+  .join("\n");
 
 console.log("pi-actors conformance");
-console.log(`suites ${report.suites}`);
-if (report.summary) console.log(report.summary);
-if (report.code !== 0) {
-  console.error(report.output.trimEnd());
-  process.exit(report.code);
+console.log(`suites ${conformanceSuites.length}`);
+
+if (summary) console.log(summary);
+if ((result.status ?? 1) !== 0) {
+  console.error(output.trimEnd());
+  process.exit(result.status ?? 1);
 }

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.31.0
+  version: 0.33.0
 ---
 
 # Actors (pi-actors)
@@ -39,12 +39,11 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
-- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
-- **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
-- **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
+- **Mailbox**: interaction contract: message types the actor accepts/emits.
+- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
 
 ## Three Verbs
 
@@ -86,8 +85,9 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
-- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
+- Core addresses: `run:<id>`, `tool:<name>`.
+- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
+- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
@@ -99,12 +99,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
-{ "target": "room:repo-health", "view": "status" }
-{ "target": "room:repo-health", "view": "roster" }
-{ "target": "room:repo-health", "view": "contacts" }
-{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
@@ -116,10 +111,10 @@ Views:
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
 - `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
-- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- `contacts`: roster-derived direct-message targets without full roster metadata.
-- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
+- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
+- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
+- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -218,13 +213,13 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/candidates/*.json` is candidate memory captured from successful inline `spawn template=...` runs. Candidates are not registered tools and do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow candidate memory by trying ad hoc actors successfully. Treat both as executable habits: candidates are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave candidate recipes as replayable evidence, not active tools. If a candidate is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
 
 Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 

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.31.0
+  version: 0.33.0
 ---
 
 # Swarm
@@ -30,8 +30,8 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, candidate recipes, command templates, async runs, or services.
-- `Candidate Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn under `~/.pi/agent/recipes/drafts`. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.

package/docs/actor-messages.md

@@ -199,7 +199,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. Ownership denials use `reason=session_mismatch owner_session=<id> current_session=<id> hint=inspect_session:<id>`; recover by inspecting the hinted `session:<id>` instead of forcing cross-session control. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 

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/candidates/*.json` are captured inline-spawn candidates, 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 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.
 - 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`.
@@ -31,9 +31,9 @@ inspect target=recipes view=summary verbose=true
 
 `tool:pi-actors` is a reserved runtime-status actor: it reports the loaded package version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available. Use it after reloads to confirm which extension code is actually live.
 
-The recipe summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority candidate paths when a broken or disabled higher-priority recipe masks a fallback.
+The recipe summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority fallback paths when a broken or disabled higher-priority recipe masks a fallback.
 
-Routine shadowing is quiet. If a bare `spawn` recipe launch already fails because an invalid or `disabled: true` user recipe blocks a lower-priority candidate, the launch error adds compact tokens such as `reason=shadowed_invalid` or `reason=shadowed_disabled`, `active_path`, `blocked_candidate`, and `hint=inspect_recipes_doctor`.
+Routine shadowing is quiet. If a bare `spawn` recipe launch already fails because an invalid or `disabled: true` user recipe blocks a lower-priority fallback, the launch error adds compact tokens such as `reason=shadowed_invalid` or `reason=shadowed_disabled`, `active_path`, `blocked_fallback`, and `hint=inspect_recipes_doctor`.
 
 ## Registering Tools
 

package/index.ts

@@ -102,7 +102,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     onChange: () =>
       activeRunContext && scheduleRunEventUpdate(activeRunContext),
   });
-  const actorToolDefinitions = new Map<string, any>();
+  const actorToolDefinitions = new Map<string, Tools.ActorToolDefinition>();
   const runtime = Runtime.createAutoToolsRuntime({
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,

package/lib/observability.ts

@@ -1021,19 +1021,31 @@ function formatRecipePersistenceSuggestion(transition: RunTransition): string {
   return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, 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.`;
 }
 
+function formatTransitionNextActions(transition: RunTransition): string {
+  const actions = [
+    `inspect target=run:${transition.run} view=status`,
+    transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
+      ? `inspect target=run:${transition.run} view=artifacts`
+      : `inspect target=run:${transition.run} view=tail`,
+    `inspect target=run:${transition.run} view=messages`,
+  ].filter(Boolean);
+  return `\nNext actions: ${actions.join(" | ")}`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+  const nextActions = formatTransitionNextActions(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.${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${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.`;
+    return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was cancelled.${nextActions}`;
   if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was force-killed.${nextActions}`;
   if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
-  return `Run ${transition.run} finished with status ${transition.to}. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} exited before writing a result.${nextActions}`;
+  return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
 }