pi-extensible-workflows 1.0.1 → 3.0.0

package/dist/src/herdr.d.ts

@@ -0,0 +1,12 @@
+export type HerdrPaneAction = "inspect" | "transcript" | "fork";
+export interface HerdrPaneRequest {
+    action: HerdrPaneAction;
+    cwd: string;
+    sessionId?: string;
+    original?: string;
+    readOnly?: boolean;
+}
+export type HerdrCommandRunner = (args: readonly string[]) => Promise<string>;
+export declare function herdrPaneId(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function herdrPaneCommand(request: HerdrPaneRequest): string;
+export declare function openHerdrPane(request: HerdrPaneRequest, runner?: HerdrCommandRunner): Promise<string>;

package/dist/src/herdr.js

@@ -0,0 +1,74 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const runHerdr = (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;
+}
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+function json(value) { return JSON.parse(value); }
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(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 cliPath = fileURLToPath(new URL("./cli.js", import.meta.resolve("pi-extensible-workflows")));
+    const environment = ["PI_CODING_AGENT_DIR", "PI_CODING_AGENT_SESSION_DIR"].flatMap((name) => process.env[name] === undefined ? [] : [`${name}=${shellQuote(process.env[name] ?? "")}`]);
+    const command = request.action === "inspect"
+        ? [shellQuote(process.execPath), shellQuote(cliPath), "inspect", shellQuote(request.sessionId ?? "")]
+        : request.action === "transcript"
+            ? [shellQuote(process.execPath), shellQuote(cliPath), "transcript", shellQuote(request.original ?? "")]
+            : ["pi", "--fork", shellQuote(request.original ?? ""), ...(request.readOnly ? ["--tools", shellQuote("read,grep,find,ls")] : [])];
+    return `cd ${shellQuote(request.cwd)} && ${environment.length ? `${environment.join(" ")} ` : ""}${command.join(" ")}`;
+}
+export function herdrPaneCommand(request) { return commandFor(request); }
+export async function openHerdrPane(request, runner = runHerdr) {
+    const targetPane = 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.action === "inspect" && !request.sessionId) || (request.action !== "inspect" && !request.original))
+        throw new Error("Pane action is missing its session source.");
+    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;
+    }
+}

package/dist/src/host.d.ts

@@ -0,0 +1,62 @@
+import { Type } from "@earendil-works/pi-ai";
+import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type SessionFactory } from "./agent-execution.js";
+import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
+import { type LaunchSnapshot, type RunState, type WorkflowFailureDiagnostics } from "./types.js";
+export interface WorkflowProgressStyles {
+    accent(text: string): string;
+    success(text: string): string;
+    error(text: string): string;
+    warning(text: string): string;
+    muted(text: string): string;
+    dim(text: string): string;
+    bold(text: string): string;
+}
+export declare function formatWorkflowFailure(error: unknown): string;
+export declare class RunLifecycle {
+    #private;
+    private readonly changed?;
+    constructor(state?: RunState, changed?: ((state: RunState, previousState: RunState, reason?: string) => void | Promise<void>) | undefined);
+    get state(): RunState;
+    enter(): Promise<void>;
+    leave(): Promise<void>;
+    enterAwaitingInput(): Promise<void>;
+    resolveAwaitingInput(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    providerPause(): Promise<void>;
+    terminal(state: "completed" | "failed" | "stopped" | "interrupted" | "budget_exhausted", reason?: string): Promise<void>;
+}
+export declare function formatWorkflowPreview(args: {
+    script?: unknown;
+    workflow?: unknown;
+    name?: unknown;
+    description?: unknown;
+}): string;
+export declare const WORKFLOW_TOOL_LABEL = "Workflow";
+export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow";
+export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline launches require an explicit non-empty name; registered function launches reject name and use workflow as the run name. Runs in the background by default; completion arrives as a follow-up message. Foreground results include the completed run ID. Use workflow_retry with an explicit failed run ID to replay completed structural operations; parentRunId only reuses named worktrees.";
+export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
+    name: Type.TOptional<Type.TString>;
+    description: Type.TOptional<Type.TString>;
+    script: Type.TOptional<Type.TString>;
+    workflow: Type.TOptional<Type.TString>;
+    args: Type.TOptional<Type.TUnknown>;
+    foreground: Type.TOptional<Type.TBoolean>;
+    concurrency: Type.TOptional<Type.TInteger>;
+    budget: Type.TOptional<Type.TUnknown>;
+    parentRunId: Type.TOptional<Type.TString>;
+}>;
+export declare const WORKFLOW_RETRY_PARAMETERS: Type.TObject<{
+    runId: Type.TString;
+}>;
+export declare function formatWorkflowProgress(run: PersistedRun, spinner?: string, styles?: WorkflowProgressStyles): string;
+export declare function truncateWorkflowProgress(text: string, width: number): string[];
+export declare function formatBudgetStatus(run: Pick<PersistedRun, "budget" | "budgetVersion" | "usage" | "budgetEvents">): string[];
+export declare function formatNavigatorDashboard(run: PersistedRun, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
+export declare function formatNavigatorRun(loaded: {
+    run: PersistedRun;
+    snapshot: Readonly<LaunchSnapshot>;
+}, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string;
+export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
+export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory, agentDir?: string): void;