fix(cli): name a non-JSON error page by its title, not its whole body (#2092)

* fix(cli): name a non-JSON error page by its title, not its whole body

A non-JSON error response put its entire body into err.message. When the
Cloudflare tunnel could not reach the origin, every failed poll wrote a
~120-line HTML page into the agent log (10 pages in c4-smoke.log,
2026-09-22 to 09-29). An HTML body now becomes "HTTP <status>: <title>".
Other plain text collapses to one line, capped at 300 characters. JSON
error bodies are unchanged, and err.body keeps the full text for
callers that classify it, so spawn-retry still sees every word.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013geJsV4RJMujdvpf3JV2Cv

* test(cli): witness classification from the discarded page body

Vera's #2092 probe: a 502 page whose only classifiable words sit deep in
the body. The message drops them; err.body.message keeps them, and
classifySpawnFailure must still read rate_limit. Removing body.message
from spawn-retry's errorText fails this test and no other.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013geJsV4RJMujdvpf3JV2Cv

* chore(cli): 0.1.85 for the error-message change

cli/src changed, so the published version must rise ("Source changed ⇒
version bumped").

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013geJsV4RJMujdvpf3JV2Cv

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: lilyshen0722

cli/__tests__/api-error-text.test.mjs

@@ -0,0 +1,110 @@
+import { jest } from '@jest/globals';
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+
+const configTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-api-error-text-'));
+await jest.unstable_mockModule('os', () => ({
+  ...os,
+  default: { ...os, homedir: () => configTmpDir },
+  homedir: () => configTmpDir,
+}));
+
+const { saveInstance } = await import('../src/lib/config.js');
+const { createClient } = await import('../src/lib/api.js');
+const { classifySpawnFailure, SPAWN_FAILURE_CLASS } = await import('../src/lib/spawn-retry.js');
+
+afterAll(() => fs.rmSync(path.join(configTmpDir, '.commonly'), { recursive: true, force: true }));
+
+beforeEach(() => {
+  saveInstance({
+    key: 'dev', url: 'https://api.commonly.me', token: 't', userId: 'u1', username: 'lily',
+  });
+});
+
+const respond = (status, text) => {
+  global.fetch = jest.fn().mockResolvedValue({ ok: false, status, text: async () => text });
+};
+
+const failure = async () => {
+  try {
+    await createClient({ instance: 'dev' }).get('/api/agents/runtime/events');
+  } catch (err) {
+    return err;
+  }
+  throw new Error('expected the request to reject');
+};
+
+// The shape of the page Cloudflare serves when the tunnel cannot reach the origin.
+const tunnelPage = [
+  '<!DOCTYPE html>',
+  '<!--[if lt IE 7]> <html class="no-js ie6 oldie" lang="en-US"> <![endif]-->',
+  '<html class="no-js" lang="en-US">',
+  '    <head>',
+  '        <title>Cloudflare Tunnel error | api.commonly.me | Cloudflare</title>',
+  '    </head>',
+  '    <body>',
+  ...Array.from({ length: 100 }, (_, i) => `        <div class="row-${i}">Cloudflare Tunnel error</div>`),
+  '    </body>',
+  '</html>',
+].join('\n');
+
+test('an HTML error page becomes one line named by its <title>', async () => {
+  respond(502, tunnelPage);
+  const err = await failure();
+  expect(err.message).toBe('HTTP 502: Cloudflare Tunnel error | api.commonly.me | Cloudflare');
+  expect(err.message).not.toContain('\n');
+  expect(err.status).toBe(502);
+  // Callers that classify the failure still see the whole page.
+  expect(err.body.message).toBe(tunnelPage);
+});
+
+test('a classifiable word only in the discarded page body still classifies', async () => {
+  // 502, so the status === 429 shortcut cannot fire: the words exist only in
+  // err.body.message, which the one-line message drops (Vera, #2092 review).
+  const page = [
+    '<!DOCTYPE html><html><head><title>Bad gateway</title></head><body>',
+    ...Array.from({ length: 80 }, (_, i) => `<div class="row-${i}">upstream</div>`),
+    '<p>rate limit exceeded</p>',
+    '</body></html>',
+  ].join('\n');
+  respond(502, page);
+  const err = await failure();
+  expect(err.message).toBe('HTTP 502: Bad gateway');
+  expect(err.message).not.toMatch(/rate limit/);
+  expect(classifySpawnFailure(err)).toBe(SPAWN_FAILURE_CLASS.RATE_LIMIT);
+});
+
+test('an HTML page with no <title> is named by its status', async () => {
+  respond(503, '<html><body><h1>Service Unavailable</h1></body></html>');
+  expect((await failure()).message).toBe('HTTP 503 (HTML error page)');
+});
+
+test('a short plain-text error is kept verbatim', async () => {
+  respond(429, 'Too many requests, please try again later.');
+  const err = await failure();
+  expect(err.message).toBe('Too many requests, please try again later.');
+  expect(classifySpawnFailure(err)).toBe(SPAWN_FAILURE_CLASS.RATE_LIMIT);
+});
+
+test('a long plain-text error is collapsed to one line and capped', async () => {
+  const text = `upstream failed\n${'x'.repeat(1000)}`;
+  respond(500, text);
+  const err = await failure();
+  expect(err.message).not.toContain('\n');
+  expect(err.message).toHaveLength(301);
+  expect(err.message.endsWith('…')).toBe(true);
+  expect(err.body.message).toBe(text);
+});
+
+test('an empty body falls back to the status', async () => {
+  respond(500, '');
+  expect((await failure()).message).toBe('HTTP 500');
+});
+
+test('a JSON error body is unchanged', async () => {
+  respond(403, JSON.stringify({ error: 'grant_not_found', code: 'grant_not_found' }));
+  const err = await failure();
+  expect(err.message).toBe('grant_not_found');
+  expect(err.body.code).toBe('grant_not_found');
+});

cli/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

cli/package.json

@@ -20,14 +20,34 @@ export const sessionExpiredMessage = ({ instanceKey, baseUrl }) => (
   `Session for ${instanceKey} (${baseUrl}) has expired.\nRun: commonly login --instance ${instanceKey}`
 );
 
+// A non-JSON error body is usually an edge proxy's HTML page; a Cloudflare
+// tunnel error is ~120 lines, and the message used to be all of them, so every
+// failed poll dumped a whole page into the agent log. The message names the
+// page by its <title>; err.body keeps the full text for callers that classify it.
+const MAX_TEXT_ERROR = 300;
+const summarizeTextError = (text, status) => {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return null;
+  if (/^<(?:!doctype|html)/i.test(trimmed) || /<html[\s>]/i.test(trimmed)) {
+    const title = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, ' ').trim();
+    return title ? `HTTP ${status}: ${title}` : `HTTP ${status} (HTML error page)`;
+  }
+  const line = trimmed.replace(/\s+/g, ' ');
+  return line.length > MAX_TEXT_ERROR ? `${line.slice(0, MAX_TEXT_ERROR)}…` : line;
+};
+
 const handleResponse = async (res, session = null) => {
   const text = await res.text();
   let body;
-  try { body = JSON.parse(text); } catch { body = { message: text }; }
+  let isJson = true;
+  try { body = JSON.parse(text); } catch { body = { message: text }; isJson = false; }
   if (!res.ok) {
+    const serverMessage = isJson
+      ? body?.error || body?.message || body?.msg
+      : summarizeTextError(text, res.status);
     const msg = res.status === 401 && session && knownSessionFailure(body)
       ? sessionExpiredMessage(session)
-      : body?.error || body?.message || body?.msg || `HTTP ${res.status}`;
+      : serverMessage || `HTTP ${res.status}`;
     const err = new Error(msg);
     err.status = res.status;
     err.body = body;