@llblab/pi-actors 0.23.0 → 0.24.1

package/lib/validate-recipe.ts

@@ -0,0 +1,110 @@
+/**
+ * Template recipe validator CLI logic.
+ * Zones: recipe validation, installed script entrypoint
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+import { readResolvedRecipeConfig } from "./recipe-references.ts";
+
+export function validateRecipeUsage(): string {
+  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: string): string {
+  return resolve(
+    String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()),
+  );
+}
+
+function templateKind(template: unknown): string {
+  if (typeof template === "string") return "leaf";
+  if (Array.isArray(template)) return "sequence";
+  if (template && typeof template === "object") {
+    const node = template as Record<string, unknown>;
+    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: string, all: boolean): string[] {
+  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: string): Record<string, unknown> {
+  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: string[]): Record<string, unknown> {
+  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,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -30,7 +30,7 @@
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "pack:dry": "npm pack --dry-run",
     "validate": "npx tsc --noEmit && npm run build && npm run check && npm test && npm run pack:dry",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/build-dist.mjs",
     "prepack": "npm run build"
   },
   "files": [
@@ -45,13 +45,21 @@
     "BACKLOG.md",
     "CHANGELOG.md",
     "docs",
+    "fixtures",
     "banner.jpg"
   ],
   "pi": {
     "extensions": [
       "./dist/index.js"
     ],
+    "sourceExtensions": [
+      "./index.ts"
+    ],
     "skills": [
+      "./dist/skills/actors/SKILL.md",
+      "./dist/skills/swarm/SKILL.md"
+    ],
+    "sourceSkills": [
       "./skills/actors/SKILL.md",
       "./skills/swarm/SKILL.md"
     ],

package/recipes/actor-worker.json

@@ -0,0 +1,35 @@
+{
+  "async": true,
+  "description": "Start a canonical mailbox-backed branch worker demo actor.",
+  "args": [
+    "repo:path",
+    "branch:string",
+    "poll_ms:int"
+  ],
+  "defaults": {
+    "repo": "~/.pi/agent/extensions/pi-actors",
+    "branch": "worker",
+    "poll_ms": "1000"
+  },
+  "mailbox": {
+    "accepts": [
+      "task.assign",
+      "control.stop",
+      "control.cancel",
+      "control.kill"
+    ],
+    "emits": [
+      "actor.join",
+      "task.claim",
+      "task.result",
+      "awaiting_assignment",
+      "actor.leave",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "artifacts": {
+    "journal": "{state_dir}/worker-events.jsonl"
+  },
+  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms}"
+}

package/recipes/pipeline-quorum-review.json

@@ -1,7 +1,7 @@
 {
   "async": true,
   "imports": {
-    "quorum": "subagent-quorum.json",
+    "subagent": "subagent-prompt.json",
     "merger": "subagent-merge.json",
     "judge": "subagent-judge.json",
     "normalizer": "subagent-normalize.json"
@@ -34,12 +34,17 @@
   },
   "template": [
     {
-      "name": "quorum",
-      "values": {
-        "prompt": "{prompt}",
-        "models": "{models}",
-        "tools": "{tools}",
-        "output_format": "Vote-style Markdown: Verdict, Rationale, Evidence, Confidence."
+      "parallel": true,
+      "repeat": "{models.length}",
+      "failure": "branch",
+      "template": {
+        "name": "subagent",
+        "values": {
+          "prompt": "{prompt}",
+          "model": "{models[index]}",
+          "tools": "{tools}",
+          "output_format": "Vote-style Markdown: Verdict, Rationale, Evidence, Confidence."
+        }
       }
     },
     {

package/scripts/actor-worker.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Canonical mailbox-backed actor worker demo.
+ *
+ * Thin process shim. Runtime logic lives in lib/actor-worker.ts and is
+ * compiled to dist/lib/actor-worker.js for installed JS-only packages.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+function packageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function mainModulePath() {
+  const root = packageRoot();
+  const compiled = join(root, "dist", "lib", "actor-worker.js");
+  return existsSync(compiled) ? compiled : join(root, "lib", "actor-worker.ts");
+}
+
+const { runActorWorker } = await import(pathToFileURL(mainModulePath()).href);
+
+try {
+  await runActorWorker(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/scripts/async-runner.mjs

@@ -1,221 +1,31 @@
 #!/usr/bin/env node
 
 /**
- * Detached async-runner.
+ * Detached async-runner shim.
  *
- * This process is intentionally thin: the parent tool prepares state files and
- * starts this script in the background; this script loads the recorded run,
- * executes its command template, and writes ordinary files that status/tail/list
- * tools can inspect later.
- *
- * Keep orchestration policy out of this file.
+ * Runtime logic lives in lib/async-runner.ts and is compiled to
+ * dist/lib/async-runner.js for installed JS-only packages.
  */
 
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const stateDir = process.argv[2];
-if (!stateDir) {
-  console.error("missing state dir");
-  process.exit(1);
-}
-
-function scriptFile() {
-  return fileURLToPath(import.meta.url);
-}
-
 function packageRoot() {
-  return dirname(dirname(scriptFile()));
+  return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function libModulePath(name) {
+function mainModulePath() {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", `${name}.js`);
-  return existsSync(compiled) ? compiled : join(root, "lib", `${name}.ts`);
-}
-
-async function importLib(name) {
-  return import(pathToFileURL(libModulePath(name)).href);
+  const compiled = join(root, "dist", "lib", "async-runner.js");
+  return existsSync(compiled) ? compiled : join(root, "lib", "async-runner.ts");
 }
 
-const { executeRegisteredTool } = await importLib("execution");
-const { execCommandTemplate } = await importLib("command-templates");
-const { appendRecipeContextToPiArgs } = await importLib("actor-recipe-context");
-const { writeJsonAtomic } = await importLib("file-state");
-const runPath = join(stateDir, "run.json");
-const progressPath = join(stateDir, "progress.json");
-const resultPath = join(stateDir, "result.json");
-const eventsPath = join(stateDir, "events.jsonl");
-const outboxPath = join(stateDir, "outbox.jsonl");
-const stdoutPath = join(stateDir, "stdout.log");
-const stderrPath = join(stateDir, "stderr.log");
-const meta = JSON.parse(readFileSync(runPath, "utf8"));
-
-/**
- * Appends one lifecycle event.
- *
- * events.jsonl is append-only so observers can tail transitions even while the
- * run is still running.
- */
-function event(name, data = {}) {
-  appendFileSync(
-    eventsPath,
-    `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
-  );
-}
-
-function quoteCommandDetailPart(value) {
-  if (value === "") return "''";
-  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
-  return `'${String(value).replaceAll("'", "'\\''")}'`;
-}
+const { runAsyncRunner } = await import(pathToFileURL(mainModulePath()).href);
 
-function formatCommandDetail(command, args) {
-  return [command, ...args].map(quoteCommandDetailPart).join(" ");
-}
-
-function summarizeCommandDetail(commandDetail) {
-  return commandDetail.length > 160
-    ? `${commandDetail.slice(0, 157)}...`
-    : commandDetail;
-}
-
-function getCommandDoneDelivery(result) {
-  return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
-}
-
-function outbox(name, summary, data = {}, delivery = "log", level = "info") {
-  appendFileSync(
-    outboxPath,
-    `${JSON.stringify({ body: data, data, delivery, event: name, from: `run:${meta.run}`, level, summary, to: "coordinator", ts: new Date().toISOString(), type: name })}\n`,
-  );
-}
-/**
- * Writes the compact status snapshot.
- *
- * progress.json is rewritten atomically because observers may read it
- * concurrently.
- */
-function progress(phase, extra = {}) {
-  writeJsonAtomic(progressPath, {
-    phase,
-    updatedAt: new Date().toISOString(),
-    ...extra,
-  });
-}
-let activeSubagents = 0;
-let completedSubagents = 0;
-const subagentFailures = [];
-
-function progressRunning() {
-  progress("running", {
-    activeSubagents,
-    completed: completedSubagents,
-    failures: subagentFailures,
-  });
-}
-async function observedExec(command, args, options) {
-  const commandDetail = formatCommandDetail(command, args);
-  const execArgs = appendRecipeContextToPiArgs(
-    command,
-    args,
-    meta.recipe_context_records,
-    options?.actorRecipeContext,
-  );
-  activeSubagents += 1;
-  event("command.start", { activeSubagents, command: commandDetail });
-  progressRunning();
-  const result = await execCommandTemplate(command, execArgs, options);
-  activeSubagents = Math.max(0, activeSubagents - 1);
-  completedSubagents += 1;
-  if (result.code !== 0) {
-    subagentFailures.push({
-      code: result.code,
-      command: commandDetail,
-      killed: result.killed,
-    });
-  }
-  event("command.done", {
-    activeSubagents,
-    code: result.code,
-    command: commandDetail,
-    killed: result.killed,
-  });
-  outbox(
-    "command.done",
-    `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
-    {
-      activeSubagents,
-      ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
-      run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
-      code: result.code,
-      command: commandDetail,
-      killed: result.killed,
-    },
-    getCommandDoneDelivery(result),
-    result.code === 0 ? "info" : "error",
-  );
-  progressRunning();
-  return result;
-}
 try {
-  event("run.runner.start", { pid: process.pid });
-  progressRunning();
-  /**
-   * Reuse the same registered-tool execution path as foreground tools.
-   *
-   * The synthetic tool name is only for reporting; meta.template is the real
-   * work.
-   */
-  const result = await executeRegisteredTool(
-    {
-      name: "run_actor",
-      description: "Detached command-template run actor",
-      template: meta.template,
-      args: [],
-      defaults: {},
-    },
-    meta.values || {},
-    observedExec,
-    meta.cwd,
-  );
-  /**
-   * Tool output is already formatted/truncated by the shared execution layer.
-   * The runner persists that agent-facing text for later tail/status analysis.
-   */
-  const text = result.content?.[0]?.text || "";
-  appendFileSync(stdoutPath, text);
-  writeJsonAtomic(resultPath, {
-    code: result.details.code,
-    command: result.details.command,
-    killed: result.details.killed,
-    truncated: result.details.truncated,
-    completedAt: new Date().toISOString(),
-  });
-  progress("done", {
-    completed: 1,
-    failures: result.details.nonCriticalFailures || [],
-  });
-  event("run.done", { code: result.details.code });
+  await runAsyncRunner(process.argv[2]);
 } catch (error) {
-  /**
-   * Represent failure in every observable channel:
-   *
-   * - stderr.log for humans
-   * - result.json for structured readers
-   * - progress.json for status
-   * - events.jsonl for tail/watch flows
-   */
-  const message = error instanceof Error ? error.message : String(error);
-  appendFileSync(stderrPath, `${message}\n`);
-  writeJsonAtomic(resultPath, {
-    code: 1,
-    error: message,
-    killed: false,
-    completedAt: new Date().toISOString(),
-  });
-  progress("failed", { completed: 0, failures: [{ message }] });
-  event("run.failed", { error: message });
+  console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);
 }

package/scripts/build-dist.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * Build the JavaScript-only distributive tree.
+ *
+ * This is intentionally standalone: it is package/build glue, not reusable
+ * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
+ * assets, and syntax-checks packaged script shims.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+rmSync("dist", { recursive: true, force: true });
+mkdirSync("dist", { recursive: true });
+
+run("tsc", ["-p", "tsconfig.build.json"]);
+
+for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
+  cpSync(dir, join("dist", dir), { recursive: true });
+}
+
+const builtScripts = readdirSync(join("dist", "scripts"))
+  .filter((name) => name.endsWith(".mjs"))
+  .map((name) => join("dist", "scripts", name));
+
+run(process.execPath, ["--check", ...builtScripts]);

package/scripts/conformance.mjs

@@ -1,47 +1,33 @@
 #!/usr/bin/env node
 
 /**
- * Internal conformance runner.
+ * Internal conformance runner shim.
  *
- * This script runs the protocol-facing regression suites that exercise recipe
- * discovery, registry mutation, spawn lifecycle, message routing, room/branch
- * state, ownership checks, artifacts, and attention semantics without requiring
- * the Pi UI.
- *
- * Keep output compact for CI and release preflight use; detailed failures are
- * printed only when the underlying Node test run fails.
+ * Runtime logic lives in lib/conformance.ts and is compiled to
+ * dist/lib/conformance.js for installed JS-only packages.
  */
 
-import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-const suites = [
-  "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)));
+}
 
-const result = spawnSync(
-  process.execPath,
-  ["--experimental-strip-types", "--test", ...suites],
-  { cwd: new URL("..", import.meta.url), encoding: "utf8", stdio: "pipe" },
-);
+function mainModulePath() {
+  const root = packageRoot();
+  const compiled = join(root, "dist", "lib", "conformance.js");
+  return existsSync(compiled) ? compiled : join(root, "lib", "conformance.ts");
+}
 
-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");
+const { runConformance } = await import(pathToFileURL(mainModulePath()).href);
+const report = runConformance(packageRoot());
 
 console.log("pi-actors conformance");
-console.log(`suites ${suites.length}`);
-if (summary) console.log(summary);
-if (result.status !== 0) {
-  console.error(output.trimEnd());
-  process.exit(result.status ?? 1);
+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);
 }