pi-extensible-workflows 3.3.0 → 3.4.0

package/README.md

@@ -20,7 +20,7 @@ For source installs and local development, see the [installation guide](https://
 
 ## Capabilities
 
-The default path is a named inline workflow: write a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns. Inline launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Runs are backgrounded by default; set `foreground: true` when the final value must be returned in the same tool call. If a foreground tool call detaches before its result is accepted by the next event-loop turn, the terminal success or failure is promoted to exactly one follow-up message.
+The default path is a named inline workflow: write a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns. Inline and file-backed launches require a non-empty `name`; a reviewed JavaScript file can use `scriptPath` instead of `script`, and its contents are captured in the run at launch. Registered function launches may use `name` as an optional run label and otherwise use their registered function name. Runs are backgrounded by default; set `foreground: true` when the final value must be returned in the same tool call. If a foreground tool call detaches before its result is accepted by the next event-loop turn, the terminal success or failure is promoted to exactly one follow-up message.
 
 ```js
 const reviews = await parallel("review", {
@@ -36,7 +36,7 @@ return await agent(
 
 **Advanced capabilities:** Use registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` when the task requires them. They remain available without complicating the basic inline path. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
 
-The main Pi agent writes these scripts on the fly for each task; extensions can add reusable functions and variables, and completed workflows can resume without rerunning completed work.
+The main Pi agent writes these scripts on the fly for each task; an external review or approval flow can write one to a JavaScript file and launch it with `scriptPath`. Extensions can add reusable functions and variables, and completed workflows can resume without rerunning completed work.
 
 Learn more about roles, workflow contracts, and extension APIs in the documentation:
 

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

@@ -1,8 +1,56 @@
 import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput, WorkflowRunContext } from "./types.js";
+type AgentMessage = {
+    role: string;
+    content?: unknown;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: {
+            total: number;
+        };
+    };
+};
+type PiSession = {
+    readonly sessionId: string;
+    readonly sessionFile: string | undefined;
+    readonly messages: readonly AgentMessage[];
+    getSessionStats(): {
+        tokens: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            total: number;
+        };
+        cost: number;
+    };
+    readonly systemPrompt?: string;
+    readonly model?: {
+        provider: string;
+        model?: string;
+        id?: string;
+    };
+    readonly agent?: {
+        state: {
+            tools: readonly {
+                name: string;
+            }[];
+        };
+    };
+    subscribe?(listener: (event: unknown) => void): () => void;
+    prompt(text: string): Promise<void>;
+    steer?(text: string): Promise<void>;
+    abort?(): Promise<void>;
+    dispose(): void;
+};
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, AgentTransport, AgentTransportContext, JsonSchema, JsonValue, ModelSpec, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentSession, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowRunContext } from "./types.js";
 import type { RunStore } from "./persistence.js";
-export type { AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./types.js";
+export type { AgentSetup, AgentSetupContext, AgentSetupHook, AgentTransport, AgentTransportContext, PreparedAgentSession, RegisteredAgentSetupHook, SessionInput, WorkflowAgentMessage, WorkflowAgentSession, WorkflowAgentSessionEvent, WorkflowAgentSessionReference, WorkflowAgentSessionState, WorkflowAgentSessionStats, WorkflowAgentTurnResult } from "./types.js";
 export interface AgentBudgetHooks {
     beforeAttempt(): void;
     beforeTurn(): void;
@@ -35,7 +83,7 @@ export interface AgentExecutionOptions {
     model?: string;
     thinking?: ThinkingLevel;
     onProgress?: (progress: AgentProgress) => void | Promise<void>;
-    onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => void | Promise<void>;
+    onAttempt?: (attempt: AgentAttempt) => void | Promise<void>;
     providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>;
     modelOverride?: ModelSpec;
     tools?: readonly string[];
@@ -89,32 +137,36 @@ export interface AgentActivity {
 export interface AgentProgress {
     accounting: AgentAccounting;
     toolCalls: readonly AgentToolCallProgress[];
+    state?: WorkflowAgentSessionState;
     activity?: AgentActivity;
     lastEventAt?: number;
     persist: boolean;
 }
 export interface AgentAttempt {
     attempt: number;
-    sessionId: string;
-    sessionFile: string;
+    transport: string;
+    session?: WorkflowAgentSessionReference;
+    liveSession?: WorkflowAgentSession;
     result?: JsonValue;
     error?: {
         code: string;
         message: string;
     };
     accounting: AgentAccounting;
-    setup?: AgentSetupSummary;
+    setup: AgentSetupSummary;
 }
 export interface AgentExecutionResult {
     value: JsonValue;
     attempts: readonly AgentAttempt[];
     cwd: string;
 }
-export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
+export declare function createLocalPiSession(input: SessionInput): Promise<PiSession>;
+export declare function createLocalWorkflowAgentSession(prepared: Readonly<PreparedAgentSession>, context: Readonly<AgentTransportContext>): Promise<WorkflowAgentSession>;
+export declare const localAgentTransport: AgentTransport;
 export declare class WorkflowAgentExecutor {
     private readonly root;
-    private readonly createSession;
-    constructor(root: AgentExecutionRoot, createSession?: SessionFactory);
+    private readonly transport;
+    constructor(root: AgentExecutionRoot, transport?: AgentTransport);
     setRunContext(runContext: Readonly<WorkflowRunContext>): void;
     resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
         model: ModelSpec;
@@ -167,6 +219,7 @@ type ScheduledNode = {
     id: string;
     runId: string;
     parentId?: string;
+    prompt?: string;
     options: Readonly<ScheduledAgentOptions>;
     children: Set<string>;
     collected: boolean;
@@ -181,6 +234,7 @@ type ScheduledNode = {
 export type OwnershipRecord = {
     id: string;
     parentId?: string;
+    prompt?: string;
     label: string;
     state: ScheduledNode["state"];
     options: Readonly<ScheduledAgentOptions>;