feat(automation): add retry backoff, node timeoutMs/schemas, and version history to flow spec

- Add backoffMultiplier, maxRetryDelayMs, jitter to FlowSchema.errorHandling
- Add timeoutMs, inputSchema, outputSchema to FlowNodeSchema
- Add FlowVersionHistorySchema for rollback support
- Add comprehensive tests for all new fields

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot

packages/spec/src/automation/flow.test.ts

@@ -5,6 +5,7 @@ import {
   FlowEdgeSchema,
   FlowVariableSchema,
   FlowNodeAction,
+  FlowVersionHistorySchema,
   defineFlow,
   type Flow,
   type FlowNode,
@@ -130,6 +131,39 @@ describe('FlowNodeSchema', () => {
       expect(() => FlowNodeSchema.parse(node)).not.toThrow();
     });
   });
+
+  it('should accept node with timeoutMs', () => {
+    const result = FlowNodeSchema.safeParse({
+      id: 'http_1',
+      type: 'http_request',
+      label: 'Call API',
+      timeoutMs: 5000,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.timeoutMs).toBe(5000);
+    }
+  });
+
+  it('should accept node with inputSchema and outputSchema', () => {
+    const result = FlowNodeSchema.safeParse({
+      id: 'script_1',
+      type: 'script',
+      label: 'Process Data',
+      inputSchema: {
+        name: { type: 'string', required: true, description: 'User name' },
+        age: { type: 'number', required: false },
+      },
+      outputSchema: {
+        greeting: { type: 'string', description: 'Generated greeting' },
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.inputSchema).toBeDefined();
+      expect(result.data.outputSchema).toBeDefined();
+    }
+  });
 });
 
 describe('FlowEdgeSchema', () => {
@@ -597,6 +631,53 @@ describe('FlowSchema - errorHandling', () => {
     });
     expect(result.errorHandling).toBeUndefined();
   });
+
+  it('should accept exponential backoff configuration', () => {
+    const result = FlowSchema.safeParse({
+      name: 'backoff_flow',
+      label: 'Backoff Flow',
+      type: 'autolaunched',
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        { id: 'end', type: 'end', label: 'End' },
+      ],
+      edges: [{ id: 'e1', source: 'start', target: 'end' }],
+      errorHandling: {
+        strategy: 'retry',
+        maxRetries: 5,
+        retryDelayMs: 1000,
+        backoffMultiplier: 2,
+        maxRetryDelayMs: 30000,
+        jitter: true,
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.errorHandling!.backoffMultiplier).toBe(2);
+      expect(result.data.errorHandling!.maxRetryDelayMs).toBe(30000);
+      expect(result.data.errorHandling!.jitter).toBe(true);
+    }
+  });
+
+  it('should use defaults for backoff fields', () => {
+    const result = FlowSchema.safeParse({
+      name: 'default_backoff',
+      label: 'Default Backoff',
+      type: 'autolaunched',
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        { id: 'end', type: 'end', label: 'End' },
+      ],
+      edges: [{ id: 'e1', source: 'start', target: 'end' }],
+      errorHandling: { strategy: 'retry' },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.errorHandling!.backoffMultiplier).toBe(1);
+      expect(result.data.errorHandling!.maxRetryDelayMs).toBe(30000);
+      expect(result.data.errorHandling!.jitter).toBe(false);
+    }
+  });
 });
 
 describe('defineFlow', () => {
@@ -642,3 +723,31 @@ describe('defineFlow', () => {
     })).toThrow();
   });
 });
+
+describe('FlowVersionHistorySchema', () => {
+  it('should validate a flow version history entry', () => {
+    const result = FlowVersionHistorySchema.safeParse({
+      flowName: 'my_flow',
+      version: 1,
+      definition: {
+        name: 'my_flow',
+        label: 'My Flow',
+        type: 'autolaunched',
+        nodes: [
+          { id: 'start', type: 'start', label: 'Start' },
+          { id: 'end', type: 'end', label: 'End' },
+        ],
+        edges: [{ id: 'e1', source: 'start', target: 'end' }],
+      },
+      createdAt: '2026-01-01T00:00:00Z',
+      createdBy: 'admin',
+      changeNote: 'Initial version',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('should require flowName, version, definition, and createdAt', () => {
+    const result = FlowVersionHistorySchema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+});

packages/spec/src/automation/flow.zod.ts

@@ -72,6 +72,22 @@ export const FlowNodeSchema = z.object({
 
   /** UI Position (for the canvas) */
   position: z.object({ x: z.number(), y: z.number() }).optional(),
+
+  /** Node-level execution timeout */
+  timeoutMs: z.number().int().min(0).optional().describe('Maximum execution time for this node in milliseconds'),
+
+  /** Node input schema declaration for Studio form generation and runtime validation */
+  inputSchema: z.record(z.string(), z.object({
+    type: z.enum(['string', 'number', 'boolean', 'object', 'array']).describe('Parameter type'),
+    required: z.boolean().default(false).describe('Whether the parameter is required'),
+    description: z.string().optional().describe('Parameter description'),
+  })).optional().describe('Input parameter schema for this node'),
+
+  /** Node output schema declaration */
+  outputSchema: z.record(z.string(), z.object({
+    type: z.enum(['string', 'number', 'boolean', 'object', 'array']).describe('Output type'),
+    description: z.string().optional().describe('Output description'),
+  })).optional().describe('Output schema declaration for this node'),
 });
 
 /**
@@ -143,6 +159,9 @@ export const FlowSchema = z.object({
     strategy: z.enum(['fail', 'retry', 'continue']).default('fail').describe('How to handle node execution errors'),
     maxRetries: z.number().int().min(0).max(10).default(0).describe('Number of retry attempts (only for retry strategy)'),
     retryDelayMs: z.number().int().min(0).default(1000).describe('Delay between retries in milliseconds'),
+    backoffMultiplier: z.number().min(1).default(1).describe('Multiplier for exponential backoff between retries'),
+    maxRetryDelayMs: z.number().int().min(0).default(30000).describe('Maximum delay between retries in milliseconds'),
+    jitter: z.boolean().default(false).describe('Add random jitter to retry delay to avoid thundering herd'),
     fallbackNodeId: z.string().optional().describe('Node ID to jump to on unrecoverable error'),
   }).optional().describe('Flow-level error handling configuration'),
 });
@@ -176,3 +195,21 @@ export type FlowNode = z.input<typeof FlowNodeSchema>;
 export type FlowNodeParsed = z.infer<typeof FlowNodeSchema>;
 export type FlowEdge = z.input<typeof FlowEdgeSchema>;
 export type FlowEdgeParsed = z.infer<typeof FlowEdgeSchema>;
+
+/**
+ * Flow Version History Schema
+ * Tracks historical versions of flow definitions for rollback support.
+ *
+ * Industry alignment: Salesforce Flow Versions, n8n Workflow History.
+ */
+export const FlowVersionHistorySchema = z.object({
+  flowName: z.string().describe('Flow machine name'),
+  version: z.number().int().min(1).describe('Version number'),
+  definition: FlowSchema.describe('Complete flow definition snapshot'),
+  createdAt: z.string().datetime().describe('When this version was created'),
+  createdBy: z.string().optional().describe('User who created this version'),
+  changeNote: z.string().optional().describe('Description of what changed in this version'),
+});
+
+export type FlowVersionHistory = z.input<typeof FlowVersionHistorySchema>;
+export type FlowVersionHistoryParsed = z.infer<typeof FlowVersionHistorySchema>;