la-machina-engine 0.20.1 → 0.22.0

package/README.md

@@ -259,28 +259,59 @@ const result = await engine.run({
 }
 ```
 
-### Done — JSON Mode, Parse Failed
+### Failed — JSON Mode, Parse / Schema Error
 
-When the model doesn't return valid JSON despite instructions:
+When `outputFormat: 'json'` is requested but the final model output is
+empty, not valid JSON, or fails the supplied `outputSchema`, the run
+terminates as `status: 'failed'` with a typed code (engine ≥ 0.21.0). The
+old permissive fallback (`status: 'done'` with `data` falling back to raw
+text) is removed — a strict-JSON request that can't satisfy the contract
+fails at the engine boundary so callers never mistake an empty/invalid
+output for a successful structured result.
+
+Raw parse failure:
 
 ```json
 {
   "runId": "run_abc",
-  "status": "done",
-  "data": "Here's the pricing: Starter at $29, Pro at $99, Enterprise at $299.",
+  "status": "failed",
+  "data": null,
   "meta": {
     "nodeId": "extract",
-    "turns": 2,
-    "tokensUsed": { "input": 5000, "output": 800 },
+    "turns": 0,
+    "tokensUsed": { "input": 0, "output": 0 },
     "durationMs": 6000,
-    "output": "Here's the pricing: Starter at $29, Pro at $99, Enterprise at $299."
+    "transcript": { "path": "projects/run_abc/nodes/extract", "lastShardIndex": 0 }
   },
-  "errors": [],
+  "errors": [
+    {
+      "code": "ERR_JSON_OUTPUT_PARSE",
+      "message": "Output is not valid JSON: …"
+    }
+  ],
   "timestamp": 1712966400000
 }
 ```
 
-`data` falls back to raw text. Client checks `typeof response.data === 'object'` to verify structured output.
+Schema mismatch (parse succeeded, validation failed):
+
+```json
+{
+  "runId": "run_abc",
+  "status": "failed",
+  "data": null,
+  "errors": [
+    {
+      "code": "ERR_JSON_OUTPUT_SCHEMA",
+      "message": "Output failed schema validation: …"
+    }
+  ]
+}
+```
+
+In both cases the engine still appends a `json_parse_failure` inspect
+event (unchanged from Plan 026) — the failure is now visible BOTH in
+inspect AND on the public run result.
 
 ### Paused — Human Approval Needed
 
@@ -456,8 +487,10 @@ await engine.resume({
 | `ERR_STREAM_PARSE` | Malformed API response | No — provider issue |
 | `ERR_STREAM_INCOMPLETE` | Stream ended without message_stop | Yes — transient |
 | `ERR_UNEXPECTED_STOP` | Unknown stop reason from API | No — investigate |
-| `SCHEMA_VALIDATION_FAILED` | JSON output doesn't match outputSchema | No — adjust schema or task |
-| `JSON_PARSE_FAILED` | Model didn't return valid JSON | No — adjust task |
+| `ERR_JSON_OUTPUT_PARSE` | `outputFormat: 'json'` returned empty / non-JSON output (engine ≥ 0.21.0) | No — adjust task / prompt |
+| `ERR_JSON_OUTPUT_SCHEMA` | JSON output failed `outputSchema` validation (engine ≥ 0.21.0) | No — adjust schema or task |
+| `SCHEMA_VALIDATION_FAILED` | (Legacy inspect-only code; pre-0.21.0) JSON output doesn't match outputSchema | No — adjust schema or task |
+| `JSON_PARSE_FAILED` | (Legacy inspect-only code; pre-0.21.0) Model didn't return valid JSON | No — adjust task |
 
 ### Workflow Runner Integration