pi-extensible-workflows 0.3.2 → 1.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 ![pi-extensible-workflows workflow banner](https://raw.githubusercontent.com/vekexasia/pi-extensible-workflows/main/assets/pi-extensible-workflows-banner.png)
 
+> There are many workflow extensions but this one is **Yours.**
+
 Turn multi-agent tasks into deterministic jobs that fan out in parallel, pause for approval, and resume without rerunning completed work.
 
 [Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html)
@@ -41,12 +43,19 @@ return summary;
 Learn more about roles, workflow contracts, and extension APIs in the documentation:
 
 - [Workflow tool and invocation API](https://vekexasia.github.io/pi-extensible-workflows/developers.html#tool-api)
+- [Global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings)
+- [Aggregate run budgets](https://vekexasia.github.io/pi-extensible-workflows/developers.html#budgets)
 - [Workflow DSL and worktrees](https://vekexasia.github.io/pi-extensible-workflows/developers.html#dsl)
 - [Reusable extension primitives](https://vekexasia.github.io/pi-extensible-workflows/developers.html#extensions)
+- [Run artifacts and lifecycle events](https://vekexasia.github.io/pi-extensible-workflows/developers.html#lifecycle)
 - [Run inspection and recovery](https://vekexasia.github.io/pi-extensible-workflows/developers.html#operations)
 - [Agent patterns and model selection](https://vekexasia.github.io/pi-extensible-workflows/agents.html#patterns)
 - [Checkpoints](https://vekexasia.github.io/pi-extensible-workflows/agents.html#checkpoints)
 
+## Configuration
+
+Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.json` by default and configure concurrency, model aliases, and workflow-agent skill or extension exclusions. Trusted projects can add resource exclusions at `<project>/.pi/pi-extensible-workflows/settings.json`; they cannot override global aliases or concurrency. See [global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings) for the schema and merge rules.
+
 ## CLI
 
 ```sh

package/dist/src/agent-execution.d.ts

@@ -1,8 +1,10 @@
-import { type AgentSessionEvent, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionEvent, type InlineExtension, type SessionStats, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type AgentMessage = {
     role: string;
     content?: unknown;
+    stopReason?: string;
+    errorMessage?: string;
     usage?: {
         input: number;
         output: number;
@@ -13,14 +15,21 @@ type AgentMessage = {
         };
     };
 };
-import type { JsonSchema, JsonValue, ModelSpec } from "./index.js";
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./index.js";
 import type { RunStore } from "./persistence.js";
+export interface AgentBudgetHooks {
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(): string | undefined;
+}
 export interface AgentDefinition {
     prompt?: string;
     description?: string;
     model?: string;
     thinking?: ThinkingLevel;
     tools?: readonly string[];
+    disabledAgentResources?: AgentResourceExclusions;
 }
 export interface AgentExecutionOptions {
     label: string;
@@ -30,7 +39,7 @@ export interface AgentExecutionOptions {
     model?: string;
     thinking?: ThinkingLevel;
     onProgress?: (progress: AgentProgress) => void | Promise<void>;
-    onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">) => void | Promise<void>;
+    onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => void | Promise<void>;
     tools?: readonly string[];
     effectiveTools?: readonly string[];
     role?: string;
@@ -40,6 +49,13 @@ export interface AgentExecutionOptions {
     retryState?: string;
     worktreeOwner?: string;
     cwd?: string;
+    budget?: AgentBudgetHooks;
+    agentOptions?: Readonly<Record<string, JsonValue>>;
+    agentIdentity?: AgentIdentity;
+    conversation?: {
+        id: string;
+        turn: number;
+    };
 }
 export interface AgentExecutionRoot {
     cwd: string;
@@ -48,8 +64,16 @@ export interface AgentExecutionRoot {
     agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
     agentDir?: string;
     availableModels?: ReadonlySet<string>;
+    knownModels?: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    blockedAliases?: ReadonlySet<string>;
+    blockedAliasTargets?: Readonly<Record<string, string>>;
+    settingsPath?: string;
     runStore?: RunStore;
     providerPause?: () => Promise<void>;
+    agentSetupHooks?: readonly RegisteredAgentSetupHook[];
+    agentResourcePolicy?: () => AgentResourcePolicy | Promise<AgentResourcePolicy>;
+    runContext?: Readonly<WorkflowRunContext>;
 }
 export interface AgentAccounting {
     input: number;
@@ -83,17 +107,46 @@ export interface AgentAttempt {
         message: string;
     };
     accounting: AgentAccounting;
+    setup?: AgentSetupSummary;
 }
 export interface AgentExecutionResult {
     value: JsonValue;
     attempts: readonly AgentAttempt[];
     cwd: string;
 }
+export interface AgentSetup {
+    prompt: string;
+    options: Record<string, JsonValue>;
+    sessionInput: SessionInput;
+    createSession: SessionFactory;
+}
+export interface AgentSetupContext {
+    readonly run: Readonly<WorkflowRunContext>;
+    readonly identity: Readonly<AgentIdentity>;
+    readonly attempt: number;
+    readonly signal: AbortSignal;
+}
+export interface AgentSetupHook {
+    priority?: number;
+    setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void>;
+}
+export interface RegisteredAgentSetupHook {
+    name: string;
+    priority: number;
+    setup: AgentSetupHook["setup"];
+}
+type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
 export interface NativeSession {
     readonly sessionId: string;
     readonly sessionFile: string | undefined;
     readonly messages: readonly AgentMessage[];
+    getSessionStats(): NativeSessionStats;
     readonly systemPrompt?: string;
+    readonly model?: {
+        provider: string;
+        model?: string;
+        id?: string;
+    };
     readonly agent?: {
         state: {
             tools: readonly {
@@ -101,6 +154,8 @@ export interface NativeSession {
             }[];
         };
     };
+    getLeafId?: () => string | null;
+    getToolDefinitions?: () => unknown;
     subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
     prompt(text: string): Promise<void>;
     steer?(text: string): Promise<void>;
@@ -110,12 +165,20 @@ export interface NativeSession {
 export interface SessionInput {
     cwd: string;
     model: ModelSpec;
-    tools: readonly string[];
+    tools: string[];
     sessionLabel: string;
     agentDir?: string;
-    customTools?: readonly ToolDefinition[];
+    customTools?: ToolDefinition[];
     resultTool?: ToolDefinition;
     systemPromptAppend?: string;
+    extensionFactories?: InlineExtension[];
+    resourcePolicy?: AgentResourcePolicy;
+    options?: Record<string, JsonValue>;
+    continuation?: {
+        sessionId: string;
+        sessionFile: string;
+        leafId: string;
+    };
 }
 export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
@@ -123,8 +186,10 @@ export declare class WorkflowAgentExecutor {
     private readonly root;
     private readonly createSession;
     constructor(root: AgentExecutionRoot, createSession?: SessionFactory);
+    setRunContext(runContext: Readonly<WorkflowRunContext>): void;
     resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
         model: ModelSpec;
+        requestedModel?: string;
         tools: readonly string[];
         systemPromptAppend: string;
     };
@@ -143,6 +208,12 @@ export interface ScheduledAgentOptions {
     schema?: JsonSchema;
     retries?: number;
     timeoutMs?: number | null;
+    agentOptions?: Readonly<Record<string, JsonValue>>;
+    agentIdentity?: AgentIdentity;
+    conversation?: {
+        id: string;
+        turn: number;
+    };
 }
 export type ScheduledAgentResult = {
     id: string;
@@ -173,7 +244,7 @@ type ScheduledNode = {
     options: Readonly<ScheduledAgentOptions>;
     children: Set<string>;
     collected: boolean;
-    state: "queued" | "running" | "waiting_for_child" | "completed" | "failed" | "cancelled";
+    state: "queued" | "running" | "waiting_for_child" | "paused" | "retrying" | "completed" | "failed" | "cancelled";
     controller: AbortController;
     promise: Promise<ScheduledAgentResult>;
     resolve: (result: ScheduledAgentResult) => void;
@@ -195,7 +266,7 @@ export declare class FairAgentScheduler {
     readonly sessionLimit: number;
     private readonly writeOwnership?;
     constructor(runner: ScheduledAgentRunner, sessionLimit?: number, writeOwnership?: OwnershipWriter | undefined);
-    addRun(runId: string, limit?: number, maxAgentLaunches?: number): void;
+    addRun(runId: string, limit?: number, beforeLaunch?: () => void): void;
     spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
         id: string;
         result: Promise<ScheduledAgentResult>;
@@ -204,10 +275,12 @@ export declare class FairAgentScheduler {
     steer(parentId: string, childId: string, message: string): Promise<void>;
     cancel(id: string): void;
     cancelChildren(id: string): void;
+    retry(id: string): void;
+    attemptStarted(id: string): void;
     cancelRun(runId: string): Promise<void>;
     toolsFor(parentId: string, resolveTools?: (role: string | undefined, tools: readonly string[] | undefined, model: string | undefined, inheritedTools: readonly string[], thinking: ThinkingLevel | undefined) => readonly string[]): ToolDefinition[];
     snapshot(): readonly OwnershipRecord[];
-    restoreRun(runId: string, limit: number, maxAgentLaunches: number, ownership: readonly OwnershipRecord[]): void;
+    restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void): void;
     flush(): Promise<void>;
 }
 export {};