pi-extensible-workflows 0.3.0

package/dist/src/index.d.ts

@@ -0,0 +1,362 @@
+import { Type } from "@earendil-works/pi-ai";
+import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type AgentActivity, type AgentAttempt, type AgentDefinition, type SessionFactory } from "./agent-execution.js";
+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"];
+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 ERROR_CODES: readonly ["INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_LIMIT_EXCEEDED", "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "INTERNAL_ERROR"];
+export type RunState = (typeof RUN_STATES)[number];
+export type AgentState = (typeof AGENT_STATES)[number];
+export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonSchema = {
+    [key: string]: JsonValue;
+};
+export interface WorkflowErrorShape {
+    code: WorkflowErrorCode;
+    message: string;
+}
+export interface ModelSpec {
+    provider: string;
+    model: string;
+    thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+export interface WorkflowMetadata {
+    name: string;
+    description?: string;
+}
+export interface WorkflowSettings {
+    concurrency: number;
+    maxAgentLaunches: number;
+}
+export interface AgentAttemptSummary {
+    attempt: number;
+    sessionId: string;
+    sessionFile: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    accounting: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+}
+export interface AgentRecord {
+    id: string;
+    name: string;
+    label?: string;
+    path: string;
+    state: AgentState;
+    parentId?: string;
+    parentBreadcrumb?: string;
+    role?: string;
+    model: ModelSpec;
+    tools: readonly string[];
+    attempts: number;
+    attemptDetails?: readonly AgentAttemptSummary[];
+    accounting?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+    toolCalls?: readonly {
+        id: string;
+        name: string;
+        state: "running" | "completed" | "failed";
+    }[];
+    activity?: AgentActivity | undefined;
+}
+export interface RunRecord {
+    id: string;
+    workflowName: string;
+    cwd: string;
+    sessionId: string;
+    state: RunState;
+    phase?: string;
+    agents: readonly AgentRecord[];
+    error?: WorkflowErrorShape;
+}
+export interface LaunchSnapshot {
+    identityVersion?: number;
+    script: string;
+    args: JsonValue;
+    metadata: WorkflowMetadata;
+    settings: WorkflowSettings;
+    models: readonly string[];
+    tools: readonly string[];
+    agentTypes: readonly string[];
+    roles?: Readonly<Record<string, AgentDefinition>>;
+    projectRoles?: readonly string[];
+    schemas: readonly JsonSchema[];
+}
+export interface PreflightCapabilities {
+    models: ReadonlySet<string>;
+    tools: ReadonlySet<string>;
+    agentTypes: ReadonlySet<string>;
+}
+export interface PreflightResult {
+    metadata: WorkflowMetadata;
+    referenced: {
+        phases: readonly string[];
+        models: readonly string[];
+        tools: readonly string[];
+        agentTypes: readonly string[];
+    };
+    schemas: readonly JsonSchema[];
+    dynamicAgentRoles: boolean;
+}
+export interface WorkflowOrchestrationContext {
+    agent: (...args: readonly unknown[]) => Promise<JsonValue>;
+    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>;
+    checkpoint: (...args: readonly unknown[]) => Promise<boolean>;
+    phase: (name: string) => void;
+    log: (message: string) => void;
+}
+export interface WorkflowRunContext {
+    cwd: string;
+    sessionId: string;
+    runId: string;
+    workflow: Readonly<WorkflowMetadata>;
+    args: JsonValue;
+    signal: AbortSignal;
+}
+export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
+    run: Readonly<WorkflowRunContext>;
+}
+export interface WorkflowFunction {
+    description: string;
+    input: JsonSchema;
+    output: JsonSchema;
+    run: (input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>) => Promise<JsonValue> | JsonValue;
+}
+export interface WorkflowVariable {
+    description: string;
+    schema: JsonSchema;
+    resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue;
+}
+export interface WorkflowScriptDefinition {
+    description: string;
+    script: string;
+}
+export interface WorkflowExtension {
+    namespace: string;
+    version: string;
+    headline: string;
+    description: string;
+    functions?: Readonly<Record<string, WorkflowFunction>>;
+    variables?: Readonly<Record<string, WorkflowVariable>>;
+    workflows?: Readonly<Record<string, WorkflowScriptDefinition>>;
+}
+export interface WorkflowJournal {
+    get(path: string): JsonValue | undefined;
+    put(path: string, value: JsonValue): void;
+}
+export declare class WorkflowError extends Error {
+    readonly code: WorkflowErrorCode;
+    constructor(code: WorkflowErrorCode, message: string);
+}
+export declare function formatWorkflowFailure(error: unknown): string;
+export declare class RunLifecycle {
+    #private;
+    private readonly changed?;
+    constructor(state?: RunState, changed?: ((state: RunState) => 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"): Promise<void>;
+}
+export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
+export declare function parseModelReference(value: string): ModelSpec;
+export interface CheckpointInput {
+    name: string;
+    prompt: string;
+    context: JsonValue;
+}
+export declare function validateCheckpoint(value: unknown): CheckpointInput;
+export declare function workflowSettingsPath(agentDir?: string): string;
+export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+export declare function parseRoleMarkdown(content: string, strict?: boolean): AgentDefinition;
+export declare function workflowRoleDirectories(agentDir?: string): readonly string[];
+export declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean): Readonly<Record<string, AgentDefinition>>;
+export type StaticWorkflowExecution = "parallel" | "sequential";
+export interface StaticWorkflowScope {
+    kind: "parallel" | "pipeline";
+    name: string | null;
+    key: string | null;
+}
+export interface StaticWorkflowCall {
+    kind: "agent" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+    start: number;
+    end: number;
+    name: string | null;
+    prompt: string | null;
+    model: string | null;
+    label?: string | null;
+    role: string | null;
+    retries?: number | null;
+    outputSchema?: JsonSchema | null;
+    options?: Readonly<Record<string, JsonValue>> | null;
+    optionKeys?: readonly string[];
+    execution?: StaticWorkflowExecution;
+    structure?: readonly StaticWorkflowScope[];
+}
+export declare function inspectWorkflowScript(script: string): StaticWorkflowCall[];
+export interface WorkflowCatalogFunction {
+    name: string;
+    namespace: string;
+    version: string;
+    headline: string;
+    extensionDescription: string;
+    description: string;
+    input: JsonSchema;
+    output: JsonSchema;
+}
+export interface WorkflowCatalogVariable {
+    name: string;
+    namespace: string;
+    version: string;
+    headline: string;
+    extensionDescription: string;
+    description: string;
+    schema: JsonSchema;
+}
+export interface WorkflowCatalogWorkflow {
+    name: string;
+    namespace: string;
+    version: string;
+    headline: string;
+    extensionDescription: string;
+    description: string;
+}
+export interface WorkflowCatalog {
+    functions: readonly WorkflowCatalogFunction[];
+    variables: readonly WorkflowCatalogVariable[];
+    workflows: readonly WorkflowCatalogWorkflow[];
+}
+export declare class WorkflowRegistry {
+    #private;
+    get frozen(): boolean;
+    freeze(): void;
+    register(extension: WorkflowExtension): void;
+    workflow(name: string): WorkflowScriptDefinition;
+    workflows(): Readonly<Record<string, WorkflowScriptDefinition>>;
+    catalog(): WorkflowCatalog;
+    globals(): Readonly<Record<string, {
+        namespace: string;
+        name: string;
+    }>>;
+    invokeFunction(namespace: string, name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
+    variables(): readonly {
+        namespace: string;
+        name: string;
+        variable: WorkflowVariable;
+    }[];
+}
+export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
+export declare function workflowCatalog(): WorkflowCatalog;
+export declare function registeredWorkflowDefinitions(): Readonly<Record<string, WorkflowScriptDefinition>>;
+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 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_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>;
+    maxAgentLaunches: Type.TOptional<Type.TInteger>;
+}>;
+export declare function preflight(script: string, capabilities: PreflightCapabilities, schemas?: readonly unknown[], metadata?: WorkflowMetadata): PreflightResult;
+export interface WorkflowValidationParameters {
+    name?: string;
+    description?: string;
+    script?: string;
+    workflow?: string;
+}
+export interface WorkflowValidationContext {
+    cwd: string;
+    projectTrusted: boolean;
+    availableModels: ReadonlySet<string>;
+    rootTools: ReadonlySet<string>;
+}
+export interface ValidatedWorkflowLaunch {
+    script: string;
+    checked: PreflightResult;
+    agentDefinitions: Readonly<Record<string, AgentDefinition>>;
+    projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>;
+    roleNames: readonly string[];
+}
+export declare function validateWorkflowLaunch(params: WorkflowValidationParameters, context: WorkflowValidationContext): ValidatedWorkflowLaunch;
+type LaunchSnapshotInput = Omit<LaunchSnapshot, "identityVersion"> & {
+    identityVersion?: number;
+};
+export declare function createLaunchSnapshot(input: LaunchSnapshotInput): Readonly<LaunchSnapshot>;
+export declare function loadLaunchSnapshot(input: LaunchSnapshot): Readonly<LaunchSnapshot>;
+export declare const RPC_LIMIT_BYTES: number;
+export declare const HEARTBEAT_TIMEOUT_MS = 5000;
+export interface AgentIdentity {
+    structuralPath: readonly string[];
+    callSite: string;
+    occurrence: number;
+    parentBreadcrumb?: string;
+    worktreeOwner?: string;
+}
+export interface WorkflowBridge {
+    agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
+    checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>;
+    function?: (namespace: string, name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string) => Promise<JsonValue>;
+    functions?: Readonly<Record<string, {
+        namespace: string;
+        name: string;
+    }>>;
+    variables?: Readonly<Record<string, JsonValue>>;
+    phase?: (name: string) => void | Promise<void>;
+    log?: (message: string) => void | Promise<void>;
+}
+export interface WorkflowExecution {
+    result: Promise<JsonValue>;
+    cancel: () => void;
+}
+export declare function runWorkflow(script: string, args?: JsonValue, bridge?: WorkflowBridge, signal?: AbortSignal): WorkflowExecution;
+export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">): Promise<void>;
+export declare function persistAgentAttempts(store: RunStore, id: string, attempts: readonly AgentAttempt[]): Promise<void>;
+export declare function formatWorkflowProgress(run: PersistedRun, spinner?: string): 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 default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory): void;
+export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
+export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
+export type { AgentAccounting, AgentAttempt, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentToolCallProgress } from "./agent-execution.js";
+export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
+export type { DoctorDiagnostic, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust, DoctorWorkflow } from "./doctor.js";