Improve workflow error messaging

lib/server/task-errors.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'bun:test';
+import { describeTaskFailure } from '@/lib/server/task-errors';
+
+describe('task error formatter', () => {
+  it('formats missing AI credentials for search indexing', () => {
+    const failure = describeTaskFailure({
+      task_type: 'index_search',
+      stage: 'search.embed',
+      stage_context: {
+        subject: {
+          ticker: 'AAPL',
+          label: 'doc-2'
+        }
+      },
+      payload: {
+        ticker: 'AAPL'
+      }
+    }, 'ZHIPU_API_KEY is required for AI workloads');
+
+    expect(failure.summary).toBe('Search indexing could not generate embeddings.');
+    expect(failure.detail).toContain('ZHIPU_API_KEY is not configured');
+    expect(failure.detail).toContain('AAPL · doc-2');
+  });
+
+  it('formats empty AI responses with stage context', () => {
+    const failure = describeTaskFailure({
+      task_type: 'analyze_filing',
+      stage: 'analyze.generate_report',
+      stage_context: {
+        subject: {
+          ticker: 'AAPL',
+          accessionNumber: '0000320193-26-000001'
+        }
+      },
+      payload: {
+        accessionNumber: '0000320193-26-000001'
+      }
+    }, 'AI SDK returned an empty response');
+
+    expect(failure.summary).toBe('No usable AI response during generate report.');
+    expect(failure.detail).toContain('during generate report');
+    expect(failure.detail).toContain('Retry the job');
+  });
+
+  it('formats workflow cancellations as descriptive operational failures', () => {
+    const failure = describeTaskFailure({
+      task_type: 'portfolio_insights',
+      stage: 'insights.generate',
+      stage_context: null,
+      payload: {}
+    }, 'Workflow run cancelled');
+
+    expect(failure.summary).toBe('The background workflow was cancelled.');
+    expect(failure.detail).toContain('before portfolio insight could finish');
+  });
+});