pi-extensible-workflows 2.0.0 → 3.1.0

package/dist/src/host.d.ts

@@ -0,0 +1,101 @@
+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 AgentRecord, 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 type WorkflowPhaseState = "not started" | "running" | "completed" | "failed" | "cancelled" | "interrupted" | "budget_exhausted";
+export interface WorkflowPhaseAgentCounts {
+    total: number;
+    completed: number;
+    running: number;
+    failed: number;
+    cancelled: number;
+    pending: number;
+}
+export interface WorkflowPhaseView {
+    id: string;
+    name: string;
+    occurrence: number;
+    state: WorkflowPhaseState;
+    status: WorkflowPhaseState;
+    observed: boolean;
+    afterAgent?: number;
+    agents: readonly AgentRecord[];
+    counts: WorkflowPhaseAgentCounts;
+}
+export interface WorkflowPhaseModel {
+    declaredPhases: readonly string[];
+    phases: readonly WorkflowPhaseView[];
+    currentPhaseIndex?: number;
+    currentPhaseId?: string;
+    counts: Readonly<Partial<Record<WorkflowPhaseState, number>>>;
+    unassignedAgents?: readonly AgentRecord[];
+}
+type WorkflowPhaseSource = readonly string[] | Pick<LaunchSnapshot, "phases"> | undefined;
+export declare function buildWorkflowPhaseModel(run: Pick<PersistedRun, "state" | "phase" | "phaseHistory" | "agents">, source?: WorkflowPhaseSource): WorkflowPhaseModel;
+export interface WorkflowPhaseSelection {
+    phaseId?: string | undefined;
+    agentId?: string | undefined;
+}
+export declare function preserveWorkflowPhaseSelection(model: WorkflowPhaseModel, selection: WorkflowPhaseSelection): WorkflowPhaseSelection;
+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 agentBreadcrumbParts(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): string[];
+export declare function agentBreadcrumb(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): 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 formatWorkflowPhaseDashboard(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>, width: number, selection?: WorkflowPhaseSelection, styles?: WorkflowProgressStyles): string[];
+export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
+export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory, agentDir?: string): void;
+export {};