@llblab/pi-actors 0.32.0 → 0.34.0

package/scripts/recipe-utils.mjs

@@ -1,27 +1,491 @@
 #!/usr/bin/env node
 
 /**
- * Recipe utility command bundle shim.
- *
- * Runtime logic lives in lib/recipe-utils.ts and is compiled to
- * dist/lib/recipe-utils.js for installed JS-only packages.
+ * Recipe utility command bundle.
+ * Zones: recipe utilities, deterministic helper subcommands
  */
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+// @ts-nocheck
 
-function packageRoot() {
-  return dirname(dirname(fileURLToPath(import.meta.url)));
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+function usage() {
+  console.error(`Usage:
+  recipe-utils.mjs run-summary <state-root>
+  recipe-utils.mjs run-ops-snapshot <state-root> <run-id> [lines] [stale-minutes]
+  recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
+  recipe-utils.mjs changelog-section <file> <version>
+  recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]
+  recipe-utils.mjs artifact-write <artifact-path> [create|overwrite|append]
+  recipe-utils.mjs actor-message <type> [to] [from] [summary] [metadata-json] [correlation-id] [reply-to]
+  recipe-utils.mjs package-summary <package-json>
+  recipe-utils.mjs skill-summary <skill-md> [package-json]`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
+function assertToken(value, label) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) fail(`${label} is required`);
+  if (!ADDRESS_PATTERN.test(normalized))
+    fail(`${label} contains unsupported characters: ${value}`);
+  return normalized;
+}
+
+function validateActorAddress(address, label) {
+  const value = String(address ?? "").trim();
+  if (value === "coordinator") return value;
+  const separator = value.indexOf(":");
+  if (separator < 0) fail(`${label} must include an actor kind: ${address}`);
+  const kind = value.slice(0, separator);
+  const rest = value.slice(separator + 1);
+  if (kind === "branch") {
+    const [run, branch, ...extra] = rest.split("/");
+    if (extra.length > 0)
+      fail(`${label} branch address has too many parts: ${address}`);
+    return `branch:${assertToken(run, `${label} branch run`)}/${assertToken(branch, `${label} branch id`)}`;
+  }
+  if (["run", "session", "tool"].includes(kind))
+    return `${kind}:${assertToken(rest, label)}`;
+  fail(`${label} has unsupported actor kind: ${kind}`);
+}
+
+function validateMessageType(type) {
+  const value = String(type ?? "").trim();
+  if (!MESSAGE_TYPE_PATTERN.test(value))
+    fail(`Invalid actor message type: ${type}`);
+  return value;
+}
+
+function walkFiles(dir, maxDepth = 2, depth = 0, out = []) {
+  if (depth > maxDepth || !existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) walkFiles(path, maxDepth, depth + 1, out);
+    else if (stat.isFile()) out.push(path);
+  }
+  return out;
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function getRunStatus(run, progress, result) {
+  if (progress?.phase) return progress.phase;
+  if (result?.code !== undefined) return result.code === 0 ? "done" : "failed";
+  return run.status ?? "unknown";
+}
+
+function collectRunSummary(rootValue) {
+  const root = resolve(
+    rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const rows = [];
+  for (const file of files) {
+    const run = readJson(file);
+    if (!run) {
+      rows.push({
+        run: relative(root, file),
+        status: "invalid-json",
+        recipe: "",
+        updated: "",
+      });
+      continue;
+    }
+    const runDir = dirname(file);
+    const progress = readJson(join(runDir, "progress.json"));
+    const result = readJson(join(runDir, "result.json"));
+    rows.push({
+      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      status: getRunStatus(run, progress, result),
+      recipe: run.recipe ?? run.recipe_file ?? "",
+      updated:
+        progress?.updatedAt ??
+        result?.completedAt ??
+        run.updated_at ??
+        run.completed_at ??
+        run.started_at ??
+        "",
+    });
+  }
+  rows.sort((a, b) =>
+    `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`),
+  );
+  return rows;
+}
+
+function runSummary(rootValue) {
+  console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+
+function tailJsonl(fileValue, linesValue = "80") {
+  const file = resolve(
+    fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  if (!existsSync(file)) return [];
+  const lines = Number.parseInt(linesValue, 10);
+  const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .filter(Boolean)
+    .slice(-count)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
 }
 
-function mainModulePath() {
-  const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "recipe-utils.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "recipe-utils.ts");
+function runOpsSnapshot(
+  rootValue,
+  runIdValue = "music",
+  linesValue = "80",
+  staleMinutesValue = "60",
+) {
+  const runs = collectRunSummary(rootValue);
+  const root = resolve(
+    rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const inspectedRun = String(runIdValue || "music");
+  const messageFile = join(root, inspectedRun, "outbox.jsonl");
+  const staleMs = Number(staleMinutesValue) * 60 * 1000;
+  const now = Date.now();
+  const recommendations = runs.flatMap((run) => {
+    const updatedMs = Date.parse(run.updated || "");
+    const stale =
+      Number.isFinite(updatedMs) &&
+      Number.isFinite(staleMs) &&
+      now - updatedMs > staleMs;
+    if (run.status === "running" && stale) {
+      return [
+        {
+          run: run.run,
+          reason: "running-stale",
+          suggested_message: {
+            to: `run:${run.run}`,
+            type: "control.stop",
+            body: "stop",
+          },
+        },
+      ];
+    }
+    if (["failed", "exited", "killed"].includes(run.status)) {
+      return [
+        {
+          run: run.run,
+          reason: `terminal-${run.status}`,
+          suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+        },
+      ];
+    }
+    return [];
+  });
+  console.log(
+    JSON.stringify(
+      {
+        runs,
+        inspectedRun,
+        messages: tailJsonl(messageFile, linesValue),
+        recommendations,
+      },
+      null,
+      2,
+    ),
+  );
 }
 
-const { runRecipeUtils } = await import(pathToFileURL(mainModulePath()).href);
+function playlist(
+  sourceValue,
+  extensionsValue = ".mp3,.ogg,.wav,.flac,.m4a",
+  maxDepthValue = "2",
+  outputMode = "paths",
+) {
+  const source = resolve(
+    sourceValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const maxDepth = Number.parseInt(maxDepthValue, 10);
+  const extensions = new Set(
+    extensionsValue
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const files = walkFiles(source, Number.isFinite(maxDepth) ? maxDepth : 2)
+    .filter((file) => extensions.has(extname(file).toLowerCase()))
+    .sort((a, b) => a.localeCompare(b));
+  if (outputMode === "m3u") console.log(["#EXTM3U", ...files].join("\n"));
+  else if (outputMode === "inline") console.log(files.join("|"));
+  else console.log(files.join("\n"));
+}
+
+function artifactManifest(
+  pathValue,
+  title = "Artifact",
+  status = "draft",
+  summary = "",
+) {
+  const path = resolve(
+    pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const exists = existsSync(path);
+  const stat = exists ? statSync(path) : undefined;
+  console.log(
+    JSON.stringify(
+      {
+        title,
+        status,
+        path,
+        exists,
+        bytes: stat?.size ?? 0,
+        modified: stat?.mtime?.toISOString?.() ?? null,
+        summary,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function artifactWrite(pathValue, mode = "create") {
+  const path = resolve(
+    pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  if (!["create", "overwrite", "append"].includes(mode)) {
+    fail(`Invalid artifact write mode: ${mode}`);
+  }
+  if (mode === "create" && existsSync(path)) {
+    fail(`Artifact already exists: ${path}`);
+  }
+  const content = readFileSync(0, "utf8");
+  mkdirSync(dirname(path), { recursive: true });
+  if (mode === "append") appendFileSync(path, content);
+  else writeFileSync(path, content, "utf8");
+  const stat = statSync(path);
+  console.log(
+    JSON.stringify({ path, mode, bytes: stat.size, written: true }, null, 2),
+  );
+}
+
+function actorMessage(
+  type = "event",
+  to = "coordinator",
+  from = "run:{run_id}",
+  summary = "",
+  metadataValue = "",
+  correlationId = "",
+  replyTo = "",
+) {
+  const messageType = validateMessageType(type);
+  const messageTo = validateActorAddress(to, "message.to");
+  const messageFrom = validateActorAddress(from, "message.from");
+  let metadata = {};
+  if (metadataValue) {
+    try {
+      const parsed = JSON.parse(metadataValue);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+        metadata = parsed;
+      else fail("Actor message metadata must be a JSON object");
+    } catch (error) {
+      fail(`Invalid actor message metadata JSON: ${error.message}`);
+    }
+  }
+  const bodyText = readFileSync(0, "utf8");
+  const trimmed = bodyText.trim();
+  let body = bodyText;
+  if (trimmed) {
+    try {
+      body = JSON.parse(trimmed);
+    } catch {
+      body = bodyText;
+    }
+  }
+  console.log(
+    JSON.stringify(
+      {
+        to: messageTo,
+        from: messageFrom,
+        type: messageType,
+        summary: summary || messageType,
+        body,
+        ...(correlationId ? { correlation_id: correlationId } : {}),
+        ...(replyTo ? { reply_to: replyTo } : {}),
+        metadata,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function packageSummary(fileValue = "package.json") {
+  const file = resolve(
+    fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const pkg = readJson(file);
+  if (!pkg) fail(`Package JSON not found or invalid: ${fileValue}`);
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === "object"
+      ? Object.keys(pkg.scripts).sort()
+      : [];
+  const dependencies =
+    pkg.dependencies && typeof pkg.dependencies === "object"
+      ? Object.keys(pkg.dependencies).sort()
+      : [];
+  const devDependencies =
+    pkg.devDependencies && typeof pkg.devDependencies === "object"
+      ? Object.keys(pkg.devDependencies).sort()
+      : [];
+  console.log(
+    JSON.stringify(
+      {
+        name: pkg.name ?? "",
+        version: pkg.version ?? "",
+        type: pkg.type ?? "",
+        private: Boolean(pkg.private),
+        packageManager: pkg.packageManager ?? "",
+        files: Array.isArray(pkg.files) ? pkg.files : [],
+        bin: pkg.bin ?? null,
+        main: pkg.main ?? "",
+        exports: pkg.exports ?? null,
+        scripts,
+        dependencyCount: dependencies.length,
+        devDependencyCount: devDependencies.length,
+        dependencies,
+        devDependencies,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function parseSkillFrontmatter(content) {
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+  const fields = {};
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (match) fields[match[1]] = match[2].trim();
+  }
+  return { frontmatter, fields };
+}
+
+function skillSummary(skillValue, packageValue = "package.json") {
+  const skillFile = resolve(
+    skillValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const packageFile = resolve(
+    packageValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const content = readFileSync(skillFile, "utf8");
+  const pkg = readJson(packageFile) ?? {};
+  const { frontmatter, fields } = parseSkillFrontmatter(content);
+  const scalarLines = frontmatter
+    .split(/\r?\n/)
+    .filter((line) => /^\w+:\s*\S/.test(line));
+  const extraColonLines = scalarLines.filter(
+    (line) => (line.match(/:/g) ?? []).length > 1,
+  );
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+  const version =
+    fields.version ??
+    frontmatter.match(/^\s+version:\s*([^\n]+)\s*$/m)?.[1]?.trim() ??
+    "";
+  console.log(
+    JSON.stringify(
+      {
+        path: skillValue,
+        name: fields.name ?? "",
+        description: fields.description ?? "",
+        version,
+        packageVersion: pkg.version ?? "",
+        versionMatchesPackage: version === pkg.version,
+        frontmatterExtraColonLines: extraColonLines,
+        bodyLineCount: body.split(/\r?\n/).length,
+        headings: body.split(/\r?\n/).filter((line) => /^#{1,6}\s/.test(line)),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function changelogSection(fileValue, version) {
+  const file = resolve(fileValue);
+  const lines = readFileSync(file, "utf8").split(/\r?\n/);
+  const start = lines.findIndex(
+    (line) => line.startsWith("## ") && line.includes(version),
+  );
+  if (start < 0) fail(`Version section not found: ${version}`);
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (lines[index].startsWith("## ")) {
+      end = index;
+      break;
+    }
+  }
+  console.log(lines.slice(start, end).join("\n").trimEnd());
+}
+
+function runRecipeUtils(argv = process.argv.slice(2)) {
+const [command, ...args] = argv;
+if (!command) {
+  usage();
+  process.exit(1);
+}
+
+if (command === "run-summary")
+  runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+else if (command === "run-ops-snapshot")
+  runOpsSnapshot(
+    args[0] ?? "~/.pi/agent/tmp/pi-actors/runs",
+    args[1] ?? "music",
+    args[2],
+    args[3],
+  );
+else if (command === "playlist")
+  playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
+else if (command === "changelog-section")
+  changelogSection(args[0] ?? "CHANGELOG.md", args[1] ?? "Unreleased");
+else if (command === "artifact-manifest")
+  artifactManifest(args[0] ?? "artifact.md", args[1], args[2], args[3]);
+else if (command === "artifact-write")
+  artifactWrite(args[0] ?? "artifact.md", args[1] ?? "create");
+else if (command === "actor-message")
+  actorMessage(args[0], args[1], args[2], args[3], args[4], args[5], args[6]);
+else if (command === "package-summary")
+  packageSummary(args[0] ?? "package.json");
+else if (command === "skill-summary")
+  skillSummary(args[0] ?? "skills/actors/SKILL.md", args[1] ?? "package.json");
+else {
+  usage();
+  fail(`Unknown command: ${command}`);
+}
+}
 
 try {
   runRecipeUtils(process.argv.slice(2));

package/scripts/validate-recipe.mjs

@@ -1,27 +1,127 @@
-#!/usr/bin/env -S node --experimental-strip-types
+#!/usr/bin/env node
 
 /**
- * Template recipe validator CLI shim.
+ * Template recipe validator CLI.
  *
- * Runtime logic lives in lib/validate-recipe.ts and is compiled to
- * dist/lib/validate-recipe.js for installed JS-only packages.
+ * Owns CLI parsing and report formatting directly. Recipe parsing remains in
+ * the reusable recipe-reference domain.
  */
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 function packageRoot() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function mainModulePath() {
+async function importRuntimeModule(name) {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "validate-recipe.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "validate-recipe.ts");
+  const compiled = join(root, "dist", "lib", `${name}.js`);
+  const source = join(root, "lib", `${name}.ts`);
+  return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }
 
-const { validateRecipes } = await import(pathToFileURL(mainModulePath()).href);
+const { readResolvedRecipeConfig } = await importRuntimeModule("recipes-references");
+
+export function validateRecipeUsage() {
+  return `Usage:
+  validate-recipe.mjs <recipe-file-or-dir> [--all]
+
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`;
+}
+
+function expandPath(value) {
+  return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()));
+}
+
+function templateKind(template) {
+  if (typeof template === "string") return "leaf";
+  if (Array.isArray(template)) return "sequence";
+  if (template && typeof template === "object") {
+    const node = template;
+    if (typeof node.template === "string") return "leaf";
+    if (Array.isArray(node.template))
+      return node.parallel === true ? "parallel" : "sequence";
+    if (node.parallel === true) return "parallel";
+    return "object";
+  }
+  return "unknown";
+}
+
+function recipeFiles(target, all) {
+  if (!existsSync(target)) throw new Error(`Recipe path not found: ${target}`);
+  const stat = statSync(target);
+  if (stat.isFile()) return [target];
+  if (!stat.isDirectory())
+    throw new Error(`Recipe path is not a file or directory: ${target}`);
+  if (!all) throw new Error("Directory validation requires --all.");
+  return readdirSync(target)
+    .filter((file) => file.endsWith(".json") || file.endsWith(".md"))
+    .sort((a, b) => a.localeCompare(b))
+    .map((file) => resolve(target, file));
+}
+
+function validateFile(file) {
+  try {
+    const config = readResolvedRecipeConfig(file);
+    if (!config?.template)
+      throw new Error("Recipe must define a non-empty template.");
+    return {
+      file,
+      ok: true,
+      name: config.name ?? "",
+      async: Boolean(config.async),
+      args: Array.isArray(config.args) ? config.args : [],
+      defaults:
+        config.defaults && typeof config.defaults === "object"
+          ? Object.keys(config.defaults).sort()
+          : [],
+      imports:
+        config.imports && typeof config.imports === "object"
+          ? Object.keys(config.imports).sort()
+          : [],
+      mailbox:
+        config.mailbox && typeof config.mailbox === "object"
+          ? {
+              accepts: Array.isArray(config.mailbox.accepts)
+                ? config.mailbox.accepts
+                : [],
+              emits: Array.isArray(config.mailbox.emits)
+                ? config.mailbox.emits
+                : [],
+            }
+          : undefined,
+      template: templateKind(config.template),
+    };
+  } catch (error) {
+    return {
+      file,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function validateRecipes(argv) {
+  const targetArg = argv.find((arg) => !arg.startsWith("-"));
+  const all = argv.includes("--all");
+  if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
+    return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
+  }
+
+  const files = recipeFiles(expandPath(targetArg), all);
+  const results = files.map(validateFile);
+  const failed = results.filter((result) => !result.ok).length;
+  return {
+    ok: failed === 0,
+    total: results.length,
+    passed: results.length - failed,
+    failed,
+    results,
+  };
+}
 
 try {
   const report = validateRecipes(process.argv.slice(2));

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.34.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.34.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/actor-worker.d.ts

@@ -1,16 +0,0 @@
-/**
- * Canonical mailbox-backed actor worker entrypoint logic.
- * Zones: worker demo, mailbox loop recipe runtime
- */
-interface ActorWorkerArgs {
-    artifact_dir?: string;
-    branch?: string;
-    poll_ms?: string | number;
-    run?: string;
-    stale_claim_ms?: string | number;
-    state_dir?: string;
-    write_artifacts?: string | boolean;
-}
-export declare function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs;
-export declare function runActorWorker(argv?: string[]): Promise<void>;
-export {};