@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/harness/delegation-response-actions.ts

@@ -0,0 +1,295 @@
+import {
+  parseDelegatedStepResult,
+  type SubagentDelegationResponse,
+  type SubagentDelegationUpdate,
+} from '../integrations/subagents/protocol.ts';
+import { advanceRun } from '../engine/transitions.ts';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import type { ActiveDelegation, DelegationFailureDetails } from './types.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'catalog'
+  | 'cleanupDelegation'
+  | 'delegationFailures'
+  | 'dependencies'
+  | 'finishDelegation'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'mutationQueue'
+  | 'pauseForDelegationFailure'
+  | 'releaseMainAfterCancellation'
+  | 'retainUnconfirmedDelegation'
+  | 'retryDelegationAfterFailure'
+  | 'run'
+  | 'sessionEpoch'
+  | 'settleAfterTransition'
+  | 'subagents'
+  | 'submitGate'
+  | 'updateStatus'
+>;
+
+export type DelegationResponseActions = {
+  handleDelegationUpdate: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    update: SubagentDelegationUpdate,
+  ) => void;
+  queueDelegationResponse: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ) => void;
+  queueDelegationFailure: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    reason: string,
+  ) => void;
+  finishDelegation: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ) => Promise<void>;
+};
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && 'code' in error && error.code === code;
+}
+
+function handleDelegationUpdate(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  update: SubagentDelegationUpdate,
+): void {
+  if (this.activeDelegation !== active) return;
+  const progress = [
+    update.currentTool ? `tool ${update.currentTool}` : undefined,
+    update.toolCount !== undefined ? `${update.toolCount} calls` : undefined,
+    update.tokens !== undefined ? `${update.tokens} tokens` : undefined,
+  ].filter((part): part is string => part !== undefined);
+  active.progress = progress.join(', ') || 'running';
+  this.updateStatus();
+}
+
+function queueDelegationResponse(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  response: SubagentDelegationResponse,
+): void {
+  void this.mutationQueue
+    .run(() => this.finishDelegation(active, response))
+    .catch((error: unknown) => {
+      this.pauseForDelegationFailure(
+        error instanceof Error ? error.message : String(error),
+      );
+    });
+}
+
+function queueDelegationFailure(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  reason: string,
+): void {
+  void this.mutationQueue
+    .run(async () => {
+      if (this.activeDelegation !== active) {
+        await this.cleanupDelegation(active);
+        return;
+      }
+      if (this.subagents.activeRequestId === active.requestId) {
+        this.retainUnconfirmedDelegation(active, reason);
+        return;
+      }
+      this.activeDelegation = undefined;
+      await this.cleanupDelegation(active);
+      this.pauseForDelegationFailure(reason);
+    })
+    .catch((error: unknown) => {
+      this.pauseForDelegationFailure(
+        error instanceof Error ? error.message : String(error),
+      );
+    });
+}
+
+async function finishDelegation(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  response: SubagentDelegationResponse,
+): Promise<void> {
+  if (this.activeDelegation !== active) {
+    await this.cleanupDelegation(active);
+    return;
+  }
+  this.activeDelegation = undefined;
+  let terminalFailure: DelegationFailureDetails | undefined;
+  let cleanupAttempted = false;
+
+  try {
+    if (
+      !this.isSessionActive ||
+      this.sessionEpoch !== active.sessionEpoch ||
+      !this.run ||
+      this.run.status !== 'running' ||
+      this.run.runId !== active.runId ||
+      this.run.currentStepId !== active.stepId ||
+      this.run.currentStepDigest !== active.stepDigest
+    ) {
+      return;
+    }
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    const step = workflow?.definition.steps[this.run.currentStepId];
+    if (!workflow || !step) {
+      throw new Error('Active workflow configuration is unavailable');
+    }
+    let recoveredTerminalFailure: DelegationFailureDetails | undefined;
+    if (
+      response.status !== 'completed' ||
+      this.delegationFailures.hasContradictoryCompletion(response)
+    ) {
+      const failure = await this.delegationFailures.describeDelegationFailure(
+        active,
+        response,
+      );
+      terminalFailure = failure;
+      if (
+        response.status !== 'failed' ||
+        failure.diagnostic?.completionAfterFailure !== true
+      ) {
+        throw new Error(failure.reason);
+      }
+      const projectionError = this.delegationFailures.recoveredProjectionError(
+        active,
+        response,
+        failure.diagnostic,
+      );
+      if (projectionError) {
+        throw new Error(
+          this.delegationFailures.rejectedRecoveryReason(
+            failure,
+            projectionError,
+          ),
+        );
+      }
+      recoveredTerminalFailure = failure;
+    }
+    const requiredSkillWarning =
+      step.requires.skills.length > 0
+        ? response.warnings?.find((warning) => /skill/i.test(warning))
+        : undefined;
+    if (requiredSkillWarning) {
+      throw new Error(
+        `Subagent skill preflight failed: ${requiredSkillWarning}`,
+      );
+    }
+
+    let serializedResult: string;
+    try {
+      serializedResult = await this.dependencies.readDelegatedResult(active);
+    } catch (error) {
+      if (recoveredTerminalFailure) {
+        throw new Error(
+          this.delegationFailures.rejectedRecoveryReason(
+            recoveredTerminalFailure,
+            error,
+          ),
+          { cause: error },
+        );
+      }
+      if (hasErrorCode(error, 'ENOENT')) {
+        throw new Error(
+          `Subagent "${active.agent}" completed without producing the required correlated structured_output result`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+
+    let result: WorkflowStepResult;
+    try {
+      const rawResult: unknown = JSON.parse(serializedResult);
+      result = parseDelegatedStepResult(rawResult, active.policy);
+    } catch (error) {
+      if (recoveredTerminalFailure) {
+        throw new Error(
+          this.delegationFailures.rejectedRecoveryReason(
+            recoveredTerminalFailure,
+            error,
+          ),
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+    if (
+      recoveredTerminalFailure?.diagnostic &&
+      !this.delegationFailures.completionMatchesResult(
+        recoveredTerminalFailure.diagnostic,
+        result,
+        active.policy,
+      )
+    ) {
+      throw new Error(
+        this.delegationFailures.rejectedRecoveryReason(
+          recoveredTerminalFailure,
+          'structured_output transcript value does not match the correlated result',
+        ),
+      );
+    }
+    if (recoveredTerminalFailure) {
+      const isFalsePositive =
+        recoveredTerminalFailure.diagnostic?.correlation ===
+        'successful-output-before-completion';
+      this.latestContext?.ui.notify(
+        isFalsePositive
+          ? `Accepted "${active.stepId}" because the trusted child transcript proved the terminal tool error was a false positive and produced a matching structured result`
+          : `Accepted "${active.stepId}" because the child resolved an earlier tool failure and produced a valid structured result`,
+        'warning',
+      );
+    }
+    if (step.gate?.submitOutcome === result.outcome) {
+      await this.submitGate(
+        workflow,
+        this.run,
+        result.outcome,
+        result.artifact ?? '',
+      );
+      return;
+    }
+
+    this.run = advanceRun(
+      workflow,
+      this.run,
+      result.outcome,
+      result.summary,
+      this.dependencies.now(),
+    );
+    this.settleAfterTransition(workflow);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    cleanupAttempted = true;
+    await this.cleanupDelegation(active);
+    if (!this.retryDelegationAfterFailure(active, terminalFailure, reason)) {
+      this.pauseForDelegationFailure(reason);
+    }
+  } finally {
+    try {
+      if (!cleanupAttempted) await this.cleanupDelegation(active);
+    } finally {
+      if (active.cancelling) this.releaseMainAfterCancellation(active);
+    }
+  }
+}
+
+/**
+ * Returns delegation response and result-processing actions for composition.
+ */
+export function createDelegationResponseActions(): DelegationResponseActions {
+  return {
+    handleDelegationUpdate,
+    queueDelegationResponse,
+    queueDelegationFailure,
+    finishDelegation,
+  };
+}

package/src/harness/delegation-retry-policy.ts

@@ -0,0 +1,118 @@
+import { digest } from '../digest.ts';
+import type { ChildStepPolicy } from '../integrations/subagents/protocol.ts';
+import type { DelegationFailureDetails } from './types.ts';
+
+const MAX_FAILURE_FIELD_CHARS = 1_600;
+export const MAX_DELEGATION_RECOVERY_ATTEMPTS = 2;
+
+const normalizedFingerprintField = (
+  value: string | undefined,
+): string | undefined => value?.trim().replaceAll(/\s+/g, ' ') || undefined;
+
+/**
+ * Creates a stable identity for the semantic evidence behind one failure.
+ *
+ * Runtime request identifiers and session paths are deliberately absent so a
+ * fresh child repeating the same failed approach is recognized.
+ *
+ * @param failure - Normalized terminal failure evidence.
+ * @returns Stable digest used to stop duplicate automatic recovery attempts.
+ */
+export function delegationFailureFingerprint(
+  failure: DelegationFailureDetails,
+): string {
+  return digest({
+    status: failure.status,
+    exitCode: failure.exitCode,
+    error: normalizedFingerprintField(failure.error),
+    recoveryBlocker: failure.recoveryBlocker,
+    replayToolCount: failure.replayAudit?.toolCount,
+    diagnostic: failure.diagnostic
+      ? {
+          tool: normalizedFingerprintField(failure.diagnostic.tool),
+          call: normalizedFingerprintField(failure.diagnostic.call),
+          output: normalizedFingerprintField(failure.diagnostic.output),
+        }
+      : undefined,
+  });
+}
+
+/**
+ * Bounds a failure field while retaining evidence from both ends.
+ *
+ * @param value - Untrusted diagnostic text.
+ * @returns Text safe for inclusion in a workflow notification.
+ */
+export function boundedFailureField(value: string): string {
+  if (value.length <= MAX_FAILURE_FIELD_CHARS) return value;
+  const marker = '… [truncated] …';
+  const available = MAX_FAILURE_FIELD_CHARS - marker.length - 2;
+  const startLength = Math.ceil(available / 2);
+  const endLength = Math.floor(available / 2);
+  return `${value.slice(0, startLength)}\n${marker}\n${value.slice(-endLength)}`;
+}
+
+/**
+ * Returns whether a terminal failure contains evidence suitable for recovery.
+ *
+ * @param failure - Normalized terminal failure.
+ * @returns Whether diagnostic recovery may be attempted.
+ */
+export function isRetryableTerminalFailure(
+  failure: DelegationFailureDetails,
+): boolean {
+  if (failure.recoveryBlocker !== undefined) return false;
+  if (
+    failure.status === 'timed_out' ||
+    failure.status === 'turn_budget_exhausted' ||
+    failure.status === 'tool_budget_exhausted'
+  ) {
+    return true;
+  }
+  if (
+    failure.status !== 'failed' &&
+    failure.status !== 'structured_output_failed'
+  ) {
+    return false;
+  }
+  return (
+    failure.error !== undefined ||
+    (Number.isSafeInteger(failure.exitCode) && failure.exitCode !== 0)
+  );
+}
+
+/**
+ * Applies replay-safety policy to a proposed delegation retry.
+ *
+ * @param policy - Child policy from the failed delegation.
+ * @param isReplayExplicitlyAuthorized - Workflow-level retry authorization.
+ * @param replayAudit - Transcript-derived replay evidence.
+ * @returns Whether retrying the delegation is safe.
+ */
+export function isSafeToRetryDelegation(
+  policy: ChildStepPolicy,
+  isReplayExplicitlyAuthorized: boolean,
+  replayAudit: DelegationFailureDetails['replayAudit'],
+): boolean {
+  return (
+    replayAudit?.replaySafe === true &&
+    (isReplayExplicitlyAuthorized ||
+      policy.permissions.bash.mode === 'deny' ||
+      policy.permissions.bash.mode === 'read-only')
+  );
+}
+
+/**
+ * Extends a failure reason with bounded recovery-rejection evidence.
+ *
+ * @param failure - Original normalized failure.
+ * @param error - Error raised while attempting recovery.
+ * @returns User-facing rejection reason.
+ */
+export function rejectedRecoveryReason(
+  failure: DelegationFailureDetails,
+  error: unknown,
+): string {
+  const detail = error instanceof Error ? error.message : String(error);
+  return `${failure.reason}\nRecovery rejected: ${boundedFailureField(detail)}`;
+}

package/src/harness/dependencies.ts

@@ -0,0 +1,165 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { constants, mkdtempSync, writeFileSync } from 'node:fs';
+import { lstat, open, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { loadCatalog } from '../config/load.ts';
+import {
+  requestPlannotatorReview,
+  requestPlannotatorReviewStatus,
+} from '../integrations/plannotator.ts';
+import { requestPromptGateReview } from '../integrations/prompt-gate.ts';
+import {
+  createSubagentDelegationClient,
+  type SubagentDelegationClientController,
+} from '../integrations/subagents/client.ts';
+import {
+  readDelegationReplayAudit,
+  readToolFailureDiagnostic,
+} from '../integrations/subagents/diagnostics.ts';
+import {
+  createMainStepRuntime,
+  type MainStepRuntimeController,
+} from '../runtime/main-step-runtime.ts';
+import {
+  createSerialTaskQueue,
+  type SerialTaskQueueController,
+} from '../runtime/serial-task-queue.ts';
+import { showWorkflowStatus } from '../workflow-status.ts';
+import type { ActiveDelegation } from './types.ts';
+
+const MAX_DELEGATED_RESULT_BYTES = 1024 * 1024;
+
+export type DelegationWorkspace = {
+  resultDirectory: string;
+  capabilityPath: string;
+  capabilityToken: string;
+  resultPath: string;
+};
+
+export type WorkflowHarnessDependencies = {
+  readonly now: () => number;
+  readonly createRequestId: () => string;
+  readonly createAbortController: () => AbortController;
+  readonly createDelegationWorkspace: () => DelegationWorkspace;
+  readonly readDelegatedResult: (active: ActiveDelegation) => Promise<string>;
+  readonly removeDelegationWorkspace: (
+    resultDirectory: string,
+  ) => Promise<void>;
+  readonly currentWorkingDirectory: () => string;
+  readonly waitForDelay: (delayMs: number) => Promise<void>;
+  readonly loadCatalog: typeof loadCatalog;
+  readonly requestPlannotatorReview: typeof requestPlannotatorReview;
+  readonly requestPlannotatorReviewStatus: typeof requestPlannotatorReviewStatus;
+  readonly requestPromptGateReview: typeof requestPromptGateReview;
+  readonly readDelegationReplayAudit: typeof readDelegationReplayAudit;
+  readonly readToolFailureDiagnostic: typeof readToolFailureDiagnostic;
+  readonly showWorkflowStatus: typeof showWorkflowStatus;
+  readonly createSubagentClient: (
+    pi: ExtensionAPI,
+  ) => SubagentDelegationClientController;
+  readonly createMainStepRuntime: (
+    pi: ExtensionAPI,
+  ) => MainStepRuntimeController;
+  readonly createMutationQueue: () => SerialTaskQueueController;
+  readonly scheduleInterval: (
+    operation: () => void,
+    intervalMs: number,
+  ) => ReturnType<typeof setInterval>;
+  readonly cancelInterval: (timer: ReturnType<typeof setInterval>) => void;
+};
+
+function createDelegationWorkspace(): DelegationWorkspace {
+  const resultDirectory = mkdtempSync(join(tmpdir(), 'pi-workflows-step-'));
+  const capabilityPath = join(resultDirectory, 'capability');
+  const capabilityToken = randomBytes(32).toString('hex');
+  const resultPath = join(resultDirectory, 'result.json');
+  writeFileSync(capabilityPath, capabilityToken, {
+    encoding: 'utf8',
+    flag: 'wx',
+    mode: 0o600,
+  });
+  return {
+    resultDirectory,
+    capabilityPath,
+    capabilityToken,
+    resultPath,
+  };
+}
+
+async function readDelegatedResult(active: ActiveDelegation): Promise<string> {
+  const expectedPath = join(active.resultDirectory, 'result.json');
+  if (active.policy.resultPath !== expectedPath) {
+    throw new Error(
+      'delegated result path does not match its private directory',
+    );
+  }
+  const inspected = await lstat(expectedPath);
+  if (inspected.isSymbolicLink() || !inspected.isFile()) {
+    throw new Error('delegated result is not a regular file');
+  }
+  const handle = await open(
+    expectedPath,
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  try {
+    const beforeRead = await handle.stat();
+    if (!beforeRead.isFile() || beforeRead.size > MAX_DELEGATED_RESULT_BYTES) {
+      throw new Error('delegated result is not a bounded regular file');
+    }
+    const value = await handle.readFile({ encoding: 'utf8' });
+    const afterRead = await handle.stat();
+    if (
+      afterRead.dev !== beforeRead.dev ||
+      afterRead.ino !== beforeRead.ino ||
+      afterRead.size !== beforeRead.size ||
+      afterRead.mtimeMs !== beforeRead.mtimeMs
+    ) {
+      throw new Error('delegated result changed while it was being read');
+    }
+    return value;
+  } finally {
+    await handle.close();
+  }
+}
+
+const DEFAULT_DEPENDENCIES: WorkflowHarnessDependencies = {
+  now: () => Date.now(),
+  createRequestId: randomUUID,
+  createAbortController: () => new AbortController(),
+  createDelegationWorkspace,
+  readDelegatedResult,
+  removeDelegationWorkspace: async (resultDirectory) =>
+    rm(resultDirectory, { recursive: true, force: true }),
+  currentWorkingDirectory: () => process.cwd(),
+  waitForDelay: async (delayMs) =>
+    new Promise((resolve) => setTimeout(resolve, delayMs)),
+  loadCatalog,
+  requestPlannotatorReview,
+  requestPlannotatorReviewStatus,
+  requestPromptGateReview,
+  readDelegationReplayAudit,
+  readToolFailureDiagnostic,
+  showWorkflowStatus,
+  createSubagentClient: (pi) => createSubagentDelegationClient(pi.events),
+  createMainStepRuntime: (pi) => createMainStepRuntime({ pi }),
+  createMutationQueue: createSerialTaskQueue,
+  scheduleInterval: (operation, intervalMs) =>
+    setInterval(operation, intervalMs),
+  cancelInterval: (timer) => {
+    clearInterval(timer);
+  },
+};
+
+/**
+ * Builds the effect boundary used by the workflow harness.
+ *
+ * Callers can replace individual dependencies for deterministic tests or
+ * alternate runtime integrations without changing workflow logic.
+ */
+export function createWorkflowHarnessDependencies(
+  overrides: Partial<WorkflowHarnessDependencies> = {},
+): WorkflowHarnessDependencies {
+  return { ...DEFAULT_DEPENDENCIES, ...overrides };
+}