pi-extensible-workflows 3.2.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.
+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:
 
@@ -51,35 +51,6 @@ Learn more about roles, workflow contracts, and extension APIs in the documentat
 - [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. Trusted projects can add partial overrides at `<project>/.pi/pi-extensible-workflows/settings.json`; precedence is defaults < global < trusted project < per-run options. Project collections replace global collections, so `{}` and empty arrays clear inherited aliases or resource exclusions. Untrusted project settings are ignored. See [global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings) for the schema, trust gate, source reporting, and merge rules.
-
-## CLI
-
-```sh
-npx pi-extensible-workflows doctor
-npx pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]
-npx pi-extensible-workflows inspect [session-id]
-npx pi-extensible-workflows transcript <session-file>
-npx pi-extensible-workflows run <workflow-name> [workflow arguments]
-npx pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]
-```
-
-`doctor` validates the installation and active Pi resources and remains read-only. `doctor cleanup` is an explicit, dry-run-first maintenance command: it previews terminal workflow runs older than 90 days across the current project's stored sessions and deletes them only with `--yes`; use `--older-than-days` to change the positive age threshold. It protects active, corrupt, leased, and dependency-linked runs. `inspect` opens a read-only terminal view of persisted workflow runs. `transcript` renders a session transcript to stdout. `run` derives flat CLI arguments and help from a registered function's input schema. Use `--input '<json>'` for nested or otherwise complex inputs. It executes in the current working directory, writes the final JSON result to stdout, and writes progress and errors to stderr. `export` creates an executable POSIX launcher in `~/.local/bin` by default.
-`run` and `export` accept the trust overrides `--approve` and `--no-approve`; the generated launcher forwards its arguments to `run`. `--` ends launcher option parsing, and later tokens are passed to workflow input instead of being interpreted as launcher options. Headless `run` and generated `export` launchers cannot execute workflows containing checkpoints; use the Pi workflow tool/UI path for checkpointed workflows.
-Launch snapshots use identity version 5. Cold resume rejects older snapshots, including v4 snapshots created with the previous worktree or registered-function naming contracts, with `RESUME_INCOMPATIBLE`; relaunch the workflow instead.
-
-## Development
-
-```sh
-npm ci
-npm run check
-npm run acceptance
-npm pack --dry-run --json
-```
-
-Model-backed evaluations are optional. See the [evaluation guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html#evaluation).
 
 ## License
 

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;
@@ -15,6 +63,7 @@ export interface AgentDefinition {
     model?: string;
     thinking?: ThinkingLevel;
     tools?: readonly string[];
+    overrideSystemPrompt?: boolean;
     disabledAgentResources?: AgentResourceExclusions;
 }
 export interface AgentProviderFailure {
@@ -34,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[];
@@ -56,6 +105,7 @@ export interface AgentExecutionRoot {
     tools: ReadonlySet<string>;
     agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
     agentDir?: string;
+    additionalSkillPaths?: readonly string[];
     availableModels?: ReadonlySet<string>;
     knownModels?: ReadonlySet<string>;
     modelAliases?: Readonly<Record<string, string>>;
@@ -87,36 +137,42 @@ 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;
         requestedModel?: string;
         tools: readonly string[];
+        systemPrompt?: string;
         systemPromptAppend: string;
     };
     execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools?: readonly ToolDefinition[], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult>;
@@ -163,6 +219,7 @@ type ScheduledNode = {
     id: string;
     runId: string;
     parentId?: string;
+    prompt?: string;
     options: Readonly<ScheduledAgentOptions>;
     children: Set<string>;
     collected: boolean;
@@ -177,6 +234,7 @@ type ScheduledNode = {
 export type OwnershipRecord = {
     id: string;
     parentId?: string;
+    prompt?: string;
     label: string;
     state: ScheduledNode["state"];
     options: Readonly<ScheduledAgentOptions>;