@wichayutdew/pi-workflows 2.5.0 → 2.6.0

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

@@ -1,120 +0,0 @@
-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),
-          postCompletionWarning: normalizedFingerprintField(
-            failure.diagnostic.postCompletionWarning,
-          ),
-        }
-      : 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.diagnostic?.postCompletionWarning !== 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')
-  );
-}
-
-/**
- * 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/integrations/subagents/client-delegation.ts

@@ -1,181 +0,0 @@
-import {
-  parseDelegationResponse,
-  parseDelegationUpdate,
-  requestIdOf,
-} from './client-messages.ts';
-import type {
-  ActiveDelegation,
-  DelegateOptions,
-  DelegationTimer,
-  SubagentDelegationClientDependencies,
-  SubagentEventBus,
-} from './client-types.ts';
-import {
-  SUBAGENT_DELEGATION_CANCEL_EVENT,
-  SUBAGENT_DELEGATION_PROTOCOL_VERSION,
-  SUBAGENT_DELEGATION_REQUEST_EVENT,
-  SUBAGENT_DELEGATION_RESPONSE_EVENT,
-  SUBAGENT_DELEGATION_STARTED_EVENT,
-  SUBAGENT_DELEGATION_UPDATE_EVENT,
-} from './protocol-events.ts';
-import type {
-  SubagentDelegationRequest,
-  SubagentDelegationResponse,
-} from './protocol-events.ts';
-
-export const DEFAULT_CLIENT_DEPENDENCIES = {
-  scheduleTimeout: (callback: () => void, timeoutMs: number) =>
-    setTimeout(callback, timeoutMs),
-  cancelTimeout: (timer: DelegationTimer) => {
-    clearTimeout(timer);
-  },
-} as const satisfies SubagentDelegationClientDependencies;
-
-type CreatedDelegation = {
-  readonly active: ActiveDelegation;
-  readonly promise: Promise<SubagentDelegationResponse>;
-  readonly start: () => void;
-};
-
-type CreateDelegationOptions = {
-  readonly events: SubagentEventBus;
-  readonly request: SubagentDelegationRequest;
-  readonly options: DelegateOptions;
-  readonly dependencies: SubagentDelegationClientDependencies;
-  readonly releaseActive: (requestId: string) => void;
-};
-
-function isUnsubscribe(value: unknown): value is () => void {
-  return typeof value === 'function';
-}
-
-/**
- * Creates one delegation lifecycle without retaining client-level state.
- */
-export const createDelegation = ({
-  events,
-  request,
-  options,
-  dependencies,
-  releaseActive,
-}: CreateDelegationOptions): CreatedDelegation => {
-  let requestCancellation = (): void => undefined;
-  let resolveTerminal = (): void => undefined;
-  const terminal = new Promise<void>((resolve) => {
-    resolveTerminal = resolve;
-  });
-
-  const promise = new Promise<SubagentDelegationResponse>((resolve, reject) => {
-    let isSettled = false;
-    let isCancellationRequested = false;
-    const subscriptions: Array<() => void> = [];
-
-    const subscribe = (
-      event: string,
-      handler: (data: unknown) => void,
-    ): void => {
-      const unsubscribe = events.on(event, handler);
-      if (isUnsubscribe(unsubscribe)) {
-        subscriptions.push(() => {
-          unsubscribe();
-        });
-      }
-    };
-    const stopLocalWatchers = (): void => {
-      dependencies.cancelTimeout(startTimer);
-      dependencies.cancelTimeout(overallTimer);
-      options.signal?.removeEventListener('abort', abort);
-    };
-    const cleanup = (): void => {
-      stopLocalWatchers();
-      for (const unsubscribe of subscriptions) unsubscribe();
-      releaseActive(request.requestId);
-    };
-    const finish = (
-      result:
-        | { readonly response: SubagentDelegationResponse }
-        | { readonly error: Error },
-    ): void => {
-      if (isSettled) return;
-      isSettled = true;
-      cleanup();
-      if ('response' in result) resolve(result.response);
-      else reject(result.error);
-    };
-    const emitCancel = (): void => {
-      if (isCancellationRequested || isSettled) return;
-      isCancellationRequested = true;
-      events.emit(SUBAGENT_DELEGATION_CANCEL_EVENT, {
-        version: SUBAGENT_DELEGATION_PROTOCOL_VERSION,
-        requestId: request.requestId,
-      });
-    };
-    const failAndCancel = (reason: string): void => {
-      if (isSettled) return;
-      emitCancel();
-      // A local timeout is not proof that the child process terminated.
-      // Retain correlation listeners and ownership until the terminal event.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- emitting cancellation can synchronously settle through the event bus
-      if (isSettled) return;
-      isSettled = true;
-      stopLocalWatchers();
-      reject(new Error(reason));
-    };
-    const abort = (): void => {
-      failAndCancel('subagent delegation was cancelled');
-    };
-    requestCancellation = emitCancel;
-
-    subscribe(SUBAGENT_DELEGATION_STARTED_EVENT, (data) => {
-      if (requestIdOf(data) !== request.requestId) return;
-      dependencies.cancelTimeout(startTimer);
-    });
-    subscribe(SUBAGENT_DELEGATION_UPDATE_EVENT, (data) => {
-      const update = parseDelegationUpdate(data);
-      if (!update || update.requestId !== request.requestId) return;
-      options.onUpdate?.(update);
-    });
-    subscribe(SUBAGENT_DELEGATION_RESPONSE_EVENT, (data) => {
-      const response = parseDelegationResponse(data);
-      if (!response || response.requestId !== request.requestId) return;
-      resolveTerminal();
-      if (isSettled) {
-        cleanup();
-        options.onLateTerminal?.(response);
-        return;
-      }
-      finish({ response });
-    });
-
-    const startTimer = dependencies.scheduleTimeout(() => {
-      failAndCancel(
-        'pi-subagents did not accept the delegation request; verify it is installed and loaded',
-      );
-    }, options.startTimeoutMs ?? 3_000);
-    const overallTimer = dependencies.scheduleTimeout(
-      () => {
-        failAndCancel(
-          'pi-subagents did not settle the delegation request before its deadline',
-        );
-      },
-      (request.timeoutMs ?? 900_000) + 5_000,
-    );
-    startTimer.unref();
-    overallTimer.unref();
-    options.signal?.addEventListener('abort', abort, { once: true });
-  });
-
-  return {
-    active: {
-      requestId: request.requestId,
-      requestCancellation: () => {
-        requestCancellation();
-      },
-      terminal,
-    },
-    promise,
-    start: () => {
-      events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
-    },
-  };
-};

package/src/integrations/subagents/client-messages.ts

@@ -1,66 +0,0 @@
-import { SUBAGENT_DELEGATION_PROTOCOL_VERSION } from './protocol-events.ts';
-import type {
-  SubagentDelegationResponse,
-  SubagentDelegationStatus,
-  SubagentDelegationUpdate,
-} from './protocol-events.ts';
-
-const DELEGATION_STATUSES: ReadonlySet<string> = new Set([
-  'completed',
-  'failed',
-  'timed_out',
-  'cancelled',
-  'interrupted',
-  'turn_budget_exhausted',
-  'tool_budget_exhausted',
-  'structured_output_failed',
-  'acceptance_failed',
-  'invalid_request',
-  'unavailable_context',
-]);
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  value !== null && typeof value === 'object' && !Array.isArray(value);
-
-const isDelegationStatus = (value: string): value is SubagentDelegationStatus =>
-  DELEGATION_STATUSES.has(value);
-
-const isDelegationResponse = (
-  value: unknown,
-): value is SubagentDelegationResponse =>
-  isRecord(value) &&
-  value.version === SUBAGENT_DELEGATION_PROTOCOL_VERSION &&
-  typeof value.requestId === 'string' &&
-  typeof value.status === 'string' &&
-  isDelegationStatus(value.status);
-
-const isDelegationUpdate = (
-  value: unknown,
-): value is SubagentDelegationUpdate =>
-  isRecord(value) &&
-  value.version === SUBAGENT_DELEGATION_PROTOCOL_VERSION &&
-  typeof value.requestId === 'string';
-
-/**
- * Reads a request identifier from an untrusted event payload.
- */
-export const requestIdOf = (value: unknown): string | undefined =>
-  isRecord(value) && typeof value.requestId === 'string'
-    ? value.requestId
-    : undefined;
-
-/**
- * Validates an untrusted terminal delegation response.
- */
-export const parseDelegationResponse = (
-  value: unknown,
-): SubagentDelegationResponse | undefined =>
-  isDelegationResponse(value) ? value : undefined;
-
-/**
- * Validates an untrusted delegation progress update.
- */
-export const parseDelegationUpdate = (
-  value: unknown,
-): SubagentDelegationUpdate | undefined =>
-  isDelegationUpdate(value) ? value : undefined;

package/src/integrations/subagents/client-types.ts

@@ -1,36 +0,0 @@
-import type {
-  SubagentDelegationResponse,
-  SubagentDelegationUpdate,
-} from './protocol-events.ts';
-
-export type SubagentEventBus = {
-  readonly on: (event: string, handler: (data: unknown) => void) => unknown;
-  readonly emit: (event: string, data: unknown) => void;
-};
-
-export type DelegateOptions = {
-  readonly signal?: AbortSignal;
-  readonly startTimeoutMs?: number;
-  readonly onUpdate?: (update: SubagentDelegationUpdate) => void;
-  /**
-   * Called when a terminal response arrives after the delegate promise already
-   * rejected locally. The child was still potentially alive until this event.
-   */
-  readonly onLateTerminal?: (response: SubagentDelegationResponse) => void;
-};
-
-export type DelegationTimer = ReturnType<typeof setTimeout>;
-
-export type SubagentDelegationClientDependencies = {
-  readonly scheduleTimeout: (
-    callback: () => void,
-    timeoutMs: number,
-  ) => DelegationTimer;
-  readonly cancelTimeout: (timer: DelegationTimer) => void;
-};
-
-export type ActiveDelegation = {
-  readonly requestId: string;
-  readonly requestCancellation: () => void;
-  readonly terminal: Promise<void>;
-};

package/src/integrations/subagents/diagnostic-format.ts

@@ -1,45 +0,0 @@
-import type { ToolFailureDiagnostic } from './diagnostic-types.ts';
-
-/**
- * Extracts a failed tool name from a terminal error string.
- */
-export const failedToolName = (error: string | undefined): string | undefined =>
-  error?.match(/\b([a-z][\w-]*) failed(?:\s*\(|:)/i)?.[1];
-
-/**
- * Formats a correlated tool failure as concise human-readable lines.
- */
-export const formatToolFailureDiagnostic = (
-  diagnostic: ToolFailureDiagnostic,
-): Array<string> => {
-  const hasSuccessfulOutputCorrelation =
-    diagnostic.correlation === 'successful-output-before-completion';
-  return [
-    `${hasSuccessfulOutputCorrelation ? 'Terminal-reported tool' : 'Failed tool'}: ${diagnostic.tool}`,
-    ...(diagnostic.call
-      ? [
-          `${diagnostic.tool === 'bash' ? 'Command' : 'Arguments'}: ${diagnostic.call}`,
-        ]
-      : []),
-    ...(diagnostic.output
-      ? [
-          `${hasSuccessfulOutputCorrelation ? 'Successful tool output' : 'Tool error'}: ${diagnostic.output}`,
-        ]
-      : []),
-    ...(diagnostic.postCompletionWarning
-      ? [
-          `Post-completion watchdog warning: ${diagnostic.postCompletionWarning}`,
-        ]
-      : []),
-    ...(diagnostic.correlation === 'latest-before-completion'
-      ? [
-          'Correlation: latest failed tool call before successful structured_output; terminal text did not identify the call',
-        ]
-      : []),
-    ...(hasSuccessfulOutputCorrelation
-      ? [
-          'Correlation: terminal error text came from a successful tool result before the final structured_output',
-        ]
-      : []),
-  ];
-};

package/src/integrations/subagents/diagnostic-text.ts

@@ -1,114 +0,0 @@
-const MAX_DIAGNOSTIC_FIELD_CHARS = 1_600;
-const TRUNCATION_MARKER = '… [truncated] …';
-
-/**
- * Narrows an unknown transcript value to a plain record.
- */
-export const isDiagnosticRecord = (
-  value: unknown,
-): value is Record<string, unknown> =>
-  value !== null && typeof value === 'object' && !Array.isArray(value);
-
-/**
- * Bounds diagnostic text while preserving evidence from both ends.
- */
-export const boundedDiagnosticText = (value: string): string => {
-  if (value.length <= MAX_DIAGNOSTIC_FIELD_CHARS) return value;
-  const available = MAX_DIAGNOSTIC_FIELD_CHARS - TRUNCATION_MARKER.length - 2;
-  const startLength = Math.ceil(available / 2);
-  const endLength = Math.floor(available / 2);
-  return `${value.slice(0, startLength)}\n${TRUNCATION_MARKER}\n${value.slice(-endLength)}`;
-};
-
-/**
- * Joins and bounds every text item in a transcript content array.
- */
-export const diagnosticTextContent = (value: unknown): string | undefined => {
-  if (!Array.isArray(value)) return undefined;
-  const text = value
-    .flatMap((item) =>
-      isDiagnosticRecord(item) &&
-      item.type === 'text' &&
-      typeof item.text === 'string'
-        ? [item.text]
-        : [],
-    )
-    .join('\n')
-    .trim();
-  return text ? boundedDiagnosticText(text) : undefined;
-};
-
-/**
- * Returns the first unmodified text item in transcript content.
- */
-export const firstDiagnosticTextContent = (
-  value: unknown,
-): string | undefined => {
-  if (!Array.isArray(value)) return undefined;
-  const content: ReadonlyArray<unknown> = value;
-  const text = content.find(
-    (item) =>
-      isDiagnosticRecord(item) &&
-      item.type === 'text' &&
-      typeof item.text === 'string',
-  );
-  return isDiagnosticRecord(text) && typeof text.text === 'string'
-    ? text.text
-    : undefined;
-};
-
-/**
- * Formats a tool call for bounded diagnostic output.
- */
-export const diagnosticToolCallText = ({
-  tool,
-  argumentsValue,
-}: {
-  readonly tool: string;
-  readonly argumentsValue: unknown;
-}): string | undefined => {
-  if (!isDiagnosticRecord(argumentsValue)) return undefined;
-  if (tool === 'bash') {
-    const command = argumentsValue.command ?? argumentsValue.cmd;
-    if (typeof command === 'string' && command.trim()) {
-      return boundedDiagnosticText(command.trim());
-    }
-  }
-  return boundedDiagnosticText(JSON.stringify(argumentsValue));
-};
-
-/**
- * Extracts the value from an exclusive structured-output argument shape.
- */
-export const structuredCompletionValue = (
-  argumentsValue: unknown,
-): Readonly<Record<string, unknown>> | undefined => {
-  if (!isDiagnosticRecord(argumentsValue)) return undefined;
-  if (
-    Object.keys(argumentsValue).length !== 1 ||
-    !Object.hasOwn(argumentsValue, 'value') ||
-    !isDiagnosticRecord(argumentsValue.value)
-  ) {
-    return undefined;
-  }
-  return argumentsValue.value;
-};
-
-const normalizeDiagnosticText = (value: string): string =>
-  value.replace(/\s+/g, ' ').trim().toLowerCase();
-
-/**
- * Produces normalized, non-trivial fragments for error correlation.
- */
-export const comparableDiagnosticFragments = (
-  value: string,
-): ReadonlyArray<string> => {
-  const normalizedValue = normalizeDiagnosticText(value);
-  const lines = value
-    .split(/\r?\n/)
-    .map(normalizeDiagnosticText)
-    .filter((line) => line.length >= 8);
-  return [...new Set([normalizedValue, ...lines])].filter(
-    (fragment) => fragment.length >= 8,
-  );
-};

package/src/integrations/subagents/diagnostic-types.ts

@@ -1,83 +0,0 @@
-import type { BashPermission } from '../../config/types.ts';
-
-export type ToolFailureDiagnostic = {
-  readonly tool: string;
-  readonly call?: string;
-  readonly output?: string;
-  readonly postCompletionWarning?: string;
-  readonly replaySafe?: true;
-  readonly completionAfterFailure?: true;
-  readonly completionValue?: Readonly<Record<string, unknown>>;
-  readonly transcriptToolCount?: number;
-  readonly transcriptTurnCount?: number;
-  readonly correlation?:
-    'latest-before-completion' | 'successful-output-before-completion';
-};
-
-export type DelegationReplayAudit = {
-  readonly replaySafe: boolean;
-  readonly toolCount: number;
-};
-
-export type DelegationReplayExpectation = {
-  readonly task: string;
-  readonly bashPermission: BashPermission;
-};
-
-export type SubagentSessionIdentity = {
-  readonly runId: string;
-  readonly childIndex: number;
-};
-
-export type RecordedToolCall = {
-  readonly id: string;
-  readonly order: number;
-  readonly tool: string;
-  readonly call?: string;
-  readonly completionValue?: Readonly<Record<string, unknown>>;
-};
-
-export type RecordedToolFailure = ToolFailureDiagnostic & {
-  readonly callId?: string;
-  readonly order: number;
-};
-
-export type RecordedToolSuccess = {
-  readonly order: number;
-  readonly tool: string;
-  readonly call?: string;
-  readonly output?: string;
-  readonly detectorOutput?: string;
-};
-
-export type RecordedCompletion = {
-  readonly order: number;
-  readonly value: Readonly<Record<string, unknown>>;
-};
-
-export type RecordedTranscriptWarning = {
-  readonly order: number;
-  readonly content: string;
-};
-
-export type RecordedMessage = {
-  readonly order: number;
-  readonly value: Readonly<Record<string, unknown>>;
-};
-
-export type ParsedFailureTranscript = {
-  readonly recordedCalls: ReadonlyArray<RecordedToolCall>;
-  readonly diagnostics: ReadonlyArray<RecordedToolFailure>;
-  readonly successfulResults: ReadonlyArray<RecordedToolSuccess>;
-  readonly successfulCompletions: ReadonlyArray<RecordedCompletion>;
-  readonly transcriptWarnings: ReadonlyArray<RecordedTranscriptWarning>;
-  readonly recordedMessages: ReadonlyArray<RecordedMessage>;
-  readonly resultCallIds: ReadonlySet<string>;
-  readonly hasValidFalsePositiveProof: boolean;
-  readonly lastInteractionOrder: number;
-};
-
-export type SessionTail = {
-  readonly content: string;
-  readonly truncated: boolean;
-};

package/src/integrations/subagents/diagnostics.ts

@@ -1,26 +0,0 @@
-export {
-  failedToolName,
-  formatToolFailureDiagnostic,
-} from './diagnostic-format.ts';
-export type {
-  DelegationReplayAudit,
-  DelegationReplayExpectation,
-  SubagentSessionIdentity,
-  ToolFailureDiagnostic,
-} from './diagnostic-types.ts';
-export { parseToolFailureDiagnostic } from './failure-correlation.ts';
-export { parseDelegationReplayAudit } from './replay-audit.ts';
-export {
-  auditCompletedDelegationTranscript,
-  deriveSubagentSessionRoot,
-  readDelegationReplayAudit,
-  readToolFailureDiagnostic,
-} from './session-diagnostics.ts';
-export type {
-  CompletedDelegationTranscriptAudit,
-  SubagentDiagnosticDependencies,
-  SubagentDiagnosticFileHandle,
-  SubagentDiagnosticFileSnapshot,
-  SubagentDiagnosticFileSystem,
-  SubagentDiagnosticPathInspection,
-} from './session-diagnostics.ts';