@wichayutdew/pi-workflows 2.5.1 → 2.7.0

package/src/agents/profile.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { defaultUserWorkflowDirectory } from '../config/load.ts';
+
+export const THINKING_LEVELS = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+] as const;
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export type AgentProfile = {
+  readonly prompt: string;
+  readonly model?: string;
+  readonly thinking?: ThinkingLevel;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Parses the optional YAML frontmatter and role prompt in one agent profile. */
+export function parseAgentProfile(source: string, name: string): AgentProfile {
+  if (!source.startsWith('---\n')) return { prompt: source.trim() };
+  const end = source.indexOf('\n---\n', 4);
+  if (end === -1) {
+    throw new Error(`workflow agent profile is invalid: ${name}`);
+  }
+  const metadata: unknown = parse(source.slice(4, end));
+  if (!isRecord(metadata)) {
+    throw new Error(
+      `workflow agent profile metadata must be an object: ${name}`,
+    );
+  }
+  const unknownKey = Object.keys(metadata).find(
+    (key) => key !== 'model' && key !== 'thinking',
+  );
+  if (unknownKey) {
+    throw new Error(
+      `workflow agent profile has unknown metadata "${unknownKey}": ${name}`,
+    );
+  }
+  const model = metadata.model;
+  if (model !== undefined && (typeof model !== 'string' || !model.trim())) {
+    throw new Error(
+      `workflow agent profile model must be a non-empty string: ${name}`,
+    );
+  }
+  const thinking = metadata.thinking;
+  if (
+    thinking !== undefined &&
+    (typeof thinking !== 'string' ||
+      !THINKING_LEVELS.includes(thinking as ThinkingLevel))
+  ) {
+    throw new Error(
+      `workflow agent profile thinking must be one of ${THINKING_LEVELS.join(', ')}: ${name}`,
+    );
+  }
+  const prompt = source.slice(end + 5).trim();
+  if (!prompt)
+    throw new Error(`workflow agent profile prompt is empty: ${name}`);
+  return {
+    prompt,
+    ...(typeof model === 'string' ? { model: model.trim() } : {}),
+    ...(typeof thinking === 'string'
+      ? { thinking: thinking as ThinkingLevel }
+      : {}),
+  };
+}
+
+/** Loads a user-owned agent profile, with a bundled prompt-only fallback. */
+export function loadAgentProfile(
+  name: string,
+  userDirectory = defaultUserWorkflowDirectory(),
+): AgentProfile {
+  const userPath = join(userDirectory, 'agents', `${name}.md`);
+  const bundledUrl = new URL(
+    `../../examples/starter-kit/agents/${name}.md`,
+    import.meta.url,
+  );
+  const path = existsSync(userPath) ? userPath : fileURLToPath(bundledUrl);
+  try {
+    return parseAgentProfile(readFileSync(path, 'utf8'), name);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('workflow agent')) {
+      throw error;
+    }
+    throw new Error(`workflow agent profile is unavailable: ${name}`, {
+      cause: error,
+    });
+  }
+}

package/src/config/ceiling.ts

@@ -2,8 +2,6 @@ import type {
   BashPermission,
   BashRule,
   PermissionCeiling,
-  StepSubagent,
-  SubagentPermissionCeiling,
   WorkflowDefinition,
 } from './types.ts';
 
@@ -34,81 +32,6 @@ function bashWithinCeiling(
   return requested.allow.every((rule) => allowedRules.has(ruleKey(rule)));
 }
 
-function turnBudgetErrors(
-  subagent: StepSubagent,
-  ceiling: SubagentPermissionCeiling,
-  path: string,
-): Array<string> {
-  if (!subagent.turnBudget) {
-    return [`${path}.turnBudget: required for a project workflow`];
-  }
-  return [
-    ...(subagent.turnBudget.maxTurns > ceiling.maxTurns
-      ? [`${path}.turnBudget.maxTurns: exceeds the user permission ceiling`]
-      : []),
-    ...((subagent.turnBudget.graceTurns ?? 0) > ceiling.maxGraceTurns
-      ? [`${path}.turnBudget.graceTurns: exceeds the user permission ceiling`]
-      : []),
-  ];
-}
-
-function toolBudgetErrors(
-  subagent: StepSubagent,
-  ceiling: SubagentPermissionCeiling,
-  path: string,
-): Array<string> {
-  if (!subagent.toolBudget) {
-    return [`${path}.toolBudget: required for a project workflow`];
-  }
-  return [
-    ...(subagent.toolBudget.hard > ceiling.maxToolCalls
-      ? [`${path}.toolBudget.hard: exceeds the user permission ceiling`]
-      : []),
-    ...(subagent.toolBudget.block !== '*'
-      ? [`${path}.toolBudget.block: must be "*" for a project workflow`]
-      : []),
-  ];
-}
-
-function subagentErrors(
-  subagent: StepSubagent | undefined,
-  ceiling: SubagentPermissionCeiling | undefined,
-  path: string,
-): Array<string> {
-  if (!subagent) return [];
-  if (!ceiling) {
-    return [`${path}: subagent execution exceeds the user permission ceiling`];
-  }
-  return [
-    ...(!ceiling.agents.includes(subagent.agent)
-      ? [
-          `${path}.agent: "${subagent.agent}" exceeds the user permission ceiling`,
-        ]
-      : []),
-    ...(!ceiling.contexts.includes(subagent.context)
-      ? [
-          `${path}.context: "${subagent.context}" exceeds the user permission ceiling`,
-        ]
-      : []),
-    ...(subagent.model && !ceiling.models.includes(subagent.model)
-      ? [
-          `${path}.model: "${subagent.model}" exceeds the user permission ceiling`,
-        ]
-      : []),
-    ...(subagent.timeoutMs > ceiling.maxTimeoutMs
-      ? [`${path}.timeoutMs: exceeds the user permission ceiling`]
-      : []),
-    ...(subagent.artifacts && !ceiling.artifacts
-      ? [`${path}.artifacts: exceeds the user permission ceiling`]
-      : []),
-    ...(subagent.retryToolFailures && !ceiling.retryToolFailures
-      ? [`${path}.retryToolFailures: exceeds the user permission ceiling`]
-      : []),
-    ...turnBudgetErrors(subagent, ceiling, path),
-    ...toolBudgetErrors(subagent, ceiling, path),
-  ];
-}
-
 /** Return every project-workflow permission that exceeds the user ceiling. */
 export function checkWorkflowAgainstCeiling(
   workflow: WorkflowDefinition,
@@ -149,11 +72,6 @@ export function checkWorkflowAgainstCeiling(
       ...(!bashWithinCeiling(step.permissions.bash, ceiling.bash)
         ? [`${path}.bash: exceeds the user permission ceiling`]
         : []),
-      ...subagentErrors(
-        step.subagent,
-        ceiling.subagent,
-        `workflow.steps.${stepId}.subagent`,
-      ),
     ];
   });
 }

package/src/config/types.ts

@@ -2,7 +2,7 @@ import type { KeyId } from '@earendil-works/pi-tui';
 
 export const WORKFLOW_SCHEMA_VERSION = 1 as const;
 export const DEFAULT_STATUS_SHORTCUT = 'ctrl+alt+w' as const satisfies KeyId;
-export const SUBAGENT_RUNTIME_NAME_PATTERN =
+export const AGENT_PROFILE_NAME_PATTERN =
   /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
 export const MAX_WORKSPACE_PATH_CHARS = 4_096;
 export const MAX_WORKSPACE_ALLOWED_ROOTS = 32;
@@ -41,44 +41,27 @@ export type StepRequirements = {
   readonly skills: ReadonlyArray<string>;
 };
 
-export type SubagentContext = 'fresh';
-
-export type SubagentTurnBudget = {
-  readonly maxTurns: number;
-  readonly graceTurns?: number;
-};
-
-export type SubagentToolBudget = {
-  readonly hard: number;
-  readonly soft?: number;
-  readonly block?: ReadonlyArray<string> | '*';
-};
-
-export type StepSubagent = {
-  /** Pi Subagents agent profile launched for this isolated step. */
-  readonly agent: string;
-  /** Workflow steps always use a fresh context. */
-  readonly context: SubagentContext;
-  readonly model?: string;
-  readonly timeoutMs: number;
-  readonly turnBudget?: SubagentTurnBudget;
-  readonly toolBudget?: SubagentToolBudget;
-  readonly artifacts: boolean;
-  /**
-   * Authorizes bounded automatic recovery when Bash can execute commands.
-   * Every failed attempt must still have a complete, mutation-safe replay
-   * audit.
-   */
-  readonly retryToolFailures: boolean;
+export type StepAgent = {
+  /** Workflow-owned role prompt applied to this main-agent step. */
+  readonly name: string;
 };
 
 export type PromptSpec =
   { readonly inline: string } | { readonly file: string };
 
+export type ArtifactContract = {
+  readonly maxChars: number;
+  readonly requiredSubstrings: ReadonlyArray<string>;
+  readonly forbiddenSubstrings: ReadonlyArray<string>;
+  readonly equalOccurrenceGroups: ReadonlyArray<ReadonlyArray<string>>;
+  readonly onValidationFailure?: 'retry';
+};
+
 type GateDefinition = {
   readonly submitOutcome: string;
   readonly approvedOutcome: string;
   readonly rejectedOutcome: string;
+  readonly artifactContract?: ArtifactContract;
 };
 
 export type PromptGate = GateDefinition & {
@@ -102,8 +85,8 @@ export type StepWorkspaceBinding = {
 export type WorkflowStep = {
   readonly title: string;
   readonly prompt: PromptSpec;
-  /** Omit to execute this step in the main Pi agent. */
-  readonly subagent?: StepSubagent;
+  /** Optional workflow-owned role prompt for this main-agent step. */
+  readonly agent?: StepAgent;
   readonly permissions: StepPermissions;
   readonly requires: StepRequirements;
   readonly transitions: Readonly<Record<string, StepTarget>>;
@@ -142,19 +125,6 @@ export type PermissionCeiling = {
   readonly extensions: ReadonlyArray<string>;
   readonly skills: ReadonlyArray<string>;
   readonly bash: BashPermission;
-  readonly subagent?: SubagentPermissionCeiling;
-};
-
-export type SubagentPermissionCeiling = {
-  readonly agents: ReadonlyArray<string>;
-  readonly contexts: ReadonlyArray<SubagentContext>;
-  readonly models: ReadonlyArray<string>;
-  readonly maxTimeoutMs: number;
-  readonly maxTurns: number;
-  readonly maxGraceTurns: number;
-  readonly maxToolCalls: number;
-  readonly artifacts: boolean;
-  readonly retryToolFailures: boolean;
 };
 
 export type WorkflowSettings = {
@@ -192,14 +162,6 @@ export const EMPTY_REQUIREMENTS = {
   skills: [],
 } as const satisfies StepRequirements;
 
-export const DEFAULT_STEP_SUBAGENT = {
-  agent: 'pi-workflows.step',
-  context: 'fresh',
-  timeoutMs: 900_000,
-  artifacts: false,
-  retryToolFailures: false,
-} as const satisfies StepSubagent;
-
 export const DEFAULT_SETTINGS = {
   version: WORKFLOW_SCHEMA_VERSION,
   allowProjectWorkflows: false,

package/src/config/validation/settings.ts

@@ -12,7 +12,6 @@ import {
   type ValidationResult,
 } from './shared.ts';
 import { readStatusShortcut } from './shortcut.ts';
-import { parseSubagentPermissionCeiling } from './subagent.ts';
 
 function parsePermissionCeiling(
   value: unknown,
@@ -26,7 +25,7 @@ function parsePermissionCeiling(
   }
   rejectUnknownKeys(
     value,
-    ['tools', 'mcp', 'extensions', 'skills', 'bash', 'subagent'],
+    ['tools', 'mcp', 'extensions', 'skills', 'bash'],
     path,
     errors,
   );
@@ -43,18 +42,7 @@ function parsePermissionCeiling(
     path,
     errors,
   );
-  const subagent =
-    value.subagent === undefined
-      ? undefined
-      : parseSubagentPermissionCeiling(
-          value.subagent,
-          `${path}.subagent`,
-          errors,
-        );
-  return {
-    ...permissions,
-    ...(subagent ? { subagent } : {}),
-  };
+  return permissions;
 }
 
 /** Validate and normalize untrusted user workflow settings. */

package/src/config/validation/step.ts

@@ -2,6 +2,7 @@ import { isAbsolute, win32 } from 'node:path';
 import {
   MAX_WORKSPACE_ALLOWED_ROOTS,
   MAX_WORKSPACE_PATH_CHARS,
+  type ArtifactContract,
   type PromptSpec,
   type StepWorkspaceBinding,
   type WorkflowGate,
@@ -17,7 +18,7 @@ import {
   rejectUnknownKeys,
   type ValidationErrors,
 } from './shared.ts';
-import { parseStepSubagent } from './subagent.ts';
+import { AGENT_PROFILE_NAME_PATTERN, type StepAgent } from '../types.ts';
 
 function parsePrompt(
   value: unknown,
@@ -68,6 +69,106 @@ function parseTransitions(
   return transitions;
 }
 
+function parseArtifactContract(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): ArtifactContract | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'maxChars',
+      'requiredSubstrings',
+      'forbiddenSubstrings',
+      'equalOccurrenceGroups',
+      'onValidationFailure',
+    ],
+    path,
+    errors,
+  );
+  if (value.maxChars === undefined) {
+    errors.push(`${path}.maxChars: expected an integer from 1 to 200000`);
+  }
+  const maxChars = readInteger(
+    value.maxChars,
+    200_000,
+    `${path}.maxChars`,
+    errors,
+    { min: 1, max: 200_000 },
+  );
+  const parseSubstrings = (field: string): Array<string> => {
+    const values = readStringList(
+      value[field],
+      `${path}.${field}`,
+      errors,
+      /.+/,
+    );
+    if (values.length > 32) {
+      errors.push(`${path}.${field}: at most 32 values are allowed`);
+    }
+    values.forEach((substring, index) => {
+      if (substring.length > 1_024) {
+        errors.push(`${path}.${field}[${index}]: exceeds 1024 characters`);
+      }
+    });
+    return values;
+  };
+  const equalOccurrenceGroups = (() => {
+    if (value.equalOccurrenceGroups === undefined) return [];
+    if (!Array.isArray(value.equalOccurrenceGroups)) {
+      errors.push(`${path}.equalOccurrenceGroups: expected an array`);
+      return [];
+    }
+    if (value.equalOccurrenceGroups.length > 32) {
+      errors.push(
+        `${path}.equalOccurrenceGroups: at most 32 groups are allowed`,
+      );
+    }
+    return value.equalOccurrenceGroups.reduce<Array<Array<string>>>(
+      (groups, group, index) => {
+        const groupPath = `${path}.equalOccurrenceGroups[${index}]`;
+        const values = readStringList(group, groupPath, errors, /.+/);
+        if (values.length < 2) {
+          errors.push(`${groupPath}: at least two values are required`);
+        }
+        if (values.length > 32) {
+          errors.push(`${groupPath}: at most 32 values are allowed`);
+        }
+        values.forEach((substring, valueIndex) => {
+          if (substring.length > 1_024) {
+            errors.push(`${groupPath}[${valueIndex}]: exceeds 1024 characters`);
+          }
+        });
+        return [...groups, values];
+      },
+      [],
+    );
+  })();
+  const onValidationFailure =
+    value.onValidationFailure === undefined
+      ? undefined
+      : readString(
+          value.onValidationFailure,
+          `${path}.onValidationFailure`,
+          errors,
+        );
+  if (onValidationFailure !== undefined && onValidationFailure !== 'retry') {
+    errors.push(`${path}.onValidationFailure: expected retry`);
+  }
+  return {
+    maxChars,
+    requiredSubstrings: parseSubstrings('requiredSubstrings'),
+    forbiddenSubstrings: parseSubstrings('forbiddenSubstrings'),
+    equalOccurrenceGroups,
+    ...(onValidationFailure === 'retry' ? { onValidationFailure } : {}),
+  };
+}
+
 function parseGate(
   value: unknown,
   path: string,
@@ -86,6 +187,7 @@ function parseGate(
       'approvedOutcome',
       'rejectedOutcome',
       'timeoutMs',
+      'artifactContract',
     ],
     path,
     errors,
@@ -120,6 +222,11 @@ function parseGate(
     errors,
     { pattern: OUTCOME_PATTERN },
   );
+  const artifactContract = parseArtifactContract(
+    value.artifactContract,
+    `${path}.artifactContract`,
+    errors,
+  );
   if (provider === 'prompt' && value.timeoutMs !== undefined) {
     errors.push(`${path}.timeoutMs: only valid with provider "plannotator"`);
   }
@@ -136,12 +243,14 @@ function parseGate(
         submitOutcome,
         approvedOutcome,
         rejectedOutcome,
+        ...(artifactContract ? { artifactContract } : {}),
       }
     : {
         provider,
         submitOutcome,
         approvedOutcome,
         rejectedOutcome,
+        ...(artifactContract ? { artifactContract } : {}),
         timeoutMs: readInteger(
           value.timeoutMs,
           30_000,
@@ -248,7 +357,7 @@ export function parseWorkflowStep(
     [
       'title',
       'prompt',
-      'subagent',
+      'agent',
       'permissions',
       'requires',
       'transitions',
@@ -264,11 +373,15 @@ export function parseWorkflowStep(
       ? stepId
       : readString(value.title, `${path}.title`, errors);
   const prompt = parsePrompt(value.prompt, `${path}.prompt`, errors);
-  const subagent = parseStepSubagent(
-    value.subagent,
-    `${path}.subagent`,
-    errors,
-  );
+  const agentName =
+    value.agent === undefined
+      ? undefined
+      : readString(value.agent, `${path}.agent`, errors, {
+          pattern: AGENT_PROFILE_NAME_PATTERN,
+        });
+  const agent: StepAgent | undefined = agentName
+    ? { name: agentName }
+    : undefined;
   const permissions = parsePermissions(
     value.permissions,
     `${path}.permissions`,
@@ -308,6 +421,14 @@ export function parseWorkflowStep(
         `${path}.transitions: submitOutcome is handled by the gate and must not be a transition`,
       );
     }
+    if (
+      gate.artifactContract?.onValidationFailure === 'retry' &&
+      !Object.hasOwn(transitions, 'retry')
+    ) {
+      errors.push(
+        `${path}.transitions: artifact-contract retry requires a "retry" transition`,
+      );
+    }
   }
   if (workspace) {
     workspace.bindOn.forEach((outcome) => {
@@ -323,7 +444,7 @@ export function parseWorkflowStep(
   return {
     title,
     prompt,
-    ...(subagent ? { subagent } : {}),
+    ...(agent ? { agent } : {}),
     permissions,
     requires,
     transitions,

package/src/config/validation/workflow.ts

@@ -91,9 +91,6 @@ function validateWorkspaceGraph(
         `${workspacePath}: only one workspace-binding step is allowed; "${firstBinderId}" also configures workspace binding`,
       );
     }
-    if (!step.subagent) {
-      errors.push(`${workspacePath}: workspace binding requires a subagent`);
-    }
     if (step.gate) {
       errors.push(
         `${workspacePath}: workspace binding is not allowed on a gated step`,
@@ -110,14 +107,13 @@ function validateWorkspaceGraph(
       }
       return target && Object.hasOwn(steps, target) ? [target] : [];
     });
-    validateWorkspaceDescendants(steps, downstream, errors);
+    validateWorkspaceDescendants(steps, downstream);
   });
 }
 
 function validateWorkspaceDescendants(
   steps: Readonly<Record<string, WorkflowStep>>,
   initialStepIds: ReadonlyArray<string>,
-  errors: ValidationErrors,
 ): void {
   const pending = [...initialStepIds];
   const visited = new Set<string>();
@@ -127,11 +123,6 @@ function validateWorkspaceDescendants(
     visited.add(stepId);
     const step = steps[stepId];
     if (!step) continue;
-    if (!step.subagent) {
-      errors.push(
-        `workflow.steps.${stepId}.subagent: every nonterminal step reachable after workspace binding must use a subagent`,
-      );
-    }
     Object.values(step.transitions).forEach((target) => {
       if (
         target !== '$done' &&

package/src/engine/run-workflow-validation.ts

@@ -183,9 +183,6 @@ export function validateRunWorkflowSemantics(
   if (sameWorkflowDigest && currentStepChanged) {
     return `current step "${run.currentStepId}" does not match the active workflow digest`;
   }
-  if (boundWorkspaceCwd && !currentStep.subagent) {
-    return `bound workflow current step "${run.currentStepId}" must use a subagent`;
-  }
   if (currentStepChanged) return undefined;
   return validatePendingGate(run, currentStep);
 }

package/src/engine/state-types.ts

@@ -46,7 +46,7 @@ export type SubagentTranscriptReference = {
   readonly trustedRoot: string;
   /** Exact child session returned by the delegation protocol. */
   readonly sessionFile: string;
-  /** Pi-subagents run identity used to confine the session path. */
+  /** Legacy child-run identity used to confine the session path. */
   readonly runId: string;
   readonly childIndex: number;
 };

package/src/harness/action-context.ts

@@ -20,14 +20,11 @@ import type { MainStepRuntimeController } from '../runtime/main-step-runtime.ts'
 import type { SerialTaskQueueController } from '../runtime/serial-task-queue.ts';
 import type { WorkflowStepResult } from '../runtime/step-result.ts';
 import type { WorkflowStatusSnapshot } from '../workflow-status.ts';
-import type { DelegationFailureActions } from './delegation-failure.ts';
 import type { WorkflowHarnessDependencies } from './dependencies.ts';
 import type { SettledStepReport } from './step-reporting.ts';
 import type {
   ActiveDelegation,
   ActivePromptReview,
-  DelegationRecovery,
-  DelegationFailureDetails,
   MainStepIdentity,
   WorkflowStartContext,
 } from './types.ts';
@@ -41,7 +38,6 @@ import type {
 export type HarnessActionContext = {
   pi: ExtensionAPI;
   dependencies: WorkflowHarnessDependencies;
-  delegationFailures: DelegationFailureActions;
   subagents: SubagentDelegationClientController;
   mainSteps: MainStepRuntimeController;
   catalog: WorkflowCatalog;
@@ -98,10 +94,7 @@ export type HarnessActionContext = {
   registerLifecycle: () => void;
   registerPolicy: () => void;
   registerMultilineCommandInput: () => void;
-  launchCurrentStep: (
-    workflow: LoadedWorkflow,
-    recovery?: DelegationRecovery,
-  ) => void;
+  launchCurrentStep: (workflow: LoadedWorkflow) => void;
   launchMainStep: (
     workflow: LoadedWorkflow,
     run: WorkflowRun,
@@ -142,11 +135,6 @@ export type HarnessActionContext = {
   ) => Promise<void>;
   cancelActiveDelegation: (reason: string) => Promise<boolean>;
   cleanupDelegation: (active: ActiveDelegation) => Promise<void>;
-  retryDelegationAfterFailure: (
-    active: ActiveDelegation,
-    failure: DelegationFailureDetails | undefined,
-    reason: string,
-  ) => boolean;
   pauseForDelegationFailure: (reason: string, failureSummary?: string) => void;
   pauseForExecutionFailure: (
     label: string,