@pixelbyte-software/pixcode 1.54.10 → 1.54.11

package/server/modules/orchestration/workflows/handoff-artifact.ts

@@ -1,175 +1,175 @@
-export const PIXCODE_HANDOFF_PROTOCOL = 'pixcode.handoff.v1' as const;
-
-export type WorkflowHandoffTaskStatus =
-  | 'ready'
-  | 'completed'
-  | 'blocked'
-  | 'failed'
-  | 'needs-review';
-
-export interface WorkflowHandoffArtifact {
-  protocol: typeof PIXCODE_HANDOFF_PROTOCOL;
-  taskStatus: WorkflowHandoffTaskStatus;
-  contextSummary: string;
-  taskResult: string;
-  changedFiles: string[];
-  blockers: string[];
-  risks: string[];
-  nextAction: string;
-  nextInstructions: string;
-  producedBy?: {
-    workflowRunId?: string;
-    nodeId?: string;
-    agentLabel?: string;
-    stage?: string;
-  };
-  createdAt: string;
-}
-
-export type HandoffArtifactParseResult =
-  | { ok: true; artifact: WorkflowHandoffArtifact }
-  | { ok: false; error: string };
-
-type HandoffArtifactMetadata = {
-  workflowRunId?: string;
-  nodeId?: string;
-  agentLabel?: string;
-  stage?: string;
-};
-
-const VALID_TASK_STATUSES = new Set<WorkflowHandoffTaskStatus>([
-  'ready',
-  'completed',
-  'blocked',
-  'failed',
-  'needs-review',
-]);
-
-function extractJsonCandidate(text: string): string | null {
-  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
-  if (fenced) return fenced;
-
-  const start = text.indexOf('{');
-  const end = text.lastIndexOf('}');
-  if (start === -1 || end === -1 || end <= start) return null;
-  return text.slice(start, end + 1);
-}
-
-function readRequiredString(record: Record<string, unknown>, key: string): string | null {
-  const value = record[key];
-  if (typeof value !== 'string' || !value.trim()) return null;
-  return value.trim();
-}
-
-function sanitizeChangedFile(filePath: string): string {
-  const normalized = filePath.trim().replaceAll('\\', '/');
-  if (!normalized) return '';
-  if (!normalized.startsWith('/') && !/^[a-zA-Z]:\//.test(normalized)) return normalized;
-  return normalized.split('/').filter(Boolean).slice(-4).join('/');
-}
-
-function readStringArray(record: Record<string, unknown>, key: string): string[] | null {
-  const value = record[key];
-  if (!Array.isArray(value)) return null;
-  return value
-    .filter((item): item is string => typeof item === 'string')
-    .map((item) => key === 'changedFiles' ? sanitizeChangedFile(item) : item.trim())
-    .filter(Boolean)
-    .slice(0, 40);
-}
-
-export function parseHandoffArtifact(
-  text: string,
-  metadata: HandoffArtifactMetadata = {},
-): HandoffArtifactParseResult {
-  const candidate = extractJsonCandidate(text);
-  if (!candidate) {
-    return { ok: false, error: 'Invalid handoff artifact: expected one JSON object.' };
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(candidate);
-  } catch (error) {
-    return {
-      ok: false,
-      error: `Invalid handoff artifact: JSON parse failed (${error instanceof Error ? error.message : String(error)}).`,
-    };
-  }
-
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return { ok: false, error: 'Invalid handoff artifact: payload must be an object.' };
-  }
-
-  const record = parsed as Record<string, unknown>;
-  if (record.protocol !== PIXCODE_HANDOFF_PROTOCOL) {
-    return { ok: false, error: `Invalid handoff artifact: protocol must be ${PIXCODE_HANDOFF_PROTOCOL}.` };
-  }
-
-  const taskStatus = record.taskStatus;
-  if (typeof taskStatus !== 'string' || !VALID_TASK_STATUSES.has(taskStatus as WorkflowHandoffTaskStatus)) {
-    return { ok: false, error: 'Invalid handoff artifact: taskStatus is missing or unsupported.' };
-  }
-
-  const contextSummary = readRequiredString(record, 'contextSummary');
-  const taskResult = readRequiredString(record, 'taskResult');
-  const changedFiles = readStringArray(record, 'changedFiles');
-  const blockers = readStringArray(record, 'blockers');
-  const risks = readStringArray(record, 'risks');
-  const nextAction = readRequiredString(record, 'nextAction');
-  const nextInstructions = readRequiredString(record, 'nextInstructions');
-
-  if (!contextSummary || !taskResult || !changedFiles || !blockers || !risks || !nextAction || !nextInstructions) {
-    return {
-      ok: false,
-      error: 'Invalid handoff artifact: required fields are protocol, taskStatus, contextSummary, taskResult, changedFiles, blockers, risks, nextAction, and nextInstructions.',
-    };
-  }
-
-  return {
-    ok: true,
-    artifact: {
-      protocol: PIXCODE_HANDOFF_PROTOCOL,
-      taskStatus: taskStatus as WorkflowHandoffTaskStatus,
-      contextSummary,
-      taskResult,
-      changedFiles,
-      blockers,
-      risks,
-      nextAction,
-      nextInstructions,
-      producedBy: {
-        workflowRunId: metadata.workflowRunId,
-        nodeId: metadata.nodeId,
-        agentLabel: metadata.agentLabel,
-        stage: metadata.stage,
-      },
-      createdAt: new Date().toISOString(),
-    },
-  };
-}
-
-export function formatHandoffArtifactForContext(artifact: WorkflowHandoffArtifact): string {
-  return [
-    `Pixcode handoff artifact (${PIXCODE_HANDOFF_PROTOCOL})`,
-    JSON.stringify(artifact, null, 2),
-  ].join('\n');
-}
-
-export function handoffArtifactToWorkflowArtifact(artifact: WorkflowHandoffArtifact): {
-  type: 'handoff-artifact';
-  data: Record<string, unknown>;
-  metadata: Record<string, unknown>;
-} {
-  return {
-    type: 'handoff-artifact',
-    data: artifact as unknown as Record<string, unknown>,
-    metadata: {
-      protocol: artifact.protocol,
-      taskStatus: artifact.taskStatus,
-      changedFileCount: artifact.changedFiles.length,
-      blockerCount: artifact.blockers.length,
-      nextAction: artifact.nextAction,
-    },
-  };
-}
+export const PIXCODE_HANDOFF_PROTOCOL = 'pixcode.handoff.v1' as const;
+
+export type WorkflowHandoffTaskStatus =
+  | 'ready'
+  | 'completed'
+  | 'blocked'
+  | 'failed'
+  | 'needs-review';
+
+export interface WorkflowHandoffArtifact {
+  protocol: typeof PIXCODE_HANDOFF_PROTOCOL;
+  taskStatus: WorkflowHandoffTaskStatus;
+  contextSummary: string;
+  taskResult: string;
+  changedFiles: string[];
+  blockers: string[];
+  risks: string[];
+  nextAction: string;
+  nextInstructions: string;
+  producedBy?: {
+    workflowRunId?: string;
+    nodeId?: string;
+    agentLabel?: string;
+    stage?: string;
+  };
+  createdAt: string;
+}
+
+export type HandoffArtifactParseResult =
+  | { ok: true; artifact: WorkflowHandoffArtifact }
+  | { ok: false; error: string };
+
+type HandoffArtifactMetadata = {
+  workflowRunId?: string;
+  nodeId?: string;
+  agentLabel?: string;
+  stage?: string;
+};
+
+const VALID_TASK_STATUSES = new Set<WorkflowHandoffTaskStatus>([
+  'ready',
+  'completed',
+  'blocked',
+  'failed',
+  'needs-review',
+]);
+
+function extractJsonCandidate(text: string): string | null {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+  if (fenced) return fenced;
+
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  return text.slice(start, end + 1);
+}
+
+function readRequiredString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  if (typeof value !== 'string' || !value.trim()) return null;
+  return value.trim();
+}
+
+function sanitizeChangedFile(filePath: string): string {
+  const normalized = filePath.trim().replaceAll('\\', '/');
+  if (!normalized) return '';
+  if (!normalized.startsWith('/') && !/^[a-zA-Z]:\//.test(normalized)) return normalized;
+  return normalized.split('/').filter(Boolean).slice(-4).join('/');
+}
+
+function readStringArray(record: Record<string, unknown>, key: string): string[] | null {
+  const value = record[key];
+  if (!Array.isArray(value)) return null;
+  return value
+    .filter((item): item is string => typeof item === 'string')
+    .map((item) => key === 'changedFiles' ? sanitizeChangedFile(item) : item.trim())
+    .filter(Boolean)
+    .slice(0, 40);
+}
+
+export function parseHandoffArtifact(
+  text: string,
+  metadata: HandoffArtifactMetadata = {},
+): HandoffArtifactParseResult {
+  const candidate = extractJsonCandidate(text);
+  if (!candidate) {
+    return { ok: false, error: 'Invalid handoff artifact: expected one JSON object.' };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Invalid handoff artifact: JSON parse failed (${error instanceof Error ? error.message : String(error)}).`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, error: 'Invalid handoff artifact: payload must be an object.' };
+  }
+
+  const record = parsed as Record<string, unknown>;
+  if (record.protocol !== PIXCODE_HANDOFF_PROTOCOL) {
+    return { ok: false, error: `Invalid handoff artifact: protocol must be ${PIXCODE_HANDOFF_PROTOCOL}.` };
+  }
+
+  const taskStatus = record.taskStatus;
+  if (typeof taskStatus !== 'string' || !VALID_TASK_STATUSES.has(taskStatus as WorkflowHandoffTaskStatus)) {
+    return { ok: false, error: 'Invalid handoff artifact: taskStatus is missing or unsupported.' };
+  }
+
+  const contextSummary = readRequiredString(record, 'contextSummary');
+  const taskResult = readRequiredString(record, 'taskResult');
+  const changedFiles = readStringArray(record, 'changedFiles');
+  const blockers = readStringArray(record, 'blockers');
+  const risks = readStringArray(record, 'risks');
+  const nextAction = readRequiredString(record, 'nextAction');
+  const nextInstructions = readRequiredString(record, 'nextInstructions');
+
+  if (!contextSummary || !taskResult || !changedFiles || !blockers || !risks || !nextAction || !nextInstructions) {
+    return {
+      ok: false,
+      error: 'Invalid handoff artifact: required fields are protocol, taskStatus, contextSummary, taskResult, changedFiles, blockers, risks, nextAction, and nextInstructions.',
+    };
+  }
+
+  return {
+    ok: true,
+    artifact: {
+      protocol: PIXCODE_HANDOFF_PROTOCOL,
+      taskStatus: taskStatus as WorkflowHandoffTaskStatus,
+      contextSummary,
+      taskResult,
+      changedFiles,
+      blockers,
+      risks,
+      nextAction,
+      nextInstructions,
+      producedBy: {
+        workflowRunId: metadata.workflowRunId,
+        nodeId: metadata.nodeId,
+        agentLabel: metadata.agentLabel,
+        stage: metadata.stage,
+      },
+      createdAt: new Date().toISOString(),
+    },
+  };
+}
+
+export function formatHandoffArtifactForContext(artifact: WorkflowHandoffArtifact): string {
+  return [
+    `Pixcode handoff artifact (${PIXCODE_HANDOFF_PROTOCOL})`,
+    JSON.stringify(artifact, null, 2),
+  ].join('\n');
+}
+
+export function handoffArtifactToWorkflowArtifact(artifact: WorkflowHandoffArtifact): {
+  type: 'handoff-artifact';
+  data: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+} {
+  return {
+    type: 'handoff-artifact',
+    data: artifact as unknown as Record<string, unknown>,
+    metadata: {
+      protocol: artifact.protocol,
+      taskStatus: artifact.taskStatus,
+      changedFileCount: artifact.changedFiles.length,
+      blockerCount: artifact.blockers.length,
+      nextAction: artifact.nextAction,
+    },
+  };
+}

package/server/modules/orchestration/workflows/workflow-fallback-policy.ts

@@ -1,161 +1,161 @@
-import type { WorkflowNode, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
-
-export const PIXCODE_FALLBACK_POLICY_PROTOCOL = 'pixcode.fallback-policy.v1';
-
-export type WorkflowFallbackTrigger = 'provider_failure' | 'timeout' | 'tool_failure' | 'invalid_output';
-
-export interface WorkflowFallbackPolicy {
-  protocol: typeof PIXCODE_FALLBACK_POLICY_PROTOCOL;
-  enabled: boolean;
-  triggers: WorkflowFallbackTrigger[];
-  maxFallbacksPerRun: number;
-  requireDifferentAgent: boolean;
-}
-
-export interface WorkflowFallbackDecision {
-  shouldFallback: boolean;
-  trigger: WorkflowFallbackTrigger;
-  reason: string;
-  policy: WorkflowFallbackPolicy;
-  skippedReason?: string;
-}
-
-const DEFAULT_TRIGGERS: WorkflowFallbackTrigger[] = [
-  'provider_failure',
-  'timeout',
-  'tool_failure',
-  'invalid_output',
-];
-
-export const DEFAULT_WORKFLOW_FALLBACK_POLICY: WorkflowFallbackPolicy = {
-  protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
-  enabled: true,
-  triggers: DEFAULT_TRIGGERS,
-  maxFallbacksPerRun: 3,
-  requireDifferentAgent: true,
-};
-
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
-}
-
-function readBoolean(value: unknown): boolean | undefined {
-  return typeof value === 'boolean' ? value : undefined;
-}
-
-function readNumber(value: unknown): number | undefined {
-  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-}
-
-function isWorkflowFallbackTrigger(value: unknown): value is WorkflowFallbackTrigger {
-  return value === 'provider_failure'
-    || value === 'timeout'
-    || value === 'tool_failure'
-    || value === 'invalid_output';
-}
-
-function readFallbackTriggers(value: unknown): WorkflowFallbackTrigger[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const triggers = value.filter(isWorkflowFallbackTrigger);
-  return triggers.length > 0 ? [...new Set(triggers)] : undefined;
-}
-
-export function readWorkflowFallbackPolicy(metadata?: Record<string, unknown>): WorkflowFallbackPolicy {
-  const settings = readRecord(metadata?.settings) ?? {};
-  const configured = readRecord(settings.fallbackPolicy) ?? {};
-  const maxFallbacksPerRun = readNumber(configured.maxFallbacksPerRun);
-
-  return {
-    protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
-    enabled: readBoolean(configured.enabled) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.enabled,
-    triggers: readFallbackTriggers(configured.triggers) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.triggers,
-    maxFallbacksPerRun: maxFallbacksPerRun === undefined
-      ? DEFAULT_WORKFLOW_FALLBACK_POLICY.maxFallbacksPerRun
-      : Math.max(0, Math.min(8, Math.round(maxFallbacksPerRun))),
-    requireDifferentAgent: readBoolean(configured.requireDifferentAgent)
-      ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.requireDifferentAgent,
-  };
-}
-
-export function classifyWorkflowFailure(
-  reason: string,
-  explicitTrigger?: WorkflowFallbackTrigger,
-): WorkflowFallbackTrigger {
-  if (explicitTrigger) return explicitTrigger;
-
-  const text = reason.toLocaleLowerCase('en');
-  if (/timed out|timeout|deadline/u.test(text)) return 'timeout';
-  if (/invalid (handoff|output|artifact|json|schema)|parse|protocol/u.test(text)) return 'invalid_output';
-  if (
-    /tool|command|shell|exit code|permission|file write|write failed|network|fetch|curl|wget|gh |npm |git /u
-      .test(text)
-  ) {
-    return 'tool_failure';
-  }
-  return 'provider_failure';
-}
-
-function fallbackEventCount(run: WorkflowRun): number {
-  return Array.isArray(run.metadata?.fallbackEvents) ? run.metadata.fallbackEvents.length : 0;
-}
-
-export function resolveWorkflowFallbackDecision({
-  run,
-  node,
-  reason,
-  trigger,
-  fallbackAgentInstanceId,
-}: {
-  run: WorkflowRun;
-  node: WorkflowNode;
-  reason: string;
-  trigger?: WorkflowFallbackTrigger;
-  fallbackAgentInstanceId?: string;
-}): WorkflowFallbackDecision {
-  const fallbackTrigger = classifyWorkflowFailure(reason, trigger);
-  const policy = readWorkflowFallbackPolicy(run.metadata);
-
-  if (!policy.enabled) {
-    return {
-      shouldFallback: false,
-      trigger: fallbackTrigger,
-      reason,
-      policy,
-      skippedReason: 'Fallback policy is disabled.',
-    };
-  }
-  if (!policy.triggers.includes(fallbackTrigger)) {
-    return {
-      shouldFallback: false,
-      trigger: fallbackTrigger,
-      reason,
-      policy,
-      skippedReason: `Fallback trigger ${fallbackTrigger} is not enabled.`,
-    };
-  }
-  if (fallbackEventCount(run) >= policy.maxFallbacksPerRun) {
-    return {
-      shouldFallback: false,
-      trigger: fallbackTrigger,
-      reason,
-      policy,
-      skippedReason: `Fallback limit ${policy.maxFallbacksPerRun} reached.`,
-    };
-  }
-  if (policy.requireDifferentAgent && fallbackAgentInstanceId && fallbackAgentInstanceId === node.agentInstanceId) {
-    return {
-      shouldFallback: false,
-      trigger: fallbackTrigger,
-      reason,
-      policy,
-      skippedReason: 'Fallback agent must be different from the failed agent.',
-    };
-  }
-
-  return {
-    shouldFallback: true,
-    trigger: fallbackTrigger,
-    reason,
-    policy,
-  };
-}
+import type { WorkflowNode, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
+
+export const PIXCODE_FALLBACK_POLICY_PROTOCOL = 'pixcode.fallback-policy.v1';
+
+export type WorkflowFallbackTrigger = 'provider_failure' | 'timeout' | 'tool_failure' | 'invalid_output';
+
+export interface WorkflowFallbackPolicy {
+  protocol: typeof PIXCODE_FALLBACK_POLICY_PROTOCOL;
+  enabled: boolean;
+  triggers: WorkflowFallbackTrigger[];
+  maxFallbacksPerRun: number;
+  requireDifferentAgent: boolean;
+}
+
+export interface WorkflowFallbackDecision {
+  shouldFallback: boolean;
+  trigger: WorkflowFallbackTrigger;
+  reason: string;
+  policy: WorkflowFallbackPolicy;
+  skippedReason?: string;
+}
+
+const DEFAULT_TRIGGERS: WorkflowFallbackTrigger[] = [
+  'provider_failure',
+  'timeout',
+  'tool_failure',
+  'invalid_output',
+];
+
+export const DEFAULT_WORKFLOW_FALLBACK_POLICY: WorkflowFallbackPolicy = {
+  protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
+  enabled: true,
+  triggers: DEFAULT_TRIGGERS,
+  maxFallbacksPerRun: 3,
+  requireDifferentAgent: true,
+};
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function isWorkflowFallbackTrigger(value: unknown): value is WorkflowFallbackTrigger {
+  return value === 'provider_failure'
+    || value === 'timeout'
+    || value === 'tool_failure'
+    || value === 'invalid_output';
+}
+
+function readFallbackTriggers(value: unknown): WorkflowFallbackTrigger[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const triggers = value.filter(isWorkflowFallbackTrigger);
+  return triggers.length > 0 ? [...new Set(triggers)] : undefined;
+}
+
+export function readWorkflowFallbackPolicy(metadata?: Record<string, unknown>): WorkflowFallbackPolicy {
+  const settings = readRecord(metadata?.settings) ?? {};
+  const configured = readRecord(settings.fallbackPolicy) ?? {};
+  const maxFallbacksPerRun = readNumber(configured.maxFallbacksPerRun);
+
+  return {
+    protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
+    enabled: readBoolean(configured.enabled) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.enabled,
+    triggers: readFallbackTriggers(configured.triggers) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.triggers,
+    maxFallbacksPerRun: maxFallbacksPerRun === undefined
+      ? DEFAULT_WORKFLOW_FALLBACK_POLICY.maxFallbacksPerRun
+      : Math.max(0, Math.min(8, Math.round(maxFallbacksPerRun))),
+    requireDifferentAgent: readBoolean(configured.requireDifferentAgent)
+      ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.requireDifferentAgent,
+  };
+}
+
+export function classifyWorkflowFailure(
+  reason: string,
+  explicitTrigger?: WorkflowFallbackTrigger,
+): WorkflowFallbackTrigger {
+  if (explicitTrigger) return explicitTrigger;
+
+  const text = reason.toLocaleLowerCase('en');
+  if (/timed out|timeout|deadline/u.test(text)) return 'timeout';
+  if (/invalid (handoff|output|artifact|json|schema)|parse|protocol/u.test(text)) return 'invalid_output';
+  if (
+    /tool|command|shell|exit code|permission|file write|write failed|network|fetch|curl|wget|gh |npm |git /u
+      .test(text)
+  ) {
+    return 'tool_failure';
+  }
+  return 'provider_failure';
+}
+
+function fallbackEventCount(run: WorkflowRun): number {
+  return Array.isArray(run.metadata?.fallbackEvents) ? run.metadata.fallbackEvents.length : 0;
+}
+
+export function resolveWorkflowFallbackDecision({
+  run,
+  node,
+  reason,
+  trigger,
+  fallbackAgentInstanceId,
+}: {
+  run: WorkflowRun;
+  node: WorkflowNode;
+  reason: string;
+  trigger?: WorkflowFallbackTrigger;
+  fallbackAgentInstanceId?: string;
+}): WorkflowFallbackDecision {
+  const fallbackTrigger = classifyWorkflowFailure(reason, trigger);
+  const policy = readWorkflowFallbackPolicy(run.metadata);
+
+  if (!policy.enabled) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: 'Fallback policy is disabled.',
+    };
+  }
+  if (!policy.triggers.includes(fallbackTrigger)) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: `Fallback trigger ${fallbackTrigger} is not enabled.`,
+    };
+  }
+  if (fallbackEventCount(run) >= policy.maxFallbacksPerRun) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: `Fallback limit ${policy.maxFallbacksPerRun} reached.`,
+    };
+  }
+  if (policy.requireDifferentAgent && fallbackAgentInstanceId && fallbackAgentInstanceId === node.agentInstanceId) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: 'Fallback agent must be different from the failed agent.',
+    };
+  }
+
+  return {
+    shouldFallback: true,
+    trigger: fallbackTrigger,
+    reason,
+    policy,
+  };
+}