@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/dist/src/herdr.d.ts

@@ -0,0 +1,53 @@
+export type HerdrPaneAction = "live";
+export type HerdrAgentState = "idle" | "working" | "blocked" | "unknown";
+export type HerdrAgentStatus = HerdrAgentState | "done";
+export interface HerdrPaneStatus {
+    state: HerdrAgentStatus;
+}
+export interface HerdrPaneRequest {
+    action: HerdrPaneAction;
+    cwd: string;
+    command: string;
+    paneId?: string;
+}
+export interface HerdrWorkspacePaneRequest {
+    cwd: string;
+    workspaceLabel?: string;
+    workspaceId?: string;
+    tabLabel: string;
+    command: string;
+}
+export interface HerdrWorkspacePane {
+    workspaceId: string;
+    tabId: string;
+    paneId: string;
+}
+export type HerdrCommandRunner = (args: readonly string[]) => Promise<string>;
+export declare const herdrCommandRunner: HerdrCommandRunner;
+export declare function herdrPaneId(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function herdrAvailable(env?: NodeJS.ProcessEnv): boolean;
+export declare function herdrPaneCommand(request: HerdrPaneRequest): string;
+export declare function openHerdrPane(request: HerdrPaneRequest, runner?: HerdrCommandRunner): Promise<string>;
+export declare function openHerdrWorkspacePane(request: HerdrWorkspacePaneRequest, runner?: HerdrCommandRunner): Promise<HerdrWorkspacePane>;
+export declare function openHerdrLivePane(request: HerdrPaneRequest | HerdrWorkspacePaneRequest, runner?: HerdrCommandRunner): Promise<string | HerdrWorkspacePane>;
+export declare function waitForHerdrPane(paneId: string, runner?: HerdrCommandRunner, options?: {
+    signal?: AbortSignal;
+    settled?: Promise<void>;
+    intervalMs?: number;
+    startupTimeoutMs?: number;
+    exitGraceMs?: number;
+    originatingEntrypoint?: string;
+    onStatus?: (state: HerdrAgentStatus) => void | Promise<void>;
+}): Promise<"closed" | "exited" | "idle" | "settled" | "aborted">;
+export interface HerdrAgentReporter {
+    reportSession(session: {
+        sessionId?: string;
+        sessionPath?: string;
+    }, sessionStartSource?: string): Promise<void>;
+    reportState(state: HerdrAgentState, message?: string, session?: {
+        sessionId?: string;
+        sessionPath?: string;
+    }): Promise<void>;
+    release(): Promise<void>;
+}
+export declare function createHerdrAgentReporter(paneId: string, agent: string, runner?: HerdrCommandRunner): HerdrAgentReporter;

package/dist/src/herdr.js

@@ -0,0 +1,270 @@
+import { execFile } from "node:child_process";
+import { isObject } from "./utils.js";
+export const herdrCommandRunner = (args) => new Promise((resolve, reject) => {
+    execFile("herdr", [...args], { encoding: "utf8", maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        if (error) {
+            reject(new Error(error.message));
+            return;
+        }
+        resolve(stdout);
+    });
+});
+export function herdrPaneId(env = process.env) {
+    if (env.HERDR_ENV !== "1")
+        return undefined;
+    const paneId = env.HERDR_PANE_ID?.trim();
+    return paneId || undefined;
+}
+export function herdrAvailable(env = process.env) { return Boolean(herdrPaneId(env) && env.HERDR_SOCKET_PATH); }
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+function json(value) { return JSON.parse(value); }
+function record(value) { return isObject(value) ? value : undefined; }
+function paneLayout(value, targetPane) {
+    const root = record(value);
+    const result = record(root?.result);
+    const layout = record(result?.layout);
+    const rawPanes = layout?.panes;
+    if (!Array.isArray(rawPanes))
+        throw new Error("Herdr returned an invalid pane layout.");
+    const panes = rawPanes;
+    const pane = panes.find((candidate) => record(candidate)?.pane_id === targetPane);
+    const rect = record(record(pane)?.rect);
+    const width = rect?.width;
+    const height = rect?.height;
+    if (width === undefined || height === undefined || typeof width !== "number" || typeof height !== "number")
+        throw new Error("Herdr returned an invalid target pane geometry.");
+    return { width, height };
+}
+function splitPaneId(value) {
+    const pane = record(record(record(value)?.result)?.pane);
+    const paneId = pane?.pane_id;
+    if (typeof paneId !== "string" || !paneId)
+        throw new Error("Herdr returned an invalid created pane ID.");
+    return paneId;
+}
+function commandFor(request) {
+    const environment = ["PI_CODING_AGENT_DIR", "PI_CODING_AGENT_SESSION_DIR"].flatMap((name) => process.env[name] === undefined ? [] : [`${name}=${shellQuote(process.env[name] ?? "")}`]);
+    return `cd ${shellQuote(request.cwd)} && ${environment.length ? `${environment.join(" ")} ` : ""}${request.command}`;
+}
+export function herdrPaneCommand(request) { return commandFor(request); }
+export async function openHerdrPane(request, runner = herdrCommandRunner) {
+    const targetPane = request.paneId ?? herdrPaneId();
+    if (!targetPane)
+        throw new Error("Pane actions require a Herdr-managed session with HERDR_PANE_ID.");
+    if (!request.cwd)
+        throw new Error("Pane actions require a working directory.");
+    if (!request.command)
+        throw new Error("Pane action is missing its command.");
+    const layout = paneLayout(json(await runner(["pane", "layout", "--pane", targetPane])), targetPane);
+    const direction = layout.width > layout.height ? "right" : "down";
+    const paneId = splitPaneId(json(await runner(["pane", "split", targetPane, "--direction", direction, "--no-focus"])));
+    try {
+        await runner(["pane", "run", paneId, commandFor(request)]);
+        return paneId;
+    }
+    catch (error) {
+        await runner(["pane", "close", paneId]).catch(() => undefined);
+        throw error;
+    }
+}
+function resourceId(value, resource, field) {
+    const result = record(record(value)?.result);
+    const item = record(result?.[resource]);
+    const id = item?.[field];
+    if (typeof id !== "string" || !id)
+        throw new Error(`Herdr returned an invalid ${resource} ID.`);
+    return id;
+}
+export async function openHerdrWorkspacePane(request, runner = herdrCommandRunner) {
+    if (!request.cwd || !request.tabLabel || !request.command || !request.workspaceId && !request.workspaceLabel)
+        throw new Error("Herdr workspace pane is missing required data.");
+    const created = json(await runner(request.workspaceId
+        ? ["tab", "create", "--workspace", request.workspaceId, "--cwd", request.cwd, "--label", request.tabLabel, "--no-focus"]
+        : ["workspace", "create", "--cwd", request.cwd, "--label", request.workspaceLabel ?? "", "--no-focus"]));
+    const workspaceId = request.workspaceId ?? resourceId(created, "workspace", "workspace_id");
+    let tabId = resourceId(created, "tab", "tab_id");
+    let paneId = resourceId(created, "root_pane", "pane_id");
+    try {
+        if (!request.workspaceId) {
+            await runner(["tab", "rename", tabId, request.workspaceLabel ?? ""]);
+            const tab = json(await runner(["tab", "create", "--workspace", workspaceId, "--cwd", request.cwd, "--label", request.tabLabel, "--no-focus"]));
+            tabId = resourceId(tab, "tab", "tab_id");
+            paneId = resourceId(tab, "root_pane", "pane_id");
+        }
+        await runner(["pane", "run", paneId, commandFor({ action: "live", cwd: request.cwd, command: request.command })]);
+        return { workspaceId, tabId, paneId };
+    }
+    catch (error) {
+        await runner(request.workspaceId ? ["tab", "close", tabId] : ["workspace", "close", workspaceId]).catch(() => undefined);
+        throw error;
+    }
+}
+export async function openHerdrLivePane(request, runner = herdrCommandRunner) {
+    if ("workspaceLabel" in request || "workspaceId" in request)
+        return openHerdrWorkspacePane(request, runner);
+    return openHerdrPane({ ...request, action: "live" }, runner);
+}
+function hasPiProcess(value, originatingEntrypoint) {
+    const result = record(record(value)?.result);
+    const info = record(result?.process_info);
+    const processes = info?.foreground_processes;
+    if (!Array.isArray(processes))
+        return false;
+    return processes.some((candidate) => {
+        const process = record(candidate);
+        const name = process?.name;
+        const argv0 = process?.argv0;
+        const argv = process?.argv;
+        const commandLine = process?.cmdline;
+        if (originatingEntrypoint) {
+            if (Array.isArray(argv) && argv.some((value) => value === originatingEntrypoint) || typeof commandLine === "string" && commandLine.includes(originatingEntrypoint))
+                return true;
+            return name === "pi" || argv0 === "pi" || Array.isArray(argv) && argv[0] === "pi";
+        }
+        return name === "pi" || argv0 === "pi" || Array.isArray(argv) && argv[0] === "pi" || typeof commandLine === "string" && commandLine.includes("/bin/pi");
+    });
+}
+function isHerdrStatus(value) { return value === "idle" || value === "working" || value === "blocked" || value === "unknown" || value === "done"; }
+function herdrAgentStatus(value) {
+    const result = record(record(value)?.result);
+    const agent = record(result?.agent);
+    const rawState = agent?.agent_status;
+    if (typeof rawState !== "string")
+        return undefined;
+    const state = isHerdrStatus(rawState) ? rawState : "unknown";
+    return { state };
+}
+export async function waitForHerdrPane(paneId, runner = herdrCommandRunner, options = {}) {
+    const intervalMs = options.intervalMs ?? 250;
+    const startupTimeoutMs = options.startupTimeoutMs ?? 10000;
+    const exitGraceMs = options.exitGraceMs ?? 5000;
+    const startedAt = Date.now();
+    const monitorController = new AbortController();
+    const isAborted = () => monitorController.signal.aborted;
+    let markAborted = () => { };
+    const aborted = new Promise((resolve) => { markAborted = () => { resolve("aborted"); }; });
+    const abortMonitor = () => { monitorController.abort(); markAborted(); };
+    if (options.signal?.aborted)
+        abortMonitor();
+    else
+        options.signal?.addEventListener("abort", abortMonitor, { once: true });
+    const delay = () => new Promise((resolve) => {
+        if (isAborted()) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(finish, intervalMs);
+        function finish() { clearTimeout(timer); monitorController.signal.removeEventListener("abort", finish); resolve(); }
+        monitorController.signal.addEventListener("abort", finish, { once: true });
+    });
+    const poll = async () => {
+        let sawPi = false;
+        let sawWorking = false;
+        let missingSince;
+        for (;;) {
+            if (isAborted())
+                return "aborted";
+            let piRunning;
+            try {
+                const output = await runner(["pane", "process-info", "--pane", paneId]);
+                if (isAborted())
+                    return "aborted";
+                piRunning = hasPiProcess(json(output), options.originatingEntrypoint);
+            }
+            catch {
+                if (isAborted())
+                    return "aborted";
+                return "closed";
+            }
+            if (!piRunning) {
+                if (sawPi) {
+                    missingSince ??= Date.now();
+                    if (Date.now() - missingSince >= exitGraceMs)
+                        return "exited";
+                }
+            }
+            else {
+                missingSince = undefined;
+                if (!sawPi) {
+                    sawPi = true;
+                }
+                try {
+                    const output = await runner(["agent", "get", paneId]);
+                    if (isAborted())
+                        return "aborted";
+                    const status = herdrAgentStatus(json(output));
+                    if (status) {
+                        if (status.state === "working")
+                            sawWorking = true;
+                        const shouldHandBack = options.settled === undefined && sawWorking && (status.state === "idle" || status.state === "done");
+                        try {
+                            await options.onStatus?.(status.state);
+                        }
+                        catch { /* Status notifications must not suppress pane handback. */ }
+                        if (isAborted())
+                            return "aborted";
+                        if (shouldHandBack)
+                            return "idle";
+                    }
+                }
+                catch {
+                    if (isAborted())
+                        return "aborted";
+                    /* The process monitor remains authoritative when no agent report is available. */
+                }
+            }
+            if (!piRunning && !sawPi && Date.now() - startedAt >= startupTimeoutMs)
+                throw new Error("Herdr pane did not start Pi.");
+            await delay();
+        }
+    };
+    const polling = poll();
+    try {
+        const result = await Promise.race(options.settled ? [polling, aborted, options.settled.then(() => "settled")] : [polling, aborted]);
+        if (result === "settled" || result === "aborted")
+            monitorController.abort();
+        return result;
+    }
+    finally {
+        monitorController.abort();
+        options.signal?.removeEventListener("abort", abortMonitor);
+    }
+}
+export function createHerdrAgentReporter(paneId, agent, runner = herdrCommandRunner) {
+    const source = "herdr:pi-extensible-workflows";
+    let sequence = Date.now() * 1000;
+    let released = false;
+    let queue = Promise.resolve();
+    const next = () => ++sequence;
+    const sessionArgs = (session) => session?.sessionPath ? ["--agent-session-path", session.sessionPath] : session?.sessionId ? ["--agent-session-id", session.sessionId] : [];
+    const retry = async (operation) => {
+        try {
+            await operation();
+        }
+        catch {
+            try {
+                await operation();
+            }
+            catch { /* Herdr reporting must not stop the Pi session. */ }
+        }
+    };
+    const enqueue = (operation) => {
+        const result = queue.then(operation);
+        queue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    return {
+        async reportSession(session, sessionStartSource) {
+            await enqueue(() => retry(() => runner(["pane", "report-agent-session", paneId, "--source", source, "--agent", agent, "--seq", String(next()), ...(sessionStartSource ? ["--session-start-source", sessionStartSource] : []), ...sessionArgs(session)])));
+        },
+        async reportState(state, message, session) {
+            await enqueue(() => retry(() => runner(["pane", "report-agent", paneId, "--source", source, "--agent", agent, "--state", state, "--seq", String(next()), ...(message ? ["--message", message] : []), ...sessionArgs(session)])));
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await enqueue(() => retry(() => runner(["pane", "release-agent", paneId, "--source", source, "--agent", agent, "--seq", String(next())])));
+        },
+    };
+}

package/dist/src/host-delivery.d.ts

@@ -0,0 +1,95 @@
+import { type PersistedRun, type RunStore } from "./persistence.js";
+import { WorkflowError, type JsonValue, type WorkflowFailureDiagnostics, type WorkflowMetadata } from "./types.js";
+import { SerialLane } from "./utils.js";
+export type ForegroundDetachResult = {
+    runId: string;
+    state: "running";
+    detached: true;
+    run: PersistedRun;
+};
+export type ForegroundDelivery = {
+    store: RunStore;
+    detached: boolean;
+    detach: () => Promise<ForegroundDetachResult>;
+};
+export type PendingFailureDiagnostic = {
+    diagnostic: WorkflowFailureDiagnostics;
+    store: RunStore;
+};
+type ForegroundDeliveryControllerOptions = {
+    runs: ReadonlyMap<string, {
+        store: RunStore;
+    }>;
+    deliver?: (content: string) => void;
+};
+export declare class ForegroundDeliveryController {
+    private readonly options;
+    readonly foregroundDeliveries: Map<string, ForegroundDelivery>;
+    readonly pendingFailureDiagnostics: Map<string, PendingFailureDiagnostic>;
+    readonly foregroundResumeClaims: WeakSet<RunStore>;
+    readonly terminalDeliveryLanes: WeakMap<RunStore, SerialLane>;
+    constructor(options: ForegroundDeliveryControllerOptions);
+    claimForegroundDelivery: (store: RunStore, toolCallId: string) => Promise<"claimed" | "delivered" | "detached">;
+    deliverTerminal: (store: RunStore, content: string | (() => string | Promise<string>), failure?: boolean) => Promise<void>;
+    foregroundDeliveryCandidates: (runId: string) => Array<[string, ForegroundDelivery]>;
+    moveForegroundToBackground: (runId: string) => Promise<ForegroundDetachResult>;
+    isForegroundAttached: (runId: string) => boolean;
+    deliverDetachedTerminal: (toolCallId: string, content: string | (() => string | Promise<string>), failure?: boolean) => Promise<void>;
+}
+export declare function markWorkflowFailureDiagnostics(error: WorkflowError, diagnostic: WorkflowFailureDiagnostics): void;
+export declare function formatWorkflowFailure(error: unknown): string;
+export declare function workflowFailedAt(error: unknown): string | undefined;
+export declare const DELIVERY_LIMIT_BYTES: number;
+export declare const WORKFLOW_LOG_ENTRY = "workflow-log";
+export interface WorkflowLogEntry {
+    workflowName: string;
+    message: string;
+}
+export interface CompletionContextUsage {
+    tokens: number | null;
+    contextWindow: number;
+}
+export interface CompletionDeliveryModel {
+    contextWindow?: number;
+    maxTokens?: number;
+}
+export interface CompletionDeliveryContext {
+    getContextUsage?: () => CompletionContextUsage | undefined;
+    getModel?: () => CompletionDeliveryModel | undefined;
+    model?: CompletionDeliveryModel;
+}
+export interface CompletionDeliveryOptions {
+    mode: "foreground" | "background";
+    name: string;
+    runId: string;
+    value: JsonValue;
+    resultPath: string;
+    resultBytes: number;
+    worktrees: readonly {
+        branch: string;
+        path: string;
+    }[];
+    context?: CompletionDeliveryContext;
+}
+export interface CompletionDeliveryStoreOptions extends Omit<CompletionDeliveryOptions, "worktrees"> {
+    store: Pick<RunStore, "changedWorktrees">;
+}
+export interface CompletionDeliveryResult {
+    content: string;
+    inlined: boolean;
+}
+export declare function completionDescriptor(options: Pick<CompletionDeliveryOptions, "runId" | "resultBytes"> & {
+    resultPath?: string;
+}): string;
+export declare function completionDelivery(options: CompletionDeliveryOptions): CompletionDeliveryResult;
+export declare function completionDeliveryFromStore(options: CompletionDeliveryStoreOptions): Promise<CompletionDeliveryResult>;
+export declare function utf8Prefix(value: string, maxBytes: number): string;
+export declare function failureDiagnosticsFrom(error: unknown): WorkflowFailureDiagnostics | undefined;
+export declare function incompleteRetryPaths(paths: readonly string[], completedPaths: readonly string[]): string[];
+export declare function createWorkflowFailureDiagnostics(store: RunStore, metadata: WorkflowMetadata, error: unknown, run: PersistedRun): Promise<WorkflowFailureDiagnostics>;
+export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
+export declare function formatWorkflowFailureDelivery(diagnostic: WorkflowFailureDiagnostics): string;
+export declare function formatWorkflowFailureDeliveryFallback(workflowName: string, runId: string, runDirectory: string, error: unknown, retryable?: boolean): string;
+export declare function serializeWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
+export declare function isWorkflowFailureDiagnostics(value: unknown): value is WorkflowFailureDiagnostics;
+export {};