@llblab/pi-actors 0.38.1 → 0.40.0

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

@@ -7,6 +7,7 @@ import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
 import { type RunOutboxEvent } from "./runs-outbox.ts";
+import { type RunProcessIdentity } from "./runs-process.ts";
 import * as RunsIndex from "./runs-index.ts";
 import { type ProcessRunInboxResult, type RunInboxMessage, type RunInboxStatus } from "./runs-mailbox.ts";
 import { type SendRunMessageOptions } from "./runs-messages.ts";
@@ -35,6 +36,7 @@ export interface AsyncRunStartParams {
     when?: boolean | string;
     timeout?: number | string;
     delay?: number | string;
+    accept_output?: "review_evidence";
     output?: string;
     artifacts?: Record<string, RunArtifactDeclaration>;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
@@ -68,6 +70,7 @@ export interface AsyncRunMeta {
     control?: AsyncRunControlEndpoint;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
     model_policy?: CurrentPolicyProvenance;
+    process_identity?: RunProcessIdentity;
     recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
 }
@@ -112,6 +115,7 @@ export type { SendRunMessageOptions } from "./runs-messages.ts";
 export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
 export { getRunProcessSignalPlan } from "./runs-control.ts";
 export type { RunProcessSignalPlan } from "./runs-control.ts";
+export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {

package/dist/lib/async-runs.js

@@ -3,8 +3,8 @@
  * Owns launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
  */
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, writeFileSync, } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
 import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPolicyProvenance, } from "./model-context.js";
@@ -15,8 +15,9 @@ import { resolveArtifactPaths, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } from "./runs-control.js";
 import { buildRunOutboxEventPayload, parseRunOutboxEventLine, } from "./runs-outbox.js";
+import { claimRunStateDirectory } from "./runs-ownership.js";
 import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.js";
-import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun, } from "./runs-process.js";
+import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
 import * as RunsStart from "./runs-start.js";
 import * as RunsIndex from "./runs-index.js";
 import { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
@@ -57,6 +58,7 @@ function resolveRunTemplate(params) {
         "when",
         "timeout",
         "delay",
+        "accept_output",
         "output",
         "retry",
         "failure",
@@ -228,6 +230,7 @@ export function startRun(params, cwd) {
     mkdirSync(stateDir, { recursive: true });
     const releaseStartLock = acquireStateStartLock(stateDir);
     try {
+        claimRunStateDirectory(stateDir, run);
         assertNoActiveRunState(stateDir);
         prepareStateDirForStart(stateDir);
         const stdout = join(stateDir, "stdout.log");
@@ -289,6 +292,9 @@ export function startRun(params, cwd) {
         closeSync(outFd);
         closeSync(errFd);
         meta.pid = child.pid ?? 0;
+        const processIdentity = captureRunProcessIdentity(meta.pid, cwd, stateDir, RUNNER_PATH);
+        if (processIdentity)
+            meta.process_identity = processIdentity;
         writeJsonAtomic(join(stateDir, "run.json"), meta);
         writeJsonAtomic(join(stateDir, "progress.json"), {
             completed: 0,
@@ -384,14 +390,18 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? runOrDir);
-    if (status.status !== "running")
-        throw new Error(`Run is not running: ${run}`);
     const pid = Number(status.pid || 0);
-    if (!pid || !isAlive(pid))
-        throw new Error(`Run pid is not alive: ${run}`);
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH) &&
-        !isWithinRunnerIdentityGrace(status, RUNNER_IDENTITY_GRACE_MS))
-        throw new Error(`Run pid owner mismatch: ${run}`);
+    const identity = verifyRunProcessIdentity(pid, status.process_identity);
+    if (status.status !== "running") {
+        if (identity.status === "owner_mismatch" ||
+            identity.status === "unsupported_proof") {
+            throw new Error(`Run process identity ${identity.status}: ${run}`);
+        }
+        throw new Error(`Run is not running: ${run}`);
+    }
+    if (!identity.valid) {
+        throw new Error(`Run process identity ${identity.status}: ${run}`);
+    }
     return deliverRunMessage(status, run, stateDir, message, options);
 }
 export { getRunProcessSignalPlan } from "./runs-control.js";
@@ -402,26 +412,111 @@ function markTerminalProgress(stateDir, phase) {
         : undefined;
     writeJsonAtomic(join(stateDir, "progress.json"), buildTerminalProgress(progress, phase));
 }
+function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
+    const evidencePath = join(stateDir, "review-evidence.json");
+    const manifest = readJson(evidencePath);
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        return;
+    const record = manifest;
+    if (!Array.isArray(record.commands))
+        return;
+    const completedAt = new Date().toISOString();
+    const effectiveExitCode = signal === "SIGKILL" ? 137 : 143;
+    const commands = record.commands.map((command) => {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            return command;
+        }
+        const entry = command;
+        if (entry.status !== "running" || typeof entry.id !== "string")
+            return entry;
+        const captureDir = join(stateDir, "captures", entry.id);
+        const attempts = existsSync(captureDir)
+            ? readdirSync(captureDir)
+                .filter((name) => /^attempt-\d+$/.test(name))
+                .sort()
+                .map((name, index) => {
+                const attemptDir = join(captureDir, name);
+                const stdoutFile = join(attemptDir, "stdout.log");
+                const stderrFile = join(attemptDir, "stderr.log");
+                return {
+                    attempt: index + 1,
+                    stdout: {
+                        path: relative(stateDir, stdoutFile),
+                        bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
+                    },
+                    stderr: {
+                        path: relative(stateDir, stderrFile),
+                        bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
+                    },
+                };
+            })
+            : [];
+        return {
+            ...entry,
+            status: phase,
+            completed_at: completedAt,
+            attempts,
+            effective_exit_code: effectiveExitCode,
+            killed: true,
+            ...(entry.semantic_acceptance === "pending"
+                ? { semantic_acceptance: "interrupted" }
+                : {}),
+        };
+    });
+    writeJsonAtomic(evidencePath, {
+        ...record,
+        status: phase,
+        commands,
+        updated_at: completedAt,
+    });
+}
 function stopRun(runOrDir, signal, event) {
     const status = getRunStatus(runOrDir);
     const pid = Number(status.pid || 0);
     const stateDir = String(status.state_dir);
-    if (status.status !== "running")
+    if (status.status !== "running" && status.status !== "exited") {
         return { stopped: false, reason: "not running", status };
-    if (!pid || !isAlive(pid))
-        return { stopped: false, reason: "pid not alive", status };
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH)) {
-        return { stopped: false, reason: "pid owner mismatch", status };
+    }
+    const identity = verifyRunProcessIdentity(pid, status.process_identity);
+    if (status.status === "exited") {
+        if (identity.status === "owner_mismatch" ||
+            identity.status === "unsupported_proof") {
+            return {
+                stopped: false,
+                reason: identity.status.replaceAll("_", " "),
+                process_identity_status: identity.status,
+                status,
+            };
+        }
+        return { stopped: false, reason: "not running", status };
+    }
+    if (!identity.valid) {
+        return {
+            stopped: false,
+            reason: identity.status.replaceAll("_", " "),
+            process_identity_status: identity.status,
+            status,
+        };
     }
     const signalResult = signalOwnedRunProcess(pid, signal);
     writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
     markTerminalHandled(stateDir, { event, signal });
-    if (event === "run.kill")
+    if (event === "run.kill") {
+        finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
         markTerminalProgress(stateDir, "killed");
-    if (event === "run.cancel")
+    }
+    if (event === "run.cancel") {
+        finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
         markTerminalProgress(stateDir, "cancelled");
+    }
     return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
+export function markRunTerminalNotificationHandled(stateDir, status) {
+    markTerminalHandled(stateDir, {
+        event: "run.notification",
+        status,
+    });
+}
 export function cancelRun(runOrDir) {
     const result = stopRun(runOrDir, "SIGTERM", "run.cancel");
     return Object.hasOwn(result, "stopped")

package/dist/lib/command-templates.d.ts

@@ -23,6 +23,7 @@ export interface CommandTemplateObjectConfig {
     defaults?: Record<string, unknown>;
     timeout?: number | string;
     delay?: number | string;
+    accept_output?: "review_evidence";
     output?: string;
     retry?: number | string;
     failure?: CommandTemplateFailureScope;
@@ -45,12 +46,20 @@ export interface CommandTemplateExecOptions {
     stdin?: string;
     killGrace?: number;
     retry?: number;
+    captureDir?: string;
+    captureLimitBytes?: number;
 }
 export interface CommandTemplateExecResult {
     stdout: string;
     stderr: string;
     code: number;
     killed: boolean;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stdoutFile?: string;
+    stderrFile?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
 }
 export type CommandTemplateRiskLabel = "risk.shell" | "risk.eval" | "risk.broad_fs_write" | "risk.destructive_fs" | "risk.network" | "risk.external_side_effect" | "risk.long_running" | "risk.platform_specific" | "risk.secret_touching";
 export type CommandTemplateExecCommand = (command: string, args: string[], options?: CommandTemplateExecOptions) => Promise<CommandTemplateExecResult>;

package/dist/lib/command-templates.js

@@ -4,8 +4,10 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
     "risk.eval",
@@ -386,9 +388,9 @@ export function expandCommandTemplateExecutable(command, cwd) {
     if (command === "~")
         return homedir();
     if (command.startsWith("~/"))
-        return resolve(homedir(), command.slice(2));
+        return resolvePath(homedir(), command.slice(2));
     if (command.includes("/") && !isAbsolute(command))
-        return resolve(cwd, command);
+        return resolvePath(cwd, command);
     return command;
 }
 function evaluateCommandTemplateExpression(expression, values) {
@@ -592,13 +594,67 @@ export async function execCommandTemplate(command, args, options = {}) {
         killed: false,
     };
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const result = await execCommandTemplateOnce(command, args, options);
+        const attemptOptions = options.captureDir
+            ? {
+                ...options,
+                captureDir: join(options.captureDir, `attempt-${String(attempt).padStart(3, "0")}`),
+            }
+            : options;
+        const result = await execCommandTemplateOnce(command, args, attemptOptions);
         if (result.code === 0)
             return result;
         lastResult = result;
     }
     return lastResult;
 }
+function trimCaptureTail(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let start = value.length - limit;
+    while (start < value.length && (value[start] & 0xc0) === 0x80)
+        start += 1;
+    return value.subarray(start);
+}
+function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream) {
+    let bytes = 0;
+    let content = Buffer.alloc(0);
+    let file = persistCompleteStream
+        ? join(getCaptureDir(), `${stream}.log`)
+        : undefined;
+    if (file)
+        writeFileSync(file, Buffer.alloc(0));
+    let truncated = false;
+    return {
+        append(value) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            bytes += chunk.length;
+            if (bytes > limit)
+                truncated = true;
+            if (!file && bytes <= limit) {
+                content = Buffer.concat([content, chunk]);
+                return;
+            }
+            if (!file) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            appendFileSync(file, chunk);
+            content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
+        },
+        result() {
+            if (!file && persistCompleteStream) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            return {
+                bytes,
+                content: content.toString("utf8"),
+                ...(file ? { file } : {}),
+                truncated,
+            };
+        },
+    };
+}
 function execCommandTemplateOnce(command, args, options = {}) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
@@ -606,8 +662,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
             shell: false,
             stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
         });
-        let stdout = "";
-        let stderr = "";
+        const captureLimit = Math.max(1, options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES);
+        let captureDir;
+        const getCaptureDir = () => {
+            if (captureDir)
+                return captureDir;
+            captureDir = options.captureDir
+                ? resolvePath(options.captureDir)
+                : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+            mkdirSync(captureDir, { recursive: true });
+            return captureDir;
+        };
+        const persistCompleteStreams = options.captureDir !== undefined;
+        const stdoutCapture = createBoundedCommandCapture("stdout", captureLimit, getCaptureDir, persistCompleteStreams);
+        const stderrCapture = createBoundedCommandCapture("stderr", captureLimit, getCaptureDir, persistCompleteStreams);
         let killed = false;
         let settled = false;
         let timeoutId;
@@ -632,7 +700,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
                 clearTimeout(killTimeoutId);
             if (options.signal)
                 options.signal.removeEventListener("abort", killProcess);
-            resolve({ stdout, stderr, code, killed });
+            const stdout = stdoutCapture.result();
+            const stderr = stderrCapture.result();
+            resolve({
+                stdout: stdout.content,
+                stderr: stderr.content,
+                code,
+                killed,
+                stdoutBytes: stdout.bytes,
+                stderrBytes: stderr.bytes,
+                ...(stdout.file ? { stdoutFile: stdout.file } : {}),
+                ...(stderr.file ? { stderrFile: stderr.file } : {}),
+                ...(stdout.truncated ? { stdoutTruncated: true } : {}),
+                ...(stderr.truncated ? { stderrTruncated: true } : {}),
+            });
         };
         if (options.signal) {
             if (options.signal.aborted)
@@ -643,16 +724,16 @@ function execCommandTemplateOnce(command, args, options = {}) {
         if (options.timeout !== undefined && options.timeout > 0)
             timeoutId = setTimeout(killProcess, options.timeout);
         proc.stdout?.on("data", (data) => {
-            stdout += data.toString();
+            stdoutCapture.append(data);
         });
         proc.stderr?.on("data", (data) => {
-            stderr += data.toString();
+            stderrCapture.append(data);
         });
         proc.stdin?.on("error", () => { });
         if (options.stdin !== undefined)
             proc.stdin?.end(options.stdin);
         proc.on("error", (error) => {
-            stderr += error instanceof Error ? error.message : String(error);
+            stderrCapture.append(error instanceof Error ? error.message : String(error));
             settle(1);
         });
         proc.on("close", (code) => {

package/dist/lib/config.js

@@ -24,8 +24,6 @@ export function serializeTools(source) {
             entry.name = cfg.recipe.name;
         if (cfg.recipe?.async !== undefined)
             entry.async = cfg.recipe.async;
-        if (cfg.recipe?.state_dir)
-            entry.state_dir = cfg.recipe.state_dir;
         if (cfg.recipe?.values)
             entry.values = cfg.recipe.values;
         if (cfg.template)
@@ -113,9 +111,6 @@ export function normalizeStoredTool(key, value, reservedToolNames) {
         ? {
             name: recipeName,
             ...(typeof record.async === "boolean" ? { async: record.async } : {}),
-            ...(typeof record.state_dir === "string" && record.state_dir.trim()
-                ? { state_dir: record.state_dir.trim() }
-                : {}),
             template,
             ...(record.values &&
                 typeof record.values === "object" &&

package/dist/lib/execution.d.ts

@@ -7,17 +7,33 @@ import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 export interface ToolExecOptions {
     actorRecipeContext?: CommandTemplates.CommandTemplateActorRecipeContext;
+    evidenceContext?: {
+        acceptOutput?: "review_evidence";
+        label?: string;
+        repeatIndex?: string;
+    };
     cwd?: string;
     signal?: AbortSignal;
     stdin?: string;
     timeout?: number;
     retry?: number;
+    captureDir?: string;
+    captureLimitBytes?: number;
 }
 export interface ToolExecResult {
     stdout: string;
     stderr: string;
     code: number;
     killed: boolean;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stdoutFile?: string;
+    stderrFile?: string;
+    evidenceRef?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    /** Complete internal stdout for downstream pipeline stdin; never returned to model-facing output. */
+    pipelineStdout?: string;
 }
 export interface BranchReport {
     code: number;
@@ -28,8 +44,14 @@ export interface BranchReport {
     status: "done" | "failed" | "timeout";
     stderr?: string;
     stderrBytes: number;
+    stderrCapturedBytes: number;
+    stderrFile?: string;
+    stderrTruncated?: boolean;
     stdout?: string;
     stdoutBytes: number;
+    stdoutCapturedBytes: number;
+    stdoutFile?: string;
+    stdoutTruncated?: boolean;
 }
 export interface SoftQuorumReport {
     coverage: number;
@@ -50,6 +72,14 @@ export interface RegisteredToolExecutionResult {
         command: string;
         fullOutputPath?: string;
         killed: boolean;
+        stderrBytes?: number;
+        stderrCapturedBytes?: number;
+        stderrFile?: string;
+        stderrTruncated?: boolean;
+        stdoutBytes?: number;
+        stdoutCapturedBytes?: number;
+        stdoutFile?: string;
+        stdoutTruncated?: boolean;
         nonCriticalFailures?: Array<{
             code: number;
             command: string;
@@ -64,4 +94,5 @@ export interface RegisteredToolExecutionResult {
     };
 }
 export type RegisteredToolExec = (command: string, args: string[], options?: ToolExecOptions) => Promise<ToolExecResult>;
+export declare function applyOutputAcceptancePolicy(result: ToolExecResult, output: string | undefined): Promise<ToolExecResult>;
 export declare function executeRegisteredTool(cfg: RegisteredTool, params: Record<string, unknown>, exec: RegisteredToolExec, cwd: string, signal?: AbortSignal): Promise<RegisteredToolExecutionResult>;