@llblab/pi-actors 0.33.0 → 0.34.0

package/lib/runs-outbox.ts

@@ -0,0 +1,144 @@
+/**
+ * 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/runs-process.ts

@@ -0,0 +1,51 @@
+/**
+ * Async run process identity helpers.
+ * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ */
+
+import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { platform } from "node:os";
+import { resolve } from "node:path";
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function pidMatchesRun(
+  pid: number,
+  cwd: string,
+  stateDir: string,
+  runnerPath: string,
+): boolean {
+  if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
+    return isAlive(pid);
+  try {
+    const procCwd = readlinkSync(`/proc/${pid}/cwd`);
+    const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+    return (
+      procCwd === resolve(cwd) &&
+      cmdline.includes(runnerPath) &&
+      cmdline.includes(stateDir)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function isWithinRunnerIdentityGrace(
+  meta: Record<string, unknown>,
+  graceMs: number,
+): boolean {
+  const createdAt =
+    typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
+  return (
+    Number.isFinite(createdAt) &&
+    Date.now() - createdAt >= 0 &&
+    Date.now() - createdAt <= graceMs
+  );
+}

package/lib/runs-retention.ts

@@ -0,0 +1,77 @@
+/**
+ * Async run retention operations.
+ * Owns terminal-run archive and prune filesystem behavior.
+ */
+
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import {
+  resolveArtifactManifest,
+  type RunArtifactDeclaration,
+} from "./runs-artifacts.ts";
+import { safeRunId } from "./runs-identity.ts";
+
+function archivePathFor(run: string, stateDir: string): string {
+  const archiveRoot = join(dirname(stateDir), "archived");
+  mkdirSync(archiveRoot, { recursive: true });
+  return join(
+    archiveRoot,
+    `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`,
+  );
+}
+
+export function archiveTerminalRun(
+  status: Record<string, unknown>,
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  const archiveDir = archivePathFor(run, stateDir);
+  renameSync(stateDir, archiveDir);
+  mkdirSync(stateDir, { recursive: true });
+  const tombstone = {
+    archived: true,
+    archive_dir: archiveDir,
+    original_state_dir: stateDir,
+    run,
+    status: status.status,
+    ts: new Date().toISOString(),
+  };
+  writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
+  return tombstone;
+}
+
+export function pruneTerminalRun(
+  status: Record<string, unknown>,
+  options: { preserveArtifacts?: boolean } = {},
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  const manifest = resolveArtifactManifest(
+    status.artifacts as Record<string, RunArtifactDeclaration> | undefined,
+  );
+  const preserved: Record<string, string> = {};
+  if (options.preserveArtifacts && manifest) {
+    const preserveRoot = join(
+      dirname(stateDir),
+      "preserved-artifacts",
+      safeRunId(run),
+    );
+    mkdirSync(preserveRoot, { recursive: true });
+    for (const [name, artifact] of Object.entries(manifest)) {
+      if (!artifact.exists) continue;
+      const target = join(preserveRoot, basename(artifact.path));
+      cpSync(artifact.path, target, { force: true });
+      preserved[name] = target;
+    }
+  }
+  rmSync(stateDir, { recursive: true, force: true });
+  return {
+    pruned: true,
+    preserved_artifacts: preserved,
+    run,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}

package/lib/runs-start.ts

@@ -0,0 +1,98 @@
+/**
+ * Async run start guards.
+ * Owns active-run reuse checks, start lock acquisition, and safe state-dir
+ * preparation before a new runner process is spawned.
+ */
+
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { isAlive, pidMatchesRun } from "./runs-process.ts";
+
+const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+
+export function assertNoActiveRunState(
+  stateDir: string,
+  readJson: RunJsonReader,
+  runnerPath: string,
+): void {
+  const meta = readJson(join(stateDir, "run.json"));
+  if (!meta) return;
+  const pid = Number(meta.pid || 0);
+  const cwd = String(meta.cwd ?? "");
+  if (!pid || !isAlive(pid) || !pidMatchesRun(pid, cwd, stateDir, runnerPath))
+    return;
+  throw new Error(
+    `Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`,
+  );
+}
+
+export function acquireStateStartLock(stateDir: string): () => void {
+  const lockDir = join(stateDir, ".start.lock");
+  try {
+    mkdirSync(lockDir);
+    writeFileSync(
+      join(lockDir, "owner.json"),
+      `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    try {
+      const stat = statSync(lockDir);
+      if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+        rmSync(lockDir, { recursive: true, force: true });
+        mkdirSync(lockDir);
+        writeFileSync(
+          join(lockDir, "owner.json"),
+          `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), recovered: true })}\n`,
+          "utf8",
+        );
+        return () => rmSync(lockDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Keep the original lock acquisition error below.
+    }
+    throw new Error(
+      `Run state is already being started: ${stateDir}. Retry after the current start finishes.`,
+      { cause: error },
+    );
+  }
+  return () => rmSync(lockDir, { recursive: true, force: true });
+}
+
+export function prepareStateDirForStart(
+  stateDir: string,
+  readJson: RunJsonReader,
+  runnerPath: string,
+): void {
+  const existing = readJson(join(stateDir, "run.json"));
+  const existingPid = Number(existing?.pid || 0);
+  const existingCwd =
+    typeof existing?.cwd === "string" ? existing.cwd : undefined;
+  const existingResult = readJson(join(stateDir, "result.json"));
+  if (
+    !existingResult &&
+    existingPid &&
+    existingCwd &&
+    isAlive(existingPid) &&
+    pidMatchesRun(existingPid, existingCwd, stateDir, runnerPath)
+  ) {
+    throw new Error(
+      `Run state already has an active owned process: ${String(existing?.run ?? stateDir)}. Stop it before restarting.`,
+    );
+  }
+  for (const file of [
+    "events.jsonl",
+    "inbox.jsonl",
+    "outbox.jsonl",
+    "progress.json",
+    "result.json",
+    "stderr.log",
+    "stdout.log",
+    "terminal-handled.json",
+  ]) {
+    rmSync(join(stateDir, file), { force: true });
+  }
+}

package/lib/runs-status.ts

@@ -0,0 +1,78 @@
+/**
+ * Async run status and log readers.
+ * Owns status derivation from run state files plus bounded log/event tails.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AsyncRunStatus } from "./async-runs.ts";
+import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun } from "./runs-process.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
+
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+
+function getInterruptedRunStatus(
+  stateDir: string,
+): "cancelled" | "killed" | undefined {
+  const events = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "events.jsonl"),
+  ).records.slice(-200);
+  for (const event of events.reverse()) {
+    if (event.event === "run.kill") return "killed";
+    if (event.event === "run.cancel") return "cancelled";
+  }
+  return undefined;
+}
+
+export function buildRunStatus(
+  stateDir: string,
+  runOrDir: string,
+  meta: Record<string, unknown>,
+  readJson: RunJsonReader,
+  runnerPath: string,
+  runnerIdentityGraceMs: number,
+): Record<string, unknown> {
+  const result = readJson(join(stateDir, "result.json"));
+  const pid = Number(meta.pid || 0);
+  const aliveOwnedRunner = Boolean(
+    pid &&
+      isAlive(pid) &&
+      (!Array.isArray(meta.argv) ||
+        pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir, runnerPath) ||
+        isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs)),
+  );
+  const status: AsyncRunStatus = result
+    ? Number(result.code ?? 0) === 0
+      ? "done"
+      : "failed"
+    : aliveOwnedRunner
+      ? "running"
+      : (getInterruptedRunStatus(stateDir) ?? "exited");
+  const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
+  return {
+    ...meta,
+    eventsFile: join(stateDir, "events.jsonl"),
+    inboxFile: join(stateDir, "inbox.jsonl"),
+    outboxFile: join(stateDir, "outbox.jsonl"),
+    progress: readJson(join(stateDir, "progress.json")) || null,
+    result: result || null,
+    ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
+    state_dir: String(meta.state_dir ?? stateDir),
+    stderrLog: join(stateDir, "stderr.log"),
+    stdoutLog: join(stateDir, "stdout.log"),
+    status,
+  };
+}
+
+export function tailFile(path: string, lines: number): string {
+  if (!existsSync(path)) return "";
+  const content = readFileSync(path, "utf8").trimEnd();
+  if (!content) return "";
+  return content.split("\n").slice(-lines).join("\n");
+}
+
+export function tailLines(path: string, lines: number): string[] {
+  const content = tailFile(path, lines);
+  return content ? content.split("\n") : [];
+}

package/lib/runtime.ts

@@ -9,8 +9,8 @@ import { existsSync, watch, type FSWatcher } from "node:fs";
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
 import * as Paths from "./paths.ts";
-import * as RecipeDiscovery from "./recipe-discovery.ts";
-import * as Tools from "./tools.ts";
+import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as ToolsLocal from "./tools-local.ts";
 
 export interface RuntimeContext {
   hasUI: boolean;
@@ -31,7 +31,7 @@ export interface ToolRegistryRuntimeDeps {
   getActiveTools?: () => string[];
   getAllTools: () => ToolInfoLike[];
   registerTool: (
-    definition: ReturnType<typeof Tools.createRuntimeToolDefinition>,
+    definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>,
   ) => void;
   reservedToolNames: Set<string>;
   setActiveTools?: (toolNames: string[]) => void;
@@ -100,7 +100,7 @@ export function createAutoToolsRuntime(
   function registerRuntimeTool(cfg: Config.RegisteredTool) {
     const fingerprint = getToolFingerprint(cfg);
     if (runtimeToolFingerprints.get(cfg.name) === fingerprint) return;
-    deps.registerTool(Tools.createRuntimeToolDefinition(cfg, deps.exec));
+    deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
     runtimeTools.add(cfg.name);
     runtimeToolFingerprints.set(cfg.name, fingerprint);
   }
@@ -148,7 +148,7 @@ export function createAutoToolsRuntime(
     const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
     const packagedRecipeRoot =
       deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot();
-    const discovered = RecipeDiscovery.discoverRecipeSources([
+    const discovered = RecipesDiscovery.discoverRecipeSources([
       { root: recipeRoot, defaultTool: true, mutableUsage: true },
       { root: packagedRecipeRoot },
     ]);
@@ -156,7 +156,7 @@ export function createAutoToolsRuntime(
     tools.clear();
     for (const entry of discovered.active.values()) {
       try {
-        const cfg = RecipeDiscovery.toRegisteredTool(entry);
+        const cfg = RecipesDiscovery.toRegisteredTool(entry);
         if (cfg) tools.set(cfg.name, cfg);
       } catch (error) {
         warnings.push(

package/lib/schema.ts

@@ -30,6 +30,61 @@ export interface ToolArgSpec {
   error?: string;
 }
 
+export type JsonSchema = Record<string, unknown>;
+
+export function stringSchema(description: string): JsonSchema {
+  return { description, type: "string" };
+}
+
+export function typedArgSchema(
+  description: string,
+  type: ToolArgType | undefined,
+): JsonSchema {
+  if (!type) return stringSchema(description);
+  switch (type.kind) {
+    case "int":
+      return { description, type: "integer" };
+    case "number":
+      return { description, type: "number" };
+    case "bool":
+      return { description, type: "boolean" };
+    case "array":
+      return { description, items: {}, type: "array" };
+    case "enum":
+      return { description, enum: type.values, type: "string" };
+    case "path":
+    case "string":
+      return stringSchema(description);
+  }
+}
+
+export function booleanSchema(description: string): JsonSchema {
+  return { description, type: "boolean" };
+}
+
+export function nullSchema(description: string): JsonSchema {
+  return { description, type: "null" };
+}
+
+export function arraySchema(description: string): JsonSchema {
+  return { description, items: {}, type: "array" };
+}
+
+export function unionSchema(anyOf: JsonSchema[]): JsonSchema {
+  return { anyOf };
+}
+
+export function objectSchema(
+  properties: Record<string, JsonSchema>,
+  required: string[] = [],
+): JsonSchema {
+  return { additionalProperties: false, properties, required, type: "object" };
+}
+
+export function looseObjectSchema(description: string): JsonSchema {
+  return { additionalProperties: true, description, type: "object" };
+}
+
 function mergeUnique(items: string[]): string[] {
   return [...new Set(items.filter(Boolean))];
 }

package/lib/tools-access.ts

@@ -0,0 +1,68 @@
+/**
+ * Public tool access and ownership checks
+ * Zones: session ownership, run visibility guards, tool authorization errors
+ * Owns consistent session-mismatch diagnostics for public tool execution paths
+ */
+
+import * as AsyncRuns from "./async-runs.ts";
+
+export interface SessionContext {
+  sessionManager?: { getSessionId?: () => string };
+}
+
+export function getContextSessionId(ctx: unknown): string | undefined {
+  return (ctx as SessionContext | undefined)?.sessionManager?.getSessionId?.();
+}
+
+export function requireContextSessionId(ctx: unknown, actor: string): string {
+  const sessionId = getContextSessionId(ctx);
+  if (!sessionId) {
+    throw new Error(
+      `${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`,
+    );
+  }
+  return sessionId;
+}
+
+export function sessionMismatchError(input: {
+  currentSession?: string;
+  expectedSession?: string;
+  run?: string;
+  target?: string;
+}): Error {
+  const ownerSession = input.expectedSession ?? "none";
+  const currentSession = input.currentSession ?? "none";
+  const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+  const hintTarget = input.expectedSession
+    ? `session:${input.expectedSession}`
+    : "session:all";
+  return Object.assign(
+    new Error(
+      `${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`,
+    ),
+    {
+      current_session: input.currentSession,
+      hint: `inspect target=${hintTarget} view=status`,
+      owner_session: input.expectedSession,
+      reason: "session_mismatch",
+      run: input.run,
+      target: input.target,
+    },
+  );
+}
+
+export function assertRunAccessibleToContext(
+  runId: string,
+  ctx: unknown,
+): Record<string, unknown> {
+  const status = AsyncRuns.getRunStatus(runId);
+  const sessionId = getContextSessionId(ctx);
+  if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+    throw sessionMismatchError({
+      currentSession: sessionId,
+      expectedSession: String(status.ownerId),
+      run: runId,
+    });
+  }
+  return status;
+}