@llblab/pi-actors 0.20.2 → 0.22.0

package/lib/async-runs.ts

@@ -4,7 +4,8 @@
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
 
-import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
 import {
   closeSync,
   constants,
@@ -19,6 +20,7 @@ import {
   writeFileSync,
   writeSync,
 } from "node:fs";
+import { createConnection } from "node:net";
 import { platform } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -32,13 +34,21 @@ import { writeJsonAtomic } from "./file-state.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as RecipeUsage from "./recipe-usage.ts";
+import { notifyRuntimeWake } from "./runtime-notifier.ts";
 
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
 
 export type AsyncRunLaunchSource = "spawn" | "tool";
 
+export interface AsyncRunControlEndpoint {
+  path: string;
+  type: "fifo" | "mailbox" | "named-pipe";
+}
+
 export interface AsyncRunStartParams {
   async?: boolean;
+  control?: AsyncRunControlEndpoint;
   file?: string;
   launch_source?: AsyncRunLaunchSource;
   name?: string;
@@ -112,6 +122,7 @@ export interface AsyncRunMeta {
   template: CommandTemplateValue;
   values: Record<string, unknown>;
   artifacts?: Record<string, string>;
+  control?: AsyncRunControlEndpoint;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
   recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
@@ -207,7 +218,10 @@ function assertNoActiveRunState(stateDir: string): void {
 }
 
 function resolveRecipeFile(file: string): string {
-  return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+  return (
+    RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+    RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT)
+  );
 }
 
 function isMutableUsageRecipeFile(file: string): boolean {
@@ -446,6 +460,7 @@ export function startRun(
     template: resolved.template,
     values,
     ...(artifacts ? { artifacts } : {}),
+    ...(startParams.control ? { control: startParams.control } : {}),
     ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
     ...(recipeContextRecords && recipeContextRecords.length > 0
       ? { recipe_context_records: recipeContextRecords }
@@ -650,6 +665,193 @@ export function readRunEvents(runOrDir: string, lines = 40): RunOutboxEvent[] {
     .filter((event): event is RunOutboxEvent => Boolean(event));
 }
 
+export type RunInboxStatus =
+  | "queued"
+  | "sent"
+  | "claimed"
+  | "handled"
+  | "failed";
+
+export type RunInboxMessage = Record<string, unknown> & {
+  id?: string;
+  status?: RunInboxStatus | string;
+};
+
+export interface ProcessRunInboxResult {
+  claimed: number;
+  failed: number;
+  handled: number;
+}
+
+function runInboxFile(stateDir: string): string {
+  return join(stateDir, "inbox.jsonl");
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireRunInboxLock(stateDir: string): () => void {
+  const lockDir = join(stateDir, ".inbox.lock");
+  const started = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockDir, { recursive: false });
+      writeFileSync(
+        join(lockDir, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`,
+        "utf8",
+      );
+      return () => rmSync(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      try {
+        const stat = statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+          rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - started > RUN_INBOX_LOCK_TIMEOUT_MS) {
+        throw new Error("Run inbox lock timed out.", { cause: error });
+      }
+      sleepSync(10);
+    }
+  }
+}
+
+function parseRunInboxLine(line: string): RunInboxMessage | undefined {
+  try {
+    return JSON.parse(line) as RunInboxMessage;
+  } catch {
+    return undefined;
+  }
+}
+
+function readRunInboxMessagesFromStateDir(stateDir: string): RunInboxMessage[] {
+  const file = runInboxFile(stateDir);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map(parseRunInboxLine)
+    .filter((message): message is RunInboxMessage => Boolean(message));
+}
+
+function writeRunInboxMessages(
+  stateDir: string,
+  messages: RunInboxMessage[],
+): void {
+  writeFileSync(
+    runInboxFile(stateDir),
+    messages.length
+      ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+      : "",
+    "utf8",
+  );
+}
+
+export function readRunInboxMessages(
+  runOrDir: string,
+  lines = 40,
+): RunInboxMessage[] {
+  const status = getRunStatus(runOrDir);
+  const stateDir = String(status.state_dir);
+  return tailLines(runInboxFile(stateDir), lines)
+    .map(parseRunInboxLine)
+    .filter((message): message is RunInboxMessage => Boolean(message));
+}
+
+export function updateRunInboxMessageStatus(
+  runOrDir: string,
+  id: string,
+  nextStatus: RunInboxStatus,
+  metadata: Record<string, unknown> = {},
+): boolean {
+  const status = getRunStatus(runOrDir);
+  const stateDir = String(status.state_dir);
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    const messages = readRunInboxMessagesFromStateDir(stateDir);
+    const timestampKey = `${nextStatus}_at`;
+    let changed = false;
+    const updated = messages.map((message) => {
+      if (message.id !== id) return message;
+      changed = true;
+      return {
+        ...message,
+        ...metadata,
+        [timestampKey]: new Date().toISOString(),
+        status: nextStatus,
+      };
+    });
+    if (changed) writeRunInboxMessages(stateDir, updated);
+    return changed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export function claimRunInboxMessage(
+  runOrDir: string,
+  owner = "runtime",
+  statuses: string[] = ["queued"],
+): RunInboxMessage | undefined {
+  const status = getRunStatus(runOrDir);
+  const stateDir = String(status.state_dir);
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    const messages = readRunInboxMessagesFromStateDir(stateDir);
+    const index = messages.findIndex((message) =>
+      statuses.includes(String(message.status ?? "queued")),
+    );
+    if (index < 0) return undefined;
+    const claimed = {
+      ...messages[index],
+      claimed_at: new Date().toISOString(),
+      claimed_by: owner,
+      id: typeof messages[index].id === "string" ? messages[index].id : randomUUID(),
+      status: "claimed",
+    } satisfies RunInboxMessage;
+    messages[index] = claimed;
+    writeRunInboxMessages(stateDir, messages);
+    return claimed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export async function processRunInboxMessages(
+  runOrDir: string,
+  handler: (message: RunInboxMessage) => Promise<void> | void,
+  options: { limit?: number; owner?: string; statuses?: string[] } = {},
+): Promise<ProcessRunInboxResult> {
+  const result: ProcessRunInboxResult = { claimed: 0, failed: 0, handled: 0 };
+  const limit = Math.max(1, Number(options.limit ?? 1));
+  const owner = options.owner ?? "runtime";
+  for (let index = 0; index < limit; index += 1) {
+    const message = claimRunInboxMessage(runOrDir, owner, options.statuses);
+    if (!message?.id) break;
+    result.claimed += 1;
+    try {
+      await handler(message);
+      if (updateRunInboxMessageStatus(runOrDir, message.id, "handled")) {
+        result.handled += 1;
+      }
+    } catch (error) {
+      if (
+        updateRunInboxMessageStatus(runOrDir, message.id, "failed", {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      ) {
+        result.failed += 1;
+      }
+    }
+  }
+  return result;
+}
+
 export function appendRunOutboxEvent(
   runOrDir: string,
   event: {
@@ -700,15 +902,153 @@ export function appendRunOutboxEvent(
   };
 }
 
-export function sendRunMessage(
-  runOrDir: string,
-  message: string,
-): Record<string, unknown> {
-  if (process.platform === "win32") {
-    throw new Error(
-      "run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.",
+export interface SendRunMessageOptions {
+  namedPipeSend?: (path: string, payload: string) => Promise<number>;
+  platform?: NodeJS.Platform;
+}
+
+function getRunControlEndpoint(
+  status: Record<string, unknown>,
+  stateDir: string,
+): AsyncRunControlEndpoint {
+  const control = status.control;
+  if (control && typeof control === "object" && !Array.isArray(control)) {
+    const record = control as Record<string, unknown>;
+    if (
+      (record.type === "fifo" ||
+        record.type === "mailbox" ||
+        record.type === "named-pipe") &&
+      typeof record.path === "string" &&
+      record.path.trim()
+    ) {
+      return { path: record.path, type: record.type };
+    }
+  }
+  return { path: join(stateDir, "control.fifo"), type: "fifo" };
+}
+
+function appendRunInboxMessage(stateDir: string, message: string): string {
+  const id = randomUUID();
+  const ts = new Date().toISOString();
+  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" };
+  } catch {
+    record = { body: message, type: "run.message" };
+  }
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    writeFileSync(
+      runInboxFile(stateDir),
+      `${JSON.stringify({ ...record, id, queued_at: ts, received_at: ts, status: "queued" })}\n`,
+      { flag: "a" },
     );
+  } finally {
+    releaseLock();
+  }
+  return id;
+}
+
+function writeRunMessageReceipt(
+  stateDir: string,
+  message: string,
+  bytes: number,
+  inboxId: string,
+): void {
+  const trimmedMessage = message.trim().toLowerCase();
+  const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
+    trimmedMessage,
+  );
+  const ts = new Date().toISOString();
+  writeFileSync(
+    join(stateDir, "events.jsonl"),
+    `${JSON.stringify({ bytes, event: "run.message", inbox_id: inboxId, terminal: terminalMessage || undefined, ts })}\n`,
+    { flag: "a" },
+  );
+  updateRunInboxMessageStatus(stateDir, inboxId, "sent", { bytes });
+  if (terminalMessage) {
+    markTerminalHandled(stateDir, {
+      event: "run.message",
+      message: trimmedMessage,
+    });
+  }
+}
+
+function sendRunMessageToFifo(
+  endpoint: AsyncRunControlEndpoint,
+  payload: string,
+): number {
+  if (!existsSync(endpoint.path))
+    throw new Error(`Run control FIFO not found: ${endpoint.path}`);
+  const stat = statSync(endpoint.path);
+  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+    throw new Error(`Run control endpoint is not a FIFO: ${endpoint.path}`);
   }
+  let fd: number | undefined;
+  try {
+    fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+    return writeSync(fd, payload);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function notifyRunMessageWake(
+  stateDir: string,
+  run: string,
+  bytes: number,
+  endpoint: AsyncRunControlEndpoint,
+  inboxId: string,
+): Record<string, unknown> | undefined {
+  try {
+    const event = notifyRuntimeWake(stateDir, {
+      actor: `run:${run}`,
+      metadata: { bytes, control_type: endpoint.type, inbox_id: inboxId },
+      reason: "run.message",
+    });
+    return { wake: "wake.jsonl", wake_id: event.id };
+  } catch {
+    return undefined;
+  }
+}
+
+function sendRunMessageToNamedPipe(
+  endpoint: AsyncRunControlEndpoint,
+  payload: string,
+  send?: (path: string, payload: string) => Promise<number>,
+): Promise<number> {
+  if (send) return send(endpoint.path, payload);
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint.path);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(new Error("named pipe connection timed out"));
+    }, 5000);
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve(Buffer.byteLength(payload));
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => {
+      socket.end(payload, () => finish());
+    });
+  });
+}
+
+export async function sendRunMessage(
+  runOrDir: string,
+  message: string,
+  options: SendRunMessageOptions = {},
+): Promise<Record<string, unknown>> {
   const status = getRunStatus(runOrDir);
   const stateDir = String(status.state_dir);
   const run = String(status.run ?? runOrDir);
@@ -718,64 +1058,108 @@ export function sendRunMessage(
   if (!pid || !isAlive(pid)) throw new Error(`Run pid is not alive: ${run}`);
   if (!pidMatchesRun(pid, String(status.cwd), stateDir))
     throw new Error(`Run pid owner mismatch: ${run}`);
-  const controlPath = join(stateDir, "control.fifo");
-  if (!existsSync(controlPath))
-    throw new Error(`Run control FIFO not found: ${controlPath}`);
-  const stat = statSync(controlPath);
-  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
-    throw new Error(`Run control endpoint is not a FIFO: ${controlPath}`);
-  }
+  const endpoint = getRunControlEndpoint(status, stateDir);
   const payload = message.endsWith("\n") ? message : `${message}\n`;
-  let fd: number | undefined;
+  const payloadBytes = Buffer.byteLength(payload);
+  const inboxId = appendRunInboxMessage(stateDir, message);
+  const wake = notifyRunMessageWake(stateDir, run, payloadBytes, endpoint, inboxId);
+  const runtimePlatform = options.platform ?? process.platform;
+  if (endpoint.type === "mailbox") {
+    return {
+      ...(wake ?? {}),
+      bytes: payloadBytes,
+      control: "inbox.jsonl",
+      control_path: endpoint.path,
+      control_type: endpoint.type,
+      queued: true,
+      run,
+      sent: true,
+      state_dir: stateDir,
+    };
+  }
   try {
-    fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
-    const bytes = writeSync(fd, payload);
-    const trimmedMessage = message.trim().toLowerCase();
-    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
-      trimmedMessage,
-    );
-    const ts = new Date().toISOString();
-    writeFileSync(
-      join(stateDir, "events.jsonl"),
-      `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`,
-      { flag: "a" },
-    );
-    try {
-      const envelope = JSON.parse(message) as Record<string, unknown>;
-      writeFileSync(
-        join(stateDir, "inbox.jsonl"),
-        `${JSON.stringify({ ...envelope, received_at: ts })}\n`,
-        { flag: "a" },
-      );
-    } catch {
-      // Plain control lines are already represented in events.jsonl.
-    }
-    if (terminalMessage) {
-      markTerminalHandled(stateDir, {
-        event: "run.message",
-        message: trimmedMessage,
-      });
+    if (endpoint.type === "fifo") {
+      if (runtimePlatform === "win32") {
+        throw new Error(
+          "run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.",
+        );
+      }
+      const bytes = sendRunMessageToFifo(endpoint, payload);
+      writeRunMessageReceipt(stateDir, message, bytes, inboxId);
+      return {
+        ...(wake ?? {}),
+        bytes,
+        control: "control.fifo",
+        control_path: endpoint.path,
+        control_type: endpoint.type,
+        run,
+        sent: true,
+        state_dir: stateDir,
+      };
     }
+    const bytes = await sendRunMessageToNamedPipe(
+      endpoint,
+      payload,
+      options.namedPipeSend,
+    );
+    writeRunMessageReceipt(stateDir, message, bytes, inboxId);
     return {
+      ...(wake ?? {}),
       bytes,
-      control: "control.fifo",
+      control: endpoint.path,
+      control_path: endpoint.path,
+      control_type: endpoint.type,
       run,
       sent: true,
       state_dir: stateDir,
     };
   } catch (error) {
     throw new Error(
-      `Run control FIFO is not ready: ${controlPath}: ${error instanceof Error ? error.message : String(error)}`,
+      `Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`,
     );
-  } finally {
-    if (fd !== undefined) closeSync(fd);
   }
 }
 
+export interface RunProcessSignalPlan {
+  args?: string[];
+  command?: string;
+  signalTarget: "processGroup" | "process" | "processTree";
+}
+
+export function getRunProcessSignalPlan(
+  pid: number,
+  signal: NodeJS.Signals,
+  runtimePlatform: NodeJS.Platform = process.platform,
+): RunProcessSignalPlan {
+  if (runtimePlatform === "win32") {
+    return {
+      args: [
+        "/PID",
+        String(pid),
+        "/T",
+        ...(signal === "SIGKILL" ? ["/F"] : []),
+      ],
+      command: "taskkill",
+      signalTarget: "processTree",
+    };
+  }
+  return { signalTarget: "processGroup" };
+}
+
 function signalOwnedRunProcess(
   pid: number,
   signal: NodeJS.Signals,
-): { signalTarget: "processGroup" | "process" } {
+): RunProcessSignalPlan {
+  const plan = getRunProcessSignalPlan(pid, signal);
+  if (plan.command && plan.args) {
+    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`,
+      );
+    }
+    return plan;
+  }
   try {
     process.kill(-pid, signal);
     return { signalTarget: "processGroup" };

package/lib/command-templates.ts

@@ -157,8 +157,15 @@ function getExecutableName(command: string | undefined): string {
   return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
 }
 
+function matchesFlag(arg: string, flag: string): boolean {
+  if (arg === flag) return true;
+  if (/^-[A-Za-z]$/.test(flag) && /^-[A-Za-z]+$/.test(arg))
+    return arg.slice(1).includes(flag.slice(1));
+  return false;
+}
+
 function hasAnyFlag(args: string[], flags: string[]): boolean {
-  return args.some((arg) => flags.includes(arg));
+  return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
 }
 
 function hasRiskyPathArg(args: string[]): boolean {