@llblab/pi-actors 0.19.11 → 0.20.0

package/dist/lib/execution.js

@@ -0,0 +1,450 @@
+/**
+ * Registered tool execution runtime
+ * Zones: tool execution, command templates, output formatting
+ * Owns command-template invocation execution and pi tool-result payload formatting
+ */
+import * as CommandTemplates from "./command-templates.js";
+import { formatFailureOutput, formatOutput, formatToolText } from "./output.js";
+import * as Schema from "./schema.js";
+const DEFAULT_MAX_PARALLEL_BRANCHES = 64;
+function textContent(text) {
+    return { type: "text", text };
+}
+function createTemplateConfig(cfg) {
+    if (!cfg.template)
+        throw new Error(`Tool "${cfg.name}" has no command template.`);
+    if (typeof cfg.template === "object" && !Array.isArray(cfg.template)) {
+        return {
+            ...cfg.template,
+            args: cfg.template.args ?? cfg.args,
+            defaults: mergeDefaults(cfg.defaults, cfg.template.defaults),
+        };
+    }
+    return { args: cfg.args, defaults: cfg.defaults, template: cfg.template };
+}
+function quoteCommandDetailPart(value) {
+    if (value === "")
+        return "''";
+    if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function formatInvocationDetail(invocation) {
+    return [invocation.command, ...invocation.args]
+        .map(quoteCommandDetailPart)
+        .join(" ");
+}
+function formatCommandDetail(commands) {
+    return commands.length === 1 ? commands[0] : commands.join(" && ");
+}
+function mergeDefaults(inherited, own) {
+    if (!inherited && !own)
+        return undefined;
+    return { ...(inherited ?? {}), ...(own ?? {}) };
+}
+function getNodeLabel(config, index) {
+    const normalized = CommandTemplates.normalizeCommandTemplateConfig(config);
+    if (normalized.label)
+        return normalized.label;
+    return index === undefined ? "command" : `branch ${index + 1}`;
+}
+function getBranchStatus(result) {
+    if (result.code === 0)
+        return "done";
+    return result.killed ? "timeout" : "failed";
+}
+function createBranchReport(label, command, result) {
+    return {
+        code: result.code,
+        command,
+        killed: result.killed,
+        label,
+        status: getBranchStatus(result),
+        ...(result.stderr ? { stderr: result.stderr.slice(0, 1000) } : {}),
+        stdoutBytes: Buffer.byteLength(result.stdout),
+    };
+}
+function createSoftQuorum(branches) {
+    if (branches.length === 0)
+        return undefined;
+    const done = branches.filter((branch) => branch.status === "done").length;
+    const failed = branches.length - done;
+    return {
+        coverage: done / branches.length,
+        degraded: failed > 0,
+        done,
+        expected: branches.length,
+        failed,
+        usable: done > 0,
+    };
+}
+function getMaxParallelBranches() {
+    const raw = Number(process.env.PI_ACTORS_MAX_PARALLEL_BRANCHES ?? "");
+    return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_MAX_PARALLEL_BRANCHES;
+}
+function assertParallelBranchLimit(count) {
+    const max = getMaxParallelBranches();
+    if (count <= max)
+        return;
+    throw new Error(`Command template parallel fanout ${count} exceeds limit ${max}; set PI_ACTORS_MAX_PARALLEL_BRANCHES to override intentionally.`);
+}
+function normalizeFailureScope(value) {
+    if (value === undefined)
+        return "continue";
+    if (value === "continue" || value === "branch" || value === "root")
+        return value;
+    throw new Error("Command template failure must be one of: continue, branch, root.");
+}
+function getFailureScope(config) {
+    const normalized = CommandTemplates.normalizeCommandTemplateConfig(config);
+    return normalizeFailureScope(normalized.failure);
+}
+function maxFailureScope(...scopes) {
+    const rank = { branch: 1, continue: 0, root: 2 };
+    return scopes.reduce((current, scope) => rank[scope ?? "continue"] > rank[current] ? scope : current, "continue");
+}
+function normalizeRetry(value, values) {
+    const resolved = resolveNumericControlField(value, values, "retry");
+    if (resolved === undefined)
+        return 1;
+    if (!Number.isInteger(resolved) || resolved < 1)
+        throw new Error("Command template retry must be a positive integer.");
+    return resolved;
+}
+function getRecoverConfig(config) {
+    const recovered = Array.isArray(config) ? { template: config } : config;
+    const normalized = CommandTemplates.normalizeCommandTemplateConfig(recovered);
+    if (normalized.failure !== undefined)
+        return recovered;
+    return { ...normalized, failure: "root" };
+}
+function addResultFailure(failures, execution) {
+    if (execution.result.code === 0)
+        return;
+    const failure = {
+        code: execution.result.code,
+        command: execution.commands.at(-1) ?? "<template>",
+        killed: execution.result.killed,
+    };
+    const last = failures.at(-1);
+    if (last?.code === failure.code &&
+        last.command === failure.command &&
+        last.killed === failure.killed)
+        return;
+    failures.push(failure);
+}
+function mergeExecution(target, source) {
+    target.branches.push(...source.branches);
+    target.commands.push(...source.commands);
+    target.failures.push(...source.failures);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        let timeoutId;
+        const settle = () => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            if (signal)
+                signal.removeEventListener("abort", settle);
+            resolve();
+        };
+        if (signal?.aborted)
+            return settle();
+        timeoutId = setTimeout(settle, ms);
+        if (signal)
+            signal.addEventListener("abort", settle, { once: true });
+    });
+}
+function resolveNumericControlField(value, values, label) {
+    if (value === undefined)
+        return undefined;
+    const resolved = typeof value === "string"
+        ? CommandTemplates.substituteCommandTemplateToken(value, values, label)
+        : value;
+    if (resolved === "")
+        return undefined;
+    const numeric = Number(resolved);
+    if (!Number.isFinite(numeric) || numeric < 0)
+        throw new Error(`Command template ${label} must be a non-negative number.`);
+    return numeric;
+}
+async function applyDelay(delay, values, signal) {
+    const resolved = resolveNumericControlField(delay, values, "delay");
+    if (resolved === undefined || resolved <= 0)
+        return;
+    await sleep(resolved, signal);
+}
+function joinParallelStdout(branches, results) {
+    return results
+        .map((result, index) => {
+        const branch = branches[index];
+        const header = `--- branch: ${branch.label} status: ${branch.status} ---`;
+        if (branch.status === "done")
+            return `${header}\n${result.stdout}`;
+        const stderr = branch.stderr ? `\nstderr: ${branch.stderr}` : "";
+        return `${header}\nexit: ${branch.code}${stderr}`;
+    })
+        .join("\n");
+}
+async function executeRetriableTemplateConfig(normalized, inherited, params, exec, cwd, signal, stdin, isRoot, actorRecipeContext) {
+    const maxAttempts = normalizeRetry(normalized.retry, {
+        ...(inherited.defaults ?? {}),
+        ...params,
+    });
+    const attemptConfig = {
+        ...normalized,
+        delay: undefined,
+        recover: undefined,
+        retry: undefined,
+    };
+    const aggregate = {
+        branches: [],
+        commands: [],
+        failures: [],
+        result: { code: 1, killed: false, stderr: "", stdout: "" },
+    };
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const executed = await executeTemplateConfig(attemptConfig, inherited, params, exec, cwd, signal, stdin, isRoot, actorRecipeContext);
+        mergeExecution(aggregate, executed);
+        aggregate.result = executed.result;
+        aggregate.criticalFailure = executed.criticalFailure;
+        aggregate.failureScope = executed.failureScope;
+        if (executed.result.code === 0)
+            return aggregate;
+        addResultFailure(aggregate.failures, executed);
+        if (attempt === maxAttempts)
+            return aggregate;
+        if (normalized.recover === undefined)
+            continue;
+        const recovered = await executeTemplateConfig(getRecoverConfig(normalized.recover), inherited, params, exec, cwd, signal, executed.result.stdout, false, actorRecipeContext);
+        mergeExecution(aggregate, recovered);
+        if (recovered.result.code === 0)
+            continue;
+        addResultFailure(aggregate.failures, recovered);
+        aggregate.result = recovered.result;
+        aggregate.criticalFailure = recovered.criticalFailure;
+        aggregate.failureScope = maxFailureScope(recovered.failureScope, getFailureScope(normalized));
+        return aggregate;
+    }
+    return aggregate;
+}
+async function executeTemplateConfig(config, inherited, params, exec, cwd, signal, stdin, isRoot, inheritedActorRecipeContext) {
+    const normalized = CommandTemplates.normalizeCommandTemplateConfig(config);
+    const normalizedDefaults = CommandTemplates.resolveInheritedDefaultReferences(normalized.defaults, inherited.defaults, params);
+    const context = {
+        ...(inherited.args !== undefined ? { args: inherited.args } : {}),
+        ...(inherited.defaults !== undefined
+            ? { defaults: inherited.defaults }
+            : {}),
+        ...(normalized.args !== undefined ? { args: normalized.args } : {}),
+        ...(mergeDefaults(inherited.defaults, normalizedDefaults)
+            ? { defaults: mergeDefaults(inherited.defaults, normalizedDefaults) }
+            : {}),
+    };
+    const actorRecipeContext = normalized.actorRecipeContext ?? inheritedActorRecipeContext;
+    const controlValues = { ...(context.defaults ?? {}), ...params };
+    await applyDelay(normalized.delay, controlValues, signal);
+    if (!CommandTemplates.shouldRunCommandTemplateNode(normalized.when, controlValues)) {
+        return {
+            branches: [],
+            commands: [],
+            failures: [],
+            result: { code: 0, killed: false, stderr: "", stdout: stdin ?? "" },
+        };
+    }
+    getFailureScope(normalized);
+    if (normalized.repeat !== undefined) {
+        const repeat = CommandTemplates.resolveCommandTemplateRepeat(normalized.repeat, { ...(context.defaults ?? {}), ...params });
+        if (repeat === undefined)
+            throw new Error("Command template repeat could not be resolved.");
+        if (normalized.parallel === true)
+            assertParallelBranchLimit(repeat);
+        const repeatedSteps = Array.from({ length: repeat }, (_unused, index0) => {
+            const { repeat: _repeat, ...rest } = normalized;
+            return {
+                ...rest,
+                defaults: {
+                    ...(context.defaults ?? {}),
+                    ...(rest.defaults ?? {}),
+                    ...CommandTemplates.getCommandTemplateRepeatDefaults(index0, repeat),
+                },
+            };
+        });
+        return executeTemplateConfig({ parallel: normalized.parallel === true, template: repeatedSteps }, context, params, exec, cwd, signal, stdin, isRoot, actorRecipeContext);
+    }
+    if (normalized.retry !== undefined &&
+        (Array.isArray(normalized.template) || normalized.recover !== undefined)) {
+        return executeRetriableTemplateConfig(normalized, context, params, exec, cwd, signal, stdin, isRoot, actorRecipeContext);
+    }
+    if (normalized.template &&
+        typeof normalized.template === "object" &&
+        !Array.isArray(normalized.template)) {
+        return executeTemplateConfig(normalized.template, context, params, exec, cwd, signal, stdin, false, actorRecipeContext);
+    }
+    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, {
+            ...(actorRecipeContext ? { actorRecipeContext } : {}),
+            cwd,
+            signal,
+            stdin,
+            ...(resolveNumericControlField(normalized.timeout, controlValues, "timeout") !== undefined
+                ? {
+                    timeout: resolveNumericControlField(normalized.timeout, controlValues, "timeout"),
+                }
+                : {}),
+            ...(normalized.retry !== undefined
+                ? { retry: normalizeRetry(normalized.retry, controlValues) }
+                : {}),
+        });
+        return {
+            branches: [],
+            commands: [formatInvocationDetail(invocation)],
+            failures: [],
+            result,
+        };
+    }
+    const steps = normalized.template;
+    if (steps.length === 0)
+        throw new Error(formatToolText("Tool template produced no command steps."));
+    if (normalized.parallel === true) {
+        assertParallelBranchLimit(steps.length);
+        const branchResults = await Promise.all(steps.map((step) => executeTemplateConfig(step, context, params, exec, cwd, signal, stdin, false, actorRecipeContext)));
+        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));
+        const nodeFailure = getFailureScope(normalized);
+        const rootFailure = branchResults.find((item, index) => {
+            if (item.result.code === 0)
+                return false;
+            const branchFailure = maxFailureScope(item.failureScope, item.criticalFailure ? "root" : undefined, getFailureScope(steps[index]), nodeFailure);
+            return branchFailure === "root";
+        });
+        if (rootFailure) {
+            return {
+                branches: [
+                    ...branchResults.flatMap((item) => item.branches),
+                    ...branches,
+                ],
+                commands,
+                criticalFailure: true,
+                failureScope: "root",
+                failures,
+                result: rootFailure.result,
+            };
+        }
+        const firstFailedBranch = branchResults.find((item) => item.result.code !== 0);
+        const successful = branchResults.map((item) => {
+            if (item.result.code === 0)
+                return item.result;
+            addResultFailure(failures, item);
+            return { ...item.result, code: 0, stdout: "" };
+        });
+        const result = {
+            code: 0,
+            killed: successful.some((item) => item.killed),
+            stderr: successful
+                .map((item) => item.stderr)
+                .filter(Boolean)
+                .join("\n"),
+            stdout: joinParallelStdout(branches, successful),
+        };
+        if (firstFailedBranch && nodeFailure === "branch") {
+            return {
+                commands,
+                branches: [
+                    ...branchResults.flatMap((item) => item.branches),
+                    ...branches,
+                ],
+                failureScope: "branch",
+                failures,
+                result: { ...result, code: firstFailedBranch.result.code || 1 },
+            };
+        }
+        return {
+            commands,
+            branches: [
+                ...branchResults.flatMap((item) => item.branches),
+                ...branches,
+            ],
+            failures,
+            result,
+        };
+    }
+    const branches = [];
+    const commands = [];
+    const failures = [];
+    let nextStdin = stdin;
+    let result;
+    for (const step of steps) {
+        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;
+        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") {
+                return {
+                    branches,
+                    commands,
+                    criticalFailure: true,
+                    failureScope: "root",
+                    failures,
+                    result,
+                };
+            }
+            if (failureScope === "branch") {
+                addResultFailure(failures, executed);
+                return {
+                    branches,
+                    commands,
+                    failureScope: "branch",
+                    failures,
+                    result,
+                };
+            }
+            addResultFailure(failures, executed);
+            result = { ...result, code: 0, stdout: "" };
+            nextStdin = "";
+            continue;
+        }
+        nextStdin = result.stdout;
+    }
+    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);
+}
+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);
+    const result = executed.result;
+    if (result.code !== 0) {
+        const formatted = formatFailureOutput(cfg.name, result.code, result.killed, result.stdout, result.stderr);
+        throw new Error(formatted.text);
+    }
+    const formatted = formatOutput(cfg.name, "stdout", result.stdout);
+    const templateWarnings = CommandTemplates.getCommandTemplateWarnings(createTemplateConfig(cfg));
+    return {
+        content: [textContent(formatted.text)],
+        details: {
+            code: result.code,
+            command,
+            fullOutputPath: formatted.fullOutputPath,
+            killed: result.killed,
+            ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
+            ...(executed.failures.length > 0
+                ? { nonCriticalFailures: executed.failures }
+                : {}),
+            ...(createSoftQuorum(executed.branches)
+                ? { softQuorum: createSoftQuorum(executed.branches) }
+                : {}),
+            template: cfg.template,
+            ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
+            tool: cfg.name,
+            truncated: formatted.truncated,
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * File state persistence helpers
+ * 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 writeJsonAtomic(path: string, value: unknown): void;

package/dist/lib/file-state.js

@@ -0,0 +1,25 @@
+/**
+ * File state persistence helpers
+ * 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";
+export function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        renameSync(tempPath, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            /* best effort */
+        }
+        throw error;
+    }
+}

package/dist/lib/identity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Identifier normalization helpers
+ * Zones: registry identity, shared validation
+ * Owns stable tool, argument, and file-label identifier normalization
+ */
+export declare function normalizeIdentifier(value: string, prefix: string): string;
+export declare function normalizeToolName(value: string): string;
+export declare function normalizeArgName(value: string): string;
+export declare function sanitizeFilePart(value: string): string;

package/dist/lib/identity.js

@@ -0,0 +1,27 @@
+/**
+ * Identifier normalization helpers
+ * Zones: registry identity, shared validation
+ * Owns stable tool, argument, and file-label identifier normalization
+ */
+export function normalizeIdentifier(value, prefix) {
+    let name = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!name)
+        return "";
+    if (/^[0-9]/.test(name))
+        name = `${prefix}_${name}`;
+    return name.slice(0, 64).replace(/_+$/g, "");
+}
+export function normalizeToolName(value) {
+    return normalizeIdentifier(value, "tool");
+}
+export function normalizeArgName(value) {
+    return normalizeIdentifier(value, "arg");
+}
+export function sanitizeFilePart(value) {
+    return normalizeIdentifier(value, "tool") || "tool";
+}

package/dist/lib/observability.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Async run observability helpers
+ * Zones: async runtime, ambient UI, diagnostics
+ * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
+ */
+import * as AsyncRuns from "./async-runs.ts";
+export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+export type RunOutboxDelivery = "log" | "notify" | "followup";
+export type RunOutboxLevel = "info" | "warning" | "error";
+export interface RunObservation {
+    activeSubagents?: number;
+    completed?: number;
+    descendantSubagents?: number;
+    failures?: number;
+    ownerId?: string;
+    artifacts?: Record<string, string>;
+    launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    recipeFile?: string;
+    terminalHandled?: boolean;
+    retireWhen?: string;
+    run: string;
+    tool?: string;
+    stateDir?: string;
+    status: RunObservedStatus;
+    updatedAt?: string;
+}
+export interface RunSummary {
+    cancelled: number;
+    done: number;
+    exited: number;
+    failed: number;
+    killed: number;
+    running: number;
+    runningSubagents: number;
+    runs: RunObservation[];
+    total: number;
+}
+export interface RunRetirementCandidate {
+    activeSubagents: number;
+    descendantSubagents: number;
+    run: string;
+    stateDir: string;
+}
+export interface RunTransition {
+    from: RunObservedStatus;
+    run: string;
+    stateDir?: string;
+    artifacts?: Record<string, string>;
+    launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    recipeFile?: string;
+    terminalHandled?: boolean;
+    to: RunObservedStatus;
+    tool?: string;
+}
+export interface RunOutboxEvent {
+    body?: unknown;
+    data?: unknown;
+    delivery: RunOutboxDelivery;
+    event: string;
+    id: string;
+    level: RunOutboxLevel;
+    metadata?: Record<string, unknown>;
+    run: string;
+    stateDir: string;
+    summary: string;
+    ts: string;
+}
+export type RunTransitionNotificationType = "info" | "warning" | "error";
+export declare function summarizeRuns(stateRoot?: string, ownerId?: string): RunSummary;
+export declare function countRunningSubagentsByRun(stateRoot?: string, ownerId?: string): Map<string, number>;
+export declare function countRunningSubagents(stateRoot?: string, ownerId?: string): number;
+export declare function renderSubagentStatus(count: number, frame?: number): string | undefined;
+export declare function renderRunStatus(summary: RunSummary, frame?: number): string | undefined;
+export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
+export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
+export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>): void;
+export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary): RunOutboxEvent[];
+export declare function getRunOutboxNotificationType(event: RunOutboxEvent): RunTransitionNotificationType;
+export declare function shouldNotifyRunOutboxEvent(event: RunOutboxEvent): boolean;
+export declare function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean;
+export declare function formatRunOutboxMessage(event: RunOutboxEvent): string;
+export declare function getRunTransitionNotificationType(transition: RunTransition): RunTransitionNotificationType;
+export declare function shouldNotifyRunTransition(transition: RunTransition): boolean;
+export declare function shouldSendRunTransitionFollowUp(transition: RunTransition): boolean;
+export declare function shouldSuggestRecipePersistence(transition: RunTransition): boolean;
+export declare function formatRunTransitionMessage(transition: RunTransition): string;