@llblab/pi-actors 0.22.2 → 0.22.4

package/lib/async-runs.ts

@@ -4,8 +4,8 @@
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
 
-import { randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import {
   closeSync,
   constants,
@@ -133,7 +133,10 @@ const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 
 function packageRoot(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
-  if (basename(moduleDir) === "lib" && basename(dirname(moduleDir)) === "dist") {
+  if (
+    basename(moduleDir) === "lib" &&
+    basename(dirname(moduleDir)) === "dist"
+  ) {
     return dirname(dirname(moduleDir));
   }
   return dirname(moduleDir);
@@ -409,84 +412,88 @@ export function startRun(
   try {
     assertNoActiveRunState(stateDir);
     prepareStateDirForStart(stateDir);
-  const stdout = join(stateDir, "stdout.log");
-  const stderr = join(stateDir, "stderr.log");
-  const recipeFile = startParams.file
-    ? resolveRecipeFile(startParams.file)
-    : undefined;
-  const recipe = startParams.name || getRunIdFromFile(recipeFile);
-  const includeActorRecipeContext =
-    startParams.actor_context !== false && startParams.actor_context !== "off";
-  const recipeContextRecords = recipeFile && includeActorRecipeContext
-    ? RecipeReferences.buildRecipeContextRecords(recipeFile)
-    : undefined;
-  if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-    RecipeUsage.recordRecipeLaunch(recipeFile);
-  }
-  const outFd = openSync(stdout, "a");
-  const errFd = openSync(stderr, "a");
-  const argv = asyncRunnerArgv(stateDir);
-  const values = {
-    ...(startParams.values || {}),
-    actor_address: `run:${run}`,
-    communication_file: join(stateDir, "communication.json"),
-    default_room: `room:${run}`,
-    run_id: run,
-    state_dir: stateDir,
-  };
-  const outputValues = {
-    ...(startParams.defaults || {}),
-    ...values,
-  };
-  const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
-  const meta: AsyncRunMeta = {
-    argv: [process.execPath, ...argv],
-    createdAt: new Date().toISOString(),
-    cwd,
-    ...(startParams.launch_source ? { launch_source: startParams.launch_source } : {}),
-    ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
-    pid: 0,
-    ...(recipe ? { recipe } : {}),
-    ...(recipeFile ? { recipe_file: recipeFile } : {}),
-    run,
-    state_dir: stateDir,
-    status: "running",
-    ...(startParams.tool ? { tool: startParams.tool } : {}),
-    template: resolved.template,
-    values,
-    ...(artifacts ? { artifacts } : {}),
-    ...(startParams.control ? { control: startParams.control } : {}),
-    ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
-    ...(recipeContextRecords && recipeContextRecords.length > 0
-      ? { recipe_context_records: recipeContextRecords }
-      : {}),
-    ...(startParams.retire_when === "children_terminal"
-      ? { retire_when: "children_terminal" as const }
-      : {}),
-  };
-  writeJsonAtomic(join(stateDir, "run.json"), meta);
-  const child = spawn(process.execPath, argv, {
-    cwd,
-    detached: true,
-    stdio: ["ignore", outFd, errFd],
-  });
-  closeSync(outFd);
-  closeSync(errFd);
-  meta.pid = child.pid ?? 0;
-  writeJsonAtomic(join(stateDir, "run.json"), meta);
-  writeJsonAtomic(join(stateDir, "progress.json"), {
-    completed: 0,
-    failures: [],
-    phase: "starting",
-    updatedAt: new Date().toISOString(),
-  });
-  writeFileSync(
-    join(stateDir, "events.jsonl"),
-    `${JSON.stringify({ event: "run.start", run, pid: meta.pid, ts: new Date().toISOString() })}\n`,
-    { flag: "a" },
-  );
-  child.unref();
-  return meta;
+    const stdout = join(stateDir, "stdout.log");
+    const stderr = join(stateDir, "stderr.log");
+    const recipeFile = startParams.file
+      ? resolveRecipeFile(startParams.file)
+      : undefined;
+    const recipe = startParams.name || getRunIdFromFile(recipeFile);
+    const includeActorRecipeContext =
+      startParams.actor_context !== false &&
+      startParams.actor_context !== "off";
+    const recipeContextRecords =
+      recipeFile && includeActorRecipeContext
+        ? RecipeReferences.buildRecipeContextRecords(recipeFile)
+        : undefined;
+    if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
+      RecipeUsage.recordRecipeLaunch(recipeFile);
+    }
+    const outFd = openSync(stdout, "a");
+    const errFd = openSync(stderr, "a");
+    const argv = asyncRunnerArgv(stateDir);
+    const values = {
+      ...(startParams.values || {}),
+      actor_address: `run:${run}`,
+      communication_file: join(stateDir, "communication.json"),
+      default_room: `room:${run}`,
+      run_id: run,
+      state_dir: stateDir,
+    };
+    const outputValues = {
+      ...(startParams.defaults || {}),
+      ...values,
+    };
+    const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
+    const meta: AsyncRunMeta = {
+      argv: [process.execPath, ...argv],
+      createdAt: new Date().toISOString(),
+      cwd,
+      ...(startParams.launch_source
+        ? { launch_source: startParams.launch_source }
+        : {}),
+      ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
+      pid: 0,
+      ...(recipe ? { recipe } : {}),
+      ...(recipeFile ? { recipe_file: recipeFile } : {}),
+      run,
+      state_dir: stateDir,
+      status: "running",
+      ...(startParams.tool ? { tool: startParams.tool } : {}),
+      template: resolved.template,
+      values,
+      ...(artifacts ? { artifacts } : {}),
+      ...(startParams.control ? { control: startParams.control } : {}),
+      ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+      ...(recipeContextRecords && recipeContextRecords.length > 0
+        ? { recipe_context_records: recipeContextRecords }
+        : {}),
+      ...(startParams.retire_when === "children_terminal"
+        ? { retire_when: "children_terminal" as const }
+        : {}),
+    };
+    writeJsonAtomic(join(stateDir, "run.json"), meta);
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      detached: true,
+      stdio: ["ignore", outFd, errFd],
+    });
+    closeSync(outFd);
+    closeSync(errFd);
+    meta.pid = child.pid ?? 0;
+    writeJsonAtomic(join(stateDir, "run.json"), meta);
+    writeJsonAtomic(join(stateDir, "progress.json"), {
+      completed: 0,
+      failures: [],
+      phase: "starting",
+      updatedAt: new Date().toISOString(),
+    });
+    writeFileSync(
+      join(stateDir, "events.jsonl"),
+      `${JSON.stringify({ event: "run.start", run, pid: meta.pid, ts: new Date().toISOString() })}\n`,
+      { flag: "a" },
+    );
+    child.unref();
+    return meta;
   } finally {
     releaseStartLock();
   }
@@ -806,7 +813,10 @@ export function claimRunInboxMessage(
       ...messages[index],
       claimed_at: new Date().toISOString(),
       claimed_by: owner,
-      id: typeof messages[index].id === "string" ? messages[index].id : randomUUID(),
+      id:
+        typeof messages[index].id === "string"
+          ? messages[index].id
+          : randomUUID(),
       status: "claimed",
     } satisfies RunInboxMessage;
     messages[index] = claimed;
@@ -928,9 +938,10 @@ function appendRunInboxMessage(stateDir: string, message: string): string {
   let record: Record<string, unknown>;
   try {
     const parsed = JSON.parse(message) as unknown;
-    record = parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : { body: parsed, type: "run.message" };
+    record =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : { body: parsed, type: "run.message" };
   } catch {
     record = { body: message, type: "run.message" };
   }
@@ -1057,7 +1068,13 @@ export async function sendRunMessage(
   const payload = message.endsWith("\n") ? message : `${message}\n`;
   const payloadBytes = Buffer.byteLength(payload);
   const inboxId = appendRunInboxMessage(stateDir, message);
-  const wake = notifyRunMessageWake(stateDir, run, payloadBytes, endpoint, inboxId);
+  const wake = notifyRunMessageWake(
+    stateDir,
+    run,
+    payloadBytes,
+    endpoint,
+    inboxId,
+  );
   const runtimePlatform = options.platform ?? process.platform;
   if (endpoint.type === "mailbox") {
     return {
@@ -1066,6 +1083,7 @@ export async function sendRunMessage(
       control: "inbox.jsonl",
       control_path: endpoint.path,
       control_type: endpoint.type,
+      inbox_id: inboxId,
       queued: true,
       run,
       sent: true,
@@ -1087,6 +1105,7 @@ export async function sendRunMessage(
         control: "control.fifo",
         control_path: endpoint.path,
         control_type: endpoint.type,
+        inbox_id: inboxId,
         run,
         sent: true,
         state_dir: stateDir,
@@ -1104,13 +1123,28 @@ export async function sendRunMessage(
       control: endpoint.path,
       control_path: endpoint.path,
       control_type: endpoint.type,
+      inbox_id: inboxId,
       run,
       sent: true,
       state_dir: stateDir,
     };
   } catch (error) {
-    throw new Error(
-      `Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`,
+    const deliveryError =
+      error instanceof Error ? error.message : String(error);
+    throw Object.assign(
+      new Error(
+        `Run control endpoint is not ready: ${endpoint.path}: ${deliveryError}`,
+      ),
+      {
+        control_path: endpoint.path,
+        control_type: endpoint.type,
+        delivery_error: deliveryError,
+        inbox_id: inboxId,
+        queued: true,
+        run,
+        sent: false,
+        state_dir: stateDir,
+      },
     );
   }
 }
@@ -1150,7 +1184,9 @@ function signalOwnedRunProcess(
     const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
     if (result.status !== 0) {
       throw new Error(
-        result.stderr?.trim() || result.stdout?.trim() || `${plan.command} failed`,
+        result.stderr?.trim() ||
+          result.stdout?.trim() ||
+          `${plan.command} failed`,
       );
     }
     return plan;

package/lib/observability.ts

@@ -5,7 +5,14 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -229,13 +236,25 @@ export function summarizeRuns(
     const descendantSubagents = processSubagentsByRun.get(run.run) ?? 0;
     return descendantSubagents > 0 ? { ...run, descendantSubagents } : run;
   });
-  const runningRuns = runsWithDescendants.filter((run) => run.status === "running");
+  const runningRuns = runsWithDescendants.filter(
+    (run) => run.status === "running",
+  );
   const running = runningRuns.length;
-  const done = runsWithDescendants.filter((run) => run.status === "done").length;
-  const exited = runsWithDescendants.filter((run) => run.status === "exited").length;
-  const failed = runsWithDescendants.filter((run) => run.status === "failed").length;
-  const cancelled = runsWithDescendants.filter((run) => run.status === "cancelled").length;
-  const killed = runsWithDescendants.filter((run) => run.status === "killed").length;
+  const done = runsWithDescendants.filter(
+    (run) => run.status === "done",
+  ).length;
+  const exited = runsWithDescendants.filter(
+    (run) => run.status === "exited",
+  ).length;
+  const failed = runsWithDescendants.filter(
+    (run) => run.status === "failed",
+  ).length;
+  const cancelled = runsWithDescendants.filter(
+    (run) => run.status === "cancelled",
+  ).length;
+  const killed = runsWithDescendants.filter(
+    (run) => run.status === "killed",
+  ).length;
   const progressSubagents = runningRuns.reduce(
     (sum, run) => sum + Math.max(1, Math.floor(run.activeSubagents ?? 0)),
     0,
@@ -244,7 +263,10 @@ export function summarizeRuns(
     (sum, count) => sum + count,
     0,
   );
-  const runningSubagents = Math.max(progressSubagents, running + processSubagents);
+  const runningSubagents = Math.max(
+    progressSubagents,
+    running + processSubagents,
+  );
   return {
     cancelled,
     done,
@@ -278,11 +300,16 @@ function getProcCommand(pid: string): string {
   return (readProcFile(`/proc/${pid}/cmdline`) ?? "").replaceAll("\0", " ");
 }
 
-function getRunningRunPidMap(stateRoot: string, ownerId?: string): Map<string, string> {
+function getRunningRunPidMap(
+  stateRoot: string,
+  ownerId?: string,
+): Map<string, string> {
   const pids = new Map<string, string>();
   for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
     if (run.status !== "running") continue;
-    const status = AsyncRuns.getRunStatus(run.stateDir ?? join(stateRoot, run.run));
+    const status = AsyncRuns.getRunStatus(
+      run.stateDir ?? join(stateRoot, run.run),
+    );
     const pid = Number(status.pid || 0);
     if (pid > 0) pids.set(String(pid), run.run);
   }
@@ -420,7 +447,10 @@ export function findRunRetirementCandidates(
   return summary.runs
     .map((run) => {
       const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
-      const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
+      const descendantSubagents = Math.max(
+        0,
+        Math.floor(run.descendantSubagents ?? 0),
+      );
       const childRuns = run.stateDir
         ? summary.runs.filter(
             (child) =>
@@ -429,7 +459,9 @@ export function findRunRetirementCandidates(
               isNestedStateDir(run.stateDir!, child.stateDir),
           )
         : [];
-      const runningChildRuns = childRuns.filter((child) => child.status === "running").length;
+      const runningChildRuns = childRuns.filter(
+        (child) => child.status === "running",
+      ).length;
       return {
         activeSubagents,
         childRuns: childRuns.length,
@@ -441,7 +473,9 @@ export function findRunRetirementCandidates(
           !run.terminalHandled &&
           activeSubagents + descendantSubagents + runningChildRuns <= 0,
         run,
-        terminalChildRuns: childRuns.filter((child) => TERMINAL.has(child.status)).length,
+        terminalChildRuns: childRuns.filter((child) =>
+          TERMINAL.has(child.status),
+        ).length,
       };
     })
     .filter((item) => item.ready)
@@ -462,7 +496,11 @@ export async function executeRunRetirements(
   const results: RunRetirementExecution[] = [];
   for (const candidate of findRunRetirementCandidates(summary)) {
     if (options.attempted?.has(candidate.stateDir)) {
-      results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+      results.push({
+        action: "skip",
+        run: candidate.run,
+        stateDir: candidate.stateDir,
+      });
       continue;
     }
     options.attempted?.add(candidate.stateDir);
@@ -472,12 +510,18 @@ export async function executeRunRetirements(
         `Retiring actor ${candidate.run} after child runs reached terminal state`,
         "info",
       );
-      results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+      results.push({
+        action: "stop",
+        run: candidate.run,
+        stateDir: candidate.stateDir,
+      });
       continue;
     } catch (error) {
       try {
         const cancelResult = options.cancelRun(candidate);
-        const cancelled = Boolean((cancelResult as { cancelled?: unknown }).cancelled);
+        const cancelled = Boolean(
+          (cancelResult as { cancelled?: unknown }).cancelled,
+        );
         options.notify?.(
           cancelled
             ? `Retiring actor ${candidate.run} by cancellation after graceful stop failed`
@@ -486,13 +530,23 @@ export async function executeRunRetirements(
         );
         results.push({
           action: cancelled ? "cancel" : "skip",
-          ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+          ...(cancelled
+            ? {}
+            : {
+                error: error instanceof Error ? error.message : String(error),
+              }),
           run: candidate.run,
           stateDir: candidate.stateDir,
         });
       } catch (cancelError) {
-        const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
-        options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
+        const message =
+          cancelError instanceof Error
+            ? cancelError.message
+            : String(cancelError);
+        options.notify?.(
+          `Actor retirement failed for ${candidate.run}: ${message}`,
+          "error",
+        );
         results.push({
           action: "failed",
           error: message,
@@ -505,13 +559,20 @@ export async function executeRunRetirements(
   return results;
 }
 
+function runObservationKey(
+  run: Pick<RunObservation, "run" | "stateDir">,
+): string {
+  return run.stateDir ?? run.run;
+}
+
 export function detectRunTransitions(
   previous: Map<string, RunObservedStatus>,
   summary: RunSummary,
 ): RunTransition[] {
   const transitions: RunTransition[] = [];
   for (const run of summary.runs) {
-    const old = previous.get(run.run);
+    const key = runObservationKey(run);
+    const old = previous.get(key);
     if (old && old !== run.status && TERMINAL.has(run.status)) {
       transitions.push({
         from: old,
@@ -525,7 +586,7 @@ export function detectRunTransitions(
         ...(run.tool ? { tool: run.tool } : {}),
       });
     }
-    previous.set(run.run, run.status);
+    previous.set(key, run.status);
   }
   return transitions;
 }
@@ -599,12 +660,12 @@ export function pruneRunObservationState(
   summary: RunSummary,
   terminalRuns: Iterable<string> = [],
 ): void {
-  const activeRuns = new Set(summary.runs.map((run) => run.run));
+  const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
   const terminalRunSet = new Set(terminalRuns);
   const terminalLineKeys = new Set(
     summary.runs
-      .filter((run) => terminalRunSet.has(run.run))
-      .map((run) => run.stateDir ?? run.run),
+      .filter((run) => terminalRunSet.has(runObservationKey(run)))
+      .map((run) => runObservationKey(run)),
   );
   const activeLineKeys = new Set(
     summary.runs.map((run) => run.stateDir ?? run.run),