@wichayutdew/pi-workflows 2.5.0 → 2.6.0

package/src/config/validation/subagent.ts

@@ -1,288 +0,0 @@
-import {
-  DEFAULT_STEP_SUBAGENT,
-  SUBAGENT_RUNTIME_NAME_PATTERN,
-  type StepSubagent,
-  type SubagentContext,
-  type SubagentPermissionCeiling,
-  type SubagentToolBudget,
-  type SubagentTurnBudget,
-} from '../types.ts';
-import {
-  isJsonObject,
-  readBoolean,
-  readInteger,
-  readString,
-  readStringList,
-  rejectUnknownKeys,
-  RESOURCE_SELECTOR_PATTERN,
-  TOOL_PATTERN,
-  type ValidationErrors,
-} from './shared.ts';
-
-function parseSubagentTurnBudget(
-  value: unknown,
-  path: string,
-  errors: ValidationErrors,
-): SubagentTurnBudget | undefined {
-  if (value === undefined) return undefined;
-  if (!isJsonObject(value)) {
-    errors.push(`${path}: expected an object`);
-    return undefined;
-  }
-  rejectUnknownKeys(value, ['maxTurns', 'graceTurns'], path, errors);
-  const maxTurns = readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
-    min: 1,
-    max: 1_000,
-  });
-  const graceTurns =
-    value.graceTurns === undefined
-      ? undefined
-      : readInteger(value.graceTurns, 0, `${path}.graceTurns`, errors, {
-          min: 0,
-          max: 100,
-        });
-  if (maxTurns === 0) return undefined;
-  return {
-    maxTurns,
-    ...(graceTurns !== undefined ? { graceTurns } : {}),
-  };
-}
-
-function parseSubagentToolBudget(
-  value: unknown,
-  path: string,
-  errors: ValidationErrors,
-): SubagentToolBudget | undefined {
-  if (value === undefined) return undefined;
-  if (!isJsonObject(value)) {
-    errors.push(`${path}: expected an object`);
-    return undefined;
-  }
-  rejectUnknownKeys(value, ['soft', 'hard', 'block'], path, errors);
-  const hard = readInteger(value.hard, 0, `${path}.hard`, errors, {
-    min: 1,
-    max: 100_000,
-  });
-  const soft =
-    value.soft === undefined
-      ? undefined
-      : readInteger(value.soft, 0, `${path}.soft`, errors, {
-          min: 1,
-          max: 100_000,
-        });
-
-  let block: Array<string> | '*' | undefined;
-  if (value.block === '*') {
-    block = '*';
-  } else if (value.block !== undefined) {
-    block = readStringList(value.block, `${path}.block`, errors, TOOL_PATTERN);
-    if (block.length === 0) {
-      errors.push(`${path}.block: expected "*" or at least one tool name`);
-    }
-  }
-  if (soft !== undefined && hard > 0 && soft > hard) {
-    errors.push(`${path}.soft: must not exceed hard`);
-  }
-  if (hard === 0) return undefined;
-  return {
-    hard,
-    ...(soft !== undefined ? { soft } : {}),
-    ...(block !== undefined ? { block } : {}),
-  };
-}
-
-/** Parse an optional isolated-step subagent configuration. */
-export function parseStepSubagent(
-  value: unknown,
-  path: string,
-  errors: ValidationErrors,
-): StepSubagent | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value === 'string') {
-    const agent =
-      readString(value, path, errors, {
-        pattern: SUBAGENT_RUNTIME_NAME_PATTERN,
-      }) ?? DEFAULT_STEP_SUBAGENT.agent;
-    return { ...DEFAULT_STEP_SUBAGENT, agent };
-  }
-  if (!isJsonObject(value)) {
-    errors.push(`${path}: expected an agent profile name or object`);
-    return undefined;
-  }
-  rejectUnknownKeys(
-    value,
-    [
-      'agent',
-      'context',
-      'model',
-      'timeoutMs',
-      'turnBudget',
-      'toolBudget',
-      'artifacts',
-      'retryToolFailures',
-    ],
-    path,
-    errors,
-  );
-
-  const agent =
-    value.agent === undefined
-      ? DEFAULT_STEP_SUBAGENT.agent
-      : (readString(value.agent, `${path}.agent`, errors, {
-          pattern: SUBAGENT_RUNTIME_NAME_PATTERN,
-        }) ?? DEFAULT_STEP_SUBAGENT.agent);
-  const contextValue =
-    value.context === undefined
-      ? DEFAULT_STEP_SUBAGENT.context
-      : readString(value.context, `${path}.context`, errors);
-  const context: SubagentContext = DEFAULT_STEP_SUBAGENT.context;
-  if (contextValue !== 'fresh') {
-    errors.push(`${path}.context: expected fresh`);
-  }
-  const model =
-    value.model === undefined
-      ? undefined
-      : readString(value.model, `${path}.model`, errors, {
-          pattern: RESOURCE_SELECTOR_PATTERN,
-        });
-  const timeoutMs = readInteger(
-    value.timeoutMs,
-    DEFAULT_STEP_SUBAGENT.timeoutMs,
-    `${path}.timeoutMs`,
-    errors,
-    { min: 1_000, max: 86_400_000 },
-  );
-  const turnBudget = parseSubagentTurnBudget(
-    value.turnBudget,
-    `${path}.turnBudget`,
-    errors,
-  );
-  const toolBudget = parseSubagentToolBudget(
-    value.toolBudget,
-    `${path}.toolBudget`,
-    errors,
-  );
-  const artifacts = readBoolean(
-    value.artifacts,
-    DEFAULT_STEP_SUBAGENT.artifacts,
-    `${path}.artifacts`,
-    errors,
-  );
-  const retryToolFailures = readBoolean(
-    value.retryToolFailures,
-    DEFAULT_STEP_SUBAGENT.retryToolFailures,
-    `${path}.retryToolFailures`,
-    errors,
-  );
-  return {
-    agent,
-    context,
-    ...(model ? { model } : {}),
-    timeoutMs,
-    ...(turnBudget ? { turnBudget } : {}),
-    ...(toolBudget ? { toolBudget } : {}),
-    artifacts,
-    retryToolFailures,
-  };
-}
-
-/** Parse the subagent limits inside the user permission ceiling. */
-export function parseSubagentPermissionCeiling(
-  value: unknown,
-  path: string,
-  errors: ValidationErrors,
-): SubagentPermissionCeiling | undefined {
-  if (!isJsonObject(value)) {
-    errors.push(`${path}: expected an object`);
-    return undefined;
-  }
-  rejectUnknownKeys(
-    value,
-    [
-      'agents',
-      'contexts',
-      'models',
-      'maxTimeoutMs',
-      'maxTurns',
-      'maxGraceTurns',
-      'maxToolCalls',
-      'artifacts',
-      'retryToolFailures',
-    ],
-    path,
-    errors,
-  );
-  const agents = readStringList(
-    value.agents,
-    `${path}.agents`,
-    errors,
-    SUBAGENT_RUNTIME_NAME_PATTERN,
-  );
-  const contexts = readStringList(
-    value.contexts,
-    `${path}.contexts`,
-    errors,
-    /^fresh$/,
-  ).filter((context): context is SubagentContext => context === 'fresh');
-  const models = readStringList(
-    value.models,
-    `${path}.models`,
-    errors,
-    RESOURCE_SELECTOR_PATTERN,
-  );
-  if (agents.length === 0) {
-    errors.push(`${path}.agents: at least one subagent is required`);
-  }
-  if (contexts.length === 0) {
-    errors.push(`${path}.contexts: at least one context mode is required`);
-  }
-  (
-    [
-      'maxTimeoutMs',
-      'maxTurns',
-      'maxGraceTurns',
-      'maxToolCalls',
-      'artifacts',
-    ] as const
-  )
-    .filter((field) => value[field] === undefined)
-    .forEach((field) => errors.push(`${path}.${field}: required`));
-
-  return {
-    agents,
-    contexts,
-    models,
-    maxTimeoutMs: readInteger(
-      value.maxTimeoutMs,
-      0,
-      `${path}.maxTimeoutMs`,
-      errors,
-      { min: 1_000, max: 86_400_000 },
-    ),
-    maxTurns: readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
-      min: 1,
-      max: 1_000,
-    }),
-    maxGraceTurns: readInteger(
-      value.maxGraceTurns,
-      0,
-      `${path}.maxGraceTurns`,
-      errors,
-      { min: 0, max: 100 },
-    ),
-    maxToolCalls: readInteger(
-      value.maxToolCalls,
-      0,
-      `${path}.maxToolCalls`,
-      errors,
-      { min: 1, max: 100_000 },
-    ),
-    artifacts: readBoolean(value.artifacts, false, `${path}.artifacts`, errors),
-    retryToolFailures: readBoolean(
-      value.retryToolFailures,
-      false,
-      `${path}.retryToolFailures`,
-      errors,
-    ),
-  };
-}

package/src/harness/delegation-failure.ts

@@ -1,248 +0,0 @@
-import type { WorkflowStepResult } from '../runtime/step-result.ts';
-import {
-  failedToolName,
-  formatToolFailureDiagnostic,
-  type CompletedDelegationTranscriptAudit,
-} 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;
-  completedResponseAudit: (
-    active: ActiveDelegation,
-    response: SubagentDelegationResponse,
-  ) => Promise<CompletedDelegationTranscriptAudit>;
-  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'
-  > &
-    Partial<
-      Pick<WorkflowHarnessDependencies, 'auditCompletedDelegationTranscript'>
-    >,
-): DelegationFailureActions {
-  const responseIdentity = (
-    active: ActiveDelegation,
-    response: SubagentDelegationResponse,
-  ): { readonly runId: string; readonly childIndex: 0 } | undefined => {
-    if (
-      response.childIndex !== 0 ||
-      typeof response.runId !== 'string' ||
-      (response.agent !== undefined && response.agent !== active.agent)
-    ) {
-      return undefined;
-    }
-    return { runId: response.runId, childIndex: 0 };
-  };
-
-  const completedResponseAudit = async (
-    active: ActiveDelegation,
-    response: SubagentDelegationResponse,
-  ): Promise<CompletedDelegationTranscriptAudit> => {
-    if (!dependencies.auditCompletedDelegationTranscript) {
-      return {
-        verified: false,
-        reason: 'completed transcript auditing is unavailable',
-      };
-    }
-    return dependencies.auditCompletedDelegationTranscript(
-      response.sessionFile,
-      active.trustedSessionRoot,
-      responseIdentity(active, response),
-    );
-  };
-
-  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 identity = responseIdentity(active, response);
-    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,
-        },
-      ),
-    ]);
-    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,
-    completedResponseAudit,
-    isRetryableTerminalFailure,
-    isSafeToRetryDelegation,
-    rejectedRecoveryReason,
-    completionMatchesResult,
-    recoveredProjectionError,
-    describeDelegationFailure,
-  };
-}

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

@@ -1,161 +0,0 @@
-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']),
-    ...(result.workspace === undefined ? [] : ['workspace']),
-  ].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 &&
-      completion.workspace?.cwd === result.workspace?.cwd
-    );
-  } 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;
-}