@llblab/pi-actors 0.32.0 → 0.33.0

package/AGENTS.md

@@ -20,7 +20,7 @@ Pi host
   -> index.ts composition root
      -> lib/tools.ts / prompts.ts        public tool + injected prompt surface
      -> lib/runtime.ts / registry.ts     active user recipe tools
-     -> lib/recipe-*.ts                  packaged/user/candidate recipe discovery
+     -> lib/recipe-*.ts                  packaged/user/draft recipe discovery
      -> lib/async-runs.ts                spawn lifecycle and run state
      -> lib/actor-rooms.ts               room, roster, mailbox, communication log
      -> scripts/*.mjs                    thin process entrypoints
@@ -45,8 +45,8 @@ Pi host
 
 ## Repo Surfaces
 
-- `/scripts/*.mjs`: Stable executable shims for detached/helper processes.
-- `/lib/*.ts`: Compiled domain and script-entrypoint logic. Keep `scripts/*.mjs` lightweight and move substantive behavior into named domain modules so `dist/lib` is the JS-only runtime surface. This intentionally grows a standard library: script-born behavior should gain a clear domain name when reuse is plausible. Exception: self-contained application/build scripts with no expected second consumer, such as `music-player.mjs` or `build-dist.mjs`, may remain standalone `.mjs` files.
+- `/scripts/*.mjs`: Stable executables for detached/helper processes. Keep script-only release/build/glue behavior standalone when it has no plausible second consumer.
+- `/lib/*.ts`: Compiled domains and shared script-entrypoint logic. Move substantive script behavior into named domain modules only when reuse, tests, packaged JS-only execution, or clear ownership justifies it. Do not create a lib domain solely to keep a tiny script shim thin.
 - `/recipes/*.json`: Packaged standard recipe library. Keep recipes optional, composable, policy-light, and caller-configurable.
 - `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself.
 - `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples.
@@ -62,6 +62,7 @@ Pi host
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
 - Preserve runtime output discipline because tool output flows directly into agent context.
 - Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
+- Until a stable release greater than `1.x.x`, favor context compression over compatibility shims: do not preserve legacy actor-facing names, aliases, fields, env vars, paths, or docs solely for backward compatibility when a clearer current term exists. Remove compatibility layers in the same slice that renames a concept, and record the break in `CHANGELOG.md`.
 - Keep the project lens local-first and cybernetic: agents wrap durable local capabilities as actors, then use semantic tools and messages instead of repeatedly reconstructing shell commands.
 - Design recipes as agent-callable tools: make prompts, scopes, paths, models, and policy knobs public args/defaults when the caller should decide them at invocation time.
 - Decompose oversized bullets into sublists or hierarchy; long flat list items are a context-smell.

package/BACKLOG.md

@@ -67,20 +67,6 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Stale claims are reproducible and visible in worker status.
   - Tests cover stale-claim counting without adding scheduler/broker policy.
 
-### M-23 Tool Boundary Type Tightening
-
-- Priority: Low.
-- Status: Planned.
-- Goal: Remove avoidable `any` at the Pi/tool boundary where a narrow local type can express the real contract without broad rewiring.
-- Why now: `index.ts` still keeps runtime tool definitions in a `Map<string, any>`; this is small but visible in the composition root.
-- Direction:
-  - Add or reuse a narrow exported tool-definition type from the Pi adapter or tools domain.
-  - Keep SDK details behind `lib/pi.ts`.
-  - Do not introduce a broad type-modeling pass across every schema helper.
-- Acceptance:
-  - `index.ts` no longer uses `Map<string, any>` for actor tool definitions.
-  - TypeScript validation still passes without weakening public tool schemas.
-
 ### M-17 Message Delivery Outcome Contract
 
 - Priority: High.
@@ -103,7 +89,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 - 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/candidates` are replayable but intentionally not active tools; the directory name is retained for compatibility, and the two-stage memory model now needs an explicit operator-gated promotion path.
+- 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.
@@ -116,20 +102,6 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - 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-24 Registry Path Naming Cleanup
-
-- Priority: Low.
-- Status: Planned.
-- Goal: Reduce legacy-storage naming noise without changing the persistent file path.
-- Why now: `legacy-tool-registry.json` is still a compatibility storage path, but helper names and tests should make clear that the stable path is retained intentionally.
-- Direction:
-  - Prefer neutral helper/test wording such as registry path or retained registry storage path.
-  - Keep the on-disk filename unchanged unless a separate migration is justified.
-  - Do not reintroduce legacy migration code.
-- Acceptance:
-  - Path helpers and tests no longer imply an unfinished migration.
-  - Existing registry storage compatibility remains unchanged.
-
 ### M-19 Recipe Doctor Risk Labels v2
 
 - Priority: Medium.

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.33.0: Signal-First Compatibility Pruning
+
+- `[Breaking]` Removed pre-1.x compatibility shims for draft recipe terminology: draft captures now live under `~/.pi/agent/recipes/drafts`, recipe inspection no longer emits `candidates`, spawn details no longer emit `candidate_recipe`, and shadow diagnostics use `blocked_fallback` instead of `blocked_candidate`.
+- `[Context]` Documented the pre-stable policy that context compression wins over compatibility aliases until after a stable release greater than `1.x.x`; rename slices should remove legacy actor-facing names, fields, env vars, paths, and docs instead of carrying shims.
+- `[Breaking]` Renamed retained registry storage from `legacy-tool-registry.json` to `tool-registry.json`, removing the stale compatibility noun from runtime path helpers and tests.
+- `[Types]` Added a narrow actor tool-definition type and removed the remaining `Map<string, any>` from the composition root without expanding SDK type exposure.
+- `[Scripts]` Collapsed the conformance runner back into a standalone script and removed its one-off lib domain, documenting that script-only glue should stay self-contained unless reuse or packaged runtime constraints justify a domain.
+
 ## 0.32.0: Actor Surface Minimization
 
 - `[Context]` Added durable signal/noise guidance for actor-facing surfaces: keep the model-facing concept ladder minimal, make feedback hints state-backed and action-shaped, and avoid speculative advisory prose.

package/dist/lib/paths.d.ts

@@ -17,5 +17,5 @@ export declare const EXTENSION_RUNTIME_PATHS: ExtensionRuntimePaths;
 export declare function getExtensionSkillsDir(extensionUrl: string): string;
 export declare function getExistingExtensionSkillPaths(extensionUrl: string): string[];
 export declare function getRecipeRoot(agentDir?: string): string;
-export declare function getRecipeCandidateRoot(agentDir?: string): string;
+export declare function getRecipeDraftRoot(agentDir?: string): string;
 export declare function getPackagedRecipeRoot(): string;

package/dist/lib/paths.js

@@ -13,7 +13,7 @@ export function getAgentDir(env = process.env) {
         : join(homedir(), ".pi", "agent");
 }
 export function getConfigPath(agentDir = getAgentDir()) {
-    return join(agentDir, "legacy-tool-registry.json");
+    return join(agentDir, "tool-registry.json");
 }
 export function getExtensionTmpDir(agentDir = getAgentDir(), extensionName = "pi-actors") {
     return join(agentDir, "tmp", extensionName);
@@ -39,8 +39,8 @@ export function getExistingExtensionSkillPaths(extensionUrl) {
 export function getRecipeRoot(agentDir = getAgentDir()) {
     return join(agentDir, "recipes");
 }
-export function getRecipeCandidateRoot(agentDir = getAgentDir()) {
-    return join(getRecipeRoot(agentDir), "candidates");
+export function getRecipeDraftRoot(agentDir = getAgentDir()) {
+    return join(getRecipeRoot(agentDir), "drafts");
 }
 export function getPackagedRecipeRoot() {
     const here = dirname(fileURLToPath(import.meta.url));

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

@@ -47,6 +47,6 @@ export declare function discoverRecipeSources(sources: RecipeDiscoverySource[]):
 export declare function discoverRecipes(roots: string[]): RecipeDiscoveryResult;
 export declare function createRecipeIntegrityManifest(result: RecipeDiscoveryResult): RecipeIntegrityManifestEntry[];
 export declare function getShadowedLaunchDiagnostic(result: RecipeDiscoveryResult, id: string): Record<string, unknown> | undefined;
-export declare function listCandidateRecipes(root: string): Array<Record<string, unknown>>;
+export declare function listDraftRecipes(root: string): Array<Record<string, unknown>>;
 export declare function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown>;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipe-discovery.js

@@ -324,16 +324,16 @@ function diagnosticDetails(result) {
 }
 function remediationForEntry(entry, activePath) {
     const riskyDiagnostics = entry.diagnostics.filter((message) => diagnosticSeverity(message) === "warning");
-    const blockedCandidate = entry.shadows[0];
+    const blockedFallback = entry.shadows[0];
     if (entry.invalid) {
         return {
             id: entry.id,
-            kind: blockedCandidate ? "blocking_invalid" : "invalid",
+            kind: blockedFallback ? "blocking_invalid" : "invalid",
             severity: "error",
             path: entry.path,
-            ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
-            reason: blockedCandidate
-                ? "invalid higher-priority recipe blocks a lower-priority candidate"
+            ...(blockedFallback ? { blocked_fallback: blockedFallback } : {}),
+            reason: blockedFallback
+                ? "invalid higher-priority recipe blocks a lower-priority fallback"
                 : "recipe is invalid and cannot be exposed as a tool",
             action: "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
         };
@@ -341,12 +341,12 @@ function remediationForEntry(entry, activePath) {
     if (entry.disabled && entry.active) {
         return {
             id: entry.id,
-            kind: blockedCandidate ? "blocking_disabled" : "disabled",
+            kind: blockedFallback ? "blocking_disabled" : "disabled",
             severity: "warning",
             path: entry.path,
-            ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
-            reason: blockedCandidate
-                ? "disabled higher-priority recipe intentionally blocks a lower-priority candidate"
+            ...(blockedFallback ? { blocked_fallback: blockedFallback } : {}),
+            reason: blockedFallback
+                ? "disabled higher-priority recipe intentionally blocks a lower-priority fallback"
                 : "recipe is disabled and not exposed as a tool",
             action: "keep disabled intentionally, re-enable, or delete/archive the file",
         };
@@ -420,12 +420,12 @@ export function getShadowedLaunchDiagnostic(result, id) {
         return undefined;
     return {
         active_path: active.path,
-        blocked_candidate: active.shadows[0],
+        blocked_fallback: active.shadows[0],
         hint: "inspect_recipes_doctor",
         reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
     };
 }
-export function listCandidateRecipes(root) {
+export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
         const id = RecipeReferences.getRecipeIdFromPath(path);
         const config = RecipeReferences.readRawRecipeConfig(path);

package/dist/lib/tools.d.ts

@@ -8,6 +8,11 @@ import * as Execution from "./execution.ts";
 import * as Registry from "./registry.ts";
 export type RegisterToolInput = Registry.RegisterToolInput;
 export type RegisterToolRuntimeDeps<TContext> = Registry.RegisterToolRuntimeDeps<TContext>;
+export interface ActorToolDefinition {
+    name: string;
+    execute?: (...args: never[]) => unknown;
+    [key: string]: unknown;
+}
 export interface CoreActorToolDefinitionDeps<TContext extends AsyncRunToolContext> {
     configPath: string;
     getActiveTools: () => string[];
@@ -43,6 +48,6 @@ export interface ActorMessageToolDeps<TContext = unknown> {
     getTool?: (name: string) => any | undefined;
 }
 export declare function createActorMessageToolDefinition<TContext = unknown>(deps?: ActorMessageToolDeps<TContext>): any;
-export declare function createCoreActorToolDefinitions<TContext extends AsyncRunToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): any[];
+export declare function createCoreActorToolDefinitions<TContext extends AsyncRunToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[];
 export declare function createRuntimeToolDefinition(cfg: RegisteredTool, exec: Execution.RegisteredToolExec): any;
 export {};

package/dist/lib/tools.js

@@ -168,7 +168,7 @@ function compactAsyncRunStatus(value) {
         tokens.push(`code=${String(result.code)}`);
     if (result.killed === true)
         tokens.push("killed=true");
-    const draftRecipe = status.draft_recipe ?? status.candidate_recipe;
+    const draftRecipe = status.draft_recipe;
     if (draftRecipe)
         tokens.push(`draft_recipe=${String(draftRecipe)}`);
     const nextActions = actorRunNextActions(run);
@@ -504,8 +504,8 @@ 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"}`);
     }
@@ -557,11 +557,7 @@ function compactRecipeRegistry(summary) {
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
-    const drafts = Array.isArray(summary.drafts)
-        ? summary.drafts.length
-        : 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;
@@ -702,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",
@@ -716,18 +712,18 @@ 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: `Draft recipe captured from spawn run ${String(meta.run)}`,
@@ -743,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,
     });
@@ -864,13 +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, draft_recipe: candidateRecipe }
-                    : {}),
+                ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
                 next_actions: nextActions,
             };
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -962,8 +956,7 @@ export function createInspectToolDefinition(deps = {}) {
                 const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
                 const summaryBase = {
                     ...RecipeDiscovery.summarizeDiscovery(discovered),
-                    drafts: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
-                    candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
+                    drafts: RecipeDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
                 };
                 const summary = {
                     ...summaryBase,

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.32.0
+  version: 0.33.0
 ---
 
 # Actors (pi-actors)
@@ -213,7 +213,7 @@ 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 draft memory captured from successful inline `spawn template=...` runs. The directory name is retained for compatibility; treat these as drafts, not active tools. Drafts 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 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.
 

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.32.0
+  version: 0.33.0
 ---
 
 # Swarm
@@ -31,7 +31,7 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `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, draft recipes, command templates, async runs, or services.
-- `Draft 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. Its compatibility storage path may still include `recipes/candidates`.
+- `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/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` stores captured inline-spawn draft recipes, not registered tools. The directory name is retained for compatibility; model-facing output calls them drafts. 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/paths.ts

@@ -24,7 +24,7 @@ export interface ExtensionRuntimePaths {
 }
 
 export function getConfigPath(agentDir = getAgentDir()): string {
-  return join(agentDir, "legacy-tool-registry.json");
+  return join(agentDir, "tool-registry.json");
 }
 
 export function getExtensionTmpDir(
@@ -63,8 +63,8 @@ export function getRecipeRoot(agentDir = getAgentDir()): string {
   return join(agentDir, "recipes");
 }
 
-export function getRecipeCandidateRoot(agentDir = getAgentDir()): string {
-  return join(getRecipeRoot(agentDir), "candidates");
+export function getRecipeDraftRoot(agentDir = getAgentDir()): string {
+  return join(getRecipeRoot(agentDir), "drafts");
 }
 
 export function getPackagedRecipeRoot(): string {

package/lib/recipe-discovery.ts

@@ -461,16 +461,16 @@ function remediationForEntry(
   const riskyDiagnostics = entry.diagnostics.filter(
     (message) => diagnosticSeverity(message) === "warning",
   );
-  const blockedCandidate = entry.shadows[0];
+  const blockedFallback = entry.shadows[0];
   if (entry.invalid) {
     return {
       id: entry.id,
-      kind: blockedCandidate ? "blocking_invalid" : "invalid",
+      kind: blockedFallback ? "blocking_invalid" : "invalid",
       severity: "error",
       path: entry.path,
-      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
-      reason: blockedCandidate
-        ? "invalid higher-priority recipe blocks a lower-priority candidate"
+      ...(blockedFallback ? { blocked_fallback: blockedFallback } : {}),
+      reason: blockedFallback
+        ? "invalid higher-priority recipe blocks a lower-priority fallback"
         : "recipe is invalid and cannot be exposed as a tool",
       action:
         "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
@@ -479,12 +479,12 @@ function remediationForEntry(
   if (entry.disabled && entry.active) {
     return {
       id: entry.id,
-      kind: blockedCandidate ? "blocking_disabled" : "disabled",
+      kind: blockedFallback ? "blocking_disabled" : "disabled",
       severity: "warning",
       path: entry.path,
-      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
-      reason: blockedCandidate
-        ? "disabled higher-priority recipe intentionally blocks a lower-priority candidate"
+      ...(blockedFallback ? { blocked_fallback: blockedFallback } : {}),
+      reason: blockedFallback
+        ? "disabled higher-priority recipe intentionally blocks a lower-priority fallback"
         : "recipe is disabled and not exposed as a tool",
       action:
         "keep disabled intentionally, re-enable, or delete/archive the file",
@@ -568,13 +568,13 @@ export function getShadowedLaunchDiagnostic(
   if (!active.invalid && !active.disabled) return undefined;
   return {
     active_path: active.path,
-    blocked_candidate: active.shadows[0],
+    blocked_fallback: active.shadows[0],
     hint: "inspect_recipes_doctor",
     reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
   };
 }
 
-export function listCandidateRecipes(root: string): Array<Record<string, unknown>> {
+export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
     const id = RecipeReferences.getRecipeIdFromPath(path);
     const config = RecipeReferences.readRawRecipeConfig(path);

package/lib/tools.ts

@@ -27,6 +27,12 @@ export type RegisterToolInput = Registry.RegisterToolInput;
 export type RegisterToolRuntimeDeps<TContext> =
   Registry.RegisterToolRuntimeDeps<TContext>;
 
+export interface ActorToolDefinition {
+  name: string;
+  execute?: (...args: never[]) => unknown;
+  [key: string]: unknown;
+}
+
 export interface CoreActorToolDefinitionDeps<TContext extends AsyncRunToolContext> {
   configPath: string;
   getActiveTools: () => string[];
@@ -222,7 +228,7 @@ function compactAsyncRunStatus(value: unknown): string {
     tokens.push(`failures=${failures}`);
   if (result.code !== undefined) tokens.push(`code=${String(result.code)}`);
   if (result.killed === true) tokens.push("killed=true");
-  const draftRecipe = status.draft_recipe ?? status.candidate_recipe;
+  const draftRecipe = status.draft_recipe;
   if (draftRecipe) tokens.push(`draft_recipe=${String(draftRecipe)}`);
   const nextActions = actorRunNextActions(run);
   if (nextActions.length > 0)
@@ -627,8 +633,8 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
       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"}`,
@@ -683,11 +689,7 @@ function compactRecipeRegistry(summary: Record<string, unknown>): string {
   const diagnostics = Array.isArray(summary.diagnostics)
     ? summary.diagnostics.length
     : 0;
-  const drafts = Array.isArray(summary.drafts)
-    ? summary.drafts.length
-    : 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;
@@ -873,11 +875,11 @@ function shadowedRecipeLaunchDiagnostic(
   return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
 }
 
-function candidateRecipeName(run: string): string {
+function draftRecipeName(run: string): string {
   return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
 }
 
-function candidateRecipeDefaults(
+function draftRecipeDefaults(
   values: Record<string, unknown>,
 ): Record<string, unknown> | undefined {
   const ignored = new Set([
@@ -893,13 +895,13 @@ function candidateRecipeDefaults(
   return Object.keys(defaults).length > 0 ? defaults : undefined;
 }
 
-function writeSpawnCandidateRecipe(
+function writeSpawnDraftRecipe(
   input: Record<string, unknown>,
   meta: AsyncRuns.AsyncRunMeta,
 ): string | undefined {
   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 (
@@ -908,10 +910,10 @@ function writeSpawnCandidateRecipe(
     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: `Draft recipe captured from spawn run ${String(meta.run)}`,
@@ -930,7 +932,7 @@ function enhanceSpawnRecipeError(error: unknown, recipe: unknown): 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}`,
+      `${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_fallback=${diagnostic.blocked_fallback} hint=${diagnostic.hint}`,
     ),
     {
       ...diagnostic,
@@ -1118,13 +1120,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, draft_recipe: candidateRecipe }
-          : {}),
+        ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
         next_actions: nextActions,
       };
       ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -1275,12 +1275,7 @@ export function createInspectToolDefinition<TContext = unknown>(
         const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
         const summaryBase = {
           ...RecipeDiscovery.summarizeDiscovery(discovered),
-          drafts: RecipeDiscovery.listCandidateRecipes(
-            join(recipeRoot, "candidates"),
-          ),
-          candidates: RecipeDiscovery.listCandidateRecipes(
-            join(recipeRoot, "candidates"),
-          ),
+          drafts: RecipeDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
         };
         const summary = {
           ...summaryBase,
@@ -1943,7 +1938,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
 
 export function createCoreActorToolDefinitions<TContext extends AsyncRunToolContext>(
   deps: CoreActorToolDefinitionDeps<TContext>,
-): any[] {
+): ActorToolDefinition[] {
   return [
     createRegisterToolDefinition<TContext>({
       configPath: deps.configPath,

package/package.json

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

package/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/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.32.0
+  version: 0.33.0
 ---
 
 # Actors (pi-actors)
@@ -213,7 +213,7 @@ 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 draft memory captured from successful inline `spawn template=...` runs. The directory name is retained for compatibility; treat these as drafts, not active tools. Drafts 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 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.
 

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.32.0
+  version: 0.33.0
 ---
 
 # Swarm
@@ -31,7 +31,7 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `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, draft recipes, command templates, async runs, or services.
-- `Draft 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. Its compatibility storage path may still include `recipes/candidates`.
+- `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/dist/lib/conformance.d.ts

@@ -1,12 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-export declare const conformanceSuites: string[];
-export interface ConformanceReport {
-    code: number;
-    output: string;
-    summary: string;
-    suites: number;
-}
-export declare function runConformance(cwd?: URL): ConformanceReport;

package/dist/lib/conformance.js

@@ -1,28 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-import { spawnSync } from "node:child_process";
-export 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",
-];
-export function runConformance(cwd = new URL("..", import.meta.url)) {
-    const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...conformanceSuites], { cwd, encoding: "utf8", stdio: "pipe" });
-    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");
-    return {
-        code: result.status ?? 1,
-        output,
-        summary,
-        suites: conformanceSuites.length,
-    };
-}

package/lib/conformance.ts

@@ -1,46 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-
-import { spawnSync } from "node:child_process";
-
-export 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",
-];
-
-export interface ConformanceReport {
-  code: number;
-  output: string;
-  summary: string;
-  suites: number;
-}
-
-export function runConformance(cwd = new URL("..", import.meta.url)): ConformanceReport {
-  const result = spawnSync(
-    process.execPath,
-    ["--experimental-strip-types", "--test", ...conformanceSuites],
-    { cwd, encoding: "utf8", stdio: "pipe" },
-  );
-
-  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");
-
-  return {
-    code: result.status ?? 1,
-    output,
-    summary,
-    suites: conformanceSuites.length,
-  };
-}