pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/agent-retry.ts

@@ -0,0 +1,116 @@
+import { isRetryableAssistantError, type AssistantMessage } from "@earendil-works/pi-ai";
+import { abortReason, throwIfAborted } from "./cancellation.ts";
+import {
+  providerUsageLimitFromMessages,
+  type WorkflowProviderUsageLimitError,
+} from "./provider-usage-limit.ts";
+
+export const AGENT_RETRY_BASE_DELAY_MS = 1_000;
+export const AGENT_RETRY_MAX_DELAY_MS = 30_000;
+export const WORKFLOW_PROVIDER_ERROR_CODE = "WORKFLOW_PROVIDER_ERROR";
+
+export interface AgentRetryScheduler {
+  sleep(delayMs: number, signal: AbortSignal | undefined): Promise<void>;
+}
+
+export interface ProviderErrorDetails {
+  readonly stopReason: "error";
+  readonly retryable: boolean;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly api?: string;
+}
+
+/** Provider failure reconstructed from pi's terminal assistant-message metadata. */
+export class WorkflowProviderError extends Error {
+  override readonly name = "WorkflowProviderError";
+  readonly code = WORKFLOW_PROVIDER_ERROR_CODE;
+
+  constructor(
+    message: string,
+    readonly details: ProviderErrorDetails,
+  ) {
+    super(message);
+  }
+
+  get retryable(): boolean {
+    return this.details.retryable;
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: ProviderErrorDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}
+
+export const defaultAgentRetryScheduler: AgentRetryScheduler = {
+  async sleep(delayMs, signal) {
+    throwIfAborted(signal);
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => signal?.removeEventListener("abort", onAbort);
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, delayMs);
+      const onAbort = () => {
+        clearTimeout(timer);
+        cleanup();
+        reject(abortReason(signal));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  },
+};
+
+export function agentRetryDelayMs(retryAttempt: number): number {
+  return Math.min(AGENT_RETRY_MAX_DELAY_MS, AGENT_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, retryAttempt - 1));
+}
+
+export function providerErrorFromMessages(
+  messages: readonly unknown[],
+  options: { readonly pauseOnUsageLimit?: boolean } = {},
+): WorkflowProviderError | WorkflowProviderUsageLimitError | undefined {
+  const usageLimit = providerUsageLimitFromMessages(messages);
+  if (usageLimit && options.pauseOnUsageLimit) return usageLimit;
+  const message = messages.findLast(isAssistantMessage);
+  if (!message || message.stopReason !== "error") return undefined;
+  const errorMessage = typeof message.errorMessage === "string" && message.errorMessage.length > 0
+    ? message.errorMessage
+    : "Provider session ended with an unspecified error.";
+  const retryable = isRetryableAssistantError(message as AssistantMessage);
+  const provider = stringDetail(message.provider);
+  const model = stringDetail(message.model);
+  const api = stringDetail(message.api);
+  return new WorkflowProviderError(errorMessage, {
+    stopReason: "error",
+    retryable,
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(api ? { api } : {}),
+  });
+}
+
+function isAssistantMessage(value: unknown): value is {
+  readonly role: "assistant";
+  readonly stopReason?: unknown;
+  readonly errorMessage?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly api?: unknown;
+} {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "role" in value &&
+    value.role === "assistant"
+  );
+}
+
+function stringDetail(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/agent-runner-types.ts

@@ -0,0 +1,91 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type {
+  AgentSession,
+  CreateAgentSessionOptions,
+  ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+import type { WorkflowBudget } from "./budget.ts";
+import type { Semaphore } from "./concurrency.ts";
+import type { WorkflowAgentLimiter } from "./agent-limits.ts";
+import type { AgentRetryScheduler } from "./agent-retry.ts";
+import type { ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
+import type { WorkflowJournal } from "./journal.ts";
+import type { PerfSink } from "./perf.ts";
+import type { AgentOptions, WorkflowProgressEvent } from "./types.ts";
+import type { WorkflowUsageSink } from "./usage.ts";
+import type { WorktreeBaseline, WorktreeRegistry } from "./worktree.ts";
+
+export type AgentRunnerSession = Pick<
+  AgentSession,
+  | "messages"
+  | "systemPrompt"
+  | "model"
+  | "thinkingLevel"
+  | "prompt"
+  | "subscribe"
+  | "dispose"
+  | "abort"
+  | "getAllTools"
+  | "getActiveToolNames"
+  | "getToolDefinition"
+  | "setActiveToolsByName"
+  | "setAutoRetryEnabled"
+  | "getLastAssistantText"
+>;
+
+export type CreateAgentSession = (options: CreateAgentSessionOptions) => Promise<{ session: AgentRunnerSession }>;
+
+export interface AgentProgress {
+  agentQueued(phase: string | undefined, label: string): number;
+  agentStart(phase: string | undefined, label: string, id?: number): void;
+  agentTool(label: string, tool: string, id?: number): void;
+  agentDone(label: string, id?: number): void;
+  agentFailed(label: string, error: unknown, id?: number): void;
+  event(event: WorkflowProgressEvent): void;
+  log(message: string): void;
+}
+
+interface RunContextBase {
+  cwd: string;
+  hostModel: Model<Api> | undefined;
+  semaphore: Semaphore;
+  agentLimiter: WorkflowAgentLimiter;
+  agentTimeoutMs: number;
+  agentRetries: number;
+  pauseOnProviderUsageLimit?: boolean;
+  resumeEditedWorkflow?: boolean;
+  retryScheduler: AgentRetryScheduler;
+  modelProfiles: ResolvedWorkflowModelProfiles;
+  progress: AgentProgress;
+  signal: AbortSignal | undefined;
+  perf: PerfSink;
+  usage: WorkflowUsageSink;
+  budget: WorkflowBudget;
+  journal: WorkflowJournal;
+  worktrees: WorktreeRegistry;
+}
+
+/** Shared per-run context threaded into every agent() call. */
+export type RunContext = RunContextBase & (
+  | {
+      /** Production sessions inherit the host's live provider and auth state. */
+      modelRegistry: ModelRegistry;
+      createSession?: undefined;
+    }
+  | {
+      /** Injected test sessions bypass Pi's resource loader and therefore do not resolve skills. */
+      modelRegistry: Pick<ModelRegistry, "find">;
+      createSession: CreateAgentSession;
+    }
+);
+
+/** Runtime-only options. The authored WorkflowApi exposes only AgentOptions. */
+export type AgentExecutionOptions = AgentOptions & {
+  readonly worktreeBaseline?: WorktreeBaseline;
+};
+
+export interface AgentRunTags {
+  readonly [key: string]: string | number;
+  readonly label: string;
+  readonly phase: string;
+}