pi-extensible-workflows 1.0.0 → 2.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/index.d.ts

@@ -5,8 +5,8 @@ import { RunStore } from "./persistence.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
 export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export declare const AGENT_STATES: readonly ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
-export declare const WORKFLOW_ASYNC_STARTED_EVENT = "workflow:async-started";
-export declare const WORKFLOW_ASYNC_COMPLETE_EVENT = "workflow:async-complete";
+export declare const WORKFLOW_CALL_KINDS: readonly ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
+export type WorkflowCallKind = (typeof WORKFLOW_CALL_KINDS)[number];
 export declare const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
 export declare const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
 export declare const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
@@ -17,7 +17,7 @@ export declare const WORKFLOW_PHASE_CHANGED_EVENT = "workflow:phase-changed";
 export declare const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpoint-state-changed";
 export declare const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
 export declare const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
-export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
+export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
 export type RunState = (typeof RUN_STATES)[number];
 export type AgentState = (typeof AGENT_STATES)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
@@ -27,6 +27,15 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
 export type JsonSchema = {
     [key: string]: JsonValue;
 };
+export interface ShellOptions {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+export interface ShellResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
 export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
 export interface BudgetLimits {
     soft?: number;
@@ -184,6 +193,10 @@ export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase {
     path: string;
     base: string;
 }
+export interface WorkflowWorktreeReference {
+    readonly path: string;
+    readonly branch: string;
+}
 export interface AgentRecord {
     id: string;
     name: string;
@@ -215,7 +228,7 @@ export interface AgentRecord {
     activity?: AgentActivity | undefined;
 }
 export interface WorkflowRunEvent {
-    type: "warning";
+    type: string;
     message: string;
 }
 export interface RunRecord {
@@ -224,6 +237,7 @@ export interface RunRecord {
     cwd: string;
     sessionId: string;
     state: RunState;
+    parentRunId?: string;
     phase?: string;
     agents: readonly AgentRecord[];
     error?: WorkflowErrorShape;
@@ -233,9 +247,11 @@ export interface RunRecord {
     budgetEvents?: readonly BudgetEvent[];
     events?: readonly WorkflowRunEvent[];
 }
-export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
+export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 4;
 export interface LaunchSnapshot {
     identityVersion?: number;
+    launchKind?: "inline" | "function";
+    functionName?: string;
     script: string;
     args: JsonValue;
     metadata: WorkflowMetadata;
@@ -272,10 +288,14 @@ export interface PreflightResult {
 }
 export interface WorkflowOrchestrationContext {
     agent: (...args: readonly unknown[]) => Promise<JsonValue>;
+    shell: (command: string, options?: ShellOptions) => Promise<ShellResult>;
     prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string;
     parallel: (...args: readonly unknown[]) => Promise<JsonValue>;
     pipeline: (...args: readonly unknown[]) => Promise<JsonValue>;
-    withWorktree: (...args: readonly unknown[]) => Promise<JsonValue>;
+    withWorktree: {
+        (callback: WorkflowWorktreeCallback): Promise<JsonValue>;
+        (name: string, callback: WorkflowWorktreeCallback): Promise<JsonValue>;
+    };
     checkpoint: (...args: readonly unknown[]) => Promise<boolean>;
     phase: (name: string) => void;
     log: (message: string) => void;
@@ -290,7 +310,9 @@ export interface WorkflowRunContext {
 }
 export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
     run: Readonly<WorkflowRunContext>;
+    invoke: (name: string, input: Readonly<Record<string, JsonValue>>) => Promise<JsonValue>;
 }
+export type WorkflowWorktreeCallback = (reference: Readonly<WorkflowWorktreeReference>) => JsonValue | Promise<JsonValue>;
 export interface WorkflowFunction {
     description: string;
     input: JsonSchema;
@@ -302,17 +324,12 @@ export interface WorkflowVariable {
     schema: JsonSchema;
     resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue;
 }
-export interface WorkflowScriptDefinition {
-    description: string;
-    script: string;
-}
 export interface WorkflowExtension {
     version: string;
     headline: string;
     description: string;
     functions?: Readonly<Record<string, WorkflowFunction>>;
     variables?: Readonly<Record<string, WorkflowVariable>>;
-    workflows?: Readonly<Record<string, WorkflowScriptDefinition>>;
     agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
 }
 export interface WorkflowJournal {
@@ -323,6 +340,36 @@ export declare class WorkflowError extends Error {
     readonly code: WorkflowErrorCode;
     constructor(code: WorkflowErrorCode, message: string);
 }
+export interface WorkflowFailureAgent {
+    id: string;
+    label?: string;
+    role?: string;
+    structuralPath: readonly string[];
+    attempt: number;
+    sessionId?: string;
+    sessionFile?: string;
+}
+export interface WorkflowSiblingAgent {
+    id: string;
+    label?: string;
+    role?: string;
+    structuralPath: readonly string[];
+}
+export interface WorkflowFailureDiagnostics {
+    runId: string;
+    workflowName: string;
+    state: RunState;
+    failedAt: string | null;
+    error: WorkflowErrorShape;
+    failedAgent?: WorkflowFailureAgent;
+    completedSiblingAgents?: readonly WorkflowSiblingAgent[];
+    completedSiblingPaths: readonly (readonly string[])[];
+    artifacts: {
+        runDirectory: string;
+        statePath: string;
+        journalPath: string;
+    };
+}
 export declare function formatWorkflowFailure(error: unknown): string;
 export declare class RunLifecycle {
     #private;
@@ -339,6 +386,8 @@ export declare class RunLifecycle {
     terminal(state: "completed" | "failed" | "stopped" | "interrupted" | "budget_exhausted", reason?: string): Promise<void>;
 }
 export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
+declare function object(value: unknown): value is Record<string, unknown>;
+export { object as isObject };
 export declare function validateBudget(value: unknown): WorkflowBudget | undefined;
 export declare function validateBudgetPatch(value: unknown): WorkflowBudgetPatch;
 export declare class WorkflowBudgetRuntime {
@@ -395,7 +444,7 @@ export interface StaticWorkflowScope {
     key: string | null;
 }
 export interface StaticWorkflowCall {
-    kind: "agent" | "conversation" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+    kind: WorkflowCallKind;
     start: number;
     end: number;
     name: string | null;
@@ -428,27 +477,43 @@ export interface WorkflowCatalogVariable {
     description: string;
     schema: JsonSchema;
 }
-export interface WorkflowCatalogWorkflow {
-    name: string;
-    version: string;
-    headline: string;
-    extensionDescription: string;
-    description: string;
-}
 export interface WorkflowCatalog {
     functions: readonly WorkflowCatalogFunction[];
     variables: readonly WorkflowCatalogVariable[];
-    workflows: readonly WorkflowCatalogWorkflow[];
     modelAliases?: Readonly<Record<string, string>>;
 }
+export interface WorkflowCatalogIndexFunction {
+    name: string;
+    description: string;
+    input: JsonSchema;
+}
+export interface WorkflowCatalogIndexVariable {
+    name: string;
+    description: string;
+    schema: JsonSchema;
+}
+export interface WorkflowCatalogIndex {
+    functions: readonly WorkflowCatalogIndexFunction[];
+    variables: readonly WorkflowCatalogIndexVariable[];
+    modelAliases?: Readonly<Record<string, string>>;
+}
+export interface WorkflowCatalogError {
+    error: {
+        code: "NOT_FOUND";
+        name: string;
+        message: string;
+    };
+}
 export declare class WorkflowRegistry {
     #private;
     get frozen(): boolean;
     freeze(): void;
     register(extension: WorkflowExtension): void;
-    workflow(name: string): WorkflowScriptDefinition;
-    workflows(): Readonly<Record<string, WorkflowScriptDefinition>>;
+    function(name: string): WorkflowFunction;
+    functions(): Readonly<Record<string, WorkflowFunction>>;
     catalog(): WorkflowCatalog;
+    catalogIndex(): WorkflowCatalogIndex;
+    catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
     globals(): Readonly<Record<string, {
         name: string;
     }>>;
@@ -461,7 +526,9 @@ export declare class WorkflowRegistry {
 }
 export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
 export declare function workflowCatalog(): WorkflowCatalog;
-export declare function registeredWorkflowDefinitions(): Readonly<Record<string, WorkflowScriptDefinition>>;
+export declare function workflowCatalogIndex(): WorkflowCatalogIndex;
+export declare function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError;
+export declare function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>>;
 export declare function formatWorkflowPreview(args: {
     script?: unknown;
     workflow?: unknown;
@@ -470,7 +537,7 @@ export declare function formatWorkflowPreview(args: {
 }): 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 scripts require a name; registered workflows use their workflow name. Runs in the background by default; completion arrives as a follow-up message.";
+export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline scripts require a name; registered functions use their function name. Runs in the background by default; completion arrives as a follow-up message. Foreground results include the completed run ID, and parentRunId reuses matching named worktrees from a terminal run.";
 export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     name: Type.TOptional<Type.TString>;
     description: Type.TOptional<Type.TString>;
@@ -480,6 +547,7 @@ export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     foreground: Type.TOptional<Type.TBoolean>;
     concurrency: Type.TOptional<Type.TInteger>;
     budget: Type.TOptional<Type.TUnknown>;
+    parentRunId: Type.TOptional<Type.TString>;
 }>;
 export declare function preflight(script: string, capabilities: PreflightCapabilities, schemas?: readonly unknown[], metadata?: WorkflowMetadata): PreflightResult;
 export interface WorkflowValidationParameters {
@@ -487,6 +555,7 @@ export interface WorkflowValidationParameters {
     description?: string;
     script?: string;
     workflow?: string;
+    args?: unknown;
 }
 export interface WorkflowValidationContext {
     cwd: string;
@@ -496,6 +565,7 @@ export interface WorkflowValidationContext {
     modelAliases?: Readonly<Record<string, string>>;
     knownModels?: ReadonlySet<string>;
     settingsPath?: string;
+    agentDir?: string;
 }
 export interface ValidatedWorkflowLaunch {
     script: string;
@@ -503,6 +573,7 @@ export interface ValidatedWorkflowLaunch {
     agentDefinitions: Readonly<Record<string, AgentDefinition>>;
     projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>;
     roleNames: readonly string[];
+    functionName?: string;
 }
 export declare function validateWorkflowLaunch(params: WorkflowValidationParameters, context: WorkflowValidationContext): ValidatedWorkflowLaunch;
 type LaunchSnapshotInput = Omit<LaunchSnapshot, "identityVersion"> & {
@@ -523,10 +594,18 @@ export interface AgentIdentity {
         turn: number;
     };
 }
+export interface ShellIdentity {
+    structuralPath: readonly string[];
+    callSite: string;
+    occurrence: number;
+    worktreeOwner?: string;
+}
 export interface WorkflowBridge {
     agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
+    shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
     checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>;
     function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>;
+    worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>;
     functions?: Readonly<Record<string, {
         name: string;
     }>>;
@@ -548,10 +627,11 @@ export declare function formatNavigatorRun(loaded: {
     run: PersistedRun;
     snapshot: Readonly<LaunchSnapshot>;
 }, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string;
-export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory): void;
+export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
+export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory, agentDir?: string): void;
 export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export type { AwaitingCheckpoint, CompletedOperation, ConversationHead, NativeSessionReference, PendingWorkflowDecision, PersistedConversation, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
+export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
-export type { DoctorDiagnostic, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust, DoctorWorkflow } from "./doctor.js";
+export type { DoctorDiagnostic, DoctorFunction, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust } from "./doctor.js";