@llblab/pi-actors 0.25.0 → 0.26.0

package/docs/template-recipes.md

@@ -80,7 +80,7 @@ defaults:
   scope: docs
 mailbox:
   accepts:
-    - control.stop
+    - control.kill
 ---
 
 Human notes can explain intent, examples, or review guidance.
@@ -155,7 +155,7 @@ Use recipe-level `mailbox` to document the semantic messages a recipe actor acce
       "control.continue",
       "control.revise",
       "control.approve",
-      "control.stop"
+      "control.kill"
     ],
     "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
   }

package/lib/actor-worker.ts

@@ -3,17 +3,20 @@
  * Zones: worker demo, mailbox loop recipe runtime
  */
 
-import { appendFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { appendRoomMessage, ensureRoomMember } from "./actor-rooms.ts";
+import { appendRoomMessage, ensureRoomMember, readBranchInboxMessages } from "./actor-rooms.ts";
 import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.ts";
 
 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 function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs {
@@ -41,12 +44,23 @@ function text(value: unknown): string {
   return typeof value === "string" ? value : JSON.stringify(value);
 }
 
+function enabled(value: unknown): boolean {
+  return value !== false && value !== "false" && value !== "0";
+}
+
+function safeName(value: unknown): string {
+  return String(value ?? "unknown").replaceAll(/[^A-Za-z0-9_.-]+/g, "_");
+}
+
 export async function runActorWorker(argv = process.argv.slice(2)): Promise<void> {
   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]");
@@ -55,6 +69,8 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
   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: string, data: Record<string, unknown> = {}): void {
     appendFileSync(
@@ -63,6 +79,30 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
     );
   }
 
+  function staleClaims(): number {
+    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: string, data: Record<string, unknown> = {}): void {
+    writeFileSync(
+      statusPath,
+      `${JSON.stringify({ artifact_dir: artifactDir, branch, run, stale_claims: staleClaims(), state, ts: new Date().toISOString(), ...data }, null, 2)}\n`,
+    );
+  }
+
+  function writeResultArtifact(id: unknown, result: string): string | undefined {
+    if (!writeArtifacts) return undefined;
+    const path = join(artifactDir, `${safeName(id)}.txt`);
+    writeFileSync(path, `${result}\n`);
+    return path;
+  }
+
   function room(type: string, summary: string, body: Record<string, unknown> = {}): void {
     appendRoomMessage(stateDir, "main", {
       body,
@@ -82,7 +122,10 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
     `${branch} joined as mailbox worker`,
   );
   room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
-  journal("worker.started", { branch, run });
+  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) {
@@ -93,6 +136,7 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
           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}`, {
@@ -100,19 +144,31 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
           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: text(message.body),
+          result,
           type: message.type,
         });
         room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
-        journal("task.handled", { id: message.id, type: message.type });
+        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, run });
+  journal("worker.done", { branch, handled, run });
+  status("done", { handled });
 }

package/package.json

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

package/recipes/actor-worker.json

@@ -4,18 +4,20 @@
   "args": [
     "repo:path",
     "branch:string",
-    "poll_ms:int"
+    "poll_ms:int",
+    "stale_claim_ms:int",
+    "write_artifacts:bool"
   ],
   "defaults": {
     "repo": "~/.pi/agent/extensions/pi-actors",
     "branch": "worker",
-    "poll_ms": "1000"
+    "poll_ms": "1000",
+    "stale_claim_ms": "0",
+    "write_artifacts": "true"
   },
   "mailbox": {
     "accepts": [
       "task.assign",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [
@@ -29,7 +31,9 @@
     ]
   },
   "artifacts": {
-    "journal": "{state_dir}/worker-events.jsonl"
+    "journal": "{state_dir}/worker-events.jsonl",
+    "status": "{state_dir}/worker-status.json",
+    "results": "{state_dir}/worker-artifacts"
   },
-  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms}"
+  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms} --stale-claim-ms {stale_claim_ms} --write-artifacts {write_artifacts}"
 }

package/recipes/lens-swarm.json

@@ -30,8 +30,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-architect-coordinator.json

@@ -26,8 +26,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-artifact-bundle.json

@@ -35,8 +35,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-artifact-report.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-artifact-write.json

@@ -21,8 +21,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-async-run-ops.json

@@ -24,8 +24,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-checkpoint-continuation.json

@@ -22,8 +22,6 @@
     "accepts": [
       "control.reply",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-development-tasking.json

@@ -24,8 +24,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-docs-maintenance.json

@@ -23,8 +23,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-media-library.json

@@ -23,8 +23,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-quorum-review.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-release-readiness.json

@@ -40,8 +40,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-release-summary.json

@@ -29,8 +29,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-repo-health.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-research-synthesis.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-review-readiness.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/pipeline-room-swarm.json

@@ -34,8 +34,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-artifact.json

@@ -19,8 +19,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-checkpoint.json

@@ -21,8 +21,6 @@
     "accepts": [
       "control.continue",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-conflict-report.json

@@ -17,8 +17,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-contradiction-map.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-critic.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-evidence-map.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-followup.json

@@ -21,8 +21,6 @@
     "accepts": [
       "control.reply",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-judge.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-merge.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-message.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-normalize.json

@@ -16,8 +16,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-plan.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-prompt.json

@@ -14,8 +14,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-quorum.json

@@ -17,8 +17,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-review-coordinator.json

@@ -36,8 +36,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-review.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-task-card.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-tools.json

@@ -13,8 +13,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagent-verify.json

@@ -19,8 +19,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/recipes/subagents-prompts.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.25.0
+  version: 0.26.0
 ---
 
 # Actors (pi-actors)
@@ -277,7 +277,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages + platform-adapted control metadata.
 - [`utility-coordinator-lock-snapshot`](../../recipes/utility-coordinator-lock-snapshot.json): one-shot JSON snapshot of a coordinator-locker state directory.
 - [`music-player`](../../recipes/music-player.json): background local/URL/directory/playlist playback actor controlled by messages.
-- [`actor-worker`](../../recipes/actor-worker.json): canonical mailbox-backed branch worker demo that claims branch inbox work, emits room-visible task lifecycle messages, and stops on standard control messages.
+- [`actor-worker`](../../recipes/actor-worker.json): canonical mailbox-backed branch worker reference that claims branch inbox work, emits room-visible task lifecycle messages, writes compact `worker-status.json`, optionally writes per-task result artifacts under `worker-artifacts/`, surfaces stale-claim counts when `stale_claim_ms` is set, and terminates on `control.kill`.
 
 ### Subagent Atoms
 

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.25.0
+  version: 0.26.0
 ---
 
 # Swarm