From 6d99638237b99e6b58b5439d51aad2ab3a5f2343 Mon Sep 17 00:00:00 2001 From: atomic-sentry-bot Date: Sun, 15 Nov 2026 01:35:49 +0000 Subject: [PATCH 1/2] diagnostic: collect evidence for Sentry issue 7848662602 --- .../2026-11-15-diagnose-cli-chat-failures.md | 13 ++++ docs/decisions/INDEX.md | 1 + .../sentry-agent-diagnostics.test.ts | 65 +++++++++++++++++++ src/telemetry/sentry-agent-diagnostics.ts | 6 +- 4 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 docs/decisions/2026-11-15-diagnose-cli-chat-failures.md diff --git a/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md b/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md new file mode 100644 index 0000000..35e0be6 --- /dev/null +++ b/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md @@ -0,0 +1,13 @@ +--- +date: 2026-11-15 +title: "Diagnose CLI chat failures with finite tags" +--- + +# 2026-11-15 — Diagnose CLI chat failures with finite tags + +- **Context:** ATOMIC-CHAT-SERVER-1S (`7848662602`) reported `Error: cli chat: unknown` on `atc@0.2.18` (dist `b869424b124d`, the current base) with component `cli` and operation `chat`, one occurrence. The frames end at `src/terminal-service/client.ts:110` inside the SSE reading loop of `streamChat`, which the `atc chat` command reaches through `src/commands/access/terminal.ts:101`. `failureReport` scrubs the exception to `Unexpected failure in chat` and adds only `reportCodeOf(error)`, which is `undefined` for a plain `Error`, so the report names neither the branch nor the cause. `streamChat` throws four plain `Error`s (invalid endpoint, server-reported generation error, empty response body, truncated stream), and `JSON.parse` of a malformed frame throws a dynamic `SyntaxError` that no exact-message rule can name. +- **Decision:** Add four exact-message mappings from `src/terminal-service/client.ts` to the bounded diagnostic observer — `CLI_CHAT_ENDPOINT_INVALID`, `CLI_CHAT_GENERATION_ERROR`, `CLI_CHAT_EMPTY_RESPONSE`, `CLI_CHAT_STREAM_TRUNCATED` — and inspect allowlisted transport cause codes across up to five `Error` causes. Message scrubbing, filtering of expected failures, severity, consent and exit behaviour stay unchanged. +- **Consequences:** The next `cli chat` event identifies the failing client branch, or the transport cause when the stream read itself rejects. An event carrying neither tag comes from a dynamic-message branch (a `JSON.parse` `SyntaxError` or a `The server reported ...`/`Request returned HTTP ` message built at runtime), which then needs its own handling decision. The original crash is not fixed by this record: if the mapped branch is a genuine client defect it is fixed separately; if it is a provider or transport condition, its handling is decided separately. Remove or replace the rules once that decision is made. +- **Alternatives:** Reclassifying the truncation and generation-error branches as expected refusals or remote errors immediately was rejected because one uncoded event cannot show which branch fired, and changing reporting boundary exclusions requires an owner policy decision. Reporting raw messages, the server's own error text or parsed frame contents was rejected to preserve user privacy. Treating the single event as a defect fix candidate was rejected because no reproduction, endpoint or model is recorded. +- **Owner:** team. +- **Links:** [Sentry ATOMIC-CHAT-SERVER-1S](https://atomic-chat.sentry.io/issues/7848662602/), `src/terminal-service/client.ts`, `src/telemetry/native-diagnostics.ts`, `docs/decisions/2026-11-04-diagnose-chat-stream-failures.md`. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index c0feaa3..d8d6706 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -223,3 +223,4 @@ add a new one that says which record it supersedes. - [2026-11-07 — Reuse the API listener when connecting an agent](2026-11-07-reuse-api-for-connections.md) - [2026-11-07 — Package a runtime that does not inherit Windows sockets](2026-11-07-prevent-windows-socket-inheritance.md) +- **2026-11-15** — [Diagnose CLI chat failures with finite tags](2026-11-15-diagnose-cli-chat-failures.md) — name the terminal chat client's exact failure branches and approved transport causes; the original crash stays unfixed until an event names the branch. diff --git a/src/telemetry/sentry-agent-diagnostics.test.ts b/src/telemetry/sentry-agent-diagnostics.test.ts index f32d28c..7b8a60a 100644 --- a/src/telemetry/sentry-agent-diagnostics.test.ts +++ b/src/telemetry/sentry-agent-diagnostics.test.ts @@ -197,3 +197,68 @@ describe('bounded chat.stream diagnostic tags', () => { expect(nativeFailureTags(chain)).toEqual({}) }) }) + +// The `atc chat` command streams through src/terminal-service/client.ts, so these branches +// reach the same reporting boundary as chat.stream and stay unnamed without finite tags. +const cliChatContext = { component: 'cli', operation: 'chat' } + +describe('bounded CLI chat client diagnostic tags', () => { + it('names the CLI chat client branches the terminal chat command throws', () => { + expect( + nativeFailureTags(new Error('Use an HTTP endpoint without credentials, a query, or a fragment.')) + ).toEqual({ + diagnostic_code: 'CLI_CHAT_ENDPOINT_INVALID', + }) + expect( + nativeFailureTags(new Error('The server reported a generation error. Inspect the server log.')) + ).toEqual({ + diagnostic_code: 'CLI_CHAT_GENERATION_ERROR', + }) + expect(nativeFailureTags(new Error('The server returned an empty response.'))).toEqual({ + diagnostic_code: 'CLI_CHAT_EMPTY_RESPONSE', + }) + expect( + nativeFailureTags(new Error('The response ended before completion. The partial reply is kept.')) + ).toEqual({ + diagnostic_code: 'CLI_CHAT_STREAM_TRUNCATED', + }) + + // The report stays scrubbed while carrying the branch and its transport cause. + const transport = Object.assign(new Error('socket reset for private-fixture-endpoint'), { + code: 'UND_ERR_SOCKET', + }) + const report = failureReport( + new Error('The response ended before completion. The partial reply is kept.', { + cause: transport, + }), + cliChatContext + ) + expect(report).toMatchObject({ + source: 'event_listener', + level: 'error', + error: { name: 'Error', message: 'Unexpected failure in chat' }, + tags: { + component: 'cli', + operation: 'chat', + diagnostic_code: 'CLI_CHAT_STREAM_TRUNCATED', + diagnostic_cause_code: 'UND_ERR_SOCKET', + }, + }) + expect(JSON.stringify(report)).not.toContain('private-fixture') + + // Edited messages, unapproved codes and cyclic chains add no tag. + expect( + nativeFailureTags(new Error('The server returned an empty response. private-fixture-detail')) + ).toEqual({}) + const unapproved = Object.assign(new Error('private-fixture-detail'), { + code: 'CLI_CHAT_PRIVATE_CODE', + }) + expect(nativeFailureTags(new Error('wrapper', { cause: unapproved }))).toEqual({}) + const first = new Error('The server reported a generation error. Inspect the server log.') + const second = new Error('cycle', { cause: first }) + Object.defineProperty(first, 'cause', { value: second }) + expect(nativeFailureTags(first)).toEqual({ + diagnostic_code: 'CLI_CHAT_GENERATION_ERROR', + }) + }) +}) diff --git a/src/telemetry/sentry-agent-diagnostics.ts b/src/telemetry/sentry-agent-diagnostics.ts index 4412c53..36559f1 100644 --- a/src/telemetry/sentry-agent-diagnostics.ts +++ b/src/telemetry/sentry-agent-diagnostics.ts @@ -1,10 +1,14 @@ -// SENTRY_AGENT_DIAGNOSTIC_CONFIG {"rules":[{"source":"src/workspace-service/chat/chat-stream.ts","message":"The engine returned an empty response.","code":"CHAT_STREAM_EMPTY_RESPONSE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"An engine stream frame exceeded 8 MB.","code":"CHAT_STREAM_FRAME_TOO_LARGE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"The stream ended unexpectedly. The partial answer is saved.","code":"CHAT_STREAM_ENDED_UNEXPECTEDLY"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"Invalid tool-call index.","code":"CHAT_STREAM_INVALID_TOOL_CALL_INDEX"}],"include_cause_codes":true} +// SENTRY_AGENT_DIAGNOSTIC_CONFIG {"rules":[{"source":"src/workspace-service/chat/chat-stream.ts","message":"The engine returned an empty response.","code":"CHAT_STREAM_EMPTY_RESPONSE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"An engine stream frame exceeded 8 MB.","code":"CHAT_STREAM_FRAME_TOO_LARGE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"The stream ended unexpectedly. The partial answer is saved.","code":"CHAT_STREAM_ENDED_UNEXPECTEDLY"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"Invalid tool-call index.","code":"CHAT_STREAM_INVALID_TOOL_CALL_INDEX"},{"source":"src/terminal-service/client.ts","message":"Use an HTTP endpoint without credentials, a query, or a fragment.","code":"CLI_CHAT_ENDPOINT_INVALID"},{"source":"src/terminal-service/client.ts","message":"The server reported a generation error. Inspect the server log.","code":"CLI_CHAT_GENERATION_ERROR"},{"source":"src/terminal-service/client.ts","message":"The server returned an empty response.","code":"CLI_CHAT_EMPTY_RESPONSE"},{"source":"src/terminal-service/client.ts","message":"The response ended before completion. The partial reply is kept.","code":"CLI_CHAT_STREAM_TRUNCATED"}],"include_cause_codes":true} // This generated observer only enriches an existing error event. It never sends or logs. const SENTRY_AGENT_MESSAGES = new Map([ ['The engine returned an empty response.', 'CHAT_STREAM_EMPTY_RESPONSE'], ['An engine stream frame exceeded 8 MB.', 'CHAT_STREAM_FRAME_TOO_LARGE'], ['The stream ended unexpectedly. The partial answer is saved.', 'CHAT_STREAM_ENDED_UNEXPECTEDLY'], ['Invalid tool-call index.', 'CHAT_STREAM_INVALID_TOOL_CALL_INDEX'], + ['Use an HTTP endpoint without credentials, a query, or a fragment.', 'CLI_CHAT_ENDPOINT_INVALID'], + ['The server reported a generation error. Inspect the server log.', 'CLI_CHAT_GENERATION_ERROR'], + ['The server returned an empty response.', 'CLI_CHAT_EMPTY_RESPONSE'], + ['The response ended before completion. The partial reply is kept.', 'CLI_CHAT_STREAM_TRUNCATED'], ]) const SENTRY_AGENT_CAUSES = new Set([ 'ENOENT', From f6786aa8759a177c5656a12baff95bd31996557a Mon Sep 17 00:00:00 2001 From: Biogenic Ooze Date: Wed, 18 Nov 2026 14:32:52 +0300 Subject: [PATCH 2/2] fix(telemetry): tag chat failures detected by the terminal client --- .../2026-11-15-diagnose-cli-chat-failures.md | 31 +++++++-- docs/decisions/INDEX.md | 2 +- src/errors/index.ts | 1 + src/errors/terminal-chat.ts | 24 +++++++ src/telemetry/native-diagnostics.ts | 6 +- .../sentry-agent-diagnostics.test.ts | 65 ------------------- src/telemetry/sentry-agent-diagnostics.ts | 6 +- src/terminal-service/client.test.ts | 49 ++++++++++++++ src/terminal-service/client.ts | 10 +-- 9 files changed, 112 insertions(+), 82 deletions(-) create mode 100644 src/errors/terminal-chat.ts diff --git a/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md b/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md index 35e0be6..e2d568e 100644 --- a/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md +++ b/docs/decisions/2026-11-15-diagnose-cli-chat-failures.md @@ -5,9 +5,28 @@ title: "Diagnose CLI chat failures with finite tags" # 2026-11-15 — Diagnose CLI chat failures with finite tags -- **Context:** ATOMIC-CHAT-SERVER-1S (`7848662602`) reported `Error: cli chat: unknown` on `atc@0.2.18` (dist `b869424b124d`, the current base) with component `cli` and operation `chat`, one occurrence. The frames end at `src/terminal-service/client.ts:110` inside the SSE reading loop of `streamChat`, which the `atc chat` command reaches through `src/commands/access/terminal.ts:101`. `failureReport` scrubs the exception to `Unexpected failure in chat` and adds only `reportCodeOf(error)`, which is `undefined` for a plain `Error`, so the report names neither the branch nor the cause. `streamChat` throws four plain `Error`s (invalid endpoint, server-reported generation error, empty response body, truncated stream), and `JSON.parse` of a malformed frame throws a dynamic `SyntaxError` that no exact-message rule can name. -- **Decision:** Add four exact-message mappings from `src/terminal-service/client.ts` to the bounded diagnostic observer — `CLI_CHAT_ENDPOINT_INVALID`, `CLI_CHAT_GENERATION_ERROR`, `CLI_CHAT_EMPTY_RESPONSE`, `CLI_CHAT_STREAM_TRUNCATED` — and inspect allowlisted transport cause codes across up to five `Error` causes. Message scrubbing, filtering of expected failures, severity, consent and exit behaviour stay unchanged. -- **Consequences:** The next `cli chat` event identifies the failing client branch, or the transport cause when the stream read itself rejects. An event carrying neither tag comes from a dynamic-message branch (a `JSON.parse` `SyntaxError` or a `The server reported ...`/`Request returned HTTP ` message built at runtime), which then needs its own handling decision. The original crash is not fixed by this record: if the mapped branch is a genuine client defect it is fixed separately; if it is a provider or transport condition, its handling is decided separately. Remove or replace the rules once that decision is made. -- **Alternatives:** Reclassifying the truncation and generation-error branches as expected refusals or remote errors immediately was rejected because one uncoded event cannot show which branch fired, and changing reporting boundary exclusions requires an owner policy decision. Reporting raw messages, the server's own error text or parsed frame contents was rejected to preserve user privacy. Treating the single event as a defect fix candidate was rejected because no reproduction, endpoint or model is recorded. -- **Owner:** team. -- **Links:** [Sentry ATOMIC-CHAT-SERVER-1S](https://atomic-chat.sentry.io/issues/7848662602/), `src/terminal-service/client.ts`, `src/telemetry/native-diagnostics.ts`, `docs/decisions/2026-11-04-diagnose-chat-stream-failures.md`. +## Context + +ATOMIC-CHAT-SERVER-1S reported a generic CLI chat error in the SSE reader. The reporter +scrubs free-form exception text, so it could not distinguish a provider-reported generation +error from an incomplete stream. The client also preserves the message from a non-2xx HTTP +response for the caller. A message lookup could mistake that remote text for a local error. + +## Decision + +Have the terminal client attach a bounded diagnostic code when it rejects a parsed endpoint, +finds an absent response body, reads a generation error in SSE, or reaches the end of an +incomplete stream. The reporter reads that metadata from the error class. Existing allowlisted +transport codes still identify failures in the response reader, and the reporter still scrubs +remote HTTP text. + +## Consequences + +A tagged event identifies the client branch that produced it. Invalid URL syntax, malformed +SSE and arbitrary HTTP messages can still reach the reporter without a terminal chat code. +CLI output, exit status and the reporting rules use their existing behaviour. + +Owner: team + +References: [Sentry ATOMIC-CHAT-SERVER-1S](https://atomic-chat.sentry.io/issues/7848662602/), +`src/terminal-service/client.ts`, `src/telemetry/native-diagnostics.ts`. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index d090ffb..f359d2c 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -242,4 +242,4 @@ add a new one that says which record it supersedes. - [2026-11-07 — Reuse the API listener when connecting an agent](2026-11-07-reuse-api-for-connections.md) - [2026-11-07 — Package a runtime that does not inherit Windows sockets](2026-11-07-prevent-windows-socket-inheritance.md) -- **2026-11-15** — [Diagnose CLI chat failures with finite tags](2026-11-15-diagnose-cli-chat-failures.md) — name the terminal chat client's exact failure branches and approved transport causes; the original crash stays unfixed until an event names the branch. +- **2026-11-15** — [Diagnose CLI chat failures with finite tags](2026-11-15-diagnose-cli-chat-failures.md) — tag client-detected failures without interpreting remote HTTP text as a client diagnostic. diff --git a/src/errors/index.ts b/src/errors/index.ts index 693f5f2..516e72a 100644 --- a/src/errors/index.ts +++ b/src/errors/index.ts @@ -1,3 +1,4 @@ /** `AtcError`, its codes, exit codes and the one rendering of any failure. Depends on nothing. */ export * from './errors.js' export * from './ownership.js' +export { TerminalChatError } from './terminal-chat.js' diff --git a/src/errors/terminal-chat.ts b/src/errors/terminal-chat.ts new file mode 100644 index 0000000..e5cbece --- /dev/null +++ b/src/errors/terminal-chat.ts @@ -0,0 +1,24 @@ +const MESSAGES = { + CLI_CHAT_ENDPOINT_INVALID: 'Use an HTTP endpoint without credentials, a query, or a fragment.', + CLI_CHAT_GENERATION_ERROR: 'The server reported a generation error. Inspect the server log.', + CLI_CHAT_EMPTY_RESPONSE: 'The server returned an empty response.', + CLI_CHAT_STREAM_TRUNCATED: 'The response ended before completion. The partial reply is kept.', +} as const + +type TerminalChatCode = keyof typeof MESSAGES + +/** A failure detected by the terminal client itself. The code is reporting metadata. */ +export class TerminalChatError extends Error { + readonly #code: TerminalChatCode + + constructor(code: TerminalChatCode) { + super(MESSAGES[code]) + this.#code = code + } + + static diagnosticCode(error: unknown): TerminalChatCode | undefined { + if (!(error instanceof Error) || !(#code in error)) return undefined + const code = error.#code + return Object.hasOwn(MESSAGES, code) ? code : undefined + } +} diff --git a/src/telemetry/native-diagnostics.ts b/src/telemetry/native-diagnostics.ts index 0e298ca..2411cbf 100644 --- a/src/telemetry/native-diagnostics.ts +++ b/src/telemetry/native-diagnostics.ts @@ -1,3 +1,4 @@ +import { TerminalChatError } from '../errors/index.js' import { sentryAgentDiagnosticTags } from './sentry-agent-diagnostics.js' /** Fixed runtime messages become finite tags; arbitrary exception text stays private. */ const SEGMENTER_FAILURES = new Map([ @@ -15,5 +16,8 @@ function sentryBaseNativeFailureTags(error: unknown): Record { } export function nativeFailureTags(error: unknown): Record { - return { ...sentryBaseNativeFailureTags(error), ...sentryAgentDiagnosticTags(error) } + const tags = { ...sentryBaseNativeFailureTags(error), ...sentryAgentDiagnosticTags(error) } + const chatCode = TerminalChatError.diagnosticCode(error) + if (chatCode) tags['diagnostic_code'] = chatCode + return tags } diff --git a/src/telemetry/sentry-agent-diagnostics.test.ts b/src/telemetry/sentry-agent-diagnostics.test.ts index 7b8a60a..f32d28c 100644 --- a/src/telemetry/sentry-agent-diagnostics.test.ts +++ b/src/telemetry/sentry-agent-diagnostics.test.ts @@ -197,68 +197,3 @@ describe('bounded chat.stream diagnostic tags', () => { expect(nativeFailureTags(chain)).toEqual({}) }) }) - -// The `atc chat` command streams through src/terminal-service/client.ts, so these branches -// reach the same reporting boundary as chat.stream and stay unnamed without finite tags. -const cliChatContext = { component: 'cli', operation: 'chat' } - -describe('bounded CLI chat client diagnostic tags', () => { - it('names the CLI chat client branches the terminal chat command throws', () => { - expect( - nativeFailureTags(new Error('Use an HTTP endpoint without credentials, a query, or a fragment.')) - ).toEqual({ - diagnostic_code: 'CLI_CHAT_ENDPOINT_INVALID', - }) - expect( - nativeFailureTags(new Error('The server reported a generation error. Inspect the server log.')) - ).toEqual({ - diagnostic_code: 'CLI_CHAT_GENERATION_ERROR', - }) - expect(nativeFailureTags(new Error('The server returned an empty response.'))).toEqual({ - diagnostic_code: 'CLI_CHAT_EMPTY_RESPONSE', - }) - expect( - nativeFailureTags(new Error('The response ended before completion. The partial reply is kept.')) - ).toEqual({ - diagnostic_code: 'CLI_CHAT_STREAM_TRUNCATED', - }) - - // The report stays scrubbed while carrying the branch and its transport cause. - const transport = Object.assign(new Error('socket reset for private-fixture-endpoint'), { - code: 'UND_ERR_SOCKET', - }) - const report = failureReport( - new Error('The response ended before completion. The partial reply is kept.', { - cause: transport, - }), - cliChatContext - ) - expect(report).toMatchObject({ - source: 'event_listener', - level: 'error', - error: { name: 'Error', message: 'Unexpected failure in chat' }, - tags: { - component: 'cli', - operation: 'chat', - diagnostic_code: 'CLI_CHAT_STREAM_TRUNCATED', - diagnostic_cause_code: 'UND_ERR_SOCKET', - }, - }) - expect(JSON.stringify(report)).not.toContain('private-fixture') - - // Edited messages, unapproved codes and cyclic chains add no tag. - expect( - nativeFailureTags(new Error('The server returned an empty response. private-fixture-detail')) - ).toEqual({}) - const unapproved = Object.assign(new Error('private-fixture-detail'), { - code: 'CLI_CHAT_PRIVATE_CODE', - }) - expect(nativeFailureTags(new Error('wrapper', { cause: unapproved }))).toEqual({}) - const first = new Error('The server reported a generation error. Inspect the server log.') - const second = new Error('cycle', { cause: first }) - Object.defineProperty(first, 'cause', { value: second }) - expect(nativeFailureTags(first)).toEqual({ - diagnostic_code: 'CLI_CHAT_GENERATION_ERROR', - }) - }) -}) diff --git a/src/telemetry/sentry-agent-diagnostics.ts b/src/telemetry/sentry-agent-diagnostics.ts index 36559f1..4412c53 100644 --- a/src/telemetry/sentry-agent-diagnostics.ts +++ b/src/telemetry/sentry-agent-diagnostics.ts @@ -1,14 +1,10 @@ -// SENTRY_AGENT_DIAGNOSTIC_CONFIG {"rules":[{"source":"src/workspace-service/chat/chat-stream.ts","message":"The engine returned an empty response.","code":"CHAT_STREAM_EMPTY_RESPONSE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"An engine stream frame exceeded 8 MB.","code":"CHAT_STREAM_FRAME_TOO_LARGE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"The stream ended unexpectedly. The partial answer is saved.","code":"CHAT_STREAM_ENDED_UNEXPECTEDLY"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"Invalid tool-call index.","code":"CHAT_STREAM_INVALID_TOOL_CALL_INDEX"},{"source":"src/terminal-service/client.ts","message":"Use an HTTP endpoint without credentials, a query, or a fragment.","code":"CLI_CHAT_ENDPOINT_INVALID"},{"source":"src/terminal-service/client.ts","message":"The server reported a generation error. Inspect the server log.","code":"CLI_CHAT_GENERATION_ERROR"},{"source":"src/terminal-service/client.ts","message":"The server returned an empty response.","code":"CLI_CHAT_EMPTY_RESPONSE"},{"source":"src/terminal-service/client.ts","message":"The response ended before completion. The partial reply is kept.","code":"CLI_CHAT_STREAM_TRUNCATED"}],"include_cause_codes":true} +// SENTRY_AGENT_DIAGNOSTIC_CONFIG {"rules":[{"source":"src/workspace-service/chat/chat-stream.ts","message":"The engine returned an empty response.","code":"CHAT_STREAM_EMPTY_RESPONSE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"An engine stream frame exceeded 8 MB.","code":"CHAT_STREAM_FRAME_TOO_LARGE"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"The stream ended unexpectedly. The partial answer is saved.","code":"CHAT_STREAM_ENDED_UNEXPECTEDLY"},{"source":"src/workspace-service/chat/chat-stream.ts","message":"Invalid tool-call index.","code":"CHAT_STREAM_INVALID_TOOL_CALL_INDEX"}],"include_cause_codes":true} // This generated observer only enriches an existing error event. It never sends or logs. const SENTRY_AGENT_MESSAGES = new Map([ ['The engine returned an empty response.', 'CHAT_STREAM_EMPTY_RESPONSE'], ['An engine stream frame exceeded 8 MB.', 'CHAT_STREAM_FRAME_TOO_LARGE'], ['The stream ended unexpectedly. The partial answer is saved.', 'CHAT_STREAM_ENDED_UNEXPECTEDLY'], ['Invalid tool-call index.', 'CHAT_STREAM_INVALID_TOOL_CALL_INDEX'], - ['Use an HTTP endpoint without credentials, a query, or a fragment.', 'CLI_CHAT_ENDPOINT_INVALID'], - ['The server reported a generation error. Inspect the server log.', 'CLI_CHAT_GENERATION_ERROR'], - ['The server returned an empty response.', 'CLI_CHAT_EMPTY_RESPONSE'], - ['The response ended before completion. The partial reply is kept.', 'CLI_CHAT_STREAM_TRUNCATED'], ]) const SENTRY_AGENT_CAUSES = new Set([ 'ENOENT', diff --git a/src/terminal-service/client.test.ts b/src/terminal-service/client.test.ts index 960e2ec..43c0fb7 100644 --- a/src/terminal-service/client.test.ts +++ b/src/terminal-service/client.test.ts @@ -1,4 +1,5 @@ import { describe, expect, it, vi } from 'vitest' +import { failureReport } from '../telemetry/index.js' import { endpointUrl, sameEndpoint, listChatModels, streamChat } from './client.js' function response(chunks: string[]) { @@ -129,6 +130,54 @@ describe('a refused chat request', () => { }) }) +describe('CLI chat failure reports', () => { + const context = { component: 'cli', operation: 'chat' } + + async function chatFailure(reply: () => Response, endpoint = 'http://host/v1'): Promise { + return streamChat({ + endpoint, + model: 'm', + messages: [], + request: vi.fn(async () => reply()), + signal: new AbortController().signal, + onText: () => {}, + }).catch((cause: unknown) => cause) + } + + it.each([ + { + code: 'CLI_CHAT_ENDPOINT_INVALID', + endpoint: 'file:///private-fixture', + reply: () => new Response(null), + }, + { code: 'CLI_CHAT_EMPTY_RESPONSE', reply: () => new Response(null) }, + { + code: 'CLI_CHAT_GENERATION_ERROR', + reply: () => new Response('data: {"error":{"message":"private-fixture"}}\n\n'), + }, + { code: 'CLI_CHAT_STREAM_TRUNCATED', reply: () => new Response(delta('partial reply')) }, + ])('reports $code only from the local client branch', async ({ code, endpoint, reply }) => { + const error = await chatFailure(reply, endpoint) + const report = failureReport(error, context) + expect(report).toMatchObject({ + level: 'error', + error: { name: 'Error', message: 'Unexpected failure in chat' }, + tags: { ...context, diagnostic_code: code }, + }) + expect(JSON.stringify(report)).not.toContain('private-fixture') + }) + + it('keeps a matching message from a remote HTTP error out of the local diagnostic tags', async () => { + const message = 'The response ended before completion. The partial reply is kept.' + const error = await chatFailure(() => Response.json({ error: { message } }, { status: 502 })) + + expect(error).toMatchObject({ message }) + const report = failureReport(error, context) + expect(report).toMatchObject({ error: { message: 'Unexpected failure in chat' }, tags: context }) + expect(report?.tags).not.toHaveProperty('diagnostic_code') + }) +}) + it('matches loopback aliases without treating a different listener or API path as local', () => { const local = 'http://127.0.0.1:63163/v1' expect(sameEndpoint('http://localhost:63163/v1/', local)).toBe(true) diff --git a/src/terminal-service/client.ts b/src/terminal-service/client.ts index 9bb0a09..0ca30d4 100644 --- a/src/terminal-service/client.ts +++ b/src/terminal-service/client.ts @@ -1,4 +1,6 @@ /** Public OpenAI-compatible calls shared by the terminal and plain chat command. */ +import { TerminalChatError } from '../errors/index.js' + export type ChatContentPart = | { type: 'text'; text: string } | { type: 'image_url'; image_url: { url: string; detail?: 'auto' | 'low' | 'high' } } @@ -17,7 +19,7 @@ export interface ChatMessage { export function endpointUrl(value: string): string { const url = new URL(value) if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) - throw new Error('Use an HTTP endpoint without credentials, a query, or a fragment.') + throw new TerminalChatError('CLI_CHAT_ENDPOINT_INVALID') return url.toString().replace(/\/$/, '') } /** Loopback aliases share a listener, but a different port or API path is a different server. */ @@ -80,7 +82,7 @@ export async function streamChat(options: { : `Request returned HTTP ${response.status}. Check the model, endpoint, and access settings.` ) } - if (!response.body) throw new Error('The server returned an empty response.') + if (!response.body) throw new TerminalChatError('CLI_CHAT_EMPTY_RESPONSE') const reader = response.body.getReader(), decoder = new TextDecoder() let buffer = '', @@ -107,13 +109,13 @@ export async function streamChat(options: { error?: { message?: string } choices?: { delta?: { content?: string }; finish_reason?: string | null }[] } - if (chunk.error) throw new Error('The server reported a generation error. Inspect the server log.') + if (chunk.error) throw new TerminalChatError('CLI_CHAT_GENERATION_ERROR') const text = chunk.choices?.[0]?.delta?.content if (text) options.onText(text) if (chunk.choices?.[0]?.finish_reason) done = true } if (next.done) { - if (!done) throw new Error('The response ended before completion. The partial reply is kept.') + if (!done) throw new TerminalChatError('CLI_CHAT_STREAM_TRUNCATED') break } }