@llblab/pi-actors 0.22.5 → 0.24.0

package/dist/lib/async-runs.js

@@ -4,14 +4,15 @@
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, cpSync, readlinkSync, renameSync, rmSync, statSync, 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";
 import { substituteCommandTemplateToken } from "./command-templates.js";
 import { writeJsonAtomic } from "./file-state.js";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
 import * as Paths from "./paths.js";
 import * as RecipeReferences from "./recipe-references.js";
 import * as RecipeUsage from "./recipe-usage.js";
@@ -48,10 +49,60 @@ function resolveArtifactPaths(artifacts, values) {
     for (const [key, value] of Object.entries(artifacts)) {
         if (!key.trim())
             continue;
-        resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        if (typeof value === "string") {
+            resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        }
+        else if (value &&
+            typeof value === "object" &&
+            typeof value.path === "string") {
+            resolved[key] = {
+                ...value,
+                path: substituteCommandTemplateToken(value.path, values, `recipe artifacts.${key}.path`),
+            };
+        }
     }
     return Object.keys(resolved).length > 0 ? resolved : undefined;
 }
+export function resolveArtifactManifest(artifacts) {
+    if (!artifacts)
+        return undefined;
+    const manifest = {};
+    for (const [name, artifact] of Object.entries(artifacts)) {
+        const declaration = typeof artifact === "string" ? { path: artifact } : artifact;
+        if (!declaration?.path)
+            continue;
+        try {
+            const content = readFileSync(declaration.path);
+            manifest[name] = {
+                exists: true,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+                sha256: createHash("sha256").update(content).digest("hex"),
+                size: content.byteLength,
+            };
+        }
+        catch {
+            manifest[name] = {
+                exists: false,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+            };
+        }
+    }
+    return Object.keys(manifest).length > 0 ? manifest : undefined;
+}
 function resolveRunTemplate(params) {
     if (!params.template)
         throw new Error("spawn requires file or template.");
@@ -139,12 +190,7 @@ function resolveStartParams(params) {
     };
 }
 function readJson(path) {
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
+    return readJsonFileResilient(path, undefined).value;
 }
 function isAlive(pid) {
     try {
@@ -182,20 +228,12 @@ function tailLines(path, lines) {
     return content ? content.split("\n") : [];
 }
 function getInterruptedRunStatus(stateDir) {
-    const events = tailFile(join(stateDir, "events.jsonl"), 200);
-    if (!events)
-        return undefined;
-    for (const line of events.split("\n").reverse()) {
-        try {
-            const event = JSON.parse(line);
-            if (event.event === "run.kill")
-                return "killed";
-            if (event.event === "run.cancel")
-                return "cancelled";
-        }
-        catch {
-            // Ignore malformed event lines.
-        }
+    const events = readJsonlFileResilient(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;
 }
@@ -270,7 +308,7 @@ export function startRun(params, cwd) {
             ? RecipeReferences.buildRecipeContextRecords(recipeFile)
             : undefined;
         if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-            RecipeUsage.recordRecipeLaunch(recipeFile);
+            RecipeUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn");
         }
         const outFd = openSync(stdout, "a");
         const errFd = openSync(stderr, "a");
@@ -440,31 +478,111 @@ function matchesStatusFilter(status, filter) {
         return status !== "running";
     return status === filter;
 }
-export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
-    if (!existsSync(stateRoot))
+export function listRunStateDirs(stateRoot = DEFAULT_STATE_ROOT, depth = 0, seen = new Set()) {
+    if (!existsSync(stateRoot) || seen.has(resolve(stateRoot)))
+        return [];
+    seen.add(resolve(stateRoot));
+    let entries;
+    try {
+        entries = readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch {
         return [];
-    const runs = [];
-    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+    }
+    const result = [];
+    for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
+        const child = join(stateRoot, entry.name);
+        if (existsSync(join(child, "run.json")))
+            result.push(child);
+        if (depth + 1 < 8)
+            result.push(...listRunStateDirs(child, depth + 1, seen));
+    }
+    return result;
+}
+function runIndexPath(stateRoot) {
+    return join(stateRoot, "index.json");
+}
+function indexEntryFromStatus(status) {
+    const progress = status.progress && typeof status.progress === "object"
+        ? status.progress
+        : {};
+    return {
+        ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+        ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+        run: String(status.run),
+        state_dir: String(status.state_dir),
+        status: status.status,
+        ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+        updated_at: typeof progress.updatedAt === "string"
+            ? progress.updatedAt
+            : typeof status.createdAt === "string"
+                ? status.createdAt
+                : new Date(0).toISOString(),
+    };
+}
+export function rebuildRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
+    mkdirSync(stateRoot, { recursive: true });
+    const entries = listRunStateDirs(stateRoot)
+        .flatMap((stateDir) => {
         try {
-            const stateDir = join(stateRoot, entry.name);
-            const status = getRunStatus(stateDir);
-            if (!matchesStatusFilter(status.status, statusFilter))
-                continue;
-            runs.push({
-                run: status.run,
-                state_dir: stateDir,
-                status: status.status,
-                ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
-                ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
-            });
+            return [indexEntryFromStatus(getRunStatus(stateDir))];
         }
         catch {
-            // Ignore malformed run dirs.
+            return [];
         }
+    })
+        .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+    writeJsonAtomic(runIndexPath(stateRoot), {
+        entries,
+        rebuilt_at: new Date().toISOString(),
+    });
+    return entries;
+}
+export function readRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
+    const index = readJson(runIndexPath(stateRoot));
+    if (!index || typeof index !== "object")
+        return undefined;
+    const entries = index.entries;
+    if (!Array.isArray(entries))
+        return undefined;
+    const valid = entries.filter((entry) => {
+        const record = entry && typeof entry === "object"
+            ? entry
+            : {};
+        return (typeof record.run === "string" &&
+            typeof record.state_dir === "string" &&
+            typeof record.status === "string");
+    });
+    if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+        return undefined;
+    return valid;
+}
+export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
+    if (!existsSync(stateRoot))
+        return [];
+    const indexed = readRunStateIndex(stateRoot);
+    if (indexed) {
+        return indexed
+            .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+            .map((entry) => ({
+            run: entry.run,
+            state_dir: entry.state_dir,
+            status: entry.status,
+            ...(entry.tool ? { tool: entry.tool } : {}),
+            ...(entry.recipe ? { recipe: entry.recipe } : {}),
+        }));
     }
-    return runs;
+    return rebuildRunStateIndex(stateRoot)
+        .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+        .map((entry) => ({
+        run: entry.run,
+        state_dir: entry.state_dir,
+        status: entry.status,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.recipe ? { recipe: entry.recipe } : {}),
+    }));
 }
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
@@ -525,14 +643,7 @@ function parseRunInboxLine(line) {
     }
 }
 function readRunInboxMessagesFromStateDir(stateDir) {
-    const file = runInboxFile(stateDir);
-    if (!existsSync(file))
-        return [];
-    return readFileSync(file, "utf8")
-        .split("\n")
-        .filter((line) => line.trim())
-        .map(parseRunInboxLine)
-        .filter((message) => Boolean(message));
+    return readJsonlFileResilient(runInboxFile(stateDir)).records;
 }
 function writeRunInboxMessages(stateDir, messages) {
     writeFileSync(runInboxFile(stateDir), messages.length
@@ -630,11 +741,18 @@ export function appendRunOutboxEvent(runOrDir, event) {
     const run = String(status.run ?? runOrDir);
     const type = event.type || event.event || "run.message";
     const to = event.to || "coordinator";
+    const metadata = event.metadata ?? {};
+    const requiresResponse = metadata.requires_response === true;
     const payload = {
         ...(event.body !== undefined ? { body: event.body } : {}),
         ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
         ...(event.data !== undefined ? { data: event.data } : {}),
-        delivery: normalizeRunOutboxDelivery(event.delivery ?? (to === "coordinator" ? "followup" : "log")),
+        delivery: normalizeRunOutboxDelivery(event.delivery ??
+            (requiresResponse
+                ? "followup"
+                : to === "coordinator"
+                    ? "notify"
+                    : "log")),
         event: type,
         from: event.from || `run:${run}`,
         level: normalizeRunOutboxLevel(event.level),
@@ -905,6 +1023,62 @@ export function cancelRun(runOrDir) {
         ? { cancelled: result.stopped, ...result }
         : result;
 }
+function assertTerminalRun(runOrDir) {
+    const status = getRunStatus(runOrDir);
+    if (status.status === "running") {
+        throw new Error("Only terminal runs can be archived or pruned.");
+    }
+    return status;
+}
+function archivePathFor(run, stateDir) {
+    const archiveRoot = join(dirname(stateDir), "archived");
+    mkdirSync(archiveRoot, { recursive: true });
+    return join(archiveRoot, `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+}
+export function archiveRun(runOrDir) {
+    const status = assertTerminalRun(runOrDir);
+    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 pruneRun(runOrDir, options = {}) {
+    const status = assertTerminalRun(runOrDir);
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? basename(stateDir));
+    const manifest = resolveArtifactManifest(status.artifacts);
+    const preserved = {};
+    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(),
+    };
+}
 export function killRun(runOrDir) {
     const result = stopRun(runOrDir, "SIGKILL", "run.kill");
     return Object.hasOwn(result, "stopped")

package/dist/lib/build-dist.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dist build pipeline entrypoint logic.
+ * Zones: packaging, JavaScript-only distributive tree
+ */
+export declare function buildDist(): void;

package/dist/lib/build-dist.js

@@ -0,0 +1,24 @@
+/**
+ * Dist build pipeline entrypoint logic.
+ * Zones: packaging, JavaScript-only distributive tree
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+function run(command, args) {
+    const result = spawnSync(command, args, { stdio: "inherit" });
+    if (result.status !== 0)
+        process.exit(result.status ?? 1);
+}
+export function buildDist() {
+    rmSync("dist", { recursive: true, force: true });
+    mkdirSync("dist", { recursive: true });
+    run("tsc", ["-p", "tsconfig.build.json"]);
+    for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
+        cpSync(dir, join("dist", dir), { recursive: true });
+    }
+    const builtScripts = readdirSync(join("dist", "scripts"))
+        .filter((name) => name.endsWith(".mjs"))
+        .map((name) => join("dist", "scripts", name));
+    run(process.execPath, ["--check", ...builtScripts]);
+}

package/dist/lib/command-templates.js

@@ -102,23 +102,23 @@ function getLeafCommandTemplateWarnings(config) {
         const shellContent = hasAnyFlag(args, ["-c"])
             ? "shell command strings"
             : "shell scripts";
-        warnings.push(`${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting.`);
+        warnings.push(`${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting. Mitigation: keep scripts local, reviewed, and parameterized with explicit placeholders.`);
     }
     if (["node", "deno", "bun"].includes(command) &&
         hasAnyFlag(args, ["-e", "--eval"])) {
-        warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`);
+        warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
     }
     if (["python", "python3", "perl", "ruby"].includes(command) &&
         hasAnyFlag(args, ["-c", "-e"])) {
-        warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`);
+        warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`);
     }
     if (command === "rm" &&
         (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
             hasRiskyPathArg(args))) {
-        warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`);
+        warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands. Mitigation: constrain path placeholders and consider dry-run or explicit confirmation.`);
     }
     if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
-        warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`);
+        warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands. Mitigation: constrain path placeholders and prefer narrow source/destination paths.`);
     }
     return warnings;
 }

package/dist/lib/conformance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal conformance runner logic.
+ * Zones: CI/release validation, protocol regression suite selection
+ */
+export declare const conformanceSuites: string[];
+export interface ConformanceReport {
+    code: number;
+    output: string;
+    summary: string;
+    suites: number;
+}
+export declare function runConformance(cwd?: URL): ConformanceReport;

package/dist/lib/conformance.js

@@ -0,0 +1,28 @@
+/**
+ * Internal conformance runner logic.
+ * Zones: CI/release validation, protocol regression suite selection
+ */
+import { spawnSync } from "node:child_process";
+export const conformanceSuites = [
+    "tests/protocol-examples.test.ts",
+    "tests/recipe-discovery.test.ts",
+    "tests/registry.test.ts",
+    "tests/runtime-registry.test.ts",
+    "tests/async-runs.test.ts",
+    "tests/actor-rooms.test.ts",
+    "tests/tools.test.ts",
+];
+export function runConformance(cwd = new URL("..", import.meta.url)) {
+    const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...conformanceSuites], { cwd, encoding: "utf8", stdio: "pipe" });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    const summary = output
+        .split("\n")
+        .filter((line) => /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line))
+        .join("\n");
+    return {
+        code: result.status ?? 1,
+        output,
+        summary,
+        suites: conformanceSuites.length,
+    };
+}

package/dist/lib/coordinator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Multi-actor coordinator helper entrypoint logic.
+ * Zones: swarm coordination, worker pool orchestration
+ */
+export declare function runCoordinator(argv?: string[]): Promise<void>;