@llblab/pi-actors 0.32.0 → 0.34.0

package/package.json

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

package/recipes/utility-coordinator-lock-snapshot.json

@@ -9,5 +9,5 @@
     "state_dir": "~/.pi/agent/tmp/pi-actors/runs/coordinator-locker",
     "lines": "20"
   },
-  "template": "{repo}/scripts/coordinator-locker.mjs snapshot --state-dir {state_dir} --lines {lines}"
+  "template": "{repo}/scripts/locker.mjs snapshot --state-dir {state_dir} --lines {lines}"
 }

package/scripts/actor-worker.mjs

@@ -3,11 +3,11 @@
 /**
  * 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.
+ * Owns the worker argument parsing and control loop directly. Reusable room and
+ * mailbox primitives stay in lib/; this script remains the public executable.
  */
 
-import { existsSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -15,13 +15,192 @@ function packageRoot() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function mainModulePath() {
+async function importRuntimeModule(name) {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "actor-worker.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "actor-worker.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 { runActorWorker } = await import(pathToFileURL(mainModulePath()).href);
+const { appendRoomMessage, ensureRoomMember, readBranchInboxMessages } =
+  await importRuntimeModule("rooms");
+const { handleMailboxLoopOnce, isMailboxLoopStopMessage } =
+  await importRuntimeModule("mailbox-loop");
+
+export function parseActorWorkerArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2).replaceAll("-", "_");
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    index += 1;
+  }
+  return args;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function text(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function enabled(value) {
+  return value !== false && value !== "false" && value !== "0";
+}
+
+function safeName(value) {
+  return String(value ?? "unknown").replaceAll(/[^A-Za-z0-9_.-]+/g, "_");
+}
+
+export async function runActorWorker(argv = process.argv.slice(2)) {
+  const args = parseActorWorkerArgs(argv);
+  const stateDir = String(args.state_dir ?? "");
+  const run = String(args.run ?? "");
+  const branch = String(args.branch ?? "worker");
+  const pollMs = Math.max(50, Number(args.poll_ms ?? 1000));
+  const staleClaimMs = Math.max(0, Number(args.stale_claim_ms ?? 0));
+  const artifactDir = String(
+    args.artifact_dir ?? join(stateDir, "worker-artifacts"),
+  );
+  const writeArtifacts = enabled(args.write_artifacts ?? true);
+
+  if (!stateDir || !run) {
+    throw new Error(
+      "usage: actor-worker.mjs --state-dir <dir> --run <id> [--branch worker] [--poll-ms 1000]",
+    );
+  }
+
+  const branchAddress = `branch:${run}/${branch}`;
+  const roomAddress = `room:${run}`;
+  const journalPath = join(stateDir, "worker-events.jsonl");
+  const statusPath = join(stateDir, "worker-status.json");
+  if (writeArtifacts) mkdirSync(artifactDir, { recursive: true });
+
+  function journal(event, data = {}) {
+    appendFileSync(
+      journalPath,
+      `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
+    );
+  }
+
+  function staleClaims() {
+    if (staleClaimMs <= 0) return 0;
+    const cutoff = Date.now() - staleClaimMs;
+    return readBranchInboxMessages(stateDir, run, branchAddress).filter(
+      (record) => {
+        if (record.status !== "claimed" || !record.claimed_at) return false;
+        const claimedAt = Date.parse(record.claimed_at);
+        return Number.isFinite(claimedAt) && claimedAt < cutoff;
+      },
+    ).length;
+  }
+
+  function status(state, data = {}) {
+    writeFileSync(
+      statusPath,
+      `${JSON.stringify({ artifact_dir: artifactDir, branch, run, stale_claims: staleClaims(), state, ts: new Date().toISOString(), ...data }, null, 2)}\n`,
+    );
+  }
+
+  function writeResultArtifact(id, result) {
+    if (!writeArtifacts) return undefined;
+    const path = join(artifactDir, `${safeName(id)}.txt`);
+    writeFileSync(path, `${result}\n`);
+    return path;
+  }
+
+  function room(type, summary, body = {}) {
+    appendRoomMessage(stateDir, "main", {
+      body,
+      from: branchAddress,
+      summary,
+      to: roomAddress,
+      type,
+    });
+  }
+
+  ensureRoomMember(
+    stateDir,
+    run,
+    "main",
+    branchAddress,
+    { display: branch, role: "worker", status: "present" },
+    `${branch} joined as mailbox worker`,
+  );
+  room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+  journal("worker.started", {
+    artifact_dir: artifactDir,
+    branch,
+    run,
+    stale_claim_ms: staleClaimMs,
+  });
+  status("awaiting_assignment", { handled: 0, stale_claim_ms: staleClaimMs });
+
+  let handled = 0;
+  let stopping = false;
+  while (!stopping) {
+    const result = await handleMailboxLoopOnce(
+      { address: branchAddress, kind: "branch", run, stateDir },
+      (message) => {
+        if (isMailboxLoopStopMessage(message)) {
+          stopping = true;
+          room("actor.leave", `${branch} stopping`, {
+            branch,
+            reason: message.type,
+          });
+          journal("worker.stopping", { id: message.id, type: message.type });
+          status("stopping", { handled, reason: message.type });
+          return;
+        }
+        room("task.claim", `${branch} claimed ${message.type}`, {
+          branch,
+          id: message.id,
+          type: message.type,
+        });
+        const result = text(message.body);
+        const artifact = writeResultArtifact(message.id, result);
+        handled += 1;
+        room("task.result", `${branch} handled ${message.type}`, {
+          artifact,
+          branch,
+          id: message.id,
+          result,
+          type: message.type,
+        });
+        room("awaiting_assignment", `${branch} awaiting assignment`, {
+          branch,
+        });
+        journal("task.handled", {
+          artifact,
+          id: message.id,
+          type: message.type,
+        });
+        status("awaiting_assignment", {
+          handled,
+          last_artifact: artifact,
+          last_id: message.id,
+          last_type: message.type,
+          stale_claim_ms: staleClaimMs,
+        });
+      },
+      { owner: branchAddress },
+    );
+    if (!result.handled) await sleep(pollMs);
+  }
+
+  journal("worker.done", { branch, handled, run });
+  status("done", { handled });
+}
 
 try {
   await runActorWorker(process.argv.slice(2));

package/scripts/async-runner.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * Detached async-runner shim.
+ * Detached async-runner executable.
  *
- * Runtime logic lives in lib/async-runner.ts and is compiled to
- * dist/lib/async-runner.js for installed JS-only packages.
+ * Owns the run child-process control loop directly. Reusable runtime
+ * primitives stay in lib/; this script should remain understandable without
+ * chasing a one-off lib entrypoint domain.
  */
 
-import { existsSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -15,13 +16,175 @@ function packageRoot() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-function mainModulePath() {
+async function importRuntimeModule(name) {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "async-runner.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "async-runner.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 { runAsyncRunner } = await import(pathToFileURL(mainModulePath()).href);
+const { appendRecipeContextToPiArgs } =
+  await importRuntimeModule("recipes-context");
+const { execCommandTemplate } = await importRuntimeModule("command-templates");
+const { executeRegisteredTool } = await importRuntimeModule("execution");
+const { writeJsonAtomic } = await importRuntimeModule("file-state");
+
+function quoteCommandDetailPart(value) {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function formatCommandDetail(command, args) {
+  return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+
+function summarizeCommandDetail(commandDetail) {
+  return commandDetail.length > 160
+    ? `${commandDetail.slice(0, 157)}...`
+    : commandDetail;
+}
+
+export async function runAsyncRunner(stateDir = process.argv[2]) {
+  if (!stateDir) throw new Error("missing state dir");
+
+  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"));
+
+  function event(name, data = {}) {
+    appendFileSync(
+      eventsPath,
+      `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
+    );
+  }
+
+  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`,
+    );
+  }
+
+  function progress(phase, extra = {}) {
+    writeJsonAtomic(progressPath, {
+      phase,
+      updatedAt: new Date().toISOString(),
+      ...extra,
+    });
+  }
+
+  let activeSubagents = 0;
+  let completedSubagents = 0;
+  const subagentFailures = [];
+
+  function getCommandDoneDelivery(result) {
+    return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
+  }
+
+  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();
+    const result = await executeRegisteredTool(
+      {
+        name: "run_actor",
+        description: "Detached command-template run actor",
+        template: meta.template,
+        args: [],
+        defaults: {},
+      },
+      meta.values || {},
+      observedExec,
+      meta.cwd,
+    );
+    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 });
+  } catch (error) {
+    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 });
+    throw error;
+  }
+}
 
 try {
   await runAsyncRunner(process.argv[2]);

package/scripts/build-dist.mjs

@@ -5,7 +5,7 @@
  *
  * 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.
+ * assets, and syntax-checks packaged scripts.
  */
 
 import { spawnSync } from "node:child_process";

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/recipes-discovery.test.ts",
+  "tests/registry.test.ts",
+  "tests/runtime.test.ts",
+  "tests/async-runs.test.ts",
+  "tests/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);
 }