pi-workflow-engine 0.11.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/model-profile-command.ts

@@ -0,0 +1,167 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+  clearWorkflowModelProfile,
+  isWorkflowModelProfileName,
+  isWorkflowThinkingLevel,
+  resolveWorkflowModelProfiles,
+  setWorkflowModelProfile,
+  workflowModelProfilePaths,
+  WORKFLOW_MODEL_PROFILE_NAMES,
+  WORKFLOW_THINKING_LEVELS,
+  type ResolvedWorkflowModelProfiles,
+  type WorkflowModelProfilePaths,
+  type WorkflowModelProfileName,
+} from "./model-profiles.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
+
+type ConfigScope = "user" | "project";
+
+type WorkflowModelsCommand =
+  | { readonly kind: "status" }
+  | {
+      readonly kind: "set";
+      readonly scope: ConfigScope;
+      readonly profile: WorkflowModelProfileName;
+      readonly model: string;
+      readonly thinkingLevel?: Parameters<typeof setWorkflowModelProfile>[0]["profile"]["thinkingLevel"];
+    }
+  | { readonly kind: "clear"; readonly scope: ConfigScope; readonly profile: WorkflowModelProfileName }
+  | { readonly kind: "error"; readonly message: string };
+
+const USAGE =
+  "Usage: /workflow:models [status | set <small|medium|big> <provider/model> [thinkingLevel] [--user|--project] | clear <small|medium|big> [--user|--project]]";
+const MODEL_COMMAND_ACTIONS = [
+  { value: "status", description: "Show resolved workflow model profiles" },
+  { value: "set", description: "Configure an exact model for a profile" },
+  { value: "clear", description: "Remove a configured profile" },
+] as const;
+const MODEL_COMMAND_SCOPES = [
+  { value: "--user", description: "Write the user-level workflow model config" },
+  { value: "--project", description: "Write the project-level workflow model config" },
+] as const;
+
+export function registerWorkflowModelProfileCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("workflow:models", {
+    description: "Inspect or configure exact small, medium, and big workflow model profiles",
+    getArgumentCompletions: workflowModelProfileArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const command = parseWorkflowModelsCommand(args);
+      if (command.kind === "error") {
+        ctx.ui.notify(`${command.message}\n${USAGE}`, "warning");
+        return;
+      }
+
+      try {
+        const paths = workflowModelProfilePaths(ctx.cwd);
+        if (command.kind === "set") {
+          setWorkflowModelProfile({
+            configPath: paths[command.scope],
+            name: command.profile,
+            profile: {
+              model: command.model,
+              ...(command.thinkingLevel === undefined ? {} : { thinkingLevel: command.thinkingLevel }),
+            },
+            modelRegistry: ctx.modelRegistry,
+          });
+        } else if (command.kind === "clear") {
+          clearWorkflowModelProfile(paths[command.scope], command.profile);
+        }
+
+        const profiles = resolveWorkflowModelProfiles({
+          cwd: ctx.cwd,
+          modelRegistry: ctx.modelRegistry,
+          hostModel: ctx.model,
+          paths,
+        });
+        const prefix = command.kind === "status"
+          ? "Workflow model profiles"
+          : `${command.profile} ${command.kind === "set" ? "updated" : "cleared"} in ${command.scope} config`;
+        ctx.ui.notify(`${prefix}\n${formatWorkflowModelProfiles(profiles, paths)}`, "info");
+      } catch (error) {
+        ctx.ui.notify(unknownErrorMessage(error), "error");
+      }
+    },
+  });
+}
+
+export function workflowModelProfileArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+  const parts = splitArgumentPrefix(argumentPrefix);
+  const completedWithoutScopes = parts.completed.filter((token) => token !== "--user" && token !== "--project");
+  const action = completedWithoutScopes[0];
+  const scopes = parts.completed.some((token) => token === "--user" || token === "--project")
+    ? []
+    : MODEL_COMMAND_SCOPES;
+
+  if (completedWithoutScopes.length === 0) {
+    return completeCurrentArgument(argumentPrefix, MODEL_COMMAND_ACTIONS);
+  }
+  if (action === "status") return null;
+  if (completedWithoutScopes.length === 1) {
+    return completeCurrentArgument(
+      argumentPrefix,
+      WORKFLOW_MODEL_PROFILE_NAMES.map((value) => ({ value, description: `${value} workflow model profile` })),
+    );
+  }
+  if (action === "clear") return completeCurrentArgument(argumentPrefix, scopes);
+  if (action !== "set") return null;
+
+  if (completedWithoutScopes.length === 2) {
+    return null;
+  }
+  if (completedWithoutScopes.length === 3) {
+    return completeCurrentArgument(argumentPrefix, [
+      ...WORKFLOW_THINKING_LEVELS.map((value) => ({ value, description: "Thinking level" })),
+      ...scopes,
+    ]);
+  }
+  return completeCurrentArgument(argumentPrefix, scopes);
+}
+
+export function parseWorkflowModelsCommand(args: string): WorkflowModelsCommand {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === "status")) return { kind: "status" };
+
+  const userScope = tokens.includes("--user");
+  const projectScope = tokens.includes("--project");
+  if (userScope && projectScope) return { kind: "error", message: "Choose either --user or --project, not both." };
+  const scope: ConfigScope = projectScope ? "project" : "user";
+  const positional = tokens.filter((token) => token !== "--user" && token !== "--project");
+  const [action, profile, model, thinkingLevel, ...extra] = positional;
+  if (extra.length > 0) return { kind: "error", message: "Too many /workflow:models arguments." };
+  if (!profile || !isWorkflowModelProfileName(profile)) {
+    return { kind: "error", message: "Profile must be small, medium, or big." };
+  }
+
+  if (action === "clear") {
+    if (model !== undefined) return { kind: "error", message: "The clear action accepts only a profile and optional scope." };
+    return { kind: "clear", scope, profile };
+  }
+  if (action !== "set") return { kind: "error", message: `Unknown /workflow:models action "${action ?? ""}".` };
+  if (!model) return { kind: "error", message: "The set action requires an exact provider/model identity." };
+  if (thinkingLevel !== undefined && !isWorkflowThinkingLevel(thinkingLevel)) {
+    return { kind: "error", message: "Thinking level must be off, minimal, low, medium, high, xhigh, or max." };
+  }
+  return {
+    kind: "set",
+    scope,
+    profile,
+    model,
+    ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+  };
+}
+
+function formatWorkflowModelProfiles(
+  profiles: ResolvedWorkflowModelProfiles,
+  paths: WorkflowModelProfilePaths,
+): string {
+  const lines = WORKFLOW_MODEL_PROFILE_NAMES.map((name) => {
+    const profile = profiles[name];
+    const model = profile.model ? `${profile.model.provider}/${profile.model.id}` : "(no host model)";
+    const thinking = profile.thinkingLevel ?? "host";
+    const source = profile.source === "host" ? "host fallback" : `${profile.source}: ${profile.configPath}`;
+    return `${name}: ${model} · thinking ${thinking} · ${source}`;
+  });
+  return [...lines, `user: ${paths.user}`, `project: ${paths.project} (overrides user)`].join("\n");
+}

package/.pi/extensions/pi-workflow-engine/src/model-profiles.ts

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { isMissingPathError } from "./filesystem-error.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export const WORKFLOW_MODEL_PROFILE_NAMES = ["small", "medium", "big"] as const;
+export type WorkflowModelProfileName = (typeof WORKFLOW_MODEL_PROFILE_NAMES)[number];
+
+export interface WorkflowModelProfileConfig {
+  readonly model: string;
+  readonly thinkingLevel?: ThinkingLevel;
+}
+
+export interface WorkflowModelProfileFile {
+  readonly profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>>;
+}
+
+export interface WorkflowModelProfilePaths {
+  readonly user: string;
+  readonly project: string;
+}
+
+interface ResolvedWorkflowModelProfileBase {
+  readonly name: WorkflowModelProfileName;
+  readonly model: Model<Api> | undefined;
+  readonly thinkingLevel: ThinkingLevel | undefined;
+}
+
+export type ResolvedWorkflowModelProfile = ResolvedWorkflowModelProfileBase & (
+  | { readonly source: "host" }
+  | { readonly source: "project" | "user"; readonly configPath: string }
+);
+
+export type ResolvedWorkflowModelProfiles = Readonly<Record<WorkflowModelProfileName, ResolvedWorkflowModelProfile>>;
+
+export interface WorkflowModelRouteRequest {
+  readonly model?: string;
+  readonly thinkingLevel?: ThinkingLevel;
+  readonly profile?: WorkflowModelProfileName;
+}
+
+export class WorkflowModelProfileConfigError extends Error {
+  override readonly name = "WorkflowModelProfileConfigError";
+  readonly code = "WORKFLOW_MODEL_PROFILE_CONFIG";
+
+  constructor(
+    message: string,
+    readonly configPath: string,
+    readonly profile?: WorkflowModelProfileName,
+  ) {
+    super(message);
+  }
+}
+
+export const WORKFLOW_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly ThinkingLevel[];
+const THINKING_LEVELS = new Set<ThinkingLevel>(WORKFLOW_THINKING_LEVELS);
+const HOST_FALLBACK_THINKING: Record<WorkflowModelProfileName, ThinkingLevel> = {
+  small: "low",
+  medium: "medium",
+  big: "high",
+};
+const CONFIG_FILE_NAME = "workflow-models.json";
+
+export function workflowModelProfilePaths(
+  cwd: string,
+  agentDir: string = getAgentDir(),
+): WorkflowModelProfilePaths {
+  return {
+    user: join(agentDir, CONFIG_FILE_NAME),
+    project: join(cwd, ".pi", CONFIG_FILE_NAME),
+  };
+}
+
+export function resolveWorkflowModelProfiles(input: {
+  readonly cwd: string;
+  readonly modelRegistry: Pick<ModelRegistry, "find">;
+  readonly hostModel: Model<Api> | undefined;
+  readonly paths?: WorkflowModelProfilePaths;
+}): ResolvedWorkflowModelProfiles {
+  const paths = input.paths ?? workflowModelProfilePaths(input.cwd);
+  const user = readWorkflowModelProfileFile(paths.user);
+  const project = readWorkflowModelProfileFile(paths.project);
+  const resolved = { ...hostWorkflowModelProfiles(input.hostModel) };
+
+  for (const name of WORKFLOW_MODEL_PROFILE_NAMES) {
+    const projectProfile = project.profiles[name];
+    const configured = projectProfile ?? user.profiles[name];
+    if (!configured) continue;
+
+    const source = projectProfile ? "project" : "user";
+    const configPath = paths[source];
+    resolved[name] = {
+      name,
+      model: resolveConfiguredModel(name, configured.model, input.modelRegistry, configPath),
+      thinkingLevel: configured.thinkingLevel,
+      source,
+      configPath,
+    };
+  }
+
+  return resolved;
+}
+
+export function hostWorkflowModelProfiles(
+  hostModel: Model<Api> | undefined,
+): ResolvedWorkflowModelProfiles {
+  return {
+    small: { name: "small", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.small, source: "host" },
+    medium: { name: "medium", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.medium, source: "host" },
+    big: { name: "big", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.big, source: "host" },
+  };
+}
+
+export function resolveAgentModelProfile(
+  input: {
+    readonly request: WorkflowModelRouteRequest;
+    readonly profiles: ResolvedWorkflowModelProfiles;
+    readonly resolveExplicitModel: (modelRef: string) => Model<Api> | undefined;
+    readonly hostModel: Model<Api> | undefined;
+  },
+): { readonly model: Model<Api> | undefined; readonly thinkingLevel: ThinkingLevel | undefined } {
+  const profile = input.request.profile === undefined
+    ? undefined
+    : input.profiles[assertWorkflowModelProfileName(input.request.profile)];
+  return {
+    model: input.request.model === undefined
+      ? (profile?.model ?? input.hostModel)
+      : input.resolveExplicitModel(input.request.model),
+    thinkingLevel: input.request.thinkingLevel ?? profile?.thinkingLevel,
+  };
+}
+
+export function readWorkflowModelProfileFile(configPath: string): WorkflowModelProfileFile {
+  let contents: string;
+  try {
+    contents = readFileSync(configPath, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return { profiles: {} };
+    throw new WorkflowModelProfileConfigError(
+      `Could not read workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix the file permissions or remove the file.`,
+      configPath,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error) {
+    throw new WorkflowModelProfileConfigError(
+      `Invalid JSON in workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix or remove the file.`,
+      configPath,
+    );
+  }
+  return parseWorkflowModelProfileFile(parsed, configPath);
+}
+
+export function setWorkflowModelProfile(input: {
+  readonly configPath: string;
+  readonly name: WorkflowModelProfileName;
+  readonly profile: WorkflowModelProfileConfig;
+  readonly modelRegistry: Pick<ModelRegistry, "find">;
+}): void {
+  const current = readWorkflowModelProfileFile(input.configPath);
+  const next = { ...current.profiles, [input.name]: input.profile };
+  for (const name of WORKFLOW_MODEL_PROFILE_NAMES) {
+    const profile = next[name];
+    if (profile) resolveConfiguredModel(name, profile.model, input.modelRegistry, input.configPath);
+  }
+  writeWorkflowModelProfileFile(input.configPath, { profiles: next });
+}
+
+export function clearWorkflowModelProfile(configPath: string, name: WorkflowModelProfileName): void {
+  const current = readWorkflowModelProfileFile(configPath);
+  if (!current.profiles[name]) return;
+  const profiles = { ...current.profiles };
+  delete profiles[name];
+  writeWorkflowModelProfileFile(configPath, { profiles });
+}
+
+export function isWorkflowModelProfileName(value: string): value is WorkflowModelProfileName {
+  return WORKFLOW_MODEL_PROFILE_NAMES.includes(value as WorkflowModelProfileName);
+}
+
+export function isWorkflowThinkingLevel(value: string): value is ThinkingLevel {
+  return THINKING_LEVELS.has(value as ThinkingLevel);
+}
+
+function parseWorkflowModelProfileFile(value: unknown, configPath: string): WorkflowModelProfileFile {
+  if (!isRecord(value)) throw invalidConfig(configPath, "the root must be an object");
+  assertOnlyKeys(value, ["profiles"], configPath);
+  if (!isRecord(value.profiles)) throw invalidConfig(configPath, '"profiles" must be an object');
+
+  const profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>> = {};
+  for (const [name, profile] of Object.entries(value.profiles)) {
+    if (!isWorkflowModelProfileName(name)) {
+      throw invalidConfig(configPath, `unknown profile "${name}"; expected small, medium, or big`);
+    }
+    if (!isRecord(profile)) throw invalidConfig(configPath, `profile "${name}" must be an object`, name);
+    assertOnlyKeys(profile, ["model", "thinkingLevel"], configPath, name);
+    if (typeof profile.model !== "string") {
+      throw invalidConfig(configPath, `profile "${name}" requires a provider-qualified "model" string`, name);
+    }
+    assertThinkingLevel(profile.thinkingLevel, configPath, name);
+    profiles[name] = {
+      model: profile.model,
+      ...(profile.thinkingLevel === undefined ? {} : { thinkingLevel: profile.thinkingLevel }),
+    };
+  }
+  return { profiles };
+}
+
+function resolveConfiguredModel(
+  name: WorkflowModelProfileName,
+  modelRef: string,
+  modelRegistry: Pick<ModelRegistry, "find">,
+  configPath: string,
+): Model<Api> {
+  const slash = modelRef.indexOf("/");
+  if (modelRef.trim() !== modelRef || slash <= 0 || slash === modelRef.length - 1) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" model must be an exact provider/model identity; received "${modelRef}"`,
+      name,
+    );
+  }
+  const provider = modelRef.slice(0, slash);
+  const modelId = modelRef.slice(slash + 1);
+  if (/\s/.test(provider) || modelId.startsWith("/") || modelId.endsWith("/") || /\s/.test(modelId)) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" model must be an exact provider/model identity; received "${modelRef}"`,
+      name,
+    );
+  }
+  const model = modelRegistry.find(provider, modelId);
+  if (!model) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" references unavailable model "${modelRef}"; choose an exact model shown by /model and update it with /workflow:models set ${name} provider/model`,
+      name,
+    );
+  }
+  return model;
+}
+
+function assertWorkflowModelProfileName(value: string): WorkflowModelProfileName {
+  if (isWorkflowModelProfileName(value)) return value;
+  throw new Error(`Unknown workflow model profile "${value}"; expected small, medium, or big.`);
+}
+
+function assertThinkingLevel(
+  value: unknown,
+  configPath: string,
+  profile: WorkflowModelProfileName,
+): asserts value is ThinkingLevel | undefined {
+  if (value === undefined || (typeof value === "string" && isWorkflowThinkingLevel(value))) return;
+  throw invalidConfig(
+    configPath,
+    `profile "${profile}" thinkingLevel must be off, minimal, low, medium, high, xhigh, or max`,
+    profile,
+  );
+}
+
+function assertOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  configPath: string,
+  profile?: WorkflowModelProfileName,
+): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unexpected) throw invalidConfig(configPath, `unexpected key "${unexpected}"`, profile);
+}
+
+function writeWorkflowModelProfileFile(configPath: string, config: WorkflowModelProfileFile): void {
+  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    renameSync(temporaryPath, configPath);
+  } catch (error) {
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // Best effort: preserve the original write error.
+    }
+    throw new WorkflowModelProfileConfigError(
+      `Could not write workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}.`,
+      configPath,
+    );
+  }
+}
+
+function invalidConfig(
+  configPath: string,
+  reason: string,
+  profile?: WorkflowModelProfileName,
+): WorkflowModelProfileConfigError {
+  return new WorkflowModelProfileConfigError(
+    `Invalid workflow model profile config at ${configPath}: ${reason}.`,
+    configPath,
+    profile,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/.pi/extensions/pi-workflow-engine/src/options.ts

@@ -3,14 +3,48 @@ import type { WorkflowRunOptions } from "./types.ts";
 
 export const WORKFLOW_BUDGET_MIN = 1;
 export const WORKFLOW_BUDGET_MAX = 1_000_000_000;
+export const WORKFLOW_MAX_AGENTS_MIN = 1;
+export const WORKFLOW_MAX_AGENTS_MAX = 10_000;
+export const DEFAULT_WORKFLOW_MAX_AGENTS = 64;
+export const WORKFLOW_AGENT_TIMEOUT_MIN_MS = 1_000;
+export const WORKFLOW_AGENT_TIMEOUT_MAX_MS = 86_400_000;
+export const DEFAULT_WORKFLOW_AGENT_TIMEOUT_MS = 1_800_000;
+export const WORKFLOW_AGENT_RETRIES_MIN = 0;
+export const WORKFLOW_AGENT_RETRIES_MAX = 10;
+export const DEFAULT_WORKFLOW_AGENT_RETRIES = 0;
+export const WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN = 1;
+export const WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX = 10;
+export const DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS = 3;
+export const WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS = 5_000;
+export const WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS = 86_400_000;
+export const DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS = 21_600_000;
 
 export type ResolvedWorkflowRunOptions = Omit<
   WorkflowRunOptions,
-  "perf" | "concurrency" | "parallelSubmissionLimit" | "budget"
+  | "perf"
+  | "concurrency"
+  | "parallelSubmissionLimit"
+  | "maxAgents"
+  | "agentTimeoutMs"
+  | "agentRetries"
+  | "autoResumeOnUsageLimit"
+  | "usageLimitMaxAttempts"
+  | "usageLimitMaxDelayMs"
+  | "usageLimitAttempt"
+  | "resumeEditedWorkflow"
+  | "budget"
 > & {
   readonly perf: boolean;
   readonly concurrency: number;
   readonly parallelSubmissionLimit: number | null;
+  readonly maxAgents: number;
+  readonly agentTimeoutMs: number;
+  readonly agentRetries: number;
+  readonly autoResumeOnUsageLimit: boolean;
+  readonly usageLimitMaxAttempts: number;
+  readonly usageLimitMaxDelayMs: number;
+  readonly usageLimitAttempt: number;
+  readonly resumeEditedWorkflow: boolean;
   readonly budget: number | null;
 };
 
@@ -28,16 +62,63 @@ export function resolveWorkflowRunOptions(
     1,
     10_000,
   );
+  const maxAgents = clampInteger(
+    input.maxAgents ?? parseWorkflowIntegerString(env.PI_WORKFLOW_MAX_AGENTS),
+    WORKFLOW_MAX_AGENTS_MIN,
+    WORKFLOW_MAX_AGENTS_MAX,
+    DEFAULT_WORKFLOW_MAX_AGENTS,
+  );
+  const agentTimeoutMs = clampInteger(
+    input.agentTimeoutMs ?? parseWorkflowIntegerString(env.PI_WORKFLOW_AGENT_TIMEOUT_MS),
+    WORKFLOW_AGENT_TIMEOUT_MIN_MS,
+    WORKFLOW_AGENT_TIMEOUT_MAX_MS,
+    DEFAULT_WORKFLOW_AGENT_TIMEOUT_MS,
+  );
+  const agentRetries = clampInteger(
+    input.agentRetries ?? parseWorkflowIntegerString(env.PI_WORKFLOW_AGENT_RETRIES),
+    WORKFLOW_AGENT_RETRIES_MIN,
+    WORKFLOW_AGENT_RETRIES_MAX,
+    DEFAULT_WORKFLOW_AGENT_RETRIES,
+  );
   const budget = resolveBudget(input.budget, env.PI_WORKFLOW_BUDGET);
+  const usageLimitMaxAttempts = clampInteger(
+    input.usageLimitMaxAttempts ?? parseWorkflowIntegerString(env.PI_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS),
+    WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN,
+    WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+    DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS,
+  );
+  const usageLimitMaxDelayMs = clampInteger(
+    input.usageLimitMaxDelayMs ?? parseWorkflowIntegerString(env.PI_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS),
+    WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+    WORKFLOW_USAGE_LIMIT_DELAY_MAX_MS,
+    DEFAULT_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS,
+  );
   return {
     ...input,
     perf: input.perf ?? env.PI_WORKFLOW_PERF === "1",
     concurrency,
     parallelSubmissionLimit: parallelSubmissionLimit ?? null,
+    maxAgents,
+    agentTimeoutMs,
+    agentRetries,
+    autoResumeOnUsageLimit: input.autoResumeOnUsageLimit ?? env.PI_WORKFLOW_USAGE_LIMIT_AUTO_RESUME === "1",
+    usageLimitMaxAttempts,
+    usageLimitMaxDelayMs,
+    usageLimitAttempt: clampInteger(
+      input.usageLimitAttempt,
+      0,
+      WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
+      0,
+    ),
+    resumeEditedWorkflow: input.resumeEditedWorkflow === true && hasResumeRunId(input.resumeFromRunId),
     budget: budget ?? null,
   };
 }
 
+function hasResumeRunId(value: string | undefined): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
 function optionalClampedInteger(value: number | undefined, min: number, max: number): number | undefined {
   if (value === undefined || !Number.isFinite(value)) return undefined;
   return clampInteger(value, min, max, value);
@@ -54,6 +135,12 @@ function parseInteger(value: string | undefined): number | undefined {
   return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
 }
 
+export function parseWorkflowIntegerString(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
 function resolveBudget(inputBudget: number | undefined, envBudget: string | undefined): number | undefined {
   if (inputBudget !== undefined) return normalizeExplicitBudget(inputBudget);
   return envBudget === undefined ? undefined : parseWorkflowBudgetString(envBudget);

package/.pi/extensions/pi-workflow-engine/src/pi-compat.ts

@@ -0,0 +1,32 @@
+const MINIMUM_PI_VERSION = "0.80.10";
+
+const MINIMUM_PI_CORE = [0, 80, 10] as const;
+
+/** Fail during extension registration instead of failing later in a workflow. */
+export function assertSupportedPiVersion(version: string): void {
+  const core = parseVersionCore(version);
+  if (!core || compareVersionCore(core, MINIMUM_PI_CORE) < 0) {
+    throw new Error(
+      `pi-workflow-engine requires pi ${MINIMUM_PI_VERSION} or newer; detected ${JSON.stringify(version)}. Update pi before loading this extension.`,
+    );
+  }
+}
+
+function parseVersionCore(version: string): readonly [number, number, number] | undefined {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+  if (!match) return undefined;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  if (![major, minor, patch].every(Number.isSafeInteger)) return undefined;
+  return [major, minor, patch];
+}
+
+function compareVersionCore(
+  left: readonly [number, number, number],
+  right: readonly [number, number, number],
+): number {
+  const [leftMajor, leftMinor, leftPatch] = left;
+  const [rightMajor, rightMinor, rightPatch] = right;
+  return leftMajor - rightMajor || leftMinor - rightMinor || leftPatch - rightPatch;
+}

package/.pi/extensions/pi-workflow-engine/src/progress-types.ts

@@ -0,0 +1,50 @@
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
+
+export interface AgentRowSnapshot {
+  readonly id: number;
+  readonly label: string;
+  readonly status: AgentRowStatus;
+  readonly startedAt?: number;
+  readonly doneAt?: number;
+  readonly toolUses: number;
+  readonly lastTool?: string;
+  readonly error?: string;
+}
+
+export interface PhaseSnapshot {
+  readonly title: string;
+  readonly agents: readonly AgentRowSnapshot[];
+}
+
+export interface WorkflowCounterSnapshot {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+}
+
+export interface WorkflowLaneItemSnapshot {
+  readonly lane: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly status: WorkflowLaneItemStatus;
+  readonly details?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowProgressSnapshot {
+  readonly runId: string;
+  readonly title: string;
+  readonly startedAt: number;
+  readonly doneAt?: number;
+  readonly currentPhase: string;
+  readonly phases: readonly PhaseSnapshot[];
+  readonly counters: readonly WorkflowCounterSnapshot[];
+  readonly summary: readonly [string, string | number][];
+  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
+  readonly laneOverflow: readonly [string, number][];
+  readonly logs: readonly string[];
+  readonly usage?: WorkflowUsageSnapshot;
+}