pi-extensible-workflows 0.3.2 → 1.0.1

package/dist/src/index.d.ts

@@ -1,13 +1,23 @@
 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 { type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentSetupHook, type RegisteredAgentSetupHook, 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 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 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 declare const WORKFLOW_CALL_KINDS: readonly ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"];
+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";
+export declare const WORKFLOW_RUN_COMPLETED_EVENT = "workflow:run-completed";
+export declare const WORKFLOW_RUN_FAILED_EVENT = "workflow:run-failed";
+export declare const WORKFLOW_AGENT_STATE_CHANGED_EVENT = "workflow:agent-state-changed";
+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 type RunState = (typeof RUN_STATES)[number];
 export type AgentState = (typeof AGENT_STATES)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
@@ -17,10 +27,100 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
 export type JsonSchema = {
     [key: string]: JsonValue;
 };
+export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
+export interface BudgetLimits {
+    soft?: number;
+    hard?: number;
+}
+export type WorkflowBudget = Partial<Record<BudgetDimension, BudgetLimits>>;
+export type WorkflowBudgetPatch = Partial<Record<BudgetDimension, BudgetLimits | {
+    soft?: number | null;
+    hard?: number | null;
+} | null>>;
+export interface WorkflowBudgetUsage {
+    tokens: number;
+    costUsd: number;
+    durationMs: number;
+    agentLaunches: number;
+}
+export type BudgetEventType = "soft_crossed" | "hard_overrun" | "hard_exhausted" | "adjustment_requested" | "adjustment_approved" | "adjustment_rejected";
+export interface BudgetEvent {
+    type: BudgetEventType;
+    budgetVersion: number;
+    dimensions: readonly BudgetDimension[];
+    usage: WorkflowBudgetUsage;
+    limits: WorkflowBudget;
+    at: number;
+    proposalId?: string;
+    previous?: WorkflowBudget;
+    proposed?: WorkflowBudget;
+}
+export interface BudgetApprovalRequest {
+    kind: "budget";
+    proposalId: string;
+    runId: string;
+    consumed: WorkflowBudgetUsage;
+    previous: WorkflowBudget;
+    proposed: WorkflowBudget;
+    budgetVersion: number;
+}
 export interface WorkflowErrorShape {
     code: WorkflowErrorCode;
     message: string;
 }
+export interface WorkflowEventBase {
+    runId: string;
+    sessionId: string;
+    workflowName: string;
+    cwd: string;
+    runDirectory: string;
+    timestamp: number;
+}
+export type WorkflowRunStartedEvent = WorkflowEventBase;
+export type WorkflowRunResumedEvent = WorkflowEventBase;
+export interface WorkflowRunStateChangedEvent extends WorkflowEventBase {
+    previousState: RunState;
+    state: RunState;
+    reason?: string;
+    errorCode?: WorkflowErrorCode;
+}
+export interface WorkflowRunCompletedEvent extends WorkflowEventBase {
+    resultPath: string;
+}
+export interface WorkflowRunFailedEvent extends WorkflowEventBase {
+    error: WorkflowErrorShape;
+}
+export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase {
+    agentId: string;
+    displayLabel: string;
+    role?: string;
+    structuralPath: readonly string[];
+    parentId?: string;
+    parentBreadcrumb?: string;
+    worktreeOwner?: string;
+    previousState?: AgentState;
+    state: AgentState;
+    attempt: number;
+}
+export interface WorkflowPhaseChangedEvent extends WorkflowEventBase {
+    previousPhase?: string;
+    phase: string;
+}
+export type WorkflowCheckpointState = "awaiting" | "approved" | "rejected";
+export interface WorkflowCheckpointStateChangedEvent extends WorkflowEventBase {
+    name: string;
+    state: WorkflowCheckpointState;
+}
+export interface WorkflowBudgetEvent extends WorkflowEventBase {
+    type: BudgetEventType;
+    budgetVersion: number;
+    dimensions: readonly BudgetDimension[];
+    usage: WorkflowBudgetUsage;
+    limits: WorkflowBudget;
+    proposalId?: string;
+    previous?: WorkflowBudget;
+    proposed?: WorkflowBudget;
+}
 export interface ModelSpec {
     provider: string;
     model: string;
@@ -32,7 +132,34 @@ export interface WorkflowMetadata {
 }
 export interface WorkflowSettings {
     concurrency: number;
-    maxAgentLaunches: number;
+    modelAliases?: Readonly<Record<string, string>>;
+    disabledAgentResources?: Readonly<AgentResourceExclusions>;
+}
+export interface AgentResourceExclusions {
+    skills: readonly string[];
+    extensions: readonly string[];
+}
+export interface AgentResourcePolicy {
+    globalSettingsPath: string;
+    projectSettingsPath: string;
+    projectTrusted: boolean;
+    global: AgentResourceExclusions;
+    project: AgentResourceExclusions;
+    effective: AgentResourceExclusions;
+    unmatchedSkills: string[];
+    unmatchedExtensions: string[];
+}
+export interface AgentSetupSummary {
+    hookNames: readonly string[];
+    model: ModelSpec;
+    tools: readonly string[];
+    cwd: string;
+    disabledAgentResources?: {
+        skills: readonly string[];
+        extensions: readonly string[];
+        unmatchedSkills: readonly string[];
+        unmatchedExtensions: readonly string[];
+    };
 }
 export interface AgentAttemptSummary {
     attempt: number;
@@ -49,6 +176,13 @@ export interface AgentAttemptSummary {
         cacheWrite: number;
         cost: number;
     };
+    setup?: AgentSetupSummary;
+}
+export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase {
+    owner: string;
+    branch: string;
+    path: string;
+    base: string;
 }
 export interface AgentRecord {
     id: string;
@@ -57,8 +191,11 @@ export interface AgentRecord {
     path: string;
     state: AgentState;
     parentId?: string;
+    structuralPath?: readonly string[];
     parentBreadcrumb?: string;
+    worktreeOwner?: string;
     role?: string;
+    requestedModel?: string;
     model: ModelSpec;
     tools: readonly string[];
     attempts: number;
@@ -77,6 +214,10 @@ export interface AgentRecord {
     }[];
     activity?: AgentActivity | undefined;
 }
+export interface WorkflowRunEvent {
+    type: string;
+    message: string;
+}
 export interface RunRecord {
     id: string;
     workflowName: string;
@@ -86,13 +227,22 @@ export interface RunRecord {
     phase?: string;
     agents: readonly AgentRecord[];
     error?: WorkflowErrorShape;
+    budget?: WorkflowBudget;
+    budgetVersion?: number;
+    usage?: WorkflowBudgetUsage;
+    budgetEvents?: readonly BudgetEvent[];
+    events?: readonly WorkflowRunEvent[];
 }
+export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
 export interface LaunchSnapshot {
     identityVersion?: number;
     script: string;
     args: JsonValue;
     metadata: WorkflowMetadata;
     settings: WorkflowSettings;
+    budget?: WorkflowBudget;
+    settingsPath?: string;
+    modelAliases?: Readonly<Record<string, string>>;
     models: readonly string[];
     tools: readonly string[];
     agentTypes: readonly string[];
@@ -104,6 +254,10 @@ export interface PreflightCapabilities {
     models: ReadonlySet<string>;
     tools: ReadonlySet<string>;
     agentTypes: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    knownModels?: ReadonlySet<string>;
+    settingsPath?: string;
+    skipModelAvailability?: boolean;
 }
 export interface PreflightResult {
     metadata: WorkflowMetadata;
@@ -136,6 +290,7 @@ export interface WorkflowRunContext {
 }
 export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
     run: Readonly<WorkflowRunContext>;
+    invoke: (name: string, input: Readonly<Record<string, JsonValue>>) => Promise<JsonValue>;
 }
 export interface WorkflowFunction {
     description: string;
@@ -153,13 +308,13 @@ export interface WorkflowScriptDefinition {
     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>>;
+    agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
 }
 export interface WorkflowJournal {
     get(path: string): JsonValue | undefined;
@@ -173,7 +328,7 @@ 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);
+    constructor(state?: RunState, changed?: ((state: RunState, previousState: RunState, reason?: string) => void | Promise<void>) | undefined);
     get state(): RunState;
     enter(): Promise<void>;
     leave(): Promise<void>;
@@ -182,10 +337,45 @@ export declare class RunLifecycle {
     pause(): Promise<void>;
     resume(): Promise<void>;
     providerPause(): Promise<void>;
-    terminal(state: "completed" | "failed" | "stopped" | "interrupted"): Promise<void>;
+    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 {
+    #private;
+    readonly budget: WorkflowBudget | undefined;
+    readonly version: number;
+    constructor(budget: WorkflowBudget | undefined, version?: number, usage?: Partial<WorkflowBudgetUsage>, events?: readonly BudgetEvent[], options?: {
+        now?: () => number;
+        onChange?: () => void;
+        active?: boolean;
+    });
+    get usage(): WorkflowBudgetUsage;
+    get events(): readonly BudgetEvent[];
+    get hardExhausted(): boolean;
+    checkAgentLaunch(): void;
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(agentId?: string): string | undefined;
+    forAgent(agentId: string): AgentBudgetHooks;
+    transition(state: RunState): void;
+    recordEvent(event: BudgetEvent): void;
+    snapshot(): {
+        usage: WorkflowBudgetUsage;
+        budgetEvents: readonly BudgetEvent[];
+    };
+}
+export declare function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined;
+export declare function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean;
+export declare function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[];
+export declare function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean;
 export declare function parseModelReference(value: string): ModelSpec;
+export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
+export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
 export interface CheckpointInput {
     name: string;
     prompt: string;
@@ -193,8 +383,12 @@ export interface CheckpointInput {
 }
 export declare function validateCheckpoint(value: unknown): CheckpointInput;
 export declare function workflowSettingsPath(agentDir?: string): string;
+export declare function workflowProjectSettingsPath(cwd: string): string;
+export declare function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions;
 export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
-export declare function parseRoleMarkdown(content: string, strict?: boolean): AgentDefinition;
+export declare function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): AgentResourcePolicy;
+export declare function saveModelAliases(path?: string, aliases?: Readonly<Record<string, string>>): void;
+export declare function parseRoleMarkdown(content: string, strict?: boolean, rolePath?: string): 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";
@@ -204,7 +398,7 @@ export interface StaticWorkflowScope {
     key: string | null;
 }
 export interface StaticWorkflowCall {
-    kind: "agent" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+    kind: WorkflowCallKind;
     start: number;
     end: number;
     name: string | null;
@@ -222,7 +416,6 @@ export interface StaticWorkflowCall {
 export declare function inspectWorkflowScript(script: string): StaticWorkflowCall[];
 export interface WorkflowCatalogFunction {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -232,7 +425,6 @@ export interface WorkflowCatalogFunction {
 }
 export interface WorkflowCatalogVariable {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -241,7 +433,6 @@ export interface WorkflowCatalogVariable {
 }
 export interface WorkflowCatalogWorkflow {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -251,6 +442,7 @@ export interface WorkflowCatalog {
     functions: readonly WorkflowCatalogFunction[];
     variables: readonly WorkflowCatalogVariable[];
     workflows: readonly WorkflowCatalogWorkflow[];
+    modelAliases?: Readonly<Record<string, string>>;
 }
 export declare class WorkflowRegistry {
     #private;
@@ -261,15 +453,14 @@ export declare class WorkflowRegistry {
     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>;
+    invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
     variables(): readonly {
-        namespace: string;
         name: string;
         variable: WorkflowVariable;
     }[];
+    agentSetupHooks(): readonly RegisteredAgentSetupHook[];
 }
 export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
 export declare function workflowCatalog(): WorkflowCatalog;
@@ -291,7 +482,7 @@ export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     args: Type.TOptional<Type.TUnknown>;
     foreground: Type.TOptional<Type.TBoolean>;
     concurrency: Type.TOptional<Type.TInteger>;
-    maxAgentLaunches: Type.TOptional<Type.TInteger>;
+    budget: Type.TOptional<Type.TUnknown>;
 }>;
 export declare function preflight(script: string, capabilities: PreflightCapabilities, schemas?: readonly unknown[], metadata?: WorkflowMetadata): PreflightResult;
 export interface WorkflowValidationParameters {
@@ -305,6 +496,9 @@ export interface WorkflowValidationContext {
     projectTrusted: boolean;
     availableModels: ReadonlySet<string>;
     rootTools: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    knownModels?: ReadonlySet<string>;
+    settingsPath?: string;
 }
 export interface ValidatedWorkflowLaunch {
     script: string;
@@ -327,13 +521,16 @@ export interface AgentIdentity {
     occurrence: number;
     parentBreadcrumb?: string;
     worktreeOwner?: string;
+    conversation?: {
+        name: string;
+        turn: number;
+    };
 }
 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>;
+    function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>;
     functions?: Readonly<Record<string, {
-        namespace: string;
         name: string;
     }>>;
     variables?: Readonly<Record<string, JsonValue>>;
@@ -345,18 +542,19 @@ export interface WorkflowExecution {
     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 persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): 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 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;
+}, 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 type { AwaitingCheckpoint, CompletedOperation, ConversationHead, NativeSessionReference, PendingWorkflowDecision, PersistedConversation, 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 type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, 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";