@llblab/pi-actors 0.33.0 → 0.34.1

package/dist/lib/runs-outbox.js

@@ -0,0 +1,87 @@
+/**
+ * Async run outbox events.
+ * Owns outbox event normalization, parsing, and append payload formatting.
+ */
+export function normalizeRunOutboxDelivery(value) {
+    return value === "notify" || value === "followup" ? value : "log";
+}
+export function normalizeRunOutboxLevel(value) {
+    return value === "warning" || value === "error" ? value : "info";
+}
+function normalizeRunOutboxEvent(raw, run, stateDir, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    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 }
+            : {}),
+        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, run, stateDir, index) {
+    try {
+        return normalizeRunOutboxEvent(JSON.parse(line), run, stateDir, index);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildRunOutboxEventPayload(run, event) {
+    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/dist/lib/runs-process.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Async run process identity helpers.
+ * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ */
+export declare function isAlive(pid: number): boolean;
+export declare function pidMatchesRun(pid: number, cwd: string, stateDir: string, runnerPath: string): boolean;
+export declare function isWithinRunnerIdentityGrace(meta: Record<string, unknown>, graceMs: number): boolean;

package/dist/lib/runs-process.js

@@ -0,0 +1,36 @@
+/**
+ * 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) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function pidMatchesRun(pid, cwd, stateDir, runnerPath) {
+    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, graceMs) {
+    const createdAt = typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
+    return (Number.isFinite(createdAt) &&
+        Date.now() - createdAt >= 0 &&
+        Date.now() - createdAt <= graceMs);
+}

package/dist/lib/runs-retention.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Async run retention operations.
+ * Owns terminal-run archive and prune filesystem behavior.
+ */
+export declare function archiveTerminalRun(status: Record<string, unknown>): Record<string, unknown>;
+export declare function pruneTerminalRun(status: Record<string, unknown>, options?: {
+    preserveArtifacts?: boolean;
+}): Record<string, unknown>;

package/dist/lib/runs-retention.js

@@ -0,0 +1,56 @@
+/**
+ * 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.js";
+import { resolveArtifactManifest, } from "./runs-artifacts.js";
+import { safeRunId } from "./runs-identity.js";
+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 archiveTerminalRun(status) {
+    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, options = {}) {
+    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(),
+    };
+}

package/dist/lib/runs-start.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Async run start guards.
+ * Owns active-run reuse checks, start lock acquisition, and safe state-dir
+ * preparation before a new runner process is spawned.
+ */
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+export declare function assertNoActiveRunState(stateDir: string, readJson: RunJsonReader, runnerPath: string): void;
+export declare function acquireStateStartLock(stateDir: string): () => void;
+export declare function prepareStateDirForStart(stateDir: string, readJson: RunJsonReader, runnerPath: string): void;

package/dist/lib/runs-start.js

@@ -0,0 +1,67 @@
+/**
+ * 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.js";
+const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+export function assertNoActiveRunState(stateDir, readJson, runnerPath) {
+    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) {
+    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, readJson, runnerPath) {
+    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/dist/lib/runs-status.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Async run status and log readers.
+ * Owns status derivation from run state files plus bounded log/event tails.
+ */
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+export declare function buildRunStatus(stateDir: string, runOrDir: string, meta: Record<string, unknown>, readJson: RunJsonReader, runnerPath: string, runnerIdentityGraceMs: number): Record<string, unknown>;
+export declare function tailFile(path: string, lines: number): string;
+export declare function tailLines(path: string, lines: number): string[];

package/dist/lib/runs-status.js

@@ -0,0 +1,60 @@
+/**
+ * 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 { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun } from "./runs-process.js";
+import { readJsonlFileResilient } from "./state-readers.js";
+function getInterruptedRunStatus(stateDir) {
+    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;
+}
+export function buildRunStatus(stateDir, runOrDir, meta, readJson, runnerPath, runnerIdentityGraceMs) {
+    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 = 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, lines) {
+    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, lines) {
+    const content = tailFile(path, lines);
+    return content ? content.split("\n") : [];
+}

package/dist/lib/runtime.d.ts

@@ -5,7 +5,7 @@
  */
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
-import * as Tools from "./tools.ts";
+import * as ToolsLocal from "./tools-local.ts";
 export interface RuntimeContext {
     hasUI: boolean;
     ui: {
@@ -22,7 +22,7 @@ export interface ToolRegistryRuntimeDeps {
     recipeRoot?: string;
     getActiveTools?: () => string[];
     getAllTools: () => ToolInfoLike[];
-    registerTool: (definition: ReturnType<typeof Tools.createRuntimeToolDefinition>) => void;
+    registerTool: (definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>) => void;
     reservedToolNames: Set<string>;
     setActiveTools?: (toolNames: string[]) => void;
 }

package/dist/lib/runtime.js

@@ -5,8 +5,8 @@
  */
 import { existsSync, watch } from "node:fs";
 import * as Paths from "./paths.js";
-import * as RecipeDiscovery from "./recipe-discovery.js";
-import * as Tools from "./tools.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as ToolsLocal from "./tools-local.js";
 export function createAutoToolsRuntime(deps) {
     const tools = new Map();
     const runtimeToolFingerprints = new Map();
@@ -50,7 +50,7 @@ export function createAutoToolsRuntime(deps) {
         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);
     }
@@ -86,7 +86,7 @@ export function createAutoToolsRuntime(deps) {
         const warnings = [];
         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 },
         ]);
@@ -94,7 +94,7 @@ export function createAutoToolsRuntime(deps) {
         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);
             }

package/dist/lib/schema.d.ts

@@ -33,6 +33,15 @@ export interface ToolArgSpec {
     defaults: Record<string, string>;
     error?: string;
 }
+export type JsonSchema = Record<string, unknown>;
+export declare function stringSchema(description: string): JsonSchema;
+export declare function typedArgSchema(description: string, type: ToolArgType | undefined): JsonSchema;
+export declare function booleanSchema(description: string): JsonSchema;
+export declare function nullSchema(description: string): JsonSchema;
+export declare function arraySchema(description: string): JsonSchema;
+export declare function unionSchema(anyOf: JsonSchema[]): JsonSchema;
+export declare function objectSchema(properties: Record<string, JsonSchema>, required?: string[]): JsonSchema;
+export declare function looseObjectSchema(description: string): JsonSchema;
 export declare function parseToolArgToken(value: string): ParsedToolArgToken;
 export declare function parseToolArgDeclarations(value: string): ToolArgSpec;
 export declare function normalizeStoredToolArgDeclarations(argsValue: unknown, defaultsValue: unknown): ToolArgSpec & {

package/dist/lib/schema.js

@@ -4,6 +4,46 @@
  * Owns tool argument declarations, placeholder-derived tool schemas, and persisted registry normalization
  */
 import * as CommandTemplates from "./command-templates.js";
+export function stringSchema(description) {
+    return { description, type: "string" };
+}
+export function typedArgSchema(description, type) {
+    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) {
+    return { description, type: "boolean" };
+}
+export function nullSchema(description) {
+    return { description, type: "null" };
+}
+export function arraySchema(description) {
+    return { description, items: {}, type: "array" };
+}
+export function unionSchema(anyOf) {
+    return { anyOf };
+}
+export function objectSchema(properties, required = []) {
+    return { additionalProperties: false, properties, required, type: "object" };
+}
+export function looseObjectSchema(description) {
+    return { additionalProperties: true, description, type: "object" };
+}
 function mergeUnique(items) {
     return [...new Set(items.filter(Boolean))];
 }

package/dist/lib/tools-access.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+export interface SessionContext {
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function getContextSessionId(ctx: unknown): string | undefined;
+export declare function requireContextSessionId(ctx: unknown, actor: string): string;
+export declare function sessionMismatchError(input: {
+    currentSession?: string;
+    expectedSession?: string;
+    run?: string;
+    target?: string;
+}): Error;
+export declare function assertRunAccessibleToContext(runId: string, ctx: unknown): Record<string, unknown>;

package/dist/lib/tools-access.js

@@ -0,0 +1,44 @@
+/**
+ * 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.js";
+export function getContextSessionId(ctx) {
+    return ctx?.sessionManager?.getSessionId?.();
+}
+export function requireContextSessionId(ctx, actor) {
+    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) {
+    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, ctx) {
+    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;
+}

package/dist/lib/tools-inspect.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public inspect tool behavior
+ * Zones: actor observation, recipe registry inspection, room/session/tool/run views
+ * Owns the public inspect execution path and compact observation responses
+ */
+export interface InspectToolDeps<TContext = unknown> {
+    getTool?: (name: string) => any | undefined;
+    packagedRecipeRoot?: string;
+    recipeRoot?: string;
+}
+export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;