@llblab/pi-actors 0.42.2 → 0.43.0

package/lib/runs-mailbox.ts

@@ -1,208 +0,0 @@
-/**
- * Async run mailbox state.
- * Owns: durable run inbox records, claim locks, and handler status transitions.
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { readJsonlFileResilient } from "./state-readers.ts";
-
-const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
-const STALE_INBOX_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
-
-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;
-}
-
-export function runInboxFile(stateDir: string): string {
-  return join(stateDir, "inbox.jsonl");
-}
-
-export function parseRunInboxLine(line: string): RunInboxMessage | undefined {
-  try {
-    return JSON.parse(line) as RunInboxMessage;
-  } catch {
-    return undefined;
-  }
-}
-
-export function readRunInboxMessagesFromStateDir(
-  stateDir: string,
-): RunInboxMessage[] {
-  return readJsonlFileResilient<RunInboxMessage>(runInboxFile(stateDir))
-    .records;
-}
-
-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 > STALE_INBOX_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 writeRunInboxMessages(
-  stateDir: string,
-  messages: RunInboxMessage[],
-): void {
-  writeFileSync(
-    runInboxFile(stateDir),
-    messages.length
-      ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
-      : "",
-    "utf8",
-  );
-}
-
-export function updateRunInboxMessageStatusInStateDir(
-  stateDir: string,
-  id: string,
-  nextStatus: RunInboxStatus,
-  metadata: Record<string, unknown> = {},
-): boolean {
-  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 claimRunInboxMessageInStateDir(
-  stateDir: string,
-  owner = "runtime",
-  statuses: string[] = ["queued"],
-): RunInboxMessage | undefined {
-  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 function appendRunInboxMessageInStateDir(
-  stateDir: string,
-  record: Record<string, unknown>,
-): string {
-  const id = randomUUID();
-  const ts = new Date().toISOString();
-  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;
-}
-
-export async function processRunInboxMessagesInStateDir(
-  stateDir: 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 = claimRunInboxMessageInStateDir(
-      stateDir,
-      owner,
-      options.statuses,
-    );
-    if (!message?.id) break;
-    result.claimed += 1;
-    try {
-      await handler(message);
-      if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "handled")) {
-        result.handled += 1;
-      }
-    } catch (error) {
-      if (
-        updateRunInboxMessageStatusInStateDir(stateDir, message.id, "failed", {
-          error: error instanceof Error ? error.message : String(error),
-        })
-      ) {
-        result.failed += 1;
-      }
-    }
-  }
-  return result;
-}

package/lib/runs-messages.ts

@@ -1,252 +0,0 @@
-/**
- * Async run message delivery.
- * Owns: run control endpoint resolution, inbox enqueueing, wake notification,
- * transport writes, and delivery receipts.
- */
-
-import {
-  closeSync,
-  constants,
-  existsSync,
-  openSync,
-  statSync,
-  writeFileSync,
-  writeSync,
-} from "node:fs";
-import { createConnection } from "node:net";
-import { join } from "node:path";
-
-import { markTerminalHandled } from "./runs-control.ts";
-import {
-  appendRunInboxMessageInStateDir,
-  updateRunInboxMessageStatusInStateDir,
-} from "./runs-mailbox.ts";
-import { notifyRuntimeWake } from "./runtime-notifier.ts";
-
-export interface RunControlEndpoint {
-  path: string;
-  type: "fifo" | "mailbox" | "named-pipe";
-}
-
-export interface SendRunMessageOptions {
-  namedPipeSend?: (path: string, payload: string) => Promise<number>;
-  platform?: NodeJS.Platform;
-}
-
-export function getRunControlEndpoint(
-  status: Record<string, unknown>,
-  stateDir: string,
-): RunControlEndpoint {
-  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 {
-  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" };
-  }
-  return appendRunInboxMessageInStateDir(stateDir, record);
-}
-
-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" },
-  );
-  updateRunInboxMessageStatusInStateDir(stateDir, inboxId, "sent", { bytes });
-  if (terminalMessage) {
-    markTerminalHandled(stateDir, {
-      event: "run.message",
-      message: trimmedMessage,
-    });
-  }
-}
-
-function sendRunMessageToFifo(
-  endpoint: RunControlEndpoint,
-  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: RunControlEndpoint,
-  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: RunControlEndpoint,
-  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 deliverRunMessage(
-  status: Record<string, unknown>,
-  run: string,
-  stateDir: string,
-  message: string,
-  options: SendRunMessageOptions = {},
-): Promise<Record<string, unknown>> {
-  const endpoint = getRunControlEndpoint(status, stateDir);
-  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 runtimePlatform = options.platform ?? process.platform;
-  if (endpoint.type === "mailbox") {
-    return {
-      ...(wake ?? {}),
-      bytes: payloadBytes,
-      control: "inbox.jsonl",
-      control_path: endpoint.path,
-      control_type: endpoint.type,
-      inbox_id: inboxId,
-      queued: true,
-      run,
-      sent: true,
-      state_dir: stateDir,
-    };
-  }
-  try {
-    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,
-        inbox_id: inboxId,
-        run,
-        sent: true,
-        state_dir: stateDir,
-      };
-    }
-    const bytes = await sendRunMessageToNamedPipe(
-      endpoint,
-      payload,
-      options.namedPipeSend,
-    );
-    writeRunMessageReceipt(stateDir, message, bytes, inboxId);
-    return {
-      ...(wake ?? {}),
-      bytes,
-      control: endpoint.path,
-      control_path: endpoint.path,
-      control_type: endpoint.type,
-      inbox_id: inboxId,
-      run,
-      sent: true,
-      state_dir: stateDir,
-    };
-  } catch (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,
-      },
-    );
-  }
-}

package/lib/runs-outbox.ts

@@ -1,144 +0,0 @@
-/**
- * Async run outbox events.
- * Owns: outbox event normalization, parsing, and append payload formatting.
- */
-
-export type RunOutboxDelivery = "log" | "notify" | "followup";
-export type RunOutboxLevel = "info" | "warning" | "error";
-
-export interface RunOutboxEvent {
-  body?: unknown;
-  correlation_id?: string;
-  data?: unknown;
-  delivery: RunOutboxDelivery;
-  event: string;
-  from?: string;
-  id: string;
-  level: RunOutboxLevel;
-  metadata?: Record<string, unknown>;
-  reply_to?: string;
-  run: string;
-  state_dir: string;
-  summary: string;
-  to?: string;
-  ts: string;
-  type?: string;
-}
-
-export function normalizeRunOutboxDelivery(value: unknown): RunOutboxDelivery {
-  return value === "notify" || value === "followup" ? value : "log";
-}
-
-export function normalizeRunOutboxLevel(value: unknown): RunOutboxLevel {
-  return value === "warning" || value === "error" ? value : "info";
-}
-
-function normalizeRunOutboxEvent(
-  raw: unknown,
-  run: string,
-  stateDir: string,
-  index: number,
-): RunOutboxEvent | undefined {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-  const record = raw as Record<string, unknown>;
-  const event =
-    typeof record.event === "string" && record.event.trim()
-      ? record.event.trim()
-      : "run.event";
-  const summary =
-    typeof record.summary === "string" && record.summary.trim()
-      ? record.summary.trim()
-      : event;
-  const ts =
-    typeof record.ts === "string" && record.ts.trim()
-      ? record.ts.trim()
-      : new Date(0).toISOString();
-  const id =
-    typeof record.id === "string" && record.id.trim()
-      ? record.id.trim()
-      : `${run}:${index}`;
-  return {
-    ...(record.body !== undefined ? { body: record.body } : {}),
-    ...(typeof record.correlation_id === "string"
-      ? { correlation_id: record.correlation_id }
-      : {}),
-    ...(record.data !== undefined ? { data: record.data } : {}),
-    delivery: normalizeRunOutboxDelivery(record.delivery),
-    ...(record.metadata &&
-    typeof record.metadata === "object" &&
-    !Array.isArray(record.metadata)
-      ? { metadata: record.metadata as Record<string, unknown> }
-      : {}),
-    event,
-    ...(typeof record.from === "string" ? { from: record.from } : {}),
-    id,
-    level: normalizeRunOutboxLevel(record.level),
-    ...(typeof record.reply_to === "string"
-      ? { reply_to: record.reply_to }
-      : {}),
-    run,
-    state_dir: stateDir,
-    summary,
-    ...(typeof record.to === "string" ? { to: record.to } : {}),
-    ts,
-    ...(typeof record.type === "string" ? { type: record.type } : {}),
-  };
-}
-
-export function parseRunOutboxEventLine(
-  line: string,
-  run: string,
-  stateDir: string,
-  index: number,
-): RunOutboxEvent | undefined {
-  try {
-    return normalizeRunOutboxEvent(JSON.parse(line), run, stateDir, index);
-  } catch {
-    return undefined;
-  }
-}
-
-export function buildRunOutboxEventPayload(
-  run: string,
-  event: {
-    body?: unknown;
-    correlation_id?: string;
-    data?: unknown;
-    delivery?: string;
-    event?: string;
-    from?: string;
-    level?: string;
-    metadata?: Record<string, unknown>;
-    reply_to?: string;
-    summary?: string;
-    to?: string;
-    type?: string;
-  },
-): Record<string, unknown> {
-  const type = event.type || event.event || "run.message";
-  const to = event.to || "coordinator";
-  const metadata = event.metadata ?? {};
-  const requiresResponse = metadata.requires_response === true;
-  return {
-    ...(event.body !== undefined ? { body: event.body } : {}),
-    ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
-    ...(event.data !== undefined ? { data: event.data } : {}),
-    delivery: normalizeRunOutboxDelivery(
-      event.delivery ??
-        (requiresResponse
-          ? "followup"
-          : to === "coordinator"
-            ? "notify"
-            : "log"),
-    ),
-    event: type,
-    from: event.from || `run:${run}`,
-    level: normalizeRunOutboxLevel(event.level),
-    ...(event.metadata ? { metadata: event.metadata } : {}),
-    ...(event.reply_to ? { reply_to: event.reply_to } : {}),
-    summary: event.summary || type,
-    to,
-    ts: new Date().toISOString(),
-    type,
-  };
-}

package/lib/tools-mailbox.ts

@@ -1,56 +0,0 @@
-/**
- * Public tool mailbox contract helpers
- * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
- * Owns mailbox metadata normalization for public message and inspect tool paths
- */
-
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : {};
-}
-
-export function normalizeMailboxEntry(
-  value: unknown,
-): Record<string, unknown> | undefined {
-  if (typeof value === "string") return { type: value };
-  const record = asRecord(value);
-  if (typeof record.type !== "string" || !record.type.trim()) return undefined;
-  return {
-    type: record.type.trim(),
-    ...(record.body_schema !== undefined
-      ? { body_schema: record.body_schema }
-      : {}),
-    ...(record.ack !== undefined ? { ack: record.ack } : {}),
-    ...(typeof record.idempotency === "string"
-      ? { idempotency: record.idempotency }
-      : {}),
-    ...(typeof record.level === "string" ? { level: record.level } : {}),
-    ...(record.requires_response === true ? { requires_response: true } : {}),
-    ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
-  };
-}
-
-export function normalizeMailboxContracts(
-  mailbox: Record<string, unknown>,
-): Record<string, unknown[]> {
-  const accepts = Array.isArray(mailbox.accepts)
-    ? mailbox.accepts
-        .map(normalizeMailboxEntry)
-        .filter((entry): entry is Record<string, unknown> => Boolean(entry))
-    : [];
-  const emits = Array.isArray(mailbox.emits)
-    ? mailbox.emits
-        .map(normalizeMailboxEntry)
-        .filter((entry): entry is Record<string, unknown> => Boolean(entry))
-    : [];
-  return { accepts, emits };
-}
-
-export function mailboxTypes(entries: unknown[]): string[] {
-  return entries.flatMap((entry) =>
-    typeof asRecord(entry).type === "string"
-      ? [String(asRecord(entry).type)]
-      : [],
-  );
-}

package/recipes/actor-worker.json

@@ -1,39 +0,0 @@
-{
-  "async": true,
-  "description": "Start a canonical mailbox-backed branch worker demo actor.",
-  "args": [
-    "repo:path",
-    "branch:string",
-    "poll_ms:int",
-    "stale_claim_ms:int",
-    "write_artifacts:bool"
-  ],
-  "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
-    "branch": "worker",
-    "poll_ms": "1000",
-    "stale_claim_ms": "0",
-    "write_artifacts": "true"
-  },
-  "mailbox": {
-    "accepts": [
-      "task.assign",
-      "control.kill"
-    ],
-    "emits": [
-      "actor.join",
-      "task.claim",
-      "task.result",
-      "awaiting_assignment",
-      "actor.leave",
-      "run.done",
-      "run.failed"
-    ]
-  },
-  "artifacts": {
-    "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} --stale-claim-ms {stale_claim_ms} --write-artifacts {write_artifacts}"
-}