@llblab/pi-actors 0.22.3 → 0.22.4

package/dist/lib/tools.js

@@ -361,6 +361,7 @@ export function createRegisterToolDefinition(deps) {
             state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
             template: unionSchema([
                 stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+                looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
                 arraySchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateArray),
                 nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
             ]),
@@ -390,6 +391,16 @@ function messageBodyToToolParams(message) {
         return {};
     return { input: message.body };
 }
+function formatToolActorFailure(tool, message, params, error) {
+    const original = error instanceof Error ? error.message : String(error);
+    const paramsPreview = compactPreview(params, 240) ?? "{}";
+    return Object.assign(new Error(`tool actor ${tool} failed for message type ${message.type}: ${original}; params=${paramsPreview}`), {
+        message_type: message.type,
+        original_error: original,
+        params_preview: paramsPreview,
+        tool,
+    });
+}
 function runIdFromActorAddress(address) {
     if (!address)
         return undefined;
@@ -672,15 +683,16 @@ export function createInspectToolDefinition(deps = {}) {
                 if (view !== "mailbox")
                     throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
                 const status = assertRunAccessibleToContext(runId, ctx);
-                const messages = ActorRooms.readBranchInboxMessages(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const messages = branchInbox.messages;
                 return {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText(messages, input.verbose === true, compactBranchInbox(messages.map((message) => ({ ...message })))),
+                            text: maybeJsonText(input.verbose === true ? branchInbox : messages, input.verbose === true, `${compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`),
                         },
                     ],
-                    details: { messages },
+                    details: { corrupted: branchInbox.corrupted, messages },
                 };
             }
             switch (view) {
@@ -806,9 +818,7 @@ export function createActorMessageToolDefinition(deps = {}) {
                 const runId = address.value;
                 if (message.from)
                     assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
-                const status = message.from
-                    ? assertRunExistsForActorMessage(runId)
-                    : assertRunAccessibleToContext(runId, ctx);
+                const status = assertRunAccessibleToContext(runId, ctx);
                 const stateDir = String(status.state_dir ?? "");
                 if (stateDir && address.branch) {
                     const ensureBranchMember = (actorAddress) => {
@@ -834,7 +844,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             else if (address.kind === "room" && address.value && address.room) {
                 const runId = address.value;
                 assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
-                const status = assertRunExistsForActorMessage(runId);
+                const status = assertRunAccessibleToContext(runId, ctx);
                 const stateDir = String(status.state_dir ?? "");
                 if (!stateDir)
                     throw new Error(`${message.to} has no run state directory.`);
@@ -853,7 +863,14 @@ export function createActorMessageToolDefinition(deps = {}) {
                 if (!tool || typeof tool.execute !== "function") {
                     throw new Error(`tool actor not found or not executable: ${address.value}`);
                 }
-                const toolResult = await tool.execute(`message:${message.type}`, messageBodyToToolParams(message), _signal, _onUpdate, ctx);
+                const toolParams = messageBodyToToolParams(message);
+                let toolResult;
+                try {
+                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
+                }
+                catch (error) {
+                    throw formatToolActorFailure(address.value, message, toolParams, error);
+                }
                 result = {
                     invoked: true,
                     sent: true,

package/index.ts

@@ -174,7 +174,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       observedRuns,
       observedRunEventLines,
       summary,
-      transitions.map((transition) => transition.run),
+      transitions.map((transition) => transition.stateDir ?? transition.run),
     );
     for (const event of outboxEvents) {
       if (!Observability.shouldNotifyRunOutboxEvent(event)) continue;

package/lib/actor-rooms.ts

@@ -383,24 +383,86 @@ function updateRosterForMessage(
   return roster;
 }
 
-export function readBranchInboxMessages(
+export interface BranchInboxRecord extends ActorMessage {
+  id?: string;
+  queued_at?: string;
+  status?: string;
+}
+
+export interface BranchInboxReadResult {
+  corrupted: number;
+  messages: BranchInboxRecord[];
+}
+
+function readBranchInboxFile(
   stateDir: string,
   run: string,
   address: string,
   limit = 40,
-): Array<ActorMessage & { id?: string; queued_at?: string; status?: string }> {
+): BranchInboxReadResult {
   const branch = branchIdFromAddress(address, run);
   if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
   try {
-    return readJsonlTailLines(branchInboxFile(stateDir, branch), limit).map(
-      (line) => JSON.parse(line),
-    );
+    const lines = readJsonlTailLines(branchInboxFile(stateDir, branch), limit);
+    const messages: BranchInboxRecord[] = [];
+    let corrupted = 0;
+    for (const line of lines) {
+      try {
+        messages.push(JSON.parse(line));
+      } catch {
+        corrupted += 1;
+      }
+    }
+    return { corrupted, messages };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { corrupted: 0, messages: [] };
+    throw error;
+  }
+}
+
+function readAllBranchInboxLines(
+  stateDir: string,
+  run: string,
+  address: string,
+): Array<{ raw: string } | { message: BranchInboxRecord }> {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  try {
+    const content = fs.readFileSync(branchInboxFile(stateDir, branch), "utf8");
+    return content
+      .split("\n")
+      .filter((line) => line.length > 0)
+      .map((line) => {
+        try {
+          return { message: JSON.parse(line) as BranchInboxRecord };
+        } catch {
+          return { raw: line };
+        }
+      });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     throw error;
   }
 }
 
+export function readBranchInboxMessages(
+  stateDir: string,
+  run: string,
+  address: string,
+  limit = 40,
+): BranchInboxRecord[] {
+  return readBranchInboxFile(stateDir, run, address, limit).messages;
+}
+
+export function readBranchInboxDiagnostics(
+  stateDir: string,
+  run: string,
+  address: string,
+  limit = 40,
+): BranchInboxReadResult {
+  return readBranchInboxFile(stateDir, run, address, limit);
+}
+
 export function getBranchInboxTerminalRetainLimit(): number {
   const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
   return Number.isInteger(value) && value >= 0
@@ -458,17 +520,23 @@ export function updateBranchInboxMessageStatus(
   const releaseLock = acquireBranchInboxLock(stateDir, branch);
   try {
     const file = branchInboxFile(stateDir, branch);
-    const messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
+    const records = readAllBranchInboxLines(stateDir, run, address);
     let changed = false;
     const timestampKey = `${status}_at`;
-    const updated = messages.map((message) => {
-      if (message.id !== id) return message;
+    const updated = records.map((record) => {
+      if (!("message" in record) || record.message.id !== id) return record;
       changed = true;
-      return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
+      return { message: { ...record.message, ...metadata, [timestampKey]: new Date().toISOString(), status } };
     });
     if (!changed) return false;
-    const compacted = compactBranchInboxMessages(updated);
-    fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
+    const validMessages = updated.flatMap((record) => "message" in record ? [record.message] : []);
+    const compactedIds = new Set(compactBranchInboxMessages(validMessages).map((message) => message.id));
+    const lines = updated.flatMap((record) => {
+      if ("raw" in record) return [record.raw];
+      if (record.message.id && !compactedIds.has(record.message.id)) return [];
+      return [JSON.stringify(record.message)];
+    });
+    fs.writeFileSync(file, lines.length ? `${lines.join("\n")}\n` : "");
     notifyActorWake(stateDir, address, "branch.inbox.status", { id, status });
     return true;
   } finally {

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;