pi-extensible-workflows 0.3.0

package/README.md

@@ -0,0 +1,72 @@
+# pi-extensible-workflows
+
+![pi-extensible-workflows workflow banner](https://raw.githubusercontent.com/vekexasia/pi-extensible-workflows/main/assets/pi-extensible-workflows-banner.png)
+
+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)
+
+Requires Node.js 22.19 or newer. This is a trusted Pi extension with the same filesystem and process access as Pi.
+
+## Install
+
+```sh
+pi install npm:pi-extensible-workflows
+```
+
+For source installs and local development, see the [installation guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html#installation).
+
+## Capabilities
+
+A workflow can fan out across specialized agents, combine their results, and resume without rerunning completed work.
+
+```js
+const reviews = await parallel("review", {
+  correctness: () => agent("Review the current changes for correctness issues."),
+  security: () => agent("Review the current changes for security risks.", {
+    role: "security-specialist",
+  }),
+  tests: () => agent("Review the current changes for missing test coverage."),
+});
+
+const summary = await agent(
+  prompt("Deduplicate and prioritize these findings:\n\n{reviews}", { reviews }),
+);
+
+return summary;
+```
+
+`security-specialist` is an example project role. Runs execute in the background by default, and completed work is reused when a run resumes.
+
+The complete contracts and examples live in the documentation:
+
+- [Workflow tool and invocation API](https://vekexasia.github.io/pi-extensible-workflows/developers.html#tool-api)
+- [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 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)
+
+## CLI
+
+```sh
+npx pi-extensible-workflows doctor
+npx pi-extensible-workflows inspect [session-id]
+```
+
+`doctor` validates the installation and active Pi resources. `inspect` opens a read-only terminal view of persisted workflow runs.
+
+## 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
+
+MIT

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

@@ -0,0 +1,213 @@
+import { type AgentSessionEvent, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+type AgentMessage = {
+    role: string;
+    content?: unknown;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: {
+            total: number;
+        };
+    };
+};
+import type { JsonSchema, JsonValue, ModelSpec } from "./index.js";
+import type { RunStore } from "./persistence.js";
+export interface AgentDefinition {
+    prompt?: string;
+    description?: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    tools?: readonly string[];
+}
+export interface AgentExecutionOptions {
+    label: string;
+    workflowName: string;
+    phase?: string;
+    parent?: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    onProgress?: (progress: AgentProgress) => void | Promise<void>;
+    onAttempt?: (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">) => void | Promise<void>;
+    tools?: readonly string[];
+    effectiveTools?: readonly string[];
+    role?: string;
+    schema?: JsonSchema;
+    retries?: number;
+    timeoutMs?: number | null;
+    retryState?: string;
+    worktreeOwner?: string;
+    cwd?: string;
+}
+export interface AgentExecutionRoot {
+    cwd: string;
+    model: ModelSpec;
+    tools: ReadonlySet<string>;
+    agentDefinitions?: Readonly<Record<string, AgentDefinition>>;
+    agentDir?: string;
+    availableModels?: ReadonlySet<string>;
+    runStore?: RunStore;
+    providerPause?: () => Promise<void>;
+}
+export interface AgentAccounting {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+export interface AgentToolCallProgress {
+    id: string;
+    name: string;
+    state: "running" | "completed" | "failed";
+}
+export interface AgentActivity {
+    kind: "reasoning" | "tool" | "text";
+    text: string;
+}
+export interface AgentProgress {
+    accounting: AgentAccounting;
+    toolCalls: readonly AgentToolCallProgress[];
+    activity?: AgentActivity;
+    persist: boolean;
+}
+export interface AgentAttempt {
+    attempt: number;
+    sessionId: string;
+    sessionFile: string;
+    result?: JsonValue;
+    error?: {
+        code: string;
+        message: string;
+    };
+    accounting: AgentAccounting;
+}
+export interface AgentExecutionResult {
+    value: JsonValue;
+    attempts: readonly AgentAttempt[];
+    cwd: string;
+}
+export interface NativeSession {
+    readonly sessionId: string;
+    readonly sessionFile: string | undefined;
+    readonly messages: readonly AgentMessage[];
+    readonly systemPrompt?: string;
+    readonly agent?: {
+        state: {
+            tools: readonly {
+                name: string;
+            }[];
+        };
+    };
+    subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
+    prompt(text: string): Promise<void>;
+    steer?(text: string): Promise<void>;
+    abort?(): Promise<void>;
+    dispose(): void;
+}
+export interface SessionInput {
+    cwd: string;
+    model: ModelSpec;
+    tools: readonly string[];
+    sessionLabel: string;
+    agentDir?: string;
+    customTools?: readonly ToolDefinition[];
+    resultTool?: ToolDefinition;
+    systemPromptAppend?: string;
+}
+export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
+export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
+export declare class WorkflowAgentExecutor {
+    private readonly root;
+    private readonly createSession;
+    constructor(root: AgentExecutionRoot, createSession?: SessionFactory);
+    resolve(options: AgentExecutionOptions, inheritedTools?: readonly string[]): {
+        model: ModelSpec;
+        tools: readonly 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>;
+}
+export interface ScheduledAgentOptions {
+    label: string;
+    requestedLabel?: string;
+    parentBreadcrumb?: string;
+    cwd: string;
+    tools: readonly string[];
+    worktreeOwner?: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    role?: string;
+    schema?: JsonSchema;
+    retries?: number;
+    timeoutMs?: number | null;
+}
+export type ScheduledAgentResult = {
+    id: string;
+    ok: true;
+    value: JsonValue;
+} | {
+    id: string;
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface ScheduledAgentInput {
+    id: string;
+    runId: string;
+    parentId?: string;
+    prompt: string;
+    options: Readonly<ScheduledAgentOptions>;
+    signal: AbortSignal;
+    setSteer: (handler: (message: string) => void | Promise<void>) => void;
+}
+export type ScheduledAgentRunner = (input: ScheduledAgentInput) => Promise<JsonValue>;
+type ScheduledNode = {
+    id: string;
+    runId: string;
+    parentId?: string;
+    options: Readonly<ScheduledAgentOptions>;
+    children: Set<string>;
+    collected: boolean;
+    state: "queued" | "running" | "waiting_for_child" | "completed" | "failed" | "cancelled";
+    controller: AbortController;
+    promise: Promise<ScheduledAgentResult>;
+    resolve: (result: ScheduledAgentResult) => void;
+    task: () => Promise<void>;
+    restored: boolean;
+    steer?: (message: string) => void | Promise<void>;
+};
+export type OwnershipRecord = {
+    id: string;
+    parentId?: string;
+    label: string;
+    state: ScheduledNode["state"];
+    options: Readonly<ScheduledAgentOptions>;
+};
+type OwnershipWriter = (runId: string, ownership: readonly OwnershipRecord[]) => void | Promise<void>;
+export declare class FairAgentScheduler {
+    #private;
+    private readonly runner;
+    readonly sessionLimit: number;
+    private readonly writeOwnership?;
+    constructor(runner: ScheduledAgentRunner, sessionLimit?: number, writeOwnership?: OwnershipWriter | undefined);
+    addRun(runId: string, limit?: number, maxAgentLaunches?: number): void;
+    spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
+        id: string;
+        result: Promise<ScheduledAgentResult>;
+    };
+    result(parentId: string, childId: string): Promise<ScheduledAgentResult>;
+    steer(parentId: string, childId: string, message: string): Promise<void>;
+    cancel(id: string): void;
+    cancelChildren(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;
+    flush(): Promise<void>;
+}
+export {};