@hone-ai/cli 1.38.1 → 1.40.0

package/lib/anthropic-response.js

@@ -0,0 +1,58 @@
+'use strict';
+/**
+ * HC-GF-337f — read an Anthropic Messages response without losing half of it.
+ *
+ * Every CLI path used to take `data.content[0].text`. Once a model can emit a thinking block
+ * FIRST, block 0 is `{type: 'thinking'}` and that expression is `undefined`: an empty review or
+ * verdict reported as a content filter or a quota trip. The HC-GF-085 defect, on the CLI side.
+ *
+ * Returns a discriminated result; the caller owns its own exit semantics (skill-eval throws inside
+ * callLLM, release-review emits a status envelope, the judge throws so the scenario is an error and
+ * not a failed criterion). Nothing here throws, so the outcomes can be asserted in one table.
+ *
+ *   { ok: true,  text, stopReason }
+ *   { ok: false, kind: 'refusal',   category, stopReason, message }   // HTTP 200, stop_reason "refusal"
+ *   { ok: false, kind: 'truncated', stopReason, partialText, message } // cut off at the cap; partialText is null when there is none
+ *   { ok: false, kind: 'no_text',   stopReason, message }             // blocks, but none with text
+ *
+ * Order is part of the contract: a refusal is decided FIRST (it can arrive with a thinking block and
+ * no text, and must never read as `no_text`). Then `max_tokens`: a response cut off at the cap is
+ * `truncated` EVEN WHEN it carries text, because a cut-off answer can be well-formed and wrong (a review
+ * cut off before its verdict). A caller whose success means approval (release-review) therefore gets
+ * the safe answer by default. A caller for which a partial answer is harmless (a judge verdict that
+ * defaults to NO, a skill-eval answer that fails its keywords) opts in with `allowPartial: true` and
+ * then gets the text back as `ok`. The first non-blank text block wins otherwise.
+ *
+ * Every non-ok message names the label, `stop_reason:` and, when the API gave one, the refusal category.
+ * Messages begin `<label> returned no text (stop_reason: ...)` when there is no text at all: callers and
+ * tests match that prefix.
+ *
+ * ADOPTER SURFACE (HC-LC-001): this file ships in the published CLI. It is a pure classifier: no
+ * I/O, no local Claude binary.
+ *
+ * @param {object} data   the parsed response body
+ * @param {{label?: string, allowPartial?: boolean}} [opts]  label: who is asking, so three call sites read
+ *   differently in a log. allowPartial: accept text from a response cut off at max_tokens (default false).
+ */
+function readAnthropicText(data, { label, allowPartial = false } = {}) {
+  const who = label || 'the provider';
+  const stopReason = (data && data.stop_reason) || 'unknown';
+  const category = (data && data.stop_details && data.stop_details.category) || null;
+  const blocks = Array.isArray(data && data.content) ? data.content : [];
+  const cause = `stop_reason: ${stopReason}${category ? `, category: ${category}` : ''}`;
+
+  if (stopReason === 'refusal') {
+    return { ok: false, kind: 'refusal', category, stopReason, message: `${who} returned no text (${cause}): the model declined the request` };
+  }
+  const block = blocks.find((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.trim().length > 0);
+  if (stopReason === 'max_tokens' && !(block && allowPartial)) {
+    const message = block
+      ? `${who} returned an incomplete answer (${cause}): it was cut off at max_tokens and may be missing its ending; raise max_tokens`
+      : `${who} returned no text (${cause}): the answer was cut off at max_tokens before any text, thinking included; raise max_tokens`;
+    return { ok: false, kind: 'truncated', stopReason, partialText: block ? block.text : null, message };
+  }
+  if (block) return { ok: true, text: block.text, stopReason };
+  return { ok: false, kind: 'no_text', stopReason, message: `${who} returned no text (${cause})` };
+}
+
+module.exports = { readAnthropicText };