Skip to content

The open alternative to Salesforce, designed for AI.

feat(ai-chat): log one structured line per failed turn (#27102)

Etienne2293e07c0671
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/jobs/stream-agent-chat.job.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/jobs/stream-agent-chat.job.ts
index 06648333acf..8b345eef304 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/jobs/stream-agent-chat.job.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/jobs/stream-agent-chat.job.ts
@@ -49,6 +49,7 @@ import {
resolveSupersededTurnOutcome,
} from 'src/engine/metadata-modules/ai/ai-chat/utils/classify-agent-chat-turn-outcome.util';
import { AGENT_CHAT_CHECKPOINT_INTERVAL_MS } from 'src/engine/metadata-modules/ai/ai-chat/constants/agent-chat-checkpoint-interval-ms.constant';
+import { formatErrorWithCause } from 'src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util';
import { getCancelChannel } from 'src/engine/metadata-modules/ai/ai-chat/utils/get-cancel-channel.util';
import { mapErrorToStreamError } from 'src/engine/metadata-modules/ai/ai-chat/utils/map-error-to-stream-error.util';
import { tagAiChatStreamScope } from 'src/engine/metadata-modules/ai/ai-chat/utils/tag-ai-chat-stream-scope.util';
@@ -187,7 +188,7 @@ export class StreamAgentChatJob {
);
} catch (error) {
this.logger.error(
- `Stream ${data.streamId} failed: ${error instanceof Error ? error.message : String(error)}`,
+ `[AI_CHAT_TURN_FAILED] failurePhase=execution, model=${turnModelId}, threadId=${data.threadId}, workspaceId=${data.workspaceId}, streamId=${data.streamId}: ${formatErrorWithCause(error)}`,
);
const streamError = mapErrorToStreamError(error);
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-stream-recovery.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-stream-recovery.service.ts
index 969e64efd30..4d8a478296c 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-stream-recovery.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-stream-recovery.service.ts
@@ -1,4 +1,4 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
import { isNonEmptyString } from 'twenty-shared/utils';
import { MetricsService } from 'src/engine/core-modules/metrics/metrics.service';
@@ -14,6 +14,8 @@ import { InjectAgentHistoryRepository } from 'src/engine/metadata-modules/ai/ai-
@Injectable()
export class AgentChatStreamRecoveryService {
+ private readonly logger = new Logger(AgentChatStreamRecoveryService.name);
+
constructor(
@InjectAgentHistoryRepository('agentChatThread')
private readonly threadRepository: AgentHistoryRepository<AgentChatThreadWorkspaceEntity>,
@@ -62,6 +64,10 @@ export class AgentChatStreamRecoveryService {
},
});
+ this.logger.error(
+ `[AI_CHAT_TURN_FAILED] failurePhase=interrupted, threadId=${thread.id}, workspaceId=${workspaceId}: stream ${thread.activeStreamId} stopped sending heartbeats`,
+ );
+
await this.eventPublisherService.resetStreamState(thread.id);
await this.eventPublisherService
.publish({
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-streaming.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-streaming.service.ts
index 56feee1c379..655196150c9 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-streaming.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/agent-chat-streaming.service.ts
@@ -41,6 +41,7 @@ import { AgentChatEventPublisherService } from 'src/engine/metadata-modules/ai/a
import { AgentChatStreamHeartbeatService } from 'src/engine/metadata-modules/ai/ai-chat/services/agent-chat-stream-heartbeat.service';
import { AgentChatService } from 'src/engine/metadata-modules/ai/ai-chat/services/agent-chat.service';
import { AiChatFileAttachment } from 'src/engine/metadata-modules/ai/ai-chat/types/ai-chat-file-attachment.type';
+import { formatErrorWithCause } from 'src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util';
import { mapErrorToStreamError } from 'src/engine/metadata-modules/ai/ai-chat/utils/map-error-to-stream-error.util';
import {
AiException,
@@ -259,16 +260,11 @@ export class AgentChatStreamingService {
};
} catch (error) {
await this.releaseStreamClaim(threadId, workspace.id, streamId);
- const streamError = mapErrorToStreamError(error);
-
- this.metricsService.incrementCounterBy({
- key: MetricsKeys.AiChatTurnFailed,
- amount: 1,
- attributes: {
- model: modelId ?? 'unknown',
- failure_phase: 'enqueue',
- error_code: streamError.code,
- },
+ this.recordEnqueueFailure({
+ threadId,
+ workspaceId: workspace.id,
+ model: modelId ?? 'unknown',
+ error,
});
throw error;
}
@@ -365,16 +361,11 @@ export class AgentChatStreamingService {
return { streamId, messageId, turnId };
} catch (error) {
await this.releaseStreamClaim(threadId, workspace.id, streamId);
- const streamError = mapErrorToStreamError(error);
-
- this.metricsService.incrementCounterBy({
- key: MetricsKeys.AiChatTurnFailed,
- amount: 1,
- attributes: {
- model: modelId,
- failure_phase: 'enqueue',
- error_code: streamError.code,
- },
+ this.recordEnqueueFailure({
+ threadId,
+ workspaceId: workspace.id,
+ model: modelId,
+ error,
});
throw error;
}
@@ -518,16 +509,11 @@ export class AgentChatStreamingService {
await this.releaseStreamClaim(threadId, workspace.id, streamId, {
lastStreamError: thread.lastStreamError,
});
- const streamError = mapErrorToStreamError(error);
-
- this.metricsService.incrementCounterBy({
- key: MetricsKeys.AiChatTurnFailed,
- amount: 1,
- attributes: {
- model: modelId ?? 'unknown',
- failure_phase: 'enqueue',
- error_code: streamError.code,
- },
+ this.recordEnqueueFailure({
+ threadId,
+ workspaceId: workspace.id,
+ model: modelId ?? 'unknown',
+ error,
});
throw error;
}
@@ -749,16 +735,11 @@ export class AgentChatStreamingService {
);
} catch (error) {
await this.releaseStreamClaim(threadId, workspaceId, streamId);
- const streamError = mapErrorToStreamError(error);
-
- this.metricsService.incrementCounterBy({
- key: MetricsKeys.AiChatTurnFailed,
- amount: 1,
- attributes: {
- model: 'unknown',
- failure_phase: 'enqueue',
- error_code: streamError.code,
- },
+ this.recordEnqueueFailure({
+ threadId,
+ workspaceId,
+ model: 'unknown',
+ error,
});
throw error;
}
@@ -811,6 +792,32 @@ export class AgentChatStreamingService {
});
}
+ private recordEnqueueFailure({
+ threadId,
+ workspaceId,
+ model,
+ error,
+ }: {
+ threadId: string;
+ workspaceId: string;
+ model: string;
+ error: unknown;
+ }): void {
+ this.metricsService.incrementCounterBy({
+ key: MetricsKeys.AiChatTurnFailed,
+ amount: 1,
+ attributes: {
+ model,
+ failure_phase: 'enqueue',
+ error_code: mapErrorToStreamError(error).code,
+ },
+ });
+
+ this.logger.error(
+ `[AI_CHAT_TURN_FAILED] failurePhase=enqueue, model=${model}, threadId=${threadId}, workspaceId=${workspaceId}: ${formatErrorWithCause(error)}`,
+ );
+ }
+
async releaseStreamClaim(
threadId: string,
workspaceId: string,
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/format-error-with-cause.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/format-error-with-cause.util.spec.ts
new file mode 100644
index 00000000000..0fa6c3e6736
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/format-error-with-cause.util.spec.ts
@@ -0,0 +1,35 @@
+import { formatErrorWithCause } from 'src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util';
+import { computeTwentyOrmException } from 'src/engine/twenty-orm/error-handling/compute-twenty-orm-exception.util';
+
+describe('formatErrorWithCause', () => {
+ it('shows the Postgres error the ORM hides behind a generic message', () => {
+ const postgresError = Object.assign(
+ new Error('unsupported Unicode escape sequence'),
+ { code: '22P05' },
+ );
+
+ expect(formatErrorWithCause(computeTwentyOrmException(postgresError))).toBe(
+ 'Error: Data validation error. <- Error: unsupported Unicode escape sequence',
+ );
+ });
+
+ it('shows a cause the AI SDK sets as a plain string', () => {
+ const error = Object.assign(new Error('Type validation failed'), {
+ cause: 'value must be a string in the enum',
+ });
+
+ expect(formatErrorWithCause(error)).toBe(
+ 'Error: Type validation failed <- value must be a string in the enum',
+ );
+ });
+
+ it('formats an error without a cause', () => {
+ expect(formatErrorWithCause(new Error('Provider timed out'))).toBe(
+ 'Error: Provider timed out',
+ );
+ });
+
+ it('formats a thrown non-Error value', () => {
+ expect(formatErrorWithCause('boom')).toBe('boom');
+ });
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util.ts
new file mode 100644
index 00000000000..ba8fd47ea2b
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/format-error-with-cause.util.ts
@@ -0,0 +1,9 @@
+import { isDefined } from 'twenty-shared/utils';
+
+const formatError = (error: unknown): string =>
+ error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+
+export const formatErrorWithCause = (error: unknown): string =>
+ error instanceof Error && 'cause' in error && isDefined(error.cause)
+ ? `${formatError(error)} <- ${formatError(error.cause)}`
+ : formatError(error);