@wichayutdew/pi-workflows 0.2.3 → 1.0.0

package/src/harness/delegation-failure.ts

@@ -0,0 +1,215 @@
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import {
+  failedToolName,
+  formatToolFailureDiagnostic,
+} from '../integrations/subagents/diagnostics.ts';
+import type {
+  ChildStepPolicy,
+  SubagentDelegationResponse,
+} from '../integrations/subagents/protocol.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+import {
+  completionMatchesResult,
+  recoveredProjectionError,
+} from './delegation-recovery-validation.ts';
+import {
+  boundedFailureField,
+  delegationFailureFingerprint,
+  isRetryableTerminalFailure,
+  isSafeToRetryDelegation,
+  rejectedRecoveryReason,
+} from './delegation-retry-policy.ts';
+import type {
+  ActiveDelegation,
+  DelegationFailureDetails,
+  DelegationRecoveryBlocker,
+} from './types.ts';
+
+export type DelegationFailureActions = {
+  delegationFailureFingerprint: (failure: DelegationFailureDetails) => string;
+  hasContradictoryCompletion: (response: SubagentDelegationResponse) => boolean;
+  isRetryableTerminalFailure: (failure: DelegationFailureDetails) => boolean;
+  isSafeToRetryDelegation: (
+    policy: ChildStepPolicy,
+    isReplayExplicitlyAuthorized: boolean,
+    replayAudit: DelegationFailureDetails['replayAudit'],
+  ) => boolean;
+  rejectedRecoveryReason: (
+    failure: DelegationFailureDetails,
+    error: unknown,
+  ) => string;
+  completionMatchesResult: (
+    diagnostic: NonNullable<DelegationFailureDetails['diagnostic']>,
+    result: WorkflowStepResult,
+    policy: ChildStepPolicy,
+  ) => boolean;
+  recoveredProjectionError: (
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+    diagnostic: NonNullable<DelegationFailureDetails['diagnostic']>,
+  ) => string | undefined;
+  describeDelegationFailure: (
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ) => Promise<DelegationFailureDetails>;
+};
+
+function nonEmptyTerminalError(
+  response: SubagentDelegationResponse,
+): string | undefined {
+  return [response.error, response.execution?.error].find(
+    (error): error is string =>
+      typeof error === 'string' && error.trim().length > 0,
+  );
+}
+
+function nonzeroTerminalExitCode(
+  response: SubagentDelegationResponse,
+): number | undefined {
+  return [response.exitCode, response.execution?.exitCode].find(
+    (exitCode): exitCode is number =>
+      typeof exitCode === 'number' &&
+      Number.isSafeInteger(exitCode) &&
+      exitCode !== 0,
+  );
+}
+
+function hasContradictoryCompletion(
+  response: SubagentDelegationResponse,
+): boolean {
+  return (
+    response.status === 'completed' &&
+    (nonEmptyTerminalError(response) !== undefined ||
+      nonzeroTerminalExitCode(response) !== undefined)
+  );
+}
+
+function recoveryBlocker(
+  response: SubagentDelegationResponse,
+): DelegationRecoveryBlocker | undefined {
+  const execution = response.execution;
+  const fileMutation = response.effects?.fileMutation;
+  if (fileMutation?.attempted === true || fileMutation?.status === 'observed') {
+    return 'reported-mutation';
+  }
+  if (execution?.detached === true || execution?.status === 'detached') {
+    return 'detached';
+  }
+  if (execution?.stopped === true || execution?.status === 'stopped') {
+    return 'stopped';
+  }
+  if (
+    response.status === 'interrupted' ||
+    execution?.interrupted === true ||
+    execution?.status === 'paused'
+  ) {
+    return 'interrupted';
+  }
+  if (response.status === 'cancelled') return 'cancelled';
+  if (execution?.timedOut === true && response.status !== 'timed_out') {
+    return 'inconsistent-timeout';
+  }
+  return undefined;
+}
+
+function validateReplayAudit(
+  response: SubagentDelegationResponse,
+  replayAudit: DelegationFailureDetails['replayAudit'],
+): DelegationFailureDetails['replayAudit'] {
+  if (!replayAudit) return undefined;
+  if (
+    response.toolCount !== undefined &&
+    response.toolCount !== replayAudit.toolCount
+  ) {
+    return { ...replayAudit, replaySafe: false };
+  }
+  return replayAudit;
+}
+
+/**
+ * Creates pure delegation-failure evaluators plus the injected diagnostic
+ * reader used at the transcript I/O boundary.
+ */
+export function createDelegationFailureActions(
+  dependencies: Pick<
+    WorkflowHarnessDependencies,
+    'readDelegationReplayAudit' | 'readToolFailureDiagnostic'
+  >,
+): DelegationFailureActions {
+  const describeDelegationFailure = async (
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ): Promise<DelegationFailureDetails> => {
+    const blocker = recoveryBlocker(response);
+    const terminalError = nonEmptyTerminalError(response);
+    const error =
+      terminalError ?? 'The subagent returned no terminal error details.';
+    const isResponseIdentityValid =
+      response.childIndex === 0 &&
+      (response.agent === undefined || response.agent === active.agent);
+    const identity =
+      isResponseIdentityValid && response.runId !== undefined
+        ? { runId: response.runId, childIndex: 0 }
+        : undefined;
+    const [diagnostic, replayAudit] = await Promise.all([
+      dependencies.readToolFailureDiagnostic(
+        response.sessionFile,
+        active.trustedSessionRoot,
+        identity,
+        failedToolName(terminalError),
+        terminalError,
+      ),
+      dependencies.readDelegationReplayAudit(
+        response.sessionFile,
+        active.trustedSessionRoot,
+        identity,
+        {
+          task: active.transcriptTask,
+          bashPermission: active.policy.permissions.bash,
+          approvedBashCommands: active.policy.approvedBashCommands ?? [],
+        },
+      ),
+    ]);
+    const validatedReplayAudit = validateReplayAudit(response, replayAudit);
+    const exitCode =
+      nonzeroTerminalExitCode(response) ??
+      response.exitCode ??
+      response.execution?.exitCode;
+    const reason = [
+      hasContradictoryCompletion(response)
+        ? `Subagent "${active.agent}" reported terminal failure signals with completed status.`
+        : `Subagent "${active.agent}" ${response.status.replaceAll('_', ' ')}.`,
+      ...(diagnostic ? formatToolFailureDiagnostic(diagnostic) : []),
+      ...(exitCode !== undefined ? [`Subagent exit code: ${exitCode}`] : []),
+      ...(blocker
+        ? [`Automatic recovery blocked by: ${blocker.replaceAll('-', ' ')}`]
+        : []),
+      `Terminal error: ${boundedFailureField(error)}`,
+      ...(diagnostic && response.sessionFile
+        ? [
+            `Diagnostic session: ${boundedFailureField(response.sessionFile.replaceAll(/\s+/g, ' '))}`,
+          ]
+        : []),
+    ].join('\n');
+    return {
+      reason,
+      status: response.status,
+      ...(terminalError ? { error: terminalError } : {}),
+      ...(exitCode !== undefined ? { exitCode } : {}),
+      ...(blocker ? { recoveryBlocker: blocker } : {}),
+      ...(diagnostic ? { diagnostic } : {}),
+      ...(validatedReplayAudit ? { replayAudit: validatedReplayAudit } : {}),
+    };
+  };
+
+  return {
+    delegationFailureFingerprint,
+    hasContradictoryCompletion,
+    isRetryableTerminalFailure,
+    isSafeToRetryDelegation,
+    rejectedRecoveryReason,
+    completionMatchesResult,
+    recoveredProjectionError,
+    describeDelegationFailure,
+  };
+}

package/src/harness/delegation-plan.ts

@@ -0,0 +1,219 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { LoadedWorkflow, WorkflowStep } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import { allowedOutcomes } from '../engine/transitions.ts';
+import { digest } from '../digest.ts';
+import { deriveSubagentSessionRoot } from '../integrations/subagents/diagnostics.ts';
+import {
+  encodeChildPolicy,
+  type ChildStepPolicy,
+  type SubagentDelegationRequest,
+} from '../integrations/subagents/protocol.ts';
+import {
+  narrowApprovedBashCommands,
+  resolveReviewedRepositoryCwd,
+} from '../policy/approved-commands.ts';
+import { automaticRecoveryTask, buildDelegatedStepTask } from '../prompt.ts';
+import { WORKFLOW_COMPLETION_PARAMETERS } from '../runtime/completion-tool.ts';
+import { MAX_DELEGATION_RECOVERY_ATTEMPTS } from './delegation-retry-policy.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+import type { ActiveDelegation, DelegationRecovery } from './types.ts';
+
+type DelegationPlanInput = {
+  workflow: LoadedWorkflow;
+  run: WorkflowRun;
+  step: WorkflowStep;
+  sessionEpoch: number;
+  latestContext: ExtensionContext | undefined;
+  recovery: DelegationRecovery | undefined;
+};
+
+export type DelegationPlan =
+  | {
+      kind: 'invalid';
+      reason: string;
+    }
+  | {
+      kind: 'ready';
+      active: ActiveDelegation;
+      request: SubagentDelegationRequest;
+    };
+
+function delegationTranscriptBinding(
+  requestId: string,
+  policyDigest: string,
+): string {
+  return `<pi-workflows-delegation-binding-v1>${requestId}:${policyDigest}</pi-workflows-delegation-binding-v1>`;
+}
+
+function approvedCommands(
+  run: WorkflowRun,
+  step: WorkflowStep,
+): ReadonlyArray<string> {
+  return narrowApprovedBashCommands(
+    run.reviewedArtifact ?? '',
+    run.stepHandoff ?? '',
+    step.permissions.bash.approvedSources ?? [],
+  );
+}
+
+/**
+ * Creates one immutable subagent request from workflow state and injected
+ * identity/workspace effects.
+ */
+export function createDelegationPlan(
+  input: DelegationPlanInput,
+  dependencies: Pick<
+    WorkflowHarnessDependencies,
+    'createDelegationWorkspace' | 'createRequestId' | 'currentWorkingDirectory'
+  >,
+): DelegationPlan {
+  const { workflow, run, step, latestContext, recovery } = input;
+  const subagent = step.subagent;
+  if (!subagent) {
+    return {
+      kind: 'invalid',
+      reason: `Step "${run.currentStepId}" has no subagent configuration`,
+    };
+  }
+
+  const reviewedRepository = resolveReviewedRepositoryCwd(
+    run.reviewedArtifact ?? '',
+  );
+  if (reviewedRepository.kind === 'invalid') {
+    return { kind: 'invalid', reason: reviewedRepository.reason };
+  }
+
+  const delegationCwd =
+    reviewedRepository.kind === 'resolved'
+      ? reviewedRepository.cwd
+      : (latestContext?.cwd ?? dependencies.currentWorkingDirectory());
+  const requestId =
+    `${run.runId}:${run.currentStepId}:` + dependencies.createRequestId();
+  const workspace = dependencies.createDelegationWorkspace();
+  const outcomes = allowedOutcomes(workflow, run);
+  const outcomeSet = new Set(outcomes);
+  const approvedBashCommands = approvedCommands(run, step);
+  const repositoryPolicy =
+    reviewedRepository.kind === 'resolved'
+      ? {
+          repositoryCwd: reviewedRepository.repositoryCwd,
+          ...(reviewedRepository.bootstrapping
+            ? { bootstrapCwd: reviewedRepository.cwd }
+            : {}),
+        }
+      : {};
+  const policyDigest = digest({
+    version: 1,
+    requestId,
+    agent: subagent.agent,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    capabilityPath: workspace.capabilityPath,
+    resultPath: workspace.resultPath,
+    approvedBashCommands,
+    ...repositoryPolicy,
+  });
+  const policy: ChildStepPolicy = {
+    version: 1,
+    requestId,
+    agent: subagent.agent,
+    workflowId: workflow.definition.id,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepTitle: step.title,
+    policyDigest,
+    capabilityPath: workspace.capabilityPath,
+    capabilityToken: workspace.capabilityToken,
+    resultPath: workspace.resultPath,
+    permissions: structuredClone(step.permissions),
+    ...(approvedBashCommands.length > 0 ? { approvedBashCommands } : {}),
+    ...repositoryPolicy,
+    outcomes,
+    pauseOutcomes: Object.entries(step.transitions)
+      .filter(
+        ([outcome, target]) => target === '$pause' && outcomeSet.has(outcome),
+      )
+      .map(([outcome]) => outcome),
+    summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...(step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}),
+  };
+  const trustedSessionRoot = deriveSubagentSessionRoot(
+    latestContext?.sessionManager.getSessionFile(),
+  );
+  const transcriptTask = [
+    buildDelegatedStepTask(workflow, run, ''),
+    delegationTranscriptBinding(requestId, policyDigest),
+    ...(recovery
+      ? [
+          automaticRecoveryTask(
+            recovery.failures.map(({ reason }) => reason),
+            recovery.attempt,
+            MAX_DELEGATION_RECOVERY_ATTEMPTS,
+          ),
+        ]
+      : []),
+  ].join('\n\n');
+  const active: ActiveDelegation = {
+    requestId,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    sessionEpoch: input.sessionEpoch,
+    resultDirectory: workspace.resultDirectory,
+    policy,
+    transcriptTask,
+    agent: subagent.agent,
+    ...(trustedSessionRoot ? { trustedSessionRoot } : {}),
+    broadRecoveryAuthorized: subagent.retryToolFailures,
+    recoveryAttemptCount: recovery?.attempt ?? 0,
+    recoveryFailures: recovery?.failures ?? [],
+  };
+  const request: SubagentDelegationRequest = {
+    version: 1,
+    requestId,
+    agent: subagent.agent,
+    task: `${encodeChildPolicy(policy)}\n\n${transcriptTask}`,
+    // Workflow steps are isolation boundaries. Parent/sibling transcripts are
+    // replaced by the explicit workflow handoff.
+    context: 'fresh',
+    cwd: delegationCwd,
+    timeoutMs: subagent.timeoutMs,
+    skill:
+      step.permissions.skills.length > 0 ? [...step.permissions.skills] : false,
+    output: false,
+    // TypeBox schemas are structurally JSON objects, but the upstream contract
+    // exposes a generic record.
+    outputSchema: WORKFLOW_COMPLETION_PARAMETERS as unknown as Record<
+      string,
+      unknown
+    >,
+    agentContract: { version: 1 },
+    artifacts: subagent.artifacts,
+    ...(subagent.model ? { model: subagent.model } : {}),
+    ...(subagent.turnBudget
+      ? { turnBudget: structuredClone(subagent.turnBudget) }
+      : {}),
+    ...(subagent.toolBudget
+      ? {
+          toolBudget: {
+            hard: subagent.toolBudget.hard,
+            ...(subagent.toolBudget.soft === undefined
+              ? {}
+              : { soft: subagent.toolBudget.soft }),
+            ...(subagent.toolBudget.block === undefined
+              ? {}
+              : {
+                  block:
+                    subagent.toolBudget.block === '*'
+                      ? '*'
+                      : [...subagent.toolBudget.block],
+                }),
+          },
+        }
+      : {}),
+  };
+
+  return { kind: 'ready', active, request };
+}

package/src/harness/delegation-recovery-validation.ts

@@ -0,0 +1,159 @@
+import { parseDelegatedStepResult } from '../integrations/subagents/protocol.ts';
+import type {
+  ChildStepPolicy,
+  SubagentDelegationResponse,
+} from '../integrations/subagents/protocol.ts';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import type { ActiveDelegation, DelegationFailureDetails } from './types.ts';
+
+/**
+ * Verifies that transcript completion data exactly matches a recovered result.
+ *
+ * @param diagnostic - Correlated tool-failure diagnostic.
+ * @param result - Result recovered from the delegated artifact.
+ * @param policy - Child policy used to validate the result.
+ * @returns Whether the transcript and recovered artifact agree.
+ */
+export function completionMatchesResult(
+  diagnostic: NonNullable<DelegationFailureDetails['diagnostic']>,
+  result: WorkflowStepResult,
+  policy: ChildStepPolicy,
+): boolean {
+  const value = diagnostic.completionValue;
+  if (!value) return false;
+  const expectedKeys = [
+    'outcome',
+    'summary',
+    ...(result.artifact === undefined ? [] : ['artifact']),
+  ].sort();
+  const actualKeys = Object.keys(value).sort();
+  if (
+    actualKeys.length !== expectedKeys.length ||
+    !actualKeys.every((key, index) => key === expectedKeys[index])
+  ) {
+    return false;
+  }
+  try {
+    const completion = parseDelegatedStepResult(
+      {
+        ...value,
+        version: 1,
+        policyDigest: policy.policyDigest,
+      },
+      policy,
+    );
+    return (
+      completion.outcome === result.outcome &&
+      completion.summary === result.summary &&
+      completion.artifact === result.artifact
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Finds contradictory or unsafe fields in a recovered terminal projection.
+ *
+ * @param active - Active delegation identity.
+ * @param response - Terminal response received from the child.
+ * @param diagnostic - Transcript evidence correlated to the failure.
+ * @returns A rejection reason, or undefined for a valid projection.
+ */
+export function recoveredProjectionError(
+  active: ActiveDelegation,
+  response: SubagentDelegationResponse,
+  diagnostic: NonNullable<DelegationFailureDetails['diagnostic']>,
+): string | undefined {
+  if (response.agent !== active.agent) {
+    return `terminal agent identity is ${JSON.stringify(response.agent)}; expected ${JSON.stringify(active.agent)}`;
+  }
+  if (response.childIndex !== 0) {
+    return `terminal child index is ${JSON.stringify(response.childIndex)}; expected 0`;
+  }
+  if (
+    typeof response.exitCode !== 'number' ||
+    !Number.isSafeInteger(response.exitCode) ||
+    response.exitCode <= 0
+  ) {
+    return `terminal exit code is ${JSON.stringify(response.exitCode)}; expected a positive safe integer`;
+  }
+  const execution = response.execution;
+  if (!execution) return 'terminal response has no execution projection';
+  if (execution.status !== 'failed' || execution.success) {
+    return `execution projection is ${JSON.stringify({
+      status: execution.status,
+      success: execution.success,
+    })}; expected failed/false`;
+  }
+  if (execution.exitCode !== response.exitCode) {
+    return `execution exit code ${JSON.stringify(execution.exitCode)} does not match terminal exit code ${JSON.stringify(response.exitCode)}`;
+  }
+  if (
+    typeof response.error !== 'string' ||
+    !response.error ||
+    typeof execution.error !== 'string' ||
+    execution.error !== response.error
+  ) {
+    return 'terminal and execution errors are missing or do not match exactly';
+  }
+  const warnings = response.warnings as unknown;
+  if (
+    warnings !== undefined &&
+    (!Array.isArray(warnings) ||
+      warnings.some(
+        (warning) => typeof warning !== 'string' || warning.trim().length > 0,
+      ))
+  ) {
+    return `terminal response contains warning evidence: ${JSON.stringify(warnings)}`;
+  }
+  if (
+    diagnostic.transcriptToolCount !== undefined &&
+    response.toolCount !== undefined &&
+    response.toolCount !== diagnostic.transcriptToolCount
+  ) {
+    return `terminal tool count ${response.toolCount} does not match transcript tool count ${diagnostic.transcriptToolCount}`;
+  }
+  if (
+    diagnostic.transcriptTurnCount !== undefined &&
+    response.turns !== undefined &&
+    response.turns !== diagnostic.transcriptTurnCount
+  ) {
+    return `terminal turn count ${response.turns} does not match transcript turn count ${diagnostic.transcriptTurnCount}`;
+  }
+  const toolFailure = response.error.match(
+    /^\s*([a-z][\w-]*) failed\s*\(exit\s+(\d+)\)\s*:/i,
+  );
+  if (!toolFailure) {
+    return 'terminal error is not a recognized "<tool> failed (exit N): <detail>" failure';
+  }
+  const terminalTool = toolFailure[1];
+  const terminalExitCodeText = toolFailure[2];
+  if (!terminalTool || !terminalExitCodeText) {
+    return 'terminal error does not contain a complete tool failure projection';
+  }
+  const terminalExitCode = Number(terminalExitCodeText);
+  if (
+    terminalTool.toLowerCase() !== diagnostic.tool.toLowerCase() ||
+    terminalExitCode !== response.exitCode
+  ) {
+    return `terminal tool/exit ${JSON.stringify({
+      tool: terminalTool,
+      exitCode: terminalExitCode,
+    })} does not match the correlated failure ${JSON.stringify({
+      tool: diagnostic.tool,
+      exitCode: response.exitCode,
+    })}`;
+  }
+  const unsafeFlag = (
+    [
+      ['interrupted', execution.interrupted],
+      ['timedOut', execution.timedOut],
+      ['stopped', execution.stopped],
+      ['detached', execution.detached],
+    ] as const
+  ).find(([, isEnabled]) => isEnabled === true)?.[0];
+  return unsafeFlag
+    ? `execution projection reports ${unsafeFlag}=true`
+    : undefined;
+}