@llblab/pi-actors 0.39.0 → 0.40.0

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>;

package/dist/lib/execution.js

@@ -3,6 +3,7 @@
  * Zones: tool execution, command templates, output formatting
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
+import { readFile } from "node:fs/promises";
 import * as CommandTemplates from "./command-templates.js";
 import { formatFailureOutput, formatOutput, formatToolText, } from "./execution-output.js";
 import * as Schema from "./schema.js";
@@ -62,6 +63,63 @@ function getBranchStatus(result) {
         return "done";
     return result.killed ? "timeout" : "failed";
 }
+const REVIEW_RESULT_MARKER = "ACTOR_REVIEW_RESULT";
+export async function applyOutputAcceptancePolicy(result, output) {
+    if (result.code !== 0 || output !== "review_evidence")
+        return result;
+    let semanticStdout = result.pipelineStdout ?? result.stdout;
+    if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+        if (!result.stdoutFile)
+            semanticStdout = "";
+        else {
+            try {
+                semanticStdout = await readFile(result.stdoutFile, "utf8");
+            }
+            catch {
+                semanticStdout = "";
+            }
+        }
+    }
+    const firstNonWhitespaceLine = semanticStdout
+        .split(/\r?\n/)
+        .find((line) => line.trim().length > 0);
+    if (firstNonWhitespaceLine?.trim() === REVIEW_RESULT_MARKER)
+        return result;
+    return {
+        ...result,
+        code: 65,
+        stderr: [
+            result.stderr,
+            `review evidence rejected: missing ${REVIEW_RESULT_MARKER} marker`,
+        ].filter(Boolean).join("\n"),
+    };
+}
+async function resolvePipelineStdout(result) {
+    let stdout = result.pipelineStdout ?? result.stdout;
+    if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+        if (!result.stdoutFile)
+            return undefined;
+        try {
+            stdout = await readFile(result.stdoutFile, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return result.evidenceRef
+        ? `${stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+        : stdout;
+}
+function rejectIncompletePipelineOutput(result) {
+    return {
+        ...result,
+        code: 74,
+        stderr: [
+            result.stderr,
+            `incomplete pipeline stdin: complete stdout unavailable${result.stdoutFile ? `; capture path unreadable: ${result.stdoutFile}` : ""}`,
+        ].filter(Boolean).join("\n"),
+    };
+}
 function getBranchFailureReason(result) {
     if (result.code === 0) {
         return result.stdout.trim() ? undefined : "empty_output";
@@ -80,13 +138,21 @@ function createBranchReport(label, command, result) {
         label,
         status: getBranchStatus(result),
         ...(result.stderr ? { stderr: result.stderr.slice(-1000) } : {}),
-        stderrBytes: Buffer.byteLength(result.stderr),
+        stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+        stderrCapturedBytes: Buffer.byteLength(result.stderr),
+        ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+        ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
         ...(result.stdout ? { stdout: result.stdout.slice(-1000) } : {}),
-        stdoutBytes: Buffer.byteLength(result.stdout),
+        stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+        stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+        ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+        ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
     };
 }
 function isUsableBranch(branch) {
-    return branch.status === "done" && branch.stdoutBytes > 0;
+    return (branch.status === "done" &&
+        branch.stdoutBytes > 0 &&
+        branch.stdoutTruncated !== true);
 }
 function createSoftQuorum(branches) {
     if (branches.length === 0)
@@ -231,15 +297,24 @@ function formatParallelStatusHeader(branches, minSuccessful) {
         return undefined;
     return `--- parallel_status: ${getParallelStatus(branches, minSuccessful)} usable: ${countUsableBranches(branches)} expected: ${branches.length} minimum: ${minSuccessful} ---`;
 }
+function stdoutWithEvidenceReference(result) {
+    return result.evidenceRef
+        ? `${result.stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+        : result.stdout;
+}
 function joinParallelStdout(branches, results, minSuccessful) {
     const body = results
         .map((result, index) => {
         const branch = branches[index];
-        const header = `--- branch: ${branch.label} status: ${branch.status} ---`;
+        const evidence = result.evidenceRef
+            ? ` evidence_ref: ${result.evidenceRef}`
+            : "";
+        const header = `--- branch: ${branch.label} status: ${branch.status}${evidence} ---`;
         if (branch.status === "done")
-            return `${header}\n${result.stdout}`;
+            return `${header}\n${stdoutWithEvidenceReference(result)}`;
+        const stdout = result.stdout ? `\nrejected_stdout: ${result.stdout}` : "";
         const stderr = branch.stderr ? `\nstderr: ${branch.stderr}` : "";
-        return `${header}\nexit: ${branch.code}${stderr}`;
+        return `${header}\nexit: ${branch.code}${stdout}${stderr}`;
     })
         .join("\n");
     return [formatParallelStatusHeader(branches, minSuccessful), body]
@@ -369,8 +444,18 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
     if (!Array.isArray(normalized.template)) {
         const leaf = { ...normalized, ...context };
         const invocation = CommandTemplates.buildCommandTemplateInvocation(leaf, params, cwd, { emptyMessage: "Tool template produced an empty command." });
-        const result = await exec(invocation.command, invocation.args, {
+        const evidenceContext = {
+            ...(normalized.accept_output
+                ? { acceptOutput: normalized.accept_output }
+                : {}),
+            ...(normalized.label ? { label: normalized.label } : {}),
+            ...(typeof controlValues.index === "string"
+                ? { repeatIndex: controlValues.index }
+                : {}),
+        };
+        const rawResult = await exec(invocation.command, invocation.args, {
             ...(actorRecipeContext ? { actorRecipeContext } : {}),
+            ...(Object.keys(evidenceContext).length > 0 ? { evidenceContext } : {}),
             cwd,
             signal,
             stdin,
@@ -383,6 +468,7 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
                 ? { retry: normalizeRetry(normalized.retry, controlValues) }
                 : {}),
         });
+        const result = await applyOutputAcceptancePolicy(rawResult, normalized.accept_output);
         return {
             branches: [],
             commands: [formatInvocationDetail(invocation)],
@@ -398,6 +484,12 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
         const concurrency = normalizeConcurrency(normalized.concurrency, controlValues, steps.length);
         const minSuccessful = normalizeMinSuccessful(normalized.min_successful, controlValues, steps.length);
         const branchResults = await mapConcurrent(steps, concurrency, (step) => executeTemplateConfig(step, context, params, exec, cwd, signal, stdin, false, actorRecipeContext));
+        const branchPipelineStdouts = await Promise.all(branchResults.map((item) => resolvePipelineStdout(item.result)));
+        for (const [index, item] of branchResults.entries()) {
+            if (item.result.stdoutTruncated && branchPipelineStdouts[index] === undefined) {
+                item.result = rejectIncompletePipelineOutput(item.result);
+            }
+        }
         const commands = branchResults.flatMap((item) => item.commands);
         const failures = branchResults.flatMap((item) => item.failures);
         const branches = branchResults.map((item, index) => createBranchReport(getNodeLabel(steps[index], index), item.commands.at(-1) ?? "<template>", item.result));
@@ -432,8 +524,13 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
             if (item.result.code === 0)
                 return item.result;
             addResultFailure(failures, item);
-            return { ...item.result, code: 0, stdout: "" };
+            return { ...item.result, code: 0 };
         });
+        const completeSuccessful = successful.map((item, index) => ({
+            ...item,
+            stdout: branchPipelineStdouts[index] ?? item.stdout,
+            evidenceRef: undefined,
+        }));
         const result = {
             code: 0,
             killed: successful.some((item) => item.killed),
@@ -442,6 +539,11 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
                 .filter(Boolean)
                 .join("\n"),
             stdout: joinParallelStdout(branches, successful, minSuccessful),
+            pipelineStdout: joinParallelStdout(branches, completeSuccessful, minSuccessful),
+            stdoutBytes: successful.reduce((total, item) => total + (item.stdoutBytes ?? Buffer.byteLength(item.stdout)), 0),
+            ...(successful.some((item) => item.stdoutTruncated)
+                ? { stdoutTruncated: true }
+                : {}),
         };
         if (quorumUnmet && nodeFailure === "root") {
             return {
@@ -504,12 +606,28 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
     const failures = [];
     let nextStdin = stdin;
     let result;
-    for (const step of steps) {
+    for (const [stepIndex, step] of steps.entries()) {
         const executed = await executeTemplateConfig(step, context, params, exec, cwd, signal, nextStdin, false, actorRecipeContext);
         branches.push(...executed.branches);
         commands.push(...executed.commands);
         failures.push(...executed.failures);
-        result = executed.result;
+        const pipelineStdout = await resolvePipelineStdout(executed.result);
+        const incompletePipelineInput = stepIndex < steps.length - 1 && pipelineStdout === undefined;
+        result = incompletePipelineInput
+            ? rejectIncompletePipelineOutput(executed.result)
+            : executed.result;
+        executed.result = result;
+        if (incompletePipelineInput) {
+            addResultFailure(failures, executed);
+            return {
+                branches,
+                commands,
+                criticalFailure: true,
+                failureScope: "root",
+                failures,
+                result,
+            };
+        }
         if (result.code !== 0) {
             const failureScope = maxFailureScope(executed.failureScope, executed.criticalFailure ? "root" : undefined, getFailureScope(step), getFailureScope(normalized), isRoot && steps.length === 1 ? "root" : undefined);
             if (failureScope === "root") {
@@ -537,13 +655,25 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
             nextStdin = "";
             continue;
         }
-        nextStdin = result.stdout;
+        nextStdin = pipelineStdout;
     }
     return { branches, commands, failures, result: result };
 }
 async function executeTemplateSteps(cfg, params, exec, cwd, signal) {
     return executeTemplateConfig(createTemplateConfig(cfg), {}, params, exec, cwd, signal, undefined, true, undefined);
 }
+function getCaptureDetails(result) {
+    return {
+        stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+        stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+        stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+        stderrCapturedBytes: Buffer.byteLength(result.stderr),
+        ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+        ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+        ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
+        ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
+    };
+}
 export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
     const executed = await executeTemplateSteps(cfg, Schema.normalizeRuntimeValues(params, cfg.argTypes), exec, cwd, signal);
     const command = formatCommandDetail(executed.commands);
@@ -556,7 +686,9 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
                 branches: executed.branches,
                 code: result.code,
                 command,
+                fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
                 killed: result.killed,
+                ...getCaptureDetails(result),
                 ...(executed.failures.length > 0
                     ? { nonCriticalFailures: executed.failures }
                     : {}),
@@ -575,8 +707,9 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
         details: {
             code: result.code,
             command,
-            fullOutputPath: formatted.fullOutputPath,
+            fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
             killed: result.killed,
+            ...getCaptureDetails(result),
             ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
             ...(executed.failures.length > 0
                 ? { nonCriticalFailures: executed.failures }

package/dist/lib/file-state.d.ts

@@ -3,4 +3,5 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
+export declare function withFileMutationLock<T>(path: string, mutate: () => T): T;
 export declare function writeJsonAtomic(path: string, value: unknown): void;

package/dist/lib/file-state.js

@@ -3,9 +3,97 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
-import { randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, parse, resolve } from "node:path";
+const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
+function canonicalMutationPath(path) {
+    const absolute = resolve(path);
+    const suffix = [];
+    let existing = absolute;
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing || existing === parse(existing).root)
+            break;
+        suffix.unshift(basename(existing));
+        existing = parent;
+    }
+    const canonicalAncestor = existsSync(existing)
+        ? realpathSync.native(existing)
+        : existing;
+    const canonical = resolve(canonicalAncestor, ...suffix);
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+function mutationLockPath(path) {
+    const key = createHash("sha256")
+        .update(canonicalMutationPath(path))
+        .digest("hex");
+    return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
+}
+function lockOwnerIsDead(lockPath) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
+        const pid = Number(owner.pid);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === "ESRCH";
+        }
+    }
+    catch {
+        return false;
+    }
+}
+export function withFileMutationLock(path, mutate) {
+    mkdirSync(FILE_MUTATION_LOCK_ROOT, { recursive: true });
+    const lockPath = mutationLockPath(path);
+    const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            mkdirSync(lockPath);
+            try {
+                writeFileSync(join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`, "utf8");
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs >
+                    FILE_MUTATION_LOCK_STALE_MS &&
+                    lockOwnerIsDead(lockPath)) {
+                    rmSync(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+                    cause: error,
+                });
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        return mutate();
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
 export function writeJsonAtomic(path, value) {
     mkdirSync(dirname(path), { recursive: true });
     const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;

package/dist/lib/observability.d.ts

@@ -50,7 +50,7 @@ export interface RunUiSnapshot {
 }
 export interface RunUiNotificationSink {
     notify(message: string, level: "info" | "warning" | "error"): void;
-    sendFollowUp(message: {
+    sendSteering(message: {
         customType: string;
         content: string;
         display: true;

package/dist/lib/observability.js

@@ -37,12 +37,15 @@ export function deliverRunTransitionNotifications(transitions, sink) {
         sink.notify(text, getRunTransitionNotificationType(transition));
         if (!shouldSendRunTransitionFollowUp(transition))
             continue;
-        sink.sendFollowUp({
+        sink.sendSteering({
             customType: "pi-actors-run",
             content: text,
             display: true,
             details: transition,
         });
+        if (transition.stateDir) {
+            AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+        }
     }
 }
 export function deliverRunOutboxNotifications(events, sink) {
@@ -53,7 +56,7 @@ export function deliverRunOutboxNotifications(events, sink) {
         sink.notify(text, getRunOutboxNotificationType(event));
         if (!shouldSendRunOutboxFollowUp(event))
             continue;
-        sink.sendFollowUp({
+        sink.sendSteering({
             customType: "pi-actors-run-message",
             content: text,
             display: true,
@@ -494,9 +497,9 @@ export function detectRunTransitions(previous, summary) {
     for (const run of summary.runs) {
         const key = runObservationKey(run);
         const old = previous.get(key);
-        if (old && old !== run.status && TERMINAL.has(run.status)) {
+        if (!run.terminalHandled && TERMINAL.has(run.status)) {
             transitions.push({
-                from: old,
+                from: old ?? "running",
                 run: run.run,
                 ...(run.stateDir ? { stateDir: run.stateDir } : {}),
                 ...(run.artifacts ? { artifacts: run.artifacts } : {}),

package/dist/lib/pi.d.ts

@@ -7,7 +7,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 export type { ExtensionAPI, ExtensionContext };
 export interface PiNotificationSink {
     notify(message: string, level: "info" | "warning" | "error"): void;
-    sendFollowUp(message: {
+    sendSteering(message: {
         customType: string;
         content: string;
         display: true;

package/dist/lib/pi.js

@@ -9,8 +9,8 @@ export function getSessionId(ctx) {
 export function createNotificationSink(pi, ctx) {
     return {
         notify: (message, level) => ctx.ui.notify(message, level),
-        sendFollowUp: (message) => pi.sendMessage(message, {
-            deliverAs: "followUp",
+        sendSteering: (message) => pi.sendMessage(message, {
+            deliverAs: "steer",
             triggerTurn: true,
         }),
     };

package/dist/lib/prompts.d.ts

@@ -6,13 +6,12 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. When a deferred actor result gates the next step, wait for its terminal steering notification; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
     readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
-    readonly state_dir: "Optional async run state directory for a co-located template recipe.";
     readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
     readonly templateNull: "Delete the tool when template is null.";

package/dist/lib/prompts.js

@@ -16,14 +16,14 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, output.
+- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. When a deferred actor result gates the next step, wait for its terminal steering notification; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
@@ -32,7 +32,6 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
     draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
-    state_dir: "Optional async run state directory for a co-located template recipe.",
     template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
     templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
     templateNull: "Delete the tool when template is null.",

package/dist/lib/recipes-context.js

@@ -47,10 +47,10 @@ function piOptionConsumesNextArg(arg) {
 function isPiFileArgument(arg) {
     return arg.startsWith("@") && arg.length > 1;
 }
-export function findPiPrintPromptIndex(args) {
+function findPiPrintPromptIndexes(args) {
     let printMode = false;
     let positionalOnly = false;
-    let promptIndex;
+    const promptIndexes = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!positionalOnly && arg === "--") {
@@ -68,9 +68,12 @@ export function findPiPrintPromptIndex(args) {
         }
         if (!printMode || isPiFileArgument(arg))
             continue;
-        promptIndex = index;
+        promptIndexes.push(index);
     }
-    return promptIndex;
+    return promptIndexes;
+}
+export function findPiPrintPromptIndex(args) {
+    return findPiPrintPromptIndexes(args).at(-1);
 }
 function matchesActorContext(record, context) {
     if (!context)
@@ -134,14 +137,19 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
 export function materializePiPrintPromptArg(command, args, promptFile) {
     if (!isPiCommand(command))
         return { args };
-    const promptIndex = findPiPrintPromptIndex(args);
-    if (promptIndex === undefined)
+    const promptIndexes = findPiPrintPromptIndexes(args);
+    if (promptIndexes.length === 0)
         return { args };
-    const prompt = args[promptIndex];
+    const prompt = promptIndexes.map((index) => args[index]).join(" ");
     const path = typeof promptFile === "function" ? promptFile() : promptFile;
     writeFileSync(path, prompt, "utf8");
-    const next = [...args];
-    next[promptIndex] = `@${path}`;
+    const promptIndexSet = new Set(promptIndexes);
+    const firstPromptIndex = promptIndexes[0];
+    const next = args.flatMap((arg, index) => {
+        if (index === firstPromptIndex)
+            return [`@${path}`];
+        return promptIndexSet.has(index) ? [] : [arg];
+    });
     return {
         args: next,
         promptBytes: Buffer.byteLength(prompt),