@dtlabs/ai-toolkit 0.17.3 → 0.17.4

package/CHANGELOG.md

@@ -1,4 +1,12 @@
 ## 0.1.4 (2026-07-21)
+## [0.17.4](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.3...v0.17.4) (2026-10-13)
+
+
+### Bug Fixes
+
+* **workflow-control:** repair unescaped control chars in recovered JSON ([ebeddb5](https://github.com/dtlab-tech/ai-toolkit/commit/ebeddb5465ac988f94bd28d20b7f9dfdd967c2c9))
+* **workflow-control:** repair unescaped control chars in recovered JSON ([0ce2466](https://github.com/dtlab-tech/ai-toolkit/commit/0ce24666b6d4d09b25ca71b1ed3b9f0ba7c06d7a))
+
 ## [0.17.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.2...v0.17.3) (2026-10-12)
 
 

package/lib/workflow-control.js

@@ -305,6 +305,41 @@ function createControl(options) {
   return api;
 }
 
+// A model asked to emit a JSON blob as part of a chat reply (rather than through a real
+// serializer, i.e. whenever structured_output didn't get populated and extraction has to
+// recover the payload from free text) is prone to one specific, well-understood defect: a
+// long free-text field (a "report") gets its literal line breaks typed as real newlines
+// instead of the required `\n` escape. The JSON otherwise reads as entirely correct to a
+// human, but JSON.parse rejects it outright ("Bad control character in string literal") —
+// confirmed against a real run where the model's JSON was discarded for exactly this reason
+// despite carrying the correct ```json fence tag and schema-correct structure. This is a
+// narrow, mechanical repair for that one defect, not a lenient parser: it tracks whether
+// each character lies inside a double-quoted JSON string literal (honoring \" and \\
+// escapes) and re-escapes a raw newline/CR/tab ONLY there, leaving structural whitespace
+// between tokens untouched. Applied as a fallback after a plain JSON.parse fails, never in
+// place of one, so already-valid JSON is never second-guessed.
+function _repairUnescapedControlCharsInStrings(text) {
+  let result = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) { result += ch; escaped = false; }
+      else if (ch === '\\') { result += ch; escaped = true; }
+      else if (ch === '"') { result += ch; inString = false; }
+      else if (ch === '\n') { result += '\\n'; }
+      else if (ch === '\r') { result += '\\r'; }
+      else if (ch === '\t') { result += '\\t'; }
+      else { result += ch; }
+    } else {
+      if (ch === '"') inString = true;
+      result += ch;
+    }
+  }
+  return result;
+}
+
 // The model is not consistent about which delimiter it uses to mark its final structured
 // answer inside otherwise-free text — observed empirically, same agent and schema, run to
 // run: an <structured_output> tag, a ```json fence, and an unprompted <json> tag. Growing
@@ -332,8 +367,15 @@ function extractDelimitedStructuredOutput(text, schema) {
   const last = text.lastIndexOf('}');
   if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
   for (const raw of candidates) {
+    const trimmed = raw.trim();
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (e) {
+      try { parsed = JSON.parse(_repairUnescapedControlCharsInStrings(trimmed)); }
+      catch (e2) { continue; }
+    }
     try {
-      const parsed = JSON.parse(raw.trim());
       validateSchema(parsed, schema);
       return parsed;
     } catch (e) { /* try the next candidate, or fall through to null */ }
@@ -354,7 +396,18 @@ function extractDelimitedStructuredOutput(text, schema) {
 // remains the one thing that fails closed on it; this function only undoes wrapping, it is not
 // itself a validation gate.
 function extractJsonDocument(text) {
-  const tryParse = candidate => { try { JSON.parse(candidate); return candidate; } catch (e) { return null; } };
+  // Same "try the candidate as-is, then try it with raw control characters inside
+  // string literals re-escaped" fallback as extractDelimitedStructuredOutput, and
+  // for the identical reason: a long free-text field (e.g. a task description)
+  // typed with literal line breaks instead of `\n` is otherwise indistinguishable
+  // from genuinely malformed JSON, even though it's one mechanical fix away from
+  // valid. Returns the (possibly repaired) STRING to write to disk, never the
+  // parsed object — this function's contract is text recovery, not parsing.
+  const tryParse = candidate => {
+    try { JSON.parse(candidate); return candidate; } catch (e) {}
+    const repaired = _repairUnescapedControlCharsInStrings(candidate);
+    try { JSON.parse(repaired); return repaired; } catch (e) { return null; }
+  };
   const whole = tryParse(text.trim());
   if (whole != null) return whole;
   const fenceMatches = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",