@llblab/pi-actors 0.23.0 → 0.24.1

package/lib/locker.ts

@@ -0,0 +1,340 @@
+/**
+ * Local coordination locker service entrypoint logic.
+ * Zones: coordination locks, task leases, platform control endpoint
+ */
+
+// @ts-nocheck
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createServer } from "node:net";
+import { dirname, join, resolve } from "node:path";
+import readline from "node:readline";
+
+function parseArgs(argv) {
+  const args = { mode: "serve", stateDir: "", leaseMs: 600000, lines: 20 };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "serve" || arg === "snapshot") args.mode = arg;
+    else if (arg === "--state-dir") args.stateDir = argv[++index] ?? "";
+    else if (arg === "--lease-ms")
+      args.leaseMs = Number(argv[++index] ?? args.leaseMs);
+    else if (arg === "--lines")
+      args.lines = Number(argv[++index] ?? args.lines);
+  }
+  if (!args.stateDir) throw new Error("--state-dir is required");
+  if (!Number.isFinite(args.leaseMs) || args.leaseMs <= 0)
+    args.leaseMs = 600000;
+  if (!Number.isFinite(args.lines) || args.lines <= 0) args.lines = 20;
+  return args;
+}
+
+export async function runLocker(argv = process.argv.slice(2)) {
+const { mode, stateDir, leaseMs, lines } = parseArgs(argv);
+const queuePath = join(stateDir, "queue.json");
+const locksPath = join(stateDir, "locks.json");
+const journalPath = join(stateDir, "journal.jsonl");
+const outboxPath = join(stateDir, "outbox.jsonl");
+const controlPath = join(stateDir, "control.fifo");
+mkdirSync(stateDir, { recursive: true });
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function getControlEndpoint() {
+  if (process.platform !== "win32") return { path: controlPath, type: "fifo" };
+  const hash = createHash("sha256")
+    .update(resolve(stateDir))
+    .digest("hex")
+    .slice(0, 20);
+  return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
+}
+function writeControlEndpoint(endpoint) {
+  writeJson(join(stateDir, "control.json"), endpoint);
+  const runPath = join(stateDir, "run.json");
+  const run = readJson(runPath, undefined);
+  if (run && typeof run === "object")
+    writeJson(runPath, { ...run, control: endpoint });
+}
+function journal(event, data = {}) {
+  appendFileSync(
+    journalPath,
+    `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
+  );
+}
+function outbox(type, summary, body = {}, level = "info") {
+  appendFileSync(
+    outboxPath,
+    `${JSON.stringify({ to: "coordinator", from: `run:${process.env.run_id ?? "locker"}`, type, event: type, summary, body, data: body, delivery: "followup", level, ts: new Date().toISOString() })}\n`,
+  );
+}
+function now() {
+  return Date.now();
+}
+function cleanExpiredLocks(locks) {
+  const current = now();
+  const kept = {};
+  for (const [key, lock] of Object.entries(locks)) {
+    if (Number(lock.expiresAt) > current) kept[key] = lock;
+    else journal("lock.expired", { resource: key, owner: lock.owner });
+  }
+  return kept;
+}
+function normalizeMessage(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return undefined;
+  if (["stop", "quit", "exit", "cancel"].includes(trimmed.toLowerCase())) {
+    return { type: "control.stop", body: {} };
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return { type: "lock.enqueue", body: { task: trimmed } };
+  }
+}
+function tailJournal(count) {
+  if (!existsSync(journalPath)) return [];
+  return readFileSync(journalPath, "utf8")
+    .trimEnd()
+    .split("\n")
+    .filter(Boolean)
+    .slice(-count)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
+}
+function printSnapshot() {
+  const locks = cleanExpiredLocks(readJson(locksPath, {}));
+  writeJson(locksPath, locks);
+  const queue = readJson(queuePath, { items: [] });
+  console.log(
+    JSON.stringify(
+      {
+        queueDepth: Array.isArray(queue.items) ? queue.items.length : 0,
+        queue,
+        locks,
+        journal: tailJournal(lines),
+      },
+      null,
+      2,
+    ),
+  );
+}
+function nextTask(queue, locks) {
+  const items = Array.isArray(queue.items) ? queue.items : [];
+  const index = items.findIndex((item) => {
+    const resources = Array.isArray(item.resources) ? item.resources : [];
+    return resources.every((resource) => !locks[resource]);
+  });
+  if (index < 0) return undefined;
+  return items.splice(index, 1)[0];
+}
+function handle(message) {
+  const type = message.type || message.event || "lock.enqueue";
+  const body =
+    message.body && typeof message.body === "object" ? message.body : message;
+  let queue = readJson(queuePath, { items: [] });
+  let locks = cleanExpiredLocks(readJson(locksPath, {}));
+  if (type === "control.stop" || type === "control.cancel") {
+    writeJson(locksPath, locks);
+    journal("control.stop", {});
+    outbox("lock.stopped", "Locker stopped", {
+      queueDepth: queue.items?.length ?? 0,
+    });
+    process.exit(0);
+  }
+  if (type === "lock.enqueue" || type === "coord.enqueue") {
+    const item = {
+      id: body.id || `task-${Date.now()}`,
+      task: body.task ?? body,
+      resources: body.resources ?? [],
+      enqueuedAt: new Date().toISOString(),
+    };
+    queue.items = [...(queue.items ?? []), item];
+    writeJson(queuePath, queue);
+    writeJson(locksPath, locks);
+    journal("lock.enqueued", { id: item.id, resources: item.resources });
+    outbox("lock.enqueued", `Queued task ${item.id}`, {
+      id: item.id,
+      queueDepth: queue.items.length,
+    });
+    return;
+  }
+  if (type === "lock.claim" || type === "coord.claim") {
+    const owner = body.owner || message.from || "worker";
+    const item = nextTask(queue, locks);
+    if (!item) {
+      writeJson(queuePath, queue);
+      writeJson(locksPath, locks);
+      outbox("lock.empty", "No claimable task", {
+        owner,
+        queueDepth: queue.items?.length ?? 0,
+      });
+      return;
+    }
+    for (const resource of item.resources ?? [])
+      locks[resource] = { owner, task: item.id, expiresAt: now() + leaseMs };
+    writeJson(queuePath, queue);
+    writeJson(locksPath, locks);
+    journal("lock.assigned", {
+      id: item.id,
+      owner,
+      resources: item.resources,
+    });
+    outbox("lock.assigned", `Assigned task ${item.id}`, { owner, task: item });
+    return;
+  }
+  if (type === "lock.acquire") {
+    const resource = body.resource;
+    const owner = body.owner || message.from || "worker";
+    if (!resource) throw new Error("lock.acquire body.resource is required");
+    if (locks[resource])
+      outbox(
+        "lock.denied",
+        `Lock denied ${resource}`,
+        { resource, owner, current: locks[resource] },
+        "warning",
+      );
+    else {
+      locks[resource] = { owner, expiresAt: now() + leaseMs };
+      outbox("lock.granted", `Lock granted ${resource}`, { resource, owner });
+    }
+    writeJson(locksPath, locks);
+    return;
+  }
+  if (type === "lock.renew") {
+    const resource = body.resource;
+    const owner = body.owner || message.from || "worker";
+    if (!resource) throw new Error("lock.renew body.resource is required");
+    const current = locks[resource];
+    if (!current) {
+      outbox(
+        "lock.denied",
+        `Lock renew denied ${resource}`,
+        { resource, owner, reason: "missing" },
+        "warning",
+      );
+    } else if (current.owner !== owner) {
+      outbox(
+        "lock.denied",
+        `Lock renew denied ${resource}`,
+        { resource, owner, current },
+        "warning",
+      );
+    } else {
+      locks[resource] = { ...current, expiresAt: now() + leaseMs };
+      outbox("lock.renewed", `Lock renewed ${resource}`, { resource, owner });
+    }
+    writeJson(locksPath, locks);
+    return;
+  }
+  if (type === "lock.release") {
+    const resource = body.resource;
+    if (resource) delete locks[resource];
+    writeJson(locksPath, locks);
+    outbox("lock.released", `Lock released ${resource}`, { resource });
+    return;
+  }
+  if (
+    type === "lock.complete" ||
+    type === "lock.fail" ||
+    type === "coord.complete" ||
+    type === "coord.fail"
+  ) {
+    const eventType = type.startsWith("coord.")
+      ? type.replace("coord.", "lock.")
+      : type;
+    journal(eventType, body);
+    outbox(
+      eventType,
+      `${eventType} ${body.id ?? ""}`.trim(),
+      body,
+      eventType === "lock.fail" ? "error" : "info",
+    );
+    writeJson(locksPath, locks);
+    writeJson(queuePath, queue);
+    return;
+  }
+  journal("lock.unknown", { type, body });
+  outbox("lock.unknown", `Unknown message ${type}`, { type, body }, "warning");
+}
+
+if (mode === "snapshot") {
+  printSnapshot();
+  process.exit(0);
+}
+
+function handleLine(line) {
+  const message = normalizeMessage(line);
+  if (!message) return;
+  try {
+    handle(message);
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    journal("lock.error", { error: text });
+    outbox("lock.error", text, { error: text }, "error");
+  }
+}
+
+async function serveFifo(endpoint) {
+  if (!existsSync(endpoint.path)) {
+    const result = spawnSync("mkfifo", [endpoint.path]);
+    if (result.status !== 0)
+      throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+  }
+  writeControlEndpoint(endpoint);
+  while (true) {
+    const stream = await import("node:fs").then((fs) =>
+      fs.createReadStream(endpoint.path, { encoding: "utf8" }),
+    );
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) handleLine(line);
+  }
+}
+
+async function serveNamedPipe(endpoint) {
+  rmSync(endpoint.path, { force: true });
+  const server = createServer((socket) => {
+    const rl = readline.createInterface({ input: socket, crlfDelay: Infinity });
+    rl.on("line", handleLine);
+  });
+  await new Promise((resolveReady, rejectReady) => {
+    server.once("error", rejectReady);
+    server.listen(endpoint.path, () => {
+      server.off("error", rejectReady);
+      writeControlEndpoint(endpoint);
+      resolveReady();
+    });
+  });
+  await new Promise(() => {});
+}
+
+const endpoint = getControlEndpoint();
+writeJson(queuePath, readJson(queuePath, { items: [] }));
+writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
+journal("lock.started", { leaseMs, control: endpoint.type });
+outbox("lock.started", "Locker ready", { leaseMs, control: endpoint.type });
+if (endpoint.type === "named-pipe") await serveNamedPipe(endpoint);
+else await serveFifo(endpoint);
+}

package/lib/mailbox-loop.ts

@@ -0,0 +1,148 @@
+/**
+ * Minimal mailbox loop helpers.
+ * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
+ * Owns small reusable primitives for recipe authors; scheduling and task policy stay outside.
+ */
+
+import {
+  claimBranchInboxMessage,
+  updateBranchInboxMessageStatus,
+  type BranchInboxRecord,
+} from "./actor-rooms.ts";
+import {
+  claimRunInboxMessage,
+  updateRunInboxMessageStatus,
+  type RunInboxMessage,
+} from "./async-runs.ts";
+
+export type MailboxLoopMessage = RunInboxMessage | BranchInboxRecord;
+
+export type MailboxLoopTarget =
+  | {
+      kind: "run";
+      runOrDir: string;
+    }
+  | {
+      address: string;
+      kind: "branch";
+      run: string;
+      stateDir: string;
+    };
+
+export interface MailboxLoopClaimOptions {
+  owner?: string;
+  statuses?: string[];
+}
+
+export interface MailboxLoopHandleResult {
+  handled: boolean;
+  id?: string;
+  message?: MailboxLoopMessage;
+  target: MailboxLoopTarget;
+}
+
+export interface MailboxLoopDrainOptions extends MailboxLoopClaimOptions {
+  maxMessages?: number;
+  stopOnControl?: boolean;
+}
+
+export interface MailboxLoopDrainResult {
+  handled: number;
+  stopped: boolean;
+  target: MailboxLoopTarget;
+}
+
+export function isMailboxLoopStopMessage(message: unknown): boolean {
+  const type =
+    message && typeof message === "object" && "type" in message
+      ? (message as { type?: unknown }).type
+      : undefined;
+  return (
+    type === "control.stop" ||
+    type === "control.cancel" ||
+    type === "control.kill"
+  );
+}
+
+function messageId(
+  message: MailboxLoopMessage | undefined,
+): string | undefined {
+  return typeof message?.id === "string" ? message.id : undefined;
+}
+
+export function claimMailboxLoopMessage(
+  target: MailboxLoopTarget,
+  options: MailboxLoopClaimOptions = {},
+): MailboxLoopMessage | undefined {
+  const owner = options.owner ?? "mailbox-loop";
+  const statuses = options.statuses ?? ["queued"];
+  return target.kind === "run"
+    ? claimRunInboxMessage(target.runOrDir, owner, statuses)
+    : claimBranchInboxMessage(
+        target.stateDir,
+        target.run,
+        target.address,
+        owner,
+        statuses,
+      );
+}
+
+export function updateMailboxLoopMessageStatus(
+  target: MailboxLoopTarget,
+  id: string,
+  status: "claimed" | "handled" | "failed",
+  metadata: Record<string, unknown> = {},
+): boolean {
+  return target.kind === "run"
+    ? updateRunInboxMessageStatus(target.runOrDir, id, status, metadata)
+    : updateBranchInboxMessageStatus(
+        target.stateDir,
+        target.run,
+        target.address,
+        id,
+        status,
+        metadata,
+      );
+}
+
+export async function handleMailboxLoopOnce(
+  target: MailboxLoopTarget,
+  handler: (message: MailboxLoopMessage) => Promise<void> | void,
+  options: MailboxLoopClaimOptions = {},
+): Promise<MailboxLoopHandleResult> {
+  const message = claimMailboxLoopMessage(target, options);
+  const id = messageId(message);
+  if (!message || !id) return { handled: false, target };
+  try {
+    await handler(message);
+    updateMailboxLoopMessageStatus(target, id, "handled");
+    return { handled: true, id, message, target };
+  } catch (error) {
+    updateMailboxLoopMessageStatus(target, id, "failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}
+
+export async function drainMailboxLoopMessages(
+  target: MailboxLoopTarget,
+  handler: (message: MailboxLoopMessage) => Promise<void> | void,
+  options: MailboxLoopDrainOptions = {},
+): Promise<MailboxLoopDrainResult> {
+  const maxMessages = Math.max(1, Math.floor(options.maxMessages ?? 100));
+  let handled = 0;
+  for (; handled < maxMessages; handled += 1) {
+    const result = await handleMailboxLoopOnce(target, handler, options);
+    if (!result.handled || !result.message) {
+      return { handled, stopped: false, target };
+    }
+    if (
+      options.stopOnControl !== false &&
+      isMailboxLoopStopMessage(result.message)
+    ) {
+      return { handled: handled + 1, stopped: true, target };
+    }
+  }
+  return { handled, stopped: false, target };
+}

package/lib/observability.ts

@@ -16,6 +16,7 @@ import {
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
 
 export type RunObservedStatus =
   | "running"
@@ -605,15 +606,12 @@ function normalizeOutboxLevel(value: unknown): RunOutboxLevel {
   return value === "warning" || value === "error" ? value : "info";
 }
 
-function parseOutboxLine(
-  line: string,
+function parseOutboxRecord(
+  raw: Record<string, unknown>,
   run: RunObservation,
   index: number,
 ): RunOutboxEvent | undefined {
   if (!run.stateDir) return undefined;
-  try {
-    const raw = JSON.parse(line) as Record<string, unknown>;
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
     const event =
       typeof raw.event === "string" && raw.event.trim()
         ? raw.event.trim()
@@ -647,17 +645,13 @@ function parseOutboxLine(
       summary,
       ts,
     };
-  } catch {
-    return undefined;
-  }
 }
 
-function readOutboxLines(run: RunObservation): string[] {
+function readOutboxRecords(run: RunObservation): Record<string, unknown>[] {
   if (!run.stateDir) return [];
-  const path = join(run.stateDir, "outbox.jsonl");
-  if (!existsSync(path)) return [];
-  const content = readFileSync(path, "utf8").trimEnd();
-  return content ? content.split("\n") : [];
+  return readJsonlFileResilient<Record<string, unknown>>(
+    join(run.stateDir, "outbox.jsonl"),
+  ).records;
 }
 
 export function pruneRunObservationState(
@@ -665,6 +659,7 @@ export function pruneRunObservationState(
   previousLineCounts: Map<string, number>,
   summary: RunSummary,
   terminalRuns: Iterable<string> = [],
+  seenEventIds: Map<string, Set<string>> = new Map(),
 ): void {
   const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
   const terminalRunSet = new Set(terminalRuns);
@@ -685,23 +680,33 @@ export function pruneRunObservationState(
       previousLineCounts.delete(key);
     }
   }
+  for (const key of seenEventIds.keys()) {
+    if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+      seenEventIds.delete(key);
+    }
+  }
 }
 
 export function detectRunOutboxEvents(
   previousLineCounts: Map<string, number>,
   summary: RunSummary,
+  seenEventIds: Map<string, Set<string>> = new Map(),
 ): RunOutboxEvent[] {
   const events: RunOutboxEvent[] = [];
   for (const run of summary.runs) {
     const key = run.stateDir ?? run.run;
-    const lines = readOutboxLines(run);
+    const records = readOutboxRecords(run);
     const previousCount = previousLineCounts.get(key) ?? 0;
-    const start = Math.min(previousCount, lines.length);
-    for (let index = start; index < lines.length; index += 1) {
-      const event = parseOutboxLine(lines[index], run, index);
-      if (event) events.push(event);
+    const start = Math.min(previousCount, records.length);
+    const seen = seenEventIds.get(key) ?? new Set<string>();
+    for (let index = start; index < records.length; index += 1) {
+      const event = parseOutboxRecord(records[index], run, index);
+      if (!event || seen.has(event.id)) continue;
+      events.push(event);
+      seen.add(event.id);
     }
-    previousLineCounts.set(key, lines.length);
+    previousLineCounts.set(key, records.length);
+    seenEventIds.set(key, seen);
   }
   return events;
 }

package/lib/prompts.ts

@@ -29,7 +29,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;

package/lib/recipe-references.ts

@@ -311,6 +311,35 @@ function parseMarkdownFrontmatterObject(
   return result;
 }
 
+function normalizeMarkdownFrontmatterField(
+  key: string,
+  value: unknown,
+): unknown {
+  if (key === "args" && typeof value === "string") {
+    return value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+  if (key === "defaults" && Array.isArray(value)) {
+    return Object.fromEntries(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => {
+          const separator = item.indexOf(":");
+          return separator < 0
+            ? [item.trim(), ""]
+            : [
+                item.slice(0, separator).trim(),
+                parseMarkdownScalar(item.slice(separator + 1)),
+              ];
+        })
+        .filter(([name]) => Boolean(name)),
+    );
+  }
+  return value;
+}
+
 function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   const lines = value.split(/\r?\n/);
@@ -320,7 +349,10 @@ function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
     const match = line.match(/^([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
     if (!match) continue;
     if (match[2]) {
-      result[match[1]] = parseMarkdownScalar(match[2]);
+      result[match[1]] = normalizeMarkdownFrontmatterField(
+        match[1],
+        parseMarkdownScalar(match[2]),
+      );
       continue;
     }
     const nested: string[] = [];
@@ -328,7 +360,10 @@ function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
       index += 1;
       nested.push(lines[index]);
     }
-    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+    result[match[1]] = normalizeMarkdownFrontmatterField(
+      match[1],
+      parseMarkdownFrontmatterObject(nested),
+    );
   }
   return result;
 }