@anyslate/cli 0.1.0 → 0.3.0

package/src/mcp-client.mjs

@@ -1,7 +1,7 @@
 // Minimal JSON-RPC client for the AnySlate MCP service.
 //
 // The MCP service speaks the standard MCP JSON-RPC protocol. We only need
-// `tools/call` from the CLI — that one method covers `activity_submit`,
+// `tools/call` from the CLI - that one method covers `activity_submit`,
 // `checkpoint_session`, and `upload_artifact`.
 //
 // The server replies with `{ jsonrpc: '2.0', id, result | error }`. When the
@@ -9,12 +9,34 @@
 // JSON-parse it (the AnySlate dispatcher always returns JSON-encoded text).
 //
 // Streamable HTTP transport requires every non-initialize request to carry
-// an `Mcp-Session-Id` header (mcp-protocol.ts:2566). The CLI is one-shot per
+// an `Mcp-Session-Id` header (mcp-protocol.ts:5825). The CLI is one-shot per
 // invocation, so we run `initialize` first, capture the server-issued
 // session id from the response header, and reuse it for the `tools/call`.
+//
+// IMPORTANT (W2): the MCP wire protocol returns **HTTP 200 with
+// `result.isError === true`** for tool-level rejections — 403 handle denial,
+// 400 unsupported kind, 500 insert failure, tool-level 429. Trusting
+// `res.ok` alone reports every one of those as success. `callTool` therefore
+// inspects `result.isError` and maps it to `ok: false` with the embedded
+// status, which is what makes `--strict` and the checkpoint/upload-artifact
+// fail-closed contract actually mean anything.
+
+import { USER_AGENT } from './version.mjs';
 
 let nextRequestId = 1;
 
+const MCP_HEADERS = (token, sessionId) => {
+  const h = {
+    'content-type': 'application/json',
+    authorization: `Bearer ${token}`,
+    accept: 'application/json, text/event-stream',
+    'mcp-protocol-version': '2025-06-18',
+    'user-agent': USER_AGENT,
+  };
+  if (sessionId) h['mcp-session-id'] = sessionId;
+  return h;
+};
+
 async function readBody(res) {
   const ctype = res.headers.get('content-type') || '';
   // The MCP service may stream JSON-RPC results as text/event-stream
@@ -42,16 +64,153 @@ async function readBody(res) {
   }
 }
 
+/**
+ * Render a server error body as a human string, preserving `error_description`.
+ *
+ * Dropping `error_description` makes *revoked* and *mistyped* indistinguishable
+ * (defect #15) — the single most common real-world 401.
+ *
+ * @param {unknown} raw
+ * @returns {string|object|null}
+ */
+export function formatErrorPayload(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'string') return raw;
+  if (typeof raw !== 'object') return String(raw);
+
+  const desc =
+    typeof raw.error_description === 'string'
+      ? raw.error_description
+      : typeof raw.errorDescription === 'string'
+        ? raw.errorDescription
+        : null;
+  const err = raw.error;
+
+  if (typeof err === 'string' && err) {
+    return desc ? `${err}: ${desc}` : err;
+  }
+  if (err && typeof err === 'object') {
+    // JSON-RPC error object — keep the object so callers can read `.message`.
+    return err;
+  }
+  if (desc) return desc;
+  if (typeof raw.message === 'string') return raw.message;
+  return null;
+}
+
+/**
+ * Extract 429 metadata. `Retry-After` was never read and
+ * `retry_after_seconds`/`reset_at`/`reason` survived only in `raw`
+ * (defect #31). Surfacing only — no retry/backoff logic.
+ *
+ * @param {Response} res
+ * @param {unknown} raw
+ */
+export function extractRateLimit(res, raw) {
+  const header = res?.headers?.get ? res.headers.get('retry-after') : null;
+  const body = raw && typeof raw === 'object' ? raw : {};
+  const fromBody = body.retry_after_seconds ?? body.retryAfterSeconds;
+  const parsedHeader = header != null && header !== '' ? Number(header) : NaN;
+  const retryAfterSeconds = Number.isFinite(fromBody)
+    ? Number(fromBody)
+    : Number.isFinite(parsedHeader)
+      ? parsedHeader
+      : null;
+  return {
+    retry_after_seconds: retryAfterSeconds,
+    retry_after_header: header ?? null,
+    reset_at: body.reset_at ?? body.resetAt ?? null,
+    reason: body.reason ?? null,
+  };
+}
+
+/**
+ * Turn a thrown fetch error into something that names the host and the cause.
+ * Previously DNS failure, connection refused and timeout were all
+ * `request failed (fetch failed)` (defect #30).
+ *
+ * @param {unknown} err
+ * @param {string} host
+ * @param {number} timeoutMs
+ * @returns {string}
+ */
+/**
+ * Undici wraps the real cause: `fetch failed` carries `cause`, which for a
+ * refused/multi-address connect is an AggregateError whose `.errors[]` hold
+ * the codes. Walk the whole chain, or every connection error looks identical.
+ *
+ * @param {unknown} err
+ * @param {number} [depth]
+ * @returns {string|null}
+ */
+export function findErrorCode(err, depth = 0) {
+  if (!err || depth > 5) return null;
+  if (typeof err.code === 'string' && err.code) return err.code;
+  if (Array.isArray(err.errors)) {
+    for (const inner of err.errors) {
+      const code = findErrorCode(inner, depth + 1);
+      if (code) return code;
+    }
+  }
+  return findErrorCode(err.cause, depth + 1);
+}
+
+export function classifyNetworkError(err, host, timeoutMs) {
+  const message = String(err?.message ?? err ?? '');
+  const code = findErrorCode(err);
+  const seconds = Math.round((timeoutMs ?? 0) / 1000);
+
+  if (err?.name === 'AbortError' || /aborted/i.test(message)) {
+    return `timed out after ${seconds}s contacting ${host}`;
+  }
+  switch (code) {
+    case 'ENOTFOUND':
+      return `ENOTFOUND ${host} (DNS)`;
+    case 'EAI_AGAIN':
+      return `EAI_AGAIN ${host} (DNS)`;
+    case 'ECONNREFUSED':
+      return `ECONNREFUSED ${host}`;
+    case 'ECONNRESET':
+      return `ECONNRESET ${host}`;
+    case 'ETIMEDOUT':
+    case 'UND_ERR_CONNECT_TIMEOUT':
+    case 'UND_ERR_HEADERS_TIMEOUT':
+      return `timed out contacting ${host} (${code})`;
+    default:
+      break;
+  }
+  if (code && /CERT|SSL|TLS/i.test(code)) return `TLS error contacting ${host} (${code})`;
+  if (/certificate|self[- ]signed|SSL/i.test(message)) return `TLS error contacting ${host}`;
+  if (code) return `${code} ${host}`;
+  return `${message || 'request failed'} (${host})`;
+}
+
+/**
+ * Uniform failure line for every command. Network failures are not "server
+ * <status>" failures — printing `server 0` would be a lie.
+ *
+ * @param {string} prefix  e.g. `anyslate hook stop`
+ * @param {{status: number, data: unknown, networkError?: boolean}} res
+ * @returns {string}
+ */
+export function formatCallFailure(prefix, res) {
+  const msg = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
+  if (res.networkError) return `${prefix}: request failed: ${msg}\n`;
+  return `${prefix}: server ${res.status} — ${msg}\n`;
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
 async function initializeSession({ url, token, fetchImpl, ac }) {
   const res = await fetchImpl(url, {
     method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      authorization: `Bearer ${token}`,
-      accept: 'application/json, text/event-stream',
-      'mcp-protocol-version': '2025-06-18',
-      'user-agent': 'anyslate-cli/0.1.0',
-    },
+    headers: MCP_HEADERS(token),
     body: JSON.stringify({
       jsonrpc: '2.0',
       id: nextRequestId++,
@@ -59,7 +218,7 @@ async function initializeSession({ url, token, fetchImpl, ac }) {
       params: {
         protocolVersion: '2025-06-18',
         capabilities: {},
-        clientInfo: { name: 'anyslate-cli', version: '0.1.0' },
+        clientInfo: { name: 'anyslate-cli', version: USER_AGENT.split('/')[1] },
       },
     }),
     signal: ac.signal,
@@ -67,45 +226,61 @@ async function initializeSession({ url, token, fetchImpl, ac }) {
   const sid = res.headers.get('mcp-session-id');
   if (!res.ok) {
     const raw = await readBody(res);
-    return { ok: false, status: res.status, sessionId: null, raw };
+    return { ok: false, status: res.status, sessionId: null, raw, res };
   }
   if (!sid) {
-    return { ok: false, status: res.status, sessionId: null, raw: { error: 'server omitted Mcp-Session-Id header on initialize' } };
+    return {
+      ok: false,
+      status: res.status,
+      sessionId: null,
+      raw: { error: 'server omitted Mcp-Session-Id header on initialize' },
+      res,
+    };
   }
-  // Best-effort `notifications/initialized` — server returns 202 and we
+  // Best-effort `notifications/initialized` - server returns 202 and we
   // proceed regardless. Required by spec; harmless if dropped on the floor.
   try {
     await fetchImpl(url, {
       method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${token}`,
-        accept: 'application/json, text/event-stream',
-        'mcp-protocol-version': '2025-06-18',
-        'mcp-session-id': sid,
-        'user-agent': 'anyslate-cli/0.1.0',
-      },
+      headers: MCP_HEADERS(token, sid),
       body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }),
       signal: ac.signal,
     });
   } catch {
-    // Swallow — we have the session id; the notification is advisory.
+    // Swallow - we have the session id; the notification is advisory.
   }
   return { ok: true, status: res.status, sessionId: sid, raw: null };
 }
 
 /**
  * @param {object} opts
- * @param {string} opts.apiUrl
+ * @param {string} opts.apiUrl  service ROOT (the client appends `/mcp`)
  * @param {string} opts.token  Bearer token (MCP token).
  * @param {string} opts.toolName
  * @param {Record<string, unknown>} opts.args
  * @param {typeof fetch} [opts.fetchImpl]  override for tests
  * @param {number} [opts.timeoutMs]
- * @returns {Promise<{ ok: boolean, status: number, data: unknown, raw: unknown }>}
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown, raw: unknown,
+ *   isError?: boolean, networkError?: boolean, retryAfterSeconds?: number|null,
+ *   rateLimit?: object }>}
  */
-export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetch, timeoutMs = 15000, sessionId: presetSessionId }) {
-  const url = `${apiUrl.replace(/\/+$/, '')}/mcp`;
+export async function callTool({
+  apiUrl,
+  token,
+  toolName,
+  args,
+  fetchImpl = fetch,
+  timeoutMs = 15000,
+  sessionId: presetSessionId,
+}) {
+  // `apiUrl` is already normalized by loadConfig; strip again defensively so a
+  // direct caller cannot reintroduce `/mcp/mcp`.
+  const root = String(apiUrl ?? '')
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/(\/mcp)+$/i, '');
+  const url = `${root}/mcp`;
+  const host = hostOf(url);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);
 
@@ -116,12 +291,16 @@ export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetc
       if (!init.ok) {
         // Surface the auth/init failure exactly as if the tool call itself failed,
         // so the CLI's existing error handling (server 401 etc.) keeps working.
-        const errLike = init.raw && typeof init.raw === 'object' && 'error' in init.raw
-          ? init.raw.error
-          : init.raw && typeof init.raw === 'object' && 'message' in init.raw
-            ? init.raw
-            : { message: `initialize failed (HTTP ${init.status})` };
-        return { ok: false, status: init.status, data: errLike, raw: init.raw };
+        const formatted = formatErrorPayload(init.raw);
+        const errLike = formatted ?? { message: `initialize failed (HTTP ${init.status})` };
+        const out = { ok: false, status: init.status, data: errLike, raw: init.raw };
+        if (init.status === 429) {
+          const rl = extractRateLimit(init.res, init.raw);
+          out.rateLimit = rl;
+          out.retryAfterSeconds = rl.retry_after_seconds;
+          out.data = withRetryHint(errLike, rl);
+        }
+        return out;
       }
       sessionId = init.sessionId;
     }
@@ -136,39 +315,106 @@ export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetc
 
     const res = await fetchImpl(url, {
       method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${token}`,
-        accept: 'application/json, text/event-stream',
-        'mcp-protocol-version': '2025-06-18',
-        'mcp-session-id': sessionId,
-        'user-agent': 'anyslate-cli/0.1.0',
-      },
+      headers: MCP_HEADERS(token, sessionId),
       body: JSON.stringify(body),
       signal: ac.signal,
     });
 
     const status = res.status;
     const raw = await readBody(res);
+    const rateLimit = status === 429 ? extractRateLimit(res, raw) : null;
 
+    const finish = (out) => {
+      if (rateLimit) {
+        out.rateLimit = rateLimit;
+        out.retryAfterSeconds = rateLimit.retry_after_seconds;
+        out.data = withRetryHint(out.data, rateLimit);
+      }
+      return out;
+    };
+
+    // JSON-RPC transport-level error.
     if (raw && typeof raw === 'object' && 'error' in raw && raw.error) {
-      return { ok: false, status, data: raw.error, raw };
+      return finish({ ok: false, status, data: formatErrorPayload(raw) ?? raw.error, raw });
     }
 
-    // `result.content[0].text` is the AnySlate dispatcher's JSON envelope.
     const result = raw && typeof raw === 'object' ? raw.result : null;
+
+    // ---- Tool-level error: HTTP 200 + result.isError === true (W2). ----
+    if (result && typeof result === 'object' && result.isError === true) {
+      const content = Array.isArray(result.content) ? result.content[0] : null;
+      const text = content && typeof content.text === 'string' ? content.text : null;
+      let parsed = null;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = null;
+        }
+      }
+      if (parsed && typeof parsed === 'object') {
+        const embeddedStatus = Number.isFinite(parsed.status) ? Number(parsed.status) : status;
+        const data = formatErrorPayload(parsed) ?? parsed.error ?? text ?? 'tool returned isError';
+        const out = { ok: false, status: embeddedStatus, data, raw, isError: true };
+        if (embeddedStatus === 429) {
+          const rl = extractRateLimit(res, parsed);
+          out.rateLimit = rl;
+          out.retryAfterSeconds = rl.retry_after_seconds;
+          out.data = withRetryHint(data, rl);
+        }
+        return out;
+      }
+      return finish({
+        ok: false,
+        status,
+        data: text ?? 'tool returned isError with no content',
+        raw,
+        isError: true,
+      });
+    }
+
+    // `result.content[0].text` is the AnySlate dispatcher's JSON envelope.
     const content = result && Array.isArray(result.content) ? result.content[0] : null;
     if (content && content.type === 'text' && typeof content.text === 'string') {
       try {
         const parsed = JSON.parse(content.text);
-        return { ok: res.ok, status, data: parsed, raw };
+        return finish({ ok: res.ok, status, data: parsed, raw });
       } catch {
-        return { ok: res.ok, status, data: content.text, raw };
+        return finish({ ok: res.ok, status, data: content.text, raw });
       }
     }
 
-    return { ok: res.ok, status, data: result, raw };
+    // Non-2xx with no parseable JSON-RPC body: never print the literal `null`.
+    if (!res.ok) {
+      return finish({
+        ok: false,
+        status,
+        data: formatErrorPayload(raw) ?? `server returned HTTP ${status} with no JSON-RPC body`,
+        raw,
+      });
+    }
+
+    return finish({ ok: res.ok, status, data: result, raw });
+  } catch (e) {
+    return {
+      ok: false,
+      status: 0,
+      data: classifyNetworkError(e, host, timeoutMs),
+      raw: null,
+      networkError: true,
+    };
   } finally {
     clearTimeout(timer);
   }
 }
+
+function withRetryHint(data, rl) {
+  if (!rl) return data;
+  const bits = [];
+  if (rl.retry_after_seconds != null) bits.push(`retry after ${rl.retry_after_seconds}s`);
+  if (rl.reset_at) bits.push(`resets at ${rl.reset_at}`);
+  if (rl.reason) bits.push(String(rl.reason));
+  if (!bits.length) return data;
+  const base = typeof data === 'string' ? data : data == null ? 'rate limited' : JSON.stringify(data);
+  return `${base} — ${bits.join(', ')}`;
+}