@llblab/pi-actors 0.19.10 → 0.20.0

package/dist/lib/async-runs.js

@@ -0,0 +1,612 @@
+/**
+ * Command-template async run primitives
+ * Zones: async runtime, lifecycle, state files
+ * Owns detached run state, observation, log tailing, listing, and cancellation safety
+ */
+import { spawn } from "node:child_process";
+import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+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 * as Paths from "./paths.js";
+import * as RecipeReferences from "./recipe-references.js";
+import * as RecipeUsage from "./recipe-usage.js";
+const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
+const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
+function packageRoot() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    if (basename(moduleDir) === "lib" && basename(dirname(moduleDir)) === "dist") {
+        return dirname(dirname(moduleDir));
+    }
+    return dirname(moduleDir);
+}
+const PACKAGE_ROOT = packageRoot();
+const RUNNER_PATH = join(PACKAGE_ROOT, "scripts", "async-runner.mjs");
+function asyncRunnerArgv(stateDir) {
+    return existsSync(join(PACKAGE_ROOT, "dist", "lib", "execution.js"))
+        ? [RUNNER_PATH, stateDir]
+        : ["--experimental-strip-types", RUNNER_PATH, stateDir];
+}
+function safeRunId(value) {
+    const run = (value || `run-${Date.now()}`).trim();
+    if (!/^[A-Za-z0-9_.-]+$/.test(run))
+        throw new Error("Run id may contain only letters, numbers, dot, underscore, and dash.");
+    return run;
+}
+function resolveArtifactPaths(artifacts, values) {
+    if (!artifacts)
+        return undefined;
+    const resolved = {};
+    for (const [key, value] of Object.entries(artifacts)) {
+        if (!key.trim())
+            continue;
+        resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+    }
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+function resolveRunTemplate(params) {
+    if (!params.template)
+        throw new Error("spawn requires file or template.");
+    const envelope = {};
+    for (const key of [
+        "args",
+        "defaults",
+        "parallel",
+        "label",
+        "when",
+        "timeout",
+        "delay",
+        "output",
+        "retry",
+        "failure",
+        "recover",
+        "repeat",
+    ]) {
+        if (params[key] !== undefined)
+            envelope[key] = params[key];
+    }
+    if (Object.keys(envelope).length === 0)
+        return { template: params.template };
+    if (typeof params.template === "object" && !Array.isArray(params.template)) {
+        return { template: { ...envelope, ...params.template } };
+    }
+    return { template: { ...envelope, template: params.template } };
+}
+function resolveStateDir(params, run) {
+    return resolve(params.state_dir || join(DEFAULT_STATE_ROOT, run));
+}
+function assertNoActiveRunState(stateDir) {
+    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))
+        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.`);
+}
+function resolveRecipeFile(file) {
+    return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+}
+function isMutableUsageRecipeFile(file) {
+    const userRoot = resolve(DEFAULT_RECIPE_ROOT);
+    const resolved = resolve(file);
+    return resolved.startsWith(`${userRoot}/`);
+}
+function readRecipeFile(file) {
+    const path = resolveRecipeFile(file);
+    const raw = RecipeReferences.readRawRecipeConfig(path);
+    if (raw && Object.hasOwn(raw, "tool")) {
+        throw new Error(`Template recipe cannot define tool; use template in ${path}`);
+    }
+    const includeActorRecipeContext = raw?.actor_context !== false && raw?.actor_context !== "off";
+    const config = RecipeReferences.readResolvedRecipeConfig(path, [], {
+        includeActorRecipeContext,
+    });
+    if (!config) {
+        throw new Error(`Template recipe must define template: ${path}`);
+    }
+    return {
+        ...config,
+        file: path,
+        ...(includeActorRecipeContext ? {} : { actor_context: false }),
+    };
+}
+function getRunIdFromFile(file) {
+    if (!file)
+        return undefined;
+    const name = basename(file, extname(file));
+    return name || undefined;
+}
+function resolveStartParams(params) {
+    if (!params.file)
+        return params;
+    const fileParams = readRecipeFile(params.file);
+    return {
+        ...fileParams,
+        ...params,
+        run_id: params.run_id ||
+            fileParams.run_id ||
+            fileParams.name ||
+            getRunIdFromFile(fileParams.file),
+        values: { ...(fileParams.values ?? {}), ...(params.values ?? {}) },
+    };
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pidMatchesRun(pid, cwd, stateDir) {
+    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(RUNNER_PATH) &&
+            cmdline.includes(stateDir));
+    }
+    catch {
+        return false;
+    }
+}
+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");
+}
+function tailLines(path, lines) {
+    const content = tailFile(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.
+        }
+    }
+    return undefined;
+}
+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 });
+}
+function prepareStateDirForStart(stateDir) {
+    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)) {
+        throw new Error(`Run is already running: ${String(existing?.run ?? stateDir)}`);
+    }
+    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 });
+    }
+}
+export function startRun(params, cwd) {
+    const startParams = resolveStartParams(params);
+    const resolved = resolveRunTemplate(startParams);
+    const run = safeRunId(startParams.run_id);
+    const stateDir = resolveStateDir(startParams, run);
+    assertNoActiveRunState(stateDir);
+    mkdirSync(stateDir, { recursive: true });
+    const releaseStartLock = acquireStateStartLock(stateDir);
+    try {
+        assertNoActiveRunState(stateDir);
+        prepareStateDirForStart(stateDir);
+        const stdout = join(stateDir, "stdout.log");
+        const stderr = join(stateDir, "stderr.log");
+        const recipeFile = startParams.file
+            ? resolveRecipeFile(startParams.file)
+            : undefined;
+        const recipe = startParams.name || getRunIdFromFile(recipeFile);
+        const includeActorRecipeContext = startParams.actor_context !== false && startParams.actor_context !== "off";
+        const recipeContextRecords = recipeFile && includeActorRecipeContext
+            ? RecipeReferences.buildRecipeContextRecords(recipeFile)
+            : undefined;
+        if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
+            RecipeUsage.recordRecipeLaunch(recipeFile);
+        }
+        const outFd = openSync(stdout, "a");
+        const errFd = openSync(stderr, "a");
+        const argv = asyncRunnerArgv(stateDir);
+        const values = {
+            ...(startParams.values || {}),
+            actor_address: `run:${run}`,
+            communication_file: join(stateDir, "communication.json"),
+            default_room: `room:${run}`,
+            run_id: run,
+            state_dir: stateDir,
+        };
+        const outputValues = {
+            ...(startParams.defaults || {}),
+            ...values,
+        };
+        const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
+        const meta = {
+            argv: [process.execPath, ...argv],
+            createdAt: new Date().toISOString(),
+            cwd,
+            ...(startParams.launch_source ? { launch_source: startParams.launch_source } : {}),
+            ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
+            pid: 0,
+            ...(recipe ? { recipe } : {}),
+            ...(recipeFile ? { recipe_file: recipeFile } : {}),
+            run,
+            state_dir: stateDir,
+            status: "running",
+            ...(startParams.tool ? { tool: startParams.tool } : {}),
+            template: resolved.template,
+            values,
+            ...(artifacts ? { artifacts } : {}),
+            ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+            ...(recipeContextRecords && recipeContextRecords.length > 0
+                ? { recipe_context_records: recipeContextRecords }
+                : {}),
+            ...(startParams.retire_when === "children_terminal"
+                ? { retire_when: "children_terminal" }
+                : {}),
+        };
+        writeJsonAtomic(join(stateDir, "run.json"), meta);
+        const child = spawn(process.execPath, argv, {
+            cwd,
+            detached: true,
+            stdio: ["ignore", outFd, errFd],
+        });
+        closeSync(outFd);
+        closeSync(errFd);
+        meta.pid = child.pid ?? 0;
+        writeJsonAtomic(join(stateDir, "run.json"), meta);
+        writeJsonAtomic(join(stateDir, "progress.json"), {
+            completed: 0,
+            failures: [],
+            phase: "starting",
+            updatedAt: new Date().toISOString(),
+        });
+        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        child.unref();
+        return meta;
+    }
+    finally {
+        releaseStartLock();
+    }
+}
+function normalizeRunOutboxDelivery(value) {
+    return value === "notify" || value === "followup" ? value : "log";
+}
+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 getRunStatus(runOrDir) {
+    const stateDir = resolve(runOrDir.includes("/")
+        ? runOrDir
+        : join(DEFAULT_STATE_ROOT, safeRunId(runOrDir)));
+    const meta = readJson(join(stateDir, "run.json"));
+    if (!meta)
+        throw new Error(`Run not found: ${runOrDir}`);
+    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)));
+    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,
+    };
+}
+function matchesStatusFilter(status, filter) {
+    if (!filter || filter === "all")
+        return true;
+    if (filter === "active")
+        return status === "running";
+    if (filter === "terminal")
+        return status !== "running";
+    return status === filter;
+}
+export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
+    if (!existsSync(stateRoot))
+        return [];
+    const runs = [];
+    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        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 } : {}),
+            });
+        }
+        catch {
+            // Ignore malformed run dirs.
+        }
+    }
+    return runs;
+}
+export function tailRun(runOrDir, lines = 40) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const events = tailFile(join(stateDir, "events.jsonl"), lines);
+    if (events)
+        return events;
+    return (tailFile(join(stateDir, "stdout.log"), lines) ||
+        tailFile(join(stateDir, "stderr.log"), lines));
+}
+export function readRunEvents(runOrDir, lines = 40) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? runOrDir);
+    return tailLines(join(stateDir, "outbox.jsonl"), lines)
+        .map((line, index) => parseRunOutboxEventLine(line, run, stateDir, index))
+        .filter((event) => Boolean(event));
+}
+export function appendRunOutboxEvent(runOrDir, event) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? runOrDir);
+    const type = event.type || event.event || "run.message";
+    const to = event.to || "coordinator";
+    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")),
+        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,
+    };
+    const line = `${JSON.stringify(payload)}\n`;
+    writeFileSync(join(stateDir, "outbox.jsonl"), line, { flag: "a" });
+    return {
+        bytes: Buffer.byteLength(line),
+        outbox: "outbox.jsonl",
+        run,
+        sent: true,
+        state_dir: stateDir,
+    };
+}
+export function sendRunMessage(runOrDir, message) {
+    if (process.platform === "win32") {
+        throw new Error("run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.");
+    }
+    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))
+        throw new Error(`Run pid owner mismatch: ${run}`);
+    const controlPath = join(stateDir, "control.fifo");
+    if (!existsSync(controlPath))
+        throw new Error(`Run control FIFO not found: ${controlPath}`);
+    const stat = statSync(controlPath);
+    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+        throw new Error(`Run control endpoint is not a FIFO: ${controlPath}`);
+    }
+    const payload = message.endsWith("\n") ? message : `${message}\n`;
+    let fd;
+    try {
+        fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
+        const bytes = writeSync(fd, payload);
+        const trimmedMessage = message.trim().toLowerCase();
+        const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+        const ts = new Date().toISOString();
+        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
+        try {
+            const envelope = JSON.parse(message);
+            writeFileSync(join(stateDir, "inbox.jsonl"), `${JSON.stringify({ ...envelope, received_at: ts })}\n`, { flag: "a" });
+        }
+        catch {
+            // Plain control lines are already represented in events.jsonl.
+        }
+        if (terminalMessage) {
+            markTerminalHandled(stateDir, {
+                event: "run.message",
+                message: trimmedMessage,
+            });
+        }
+        return {
+            bytes,
+            control: "control.fifo",
+            run,
+            sent: true,
+            state_dir: stateDir,
+        };
+    }
+    catch (error) {
+        throw new Error(`Run control FIFO is not ready: ${controlPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function signalOwnedRunProcess(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return { signalTarget: "processGroup" };
+    }
+    catch {
+        process.kill(pid, signal);
+        return { signalTarget: "process" };
+    }
+}
+function markTerminalHandled(stateDir, details) {
+    writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
+        ...details,
+        ts: new Date().toISOString(),
+    });
+}
+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")
+        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)) {
+        return { stopped: false, reason: "pid owner mismatch", 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 });
+    return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
+}
+export function cancelRun(runOrDir) {
+    const result = stopRun(runOrDir, "SIGTERM", "run.cancel");
+    return Object.hasOwn(result, "stopped")
+        ? { cancelled: result.stopped, ...result }
+        : result;
+}
+export function killRun(runOrDir) {
+    const result = stopRun(runOrDir, "SIGKILL", "run.kill");
+    return Object.hasOwn(result, "stopped")
+        ? { killed: result.stopped, ...result }
+        : result;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Command-template standard helpers
+ * Zones: shared utils, local process execution, automation standard
+ * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
+ */
+export type CommandTemplateFailureScope = "continue" | "branch" | "root";
+export interface CommandTemplateActorRecipeContext {
+    alias?: string;
+    file?: string;
+    name?: string;
+    path?: string;
+    role?: string;
+}
+export interface CommandTemplateObjectConfig {
+    actorRecipeContext?: CommandTemplateActorRecipeContext;
+    label?: string;
+    parallel?: boolean;
+    when?: boolean | string;
+    template?: CommandTemplateValue;
+    args?: string[];
+    defaults?: Record<string, unknown>;
+    timeout?: number | string;
+    delay?: number | string;
+    output?: string;
+    retry?: number | string;
+    failure?: CommandTemplateFailureScope;
+    recover?: CommandTemplateValue;
+    repeat?: number | string;
+}
+export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
+export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
+export interface CommandTemplateLeafConfig extends CommandTemplateObjectConfig {
+    template: string;
+}
+export interface CommandTemplateInvocation {
+    command: string;
+    args: string[];
+}
+export interface CommandTemplateExecOptions {
+    cwd?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    stdin?: string;
+    killGrace?: number;
+    retry?: number;
+}
+export interface CommandTemplateExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+export type CommandTemplateExecCommand = (command: string, args: string[], options?: CommandTemplateExecOptions) => Promise<CommandTemplateExecResult>;
+export declare function normalizeCommandTemplateConfig(config: CommandTemplateConfig): CommandTemplateObjectConfig;
+export declare function resolveInheritedDefaultReferences(ownDefaults: Record<string, unknown> | undefined, inheritedDefaults: Record<string, unknown> | undefined, runtimeValues?: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function resolveCommandTemplateRepeat(value: number | string | undefined, values?: Record<string, unknown>): number | undefined;
+export declare function isCommandTemplateRepeatPlaceholder(name: string): boolean;
+export declare function getCommandTemplateRepeatDefaults(index: number, repeat: number): Record<string, string>;
+export declare function expandCommandTemplateConfigs(config: CommandTemplateConfig, inherited?: Pick<CommandTemplateObjectConfig, "args" | "defaults">): CommandTemplateLeafConfig[];
+export declare function getCommandTemplateWarnings(config: CommandTemplateConfig): string[];
+export declare function getCommandTemplateDefaults(config: CommandTemplateConfig | undefined): Record<string, string>;
+export declare function splitCommandTemplate(input: string): string[];
+export declare function expandCommandTemplateExecutable(command: string, cwd: string): string;
+export declare function shouldRunCommandTemplateNode(value: boolean | string | undefined, values: Record<string, unknown>): boolean;
+export declare function substituteCommandTemplateToken(token: string, values: Record<string, unknown>, missingLabel?: string, depth?: number): string;
+export declare function execCommandTemplate(command: string, args: string[], options?: CommandTemplateExecOptions): Promise<CommandTemplateExecResult>;
+export declare function buildCommandTemplateInvocation(config: CommandTemplateConfig, values: Record<string, unknown>, cwd: string, options?: {
+    emptyMessage?: string;
+    missingLabel?: string;
+}): CommandTemplateInvocation;