@dtlabs/ai-toolkit 0.14.2 → 0.15.0

package/CHANGELOG.md

@@ -1,4 +1,28 @@
 ## 0.1.4 (2026-07-21)
+## [0.15.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.3...v0.15.0) (2026-10-01)
+
+
+### Features
+
+* Add isolated parallel task execution and task checkpoints documentation ([e17121f](https://github.com/dtlab-tech/ai-toolkit/commit/e17121fbf118673831634f981294d58e1a665d49))
+
+
+### Bug Fixes
+
+* **workflows:** never fail-closed inside extractJsonDocument itself ([dd5f0ce](https://github.com/dtlab-tech/ai-toolkit/commit/dd5f0ce07b7145ef73e29479e4282105000cfd42))
+* **workflows:** recover JSON worker output wrapped in prose or a code fence ([b7a0d08](https://github.com/dtlab-tech/ai-toolkit/commit/b7a0d0817cf6056893906aacff87b40578c6625b))
+* **workflows:** recover JSON worker output wrapped in prose or a code fence ([0dbaece](https://github.com/dtlab-tech/ai-toolkit/commit/0dbaeceb193521c2aca59a15de3762def4881935))
+
+## [0.14.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.2...v0.14.3) (2026-10-01)
+
+
+### Bug Fixes
+
+* **workflows:** accept a schema-valid <structured_output> text block when the CLI field is empty ([6814d96](https://github.com/dtlab-tech/ai-toolkit/commit/6814d96dd10dc5807b8c20417c5a2767cce05216))
+* **workflows:** handle multiple model-chosen delimiters for the structured-output text fallback ([7d97758](https://github.com/dtlab-tech/ai-toolkit/commit/7d977589e10480e6bce66a4ca68a5dbc89b372b1))
+* **workflows:** schema-validated text fallback for empty structured_output ([f2bd76f](https://github.com/dtlab-tech/ai-toolkit/commit/f2bd76fcba554c1b30a2c84629bfd2224a721d13))
+* **workflows:** schema-validated text fallback for empty structured_output ([daa1411](https://github.com/dtlab-tech/ai-toolkit/commit/daa1411d15c919254ce948a785b31d56e6e4468c))
+
 ## [0.14.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.1...v0.14.2) (2026-10-01)
 
 

package/docs/workflow-control-plane.md

@@ -91,11 +91,23 @@ negative semantic verdict, unknown scopes, paths with spaces and explicit approv
 The live paid Claude model/permission flow has not been exercised by these tests.
 Document validation requires both a written Validation Report and a structured
 verdict (`valid: boolean`, `findings: string[]`). The validator performs one pass;
-the host owns revisions. A report or JSON in the plain-text result cannot replace
-`structured_output` from `--json-schema`. Missing structured output stops the
-workflow with an error naming the worker and required fields. Regression tests
-cover missing/malformed verdicts, a clean verdict without a report, and a negative
-verdict followed by host revision and a clean result; model responses are mocked.
+the host owns revisions. Bare plain-text JSON, with no delimiter, never substitutes
+for `structured_output` from `--json-schema`. However, the CLI's own structured-output
+extraction is turn-bound: it only populates `structured_output` when the model's final
+turn ends in a tool call carrying the schema payload, and a long multi-phase agent
+response (full report text, then a closing JSON object) ends that same turn in plain
+text instead — so `structured_output` can come back empty even though the model
+emitted a schema-valid payload in a `<structured_output>...</structured_output>`
+block, exactly as its own agent definition instructs. The host falls back to
+extracting and schema-validating that one delimited block from the plain-text result
+when `structured_output` is absent; this is a deterministic, strictly-delimited parse
+(never "guess the JSON somewhere in the text"), so it does not reintroduce LLM-driven
+I/O. A missing field, a missing/malformed delimited block, or a block that fails
+schema validation all still stop the workflow with the original error naming the
+worker and required fields. Regression tests cover missing/malformed verdicts, a
+clean verdict without a report, the delimited-text fallback (both the accepted and
+the schema-rejected case), and a negative verdict followed by host revision and a
+clean result; model responses are mocked.
 The subprocess adapter reuses FTR-018's existing qualification; no new cross-platform
 process-supervision guarantee is claimed. On Windows, the full executor test suite
 requires Git Bash ahead of the WSL launcher in PATH. User-level installations are

package/lib/workflow-control.js

@@ -186,7 +186,25 @@ function createControl(options) {
       }
       if (result.exitCode !== 0 || result.parseError || result.timedOut ||
           !result.result || result.result.is_error !== false) throw new Error('Worker failed: ' + id);
-      const payload = opts.schema ? result.result.structured_output : result.result.result;
+      let payload = opts.schema ? result.result.structured_output : result.result.result;
+      let usedTextFallback = false;
+      // The CLI's structured-output extraction is turn-bound: it only populates
+      // `structured_output` when the model's final turn ends in a tool call carrying the
+      // schema payload. A long, multi-phase agent response (visible report text, then a
+      // closing JSON object) ends that same turn in plain text instead, so `structured_output`
+      // comes back empty even though the model faithfully emitted a schema-valid payload in
+      // the plain-text result. Observed empirically (not a transient flake) with
+      // gaia-validate-feature-docs across multiple toolkit versions and multiple runs: the
+      // model never misses or mangles the payload, only the CLI's own field never gets
+      // populated — but the model is NOT consistent about how it delimits that payload inside
+      // its text (an `<structured_output>` tag one run, a ```json fence the next, same agent,
+      // same schema). Falling back to a strictly-delimited, schema-validated extraction that
+      // tries each known convention — never a bare "parse the whole result as JSON" guess —
+      // keeps the host's parse deterministic rather than asking the LLM to do I/O.
+      if (opts.schema && payload == null && typeof result.result.result === 'string') {
+        const candidate = extractDelimitedStructuredOutput(result.result.result, opts.schema);
+        if (candidate != null) { payload = candidate; usedTextFallback = true; }
+      }
       if (payload == null || (typeof payload === 'string' && !payload.trim())) {
         if (opts.schema) {
           const fields = (opts.schema.required || []).join(', ') || '(see requested schema)';
@@ -195,10 +213,11 @@ function createControl(options) {
         throw new Error('Worker returned no result: ' + id);
       }
       if (opts.schema) validateSchema(payload, opts.schema);
+      if (usedTextFallback) evidence.save({ usedTextFallback: true });
       if (outputTarget) {
         const content = opts.schema ? payload.report : payload;
         if (typeof content !== 'string' || !content.trim()) throw new Error('Worker output content missing or empty: ' + id);
-        writeOutput(outputTarget, content);
+        writeOutput(outputTarget, /\.json$/i.test(outputTarget) ? extractJsonDocument(content) : content);
       }
       evidence.save({ outcome: 'done', completedAt: new Date().toISOString() });
       return payload;
@@ -277,6 +296,57 @@ function createControl(options) {
   return api;
 }
 
+// Tries each known convention a model has been observed using to delimit its final
+// structured answer inside otherwise-free text, in order of explicitness, and returns the
+// first candidate that is both valid JSON and schema-conformant. Returns null (never throws)
+// if no candidate qualifies, so the caller's original "no structured output" error still fires
+// unchanged when the text holds nothing usable.
+function extractDelimitedStructuredOutput(text, schema) {
+  const candidates = [];
+  const tagMatch = text.match(/<structured_output>([\s\S]*?)<\/structured_output>/);
+  if (tagMatch) candidates.push(tagMatch[1]);
+  const fenceMatches = [...text.matchAll(/```json\s*([\s\S]*?)```/gi)];
+  if (fenceMatches.length) candidates.push(fenceMatches[fenceMatches.length - 1][1]);
+  for (const raw of candidates) {
+    try {
+      const parsed = JSON.parse(raw.trim());
+      validateSchema(parsed, schema);
+      return parsed;
+    } catch (e) { /* try the next candidate, or fall through to null */ }
+  }
+  return null;
+}
+
+// A worker with a declared JSON output has no Write tool (see worker()'s own comment on why):
+// its entire response text becomes the file verbatim. Some models still wrap that deliverable
+// in conversational prose and/or a Markdown code fence despite being told not to (observed
+// empirically with gaia-generate-work-breakdown on haiku: "Perfect. I have all the necessary
+// information..." before the JSON), which is a hard JSON.parse failure for every downstream
+// consumer of this file. Recover the document with the same "try each known convention, always
+// re-validate as parseable JSON, never a blind substring guess" discipline as
+// extractDelimitedStructuredOutput: the content as-is first, then the last fenced code block,
+// then the outermost brace/bracket span. Never throws — genuinely malformed JSON (not merely
+// wrapped) is passed through unchanged so the downstream deterministic validator (wb-validate.js)
+// 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; } };
+  const whole = tryParse(text.trim());
+  if (whole != null) return whole;
+  const fenceMatches = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)];
+  for (let i = fenceMatches.length - 1; i >= 0; i--) {
+    const candidate = tryParse(fenceMatches[i][1].trim());
+    if (candidate != null) return candidate;
+  }
+  const first = text.search(/[[{]/);
+  const last = Math.max(text.lastIndexOf('}'), text.lastIndexOf(']'));
+  if (first >= 0 && last > first) {
+    const candidate = tryParse(text.slice(first, last + 1).trim());
+    if (candidate != null) return candidate;
+  }
+  return text;
+}
+
 function validateSchema(value, schema) {
   if (schema.type === 'object') {
     if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid structured object');

package/package.json

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