fix: improve rollback atomicity and validate AI service responses

Track successful dependency additions during persist so rollback
removes partial adds before restoring the snapshot. Add validation
guard in BridgedStructuredGenerator to throw descriptive errors
when AI service returns null/undefined instead of failing silently.

Author: Crunchyman-ralph

.changeset/ai-cluster-generation.md

@@ -1,6 +1,5 @@
 ---
-"@tm/core": minor
-"@tm/cli": minor
+"task-master-ai": minor
 ---
 
 Add `tm clusters generate` command that uses AI to analyze tags in parallel, suggest inter-tag dependencies, and present an interactive terminal UI to review and re-order the cluster layout before persisting. Supports `--auto` for non-interactive mode and `--json` for machine-readable output.

apps/cli/src/commands/cluster-generate.command.ts

@@ -122,17 +122,27 @@ export async function persistClusterDependencies(
 		}
 	}
 
+	// Track successful additions for rollback
+	const succeededAdds: Array<{ from: string; to: string }> = [];
+
 	try {
 		for (const dep of dependencies) {
 			await tmCore.tasks.addTagDependency(dep.from, dep.to);
+			succeededAdds.push({ from: dep.from, to: dep.to });
 		}
 	} catch (error) {
+		// Remove partially-added dependencies before restoring snapshot
+		for (const { from, to } of succeededAdds) {
+			await tmCore.tasks.removeTagDependency(from, to);
+		}
+
 		// Restore original dependencies from snapshot
 		for (const [tagName, deps] of snapshot) {
 			for (const dep of deps) {
 				await tmCore.tasks.addTagDependency(tagName, dep);
 			}
 		}
+
 		throw error;
 	}
 }

packages/tm-core/src/modules/ai/structured-generation/structured-generator.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import {
+	BridgedStructuredGenerator,
+	type GenerateObjectServiceFn
+} from './structured-generator.js';
+import type { AIPrimitiveOptions } from '../types/primitives.types.js';
+
+describe('BridgedStructuredGenerator', () => {
+	describe('generate', () => {
+		it('should throw error when result is null', async () => {
+			const mockService: GenerateObjectServiceFn = vi
+				.fn()
+				.mockResolvedValue(null);
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions & { objectName?: string } = {
+				commandName: 'test-command',
+				objectName: 'test-object'
+			};
+
+			await expect(
+				generator.generate('test prompt', schema, options)
+			).rejects.toThrow(
+				'AI service returned null or undefined result (objectName: test-object, commandName: test-command)'
+			);
+		});
+
+		it('should throw error when result.mainResult is null', async () => {
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: null,
+				modelId: 'test-model',
+				providerName: 'test-provider'
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions & { objectName?: string } = {
+				commandName: 'test-command',
+				objectName: 'test-object'
+			};
+
+			await expect(
+				generator.generate('test prompt', schema, options)
+			).rejects.toThrow(
+				'AI service returned null or undefined result (objectName: test-object, commandName: test-command, modelId: test-model, providerName: test-provider)'
+			);
+		});
+
+		it('should throw error when result.mainResult is undefined', async () => {
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: undefined,
+				modelId: 'test-model',
+				providerName: 'test-provider'
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions & { objectName?: string } = {
+				commandName: 'test-command',
+				objectName: 'test-object'
+			};
+
+			await expect(
+				generator.generate('test prompt', schema, options)
+			).rejects.toThrow(
+				'AI service returned null or undefined result (objectName: test-object, commandName: test-command, modelId: test-model, providerName: test-provider)'
+			);
+		});
+
+		it('should return valid result when mainResult is present', async () => {
+			const mockResult = { value: 'test-value' };
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: mockResult,
+				modelId: 'test-model',
+				providerName: 'test-provider',
+				telemetryData: {
+					inputTokens: 10,
+					outputTokens: 20
+				}
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions & { objectName?: string } = {
+				commandName: 'test-command',
+				objectName: 'test-object'
+			};
+
+			const result = await generator.generate('test prompt', schema, options);
+
+			expect(result.data).toEqual(mockResult);
+			expect(result.usage).toEqual({
+				inputTokens: 10,
+				outputTokens: 20,
+				model: 'test-model',
+				provider: 'test-provider',
+				duration: expect.any(Number)
+			});
+		});
+
+		it('should use default objectName when not provided', async () => {
+			const mockResult = { value: 'test-value' };
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: mockResult,
+				modelId: 'test-model',
+				providerName: 'test-provider'
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions = {
+				commandName: 'test-command'
+			};
+
+			await generator.generate('test prompt', schema, options);
+
+			expect(mockService).toHaveBeenCalledWith(
+				expect.objectContaining({
+					objectName: 'generated_object'
+				})
+			);
+		});
+
+		it('should include error context without model/provider when not available', async () => {
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: null
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions & { objectName?: string } = {
+				commandName: 'test-command',
+				objectName: 'test-object'
+			};
+
+			await expect(
+				generator.generate('test prompt', schema, options)
+			).rejects.toThrow(
+				'AI service returned null or undefined result (objectName: test-object, commandName: test-command)'
+			);
+		});
+
+		it('should handle zero tokens and missing telemetry gracefully', async () => {
+			const mockResult = { value: 'test-value' };
+			const mockService: GenerateObjectServiceFn = vi.fn().mockResolvedValue({
+				mainResult: mockResult,
+				telemetryData: null
+			});
+			const generator = new BridgedStructuredGenerator(mockService);
+
+			const schema = z.object({ value: z.string() });
+			const options: AIPrimitiveOptions = {
+				commandName: 'test-command'
+			};
+
+			const result = await generator.generate('test prompt', schema, options);
+
+			expect(result.usage).toEqual({
+				inputTokens: 0,
+				outputTokens: 0,
+				model: 'unknown',
+				provider: 'unknown',
+				duration: expect.any(Number)
+			});
+		});
+	});
+});

packages/tm-core/src/modules/ai/structured-generation/structured-generator.ts

@@ -46,16 +46,33 @@ export class BridgedStructuredGenerator implements IStructuredGenerator {
 	): Promise<AIPrimitiveResult<T>> {
 		const startTime = Date.now();
 
+		const objectName = options.objectName ?? 'generated_object';
 		const result = await this.generateObjectService({
 			role: 'main',
 			systemPrompt: options.systemPrompt ?? 'You are a helpful assistant.',
 			prompt,
 			schema,
-			objectName: options.objectName ?? 'generated_object',
+			objectName,
 			commandName: options.commandName,
 			outputType: 'cli'
 		});
 
+		// Validate that the AI service returned a valid result
+		if (!result || result.mainResult === null || result.mainResult === undefined) {
+			const errorContext = [
+				`objectName: ${objectName}`,
+				`commandName: ${options.commandName}`,
+				result?.modelId && `modelId: ${result.modelId}`,
+				result?.providerName && `providerName: ${result.providerName}`
+			]
+				.filter(Boolean)
+				.join(', ');
+
+			throw new Error(
+				`AI service returned null or undefined result (${errorContext})`
+			);
+		}
+
 		const duration = Date.now() - startTime;
 
 		return {