Fix structured-output handling for non-object JSON values

Preserve scalar, array, object, boolean, number, and null structured-output payloads across provider result handling and workflow judge validation.

Update prompted-JSON wording to request a JSON value, normalize provider raw-payload metadata, and retry invalid structured-output judge responses with the original schema while keeping unsupported structured output fail-fast.

Includes provider, workflow-envelope, and judge retry regression coverage plus workflow documentation updates.

Author: hugoduncan

components/agent-session/src/psi/agent_session/workflow_judge.clj

@@ -149,14 +149,26 @@
                            :judge-output judge-output
                            :judge-event judge-event
                            :routing-result routing-result})
-                        {:judge-session-id judge-sid
-                         :judge-output judge-output
-                         :judge-event nil
-                         :routing-result (cond-> {:action :fail
-                                                  :reason :invalid-structured-output
-                                                  :output-key output-key}
-                                           (or (:opts request-result) last-structured-output)
-                                           (assoc :details {:structured-output (:structured-output structured-result)}))})))
+                        (if (< attempt max-judge-retries)
+                          (let [retry-result (if-let [opts (:opts request-result)]
+                                               (turn-execution/execute-judge-turn!
+                                                ctx judge-sid
+                                                (judge-retry-feedback last-output expected-sigs)
+                                                opts)
+                                               (turn-execution/execute-judge-turn!
+                                                ctx judge-sid
+                                                (judge-retry-feedback last-output expected-sigs)))]
+                            (recur (inc attempt)
+                                   (str/trim (:assistant-text retry-result))
+                                   (:structured-output retry-result)))
+                          {:judge-session-id judge-sid
+                           :judge-output judge-output
+                           :judge-event nil
+                           :routing-result (cond-> {:action :fail
+                                                    :reason :invalid-structured-output
+                                                    :output-key output-key}
+                                             (or (:opts request-result) last-structured-output)
+                                             (assoc :details {:structured-output (:structured-output structured-result)}))}))))
                   (let [routing-result (workflow-judge/evaluate-routing last-output routing-table
                                                                         current-step-id step-order step-runs)]
                     (if (and (= :no-match (:action routing-result))

components/agent-session/test/psi/agent_session/workflow_judge_test.clj

@@ -468,20 +468,58 @@
           (is (not (get-in @turn-opts* [:structured-output :require-provider-native?])))
           (is (= ["Return review JSON"] @turn-prompts*)))))))
 
+(deftest execute-judge-invalid-structured-output-retry-then-succeeds-test
+  ;; Tests structured-output validation failures retry with the original opts and
+  ;; can recover to a valid routed judge result.
+  (testing "structured judge output retries with structured opts and routes when retry is valid"
+    (let [turns* (atom [])]
+      (with-redefs [psi.session-persistence.core/messages-from-entries-in
+                    (fn [_ctx _sid] [])
+                    psi.workflow-runtime.turn-execution-contract/execute-judge-turn!
+                    (fn [_ctx sid text opts]
+                      (swap! turns* conj {:text text :opts opts})
+                      (if (= 1 (count @turns*))
+                        {:status :ok
+                         :session-id sid
+                         :assistant-text "APPROVED"}
+                        (let [ai-structured-output {:strategy :prompted-json
+                                                    :source :prompted-json/text
+                                                    :payload {"decision" "clear"
+                                                              "issues" []
+                                                              "confidence" 0.8}
+                                                    :raw-payload "{\"decision\":\"clear\",\"issues\":[],\"confidence\":0.8}"}]
+                          {:status :ok
+                           :session-id sid
+                           :assistant-text "{\"decision\":\"clear\",\"issues\":[],\"confidence\":0.8}"
+                           :structured-output ai-structured-output})))]
+        (let [result (workflow-judge/execute-judge!
+                      (structured-judge-test-ctx) "parent-1" "actor-1"
+                      structured-review-judge-spec structured-review-routing-table
+                      {:current-step-id "step-3-review"
+                       :step-order step-order
+                       :step-runs structured-review-step-runs})]
+          (is (= :clear (:judge-event result)))
+          (is (= {:action :complete} (:routing-result result)))
+          (is (= 2 (count @turns*)))
+          (is (= (get-in (first @turns*) [:opts :structured-output])
+                 (get-in (second @turns*) [:opts :structured-output])))
+          (is (re-find #"did not match any expected signal"
+                       (:text (second @turns*)))))))))
+
 (deftest execute-judge-invalid-structured-output-fails-locally-test
-  (testing "invalid structured judge output fails locally without prose routing or retry"
-    (let [turn-prompts* (atom [])]
+  (testing "invalid structured judge output retries and then fails locally without prose routing"
+    (let [turns* (atom [])]
       (with-redefs [psi.session-persistence.core/messages-from-entries-in
                     (fn [_ctx _sid] [])
                     psi.workflow-runtime.turn-execution-contract/execute-judge-turn!
                     (fn
                       ([_ctx sid text]
-                       (swap! turn-prompts* conj text)
+                       (swap! turns* conj {:text text :opts nil})
                        {:status :ok
                         :session-id sid
                         :assistant-text "APPROVED"})
-                      ([_ctx sid text _opts]
-                       (swap! turn-prompts* conj text)
+                      ([_ctx sid text opts]
+                       (swap! turns* conj {:text text :opts opts})
                        {:status :ok
                         :session-id sid
                         :assistant-text "APPROVED"}))]
@@ -490,7 +528,9 @@
                       structured-review-judge-spec structured-review-routing-table
                       {:current-step-id "step-3-review"
                        :step-order step-order
-                       :step-runs structured-review-step-runs})]
+                       :step-runs structured-review-step-runs})
+              turn-prompts (mapv :text @turns*)
+              structured-output-opts (mapv #(get-in % [:opts :structured-output]) @turns*)]
           (is (nil? (:judge-event result)))
           (is (= {:action :fail
                   :reason :invalid-structured-output
@@ -499,7 +539,18 @@
           (is (= :invalid
                  (get-in result [:routing-result :details :structured-output :status])))
           (is (= :invalid (get-in result [:judge-output :review :structured-output :status])))
-          (is (= ["Return review JSON"] @turn-prompts*)))))))
+          (is (= 3 (count @turns*)))
+          (is (= "Return review JSON" (first turn-prompts)))
+          (is (every? #(re-find #"did not match any expected signal" %)
+                      (rest turn-prompts)))
+          (is (every? some? structured-output-opts))
+          (is (apply = structured-output-opts))
+          (is (= (get-in (first @turns*) [:opts :structured-output :json-schema])
+                 {:type "object"
+                  :required ["decision" "issues" "confidence"]
+                  :properties {"decision" {:type "string"}
+                               "issues" {:type "array"}
+                               "confidence" {:type "number"}}})))))))
 
 (deftest execute-judge-schema-valid-negative-decision-routes-test
   (testing "schema-valid negative decision drives the configured non-clear branch"

components/ai/src/psi/ai/providers/anthropic/structured_output.clj

@@ -48,12 +48,12 @@
 
 (defn structured-output-result
   [strategy source raw-payload]
-  (let [payload (structured-output/parse-json-object raw-payload)]
+  (let [parse-result (structured-output/parse-json-value raw-payload)]
     (cond-> (assoc strategy
                    :source source
                    :raw-payload raw-payload)
-      payload (assoc :payload payload)
-      (not payload) (assoc :parse-error? true))))
+      (:parsed? parse-result) (assoc :payload (:payload parse-result))
+      (not parse-result) (assoc :parse-error? true))))
 
 (defn emit-structured-result!
   [consume-fn strategy source raw-payload]

components/ai/src/psi/ai/providers/openai/chat_completions.clj

@@ -369,19 +369,24 @@
                                (resolve-chat-tool-index stream-state tool-call fallback-idx)
                                tool-call))))
 
+(defn- structured-output-result
+  [strategy source raw-text]
+  (when (contains? #{:provider-native :prompted-json} (:strategy strategy))
+    (let [parse-result (structured-output/parse-json-value raw-text)]
+      (cond-> (assoc strategy
+                     :source source
+                     :raw-text raw-text
+                     :raw-payload raw-text)
+        (:parsed? parse-result) (assoc :payload (:payload parse-result))
+        (not parse-result) (assoc :parse-error? true)))))
+
 (defn- emit-structured-output-result!
   [stream-state consume-fn strategy source]
-  (let [{:keys [structured-result-emitted? text-buffer]} stream-state
-        raw-text @text-buffer
-        payload  (structured-output/parse-json-object raw-text)]
-    (when (and (contains? #{:provider-native :prompted-json} (:strategy strategy))
-               (compare-and-set! structured-result-emitted? false true))
-      (consume-fn {:type :structured-output-result
-                   :structured-output (cond-> (assoc strategy
-                                                     :source source
-                                                     :raw-text raw-text)
-                                        payload (assoc :payload payload
-                                                       :raw-payload payload))}))))
+  (let [{:keys [structured-result-emitted? text-buffer]} stream-state]
+    (when (compare-and-set! structured-result-emitted? false true)
+      (when-let [result (structured-output-result strategy source @text-buffer)]
+        (consume-fn {:type :structured-output-result
+                     :structured-output result})))))
 
 (defn- finish-chat-chunk!
   [stream-state consume-fn model chunk choice strategy]
@@ -474,22 +479,19 @@
                  (completions-usage-map model usage))
          logprobs (or (extract-openai-logprob-delta choice)
                       (extract-llama-logprob-delta body))
-         text (content/string-fragment (:content message))
-         payload (when (contains? #{:provider-native :prompted-json} (:strategy strategy))
-                   (structured-output/parse-json-object text))]
+         text (content/string-fragment (:content message))]
      (cond-> {:assistant-message (cond-> {:role "assistant"
                                           :content (completion-message->content message)
                                           :stop-reason stop-reason
                                           :timestamp (java.time.Instant/now)}
                                    (map? usage) (assoc :usage usage))
               :logprobs logprobs}
        strategy (assoc :structured-output
-                       (cond-> strategy
-                         payload (assoc :payload payload
-                                        :raw-payload payload
-                                        :source (if (= :provider-native (:strategy strategy))
-                                                  :openai/message-json
-                                                  :prompted-json/text))))))))
+                       (structured-output-result strategy
+                                                 (if (= :provider-native (:strategy strategy))
+                                                   :openai/message-json
+                                                   :prompted-json/text)
+                                                 text))))))
 
 (defn execute-openai
   [conversation model options]

components/ai/src/psi/ai/providers/openai/codex_structured_output.clj

@@ -18,15 +18,16 @@
 
 (defn structured-output-result
   [strategy source raw-payload]
-  (if-let [{:keys [payload]} (structured-output/parse-json-value raw-payload)]
-    (assoc strategy
-           :source source
-           :raw-payload raw-payload
-           :payload payload)
-    (assoc strategy
-           :source source
-           :raw-payload raw-payload
-           :parse-error? true)))
+  (let [parse-result (structured-output/parse-json-value raw-payload)]
+    (if (:parsed? parse-result)
+      (assoc strategy
+             :source source
+             :raw-payload raw-payload
+             :payload (:payload parse-result))
+      (assoc strategy
+             :source source
+             :raw-payload raw-payload
+             :parse-error? true))))
 
 (defn emit-structured-result!
   [consume-fn strategy source raw-payload]

components/ai/src/psi/ai/structured_output.clj

@@ -158,7 +158,7 @@
   "Return deterministic prompted-JSON fallback instructions for request."
   [request]
   (let [schema-text (json/generate-string (:json-schema request))]
-    (str "\n\nStructured output required. Return exactly one JSON object matching "
+    (str "\n\nStructured output required. Return exactly one JSON value matching "
          "the supplied JSON Schema. Do not wrap the JSON in Markdown fences, "
          "do not add prose, and do not emit extra top-level text.\n"
          "Name: " (structured-output-name request) "\n"

components/ai/test/psi/ai/providers/anthropic_structured_output_test.clj

@@ -7,6 +7,7 @@
    [psi.ai.conversation :as conv]
    [psi.ai.models :as models]
    [psi.ai.providers.anthropic :as anthropic]
+   [psi.ai.providers.anthropic.structured-output]
    [psi.ai.structured-output :as structured-output])
   (:import [java.io ByteArrayInputStream]))
 
@@ -330,15 +331,13 @@
     (is (= "{\"ok\":true}" (get-in result [:structured-output :raw-payload])))))
 
 (deftest anthropic-json-schema-output-non-streaming-parse-failure-test
-  ;; Tests Anthropic JSON Schema native non-streaming invalid/non-object output
-  ;; preserves raw text and marks parse failure without a trusted payload.
+  ;; Tests Anthropic JSON Schema native non-streaming invalid output preserves
+  ;; raw text and marks parse failure without a trusted payload.
   (let [model  (models/get-model :sonnet-4.6)
         convo  (-> (conv/create "sys")
                    (conv/add-user-message "Review this"))
         cases  [{:label "invalid-json"
-                 :text "not json"}
-                {:label "non-object-json"
-                 :text "[true]"}]]
+                 :text "not json"}]]
     (doseq [{:keys [label text]} cases]
       (let [body   {:content [{:type "text" :text text}]
                     :stop_reason "end_turn"
@@ -360,15 +359,13 @@
         (is (not (contains? (:structured-output result) :payload)) label)))))
 
 (deftest anthropic-streaming-json-schema-output-parse-failure-test
-  ;; Tests Anthropic JSON Schema native streaming invalid/non-object output emits
-  ;; a parse-failure result with raw text and no trusted payload.
+  ;; Tests Anthropic JSON Schema native streaming invalid output emits a
+  ;; parse-failure result with raw text and no trusted payload.
   (let [model (models/get-model :sonnet-4.6)
         convo (-> (conv/create "sys")
                   (conv/add-user-message "Review this"))
         cases [{:label "invalid-json"
-                :text "not json"}
-               {:label "non-object-json"
-                :text "[true]"}]]
+                :text "not json"}]]
     (doseq [{:keys [label text]} cases]
       (let [events (atom [])
             sse    (str (sse-line "message_start"
@@ -404,6 +401,31 @@
           (is (true? (:parse-error? structured)) label)
           (is (not (contains? structured :payload)) label))))))
 
+(deftest anthropic-structured-output-result-json-value-payloads-test
+  ;; Tests the shared Anthropic structured-output result helper preserves every
+  ;; valid JSON value, including present nil for JSON null.
+  (let [strategy {:strategy :provider-native
+                  :native-mechanism :anthropic/json-schema-output}
+        cases    [{:label "string" :raw "\"DONE\"" :expected "DONE"}
+                  {:label "number" :raw "42" :expected 42}
+                  {:label "boolean" :raw "true" :expected true}
+                  {:label "array" :raw "[true]" :expected [true]}
+                  {:label "object" :raw "{\"ok\":true}" :expected {:ok true}}
+                  {:label "null" :raw "null" :expected nil}]]
+    (doseq [{:keys [label raw expected]} cases
+            source [:anthropic/json-schema-output :prompted-json/text]]
+      (let [result (#'psi.ai.providers.anthropic.structured-output/structured-output-result
+                    (if (= :prompted-json/text source)
+                      {:strategy :prompted-json :fallback-used? true}
+                      strategy)
+                    source
+                    raw)]
+        (is (= expected (:payload result)) label)
+        (is (contains? result :payload) label)
+        (is (not (:parse-error? result)) label)
+        (is (= raw (:raw-payload result)) label)
+        (is (= source (:source result)) label)))))
+
 (deftest anthropic-streaming-json-schema-output-events-test
   ;; Tests JSON Schema native streaming preserves text events and emits a parsed
   ;; structured-output result sourced from ordinary assistant text.