extract-workflow-markdown-from-output-json

Persist a Workflow's large markdown field by parsing its output JSON — never retype it

Problem

A Workflow's synthesis agent(..., {schema}) returns a big markdown deliverable in a schema field (e.g. next_prompt_markdown, report, plan). You want it on disk. The instinct is to copy it out of the completion <task-notification> (or the truncated tool result) into a Write call. Two failures follow:

1. Truncation loss — the notification/tool result is capped (often a few hundred lines / ~25-35k tokens) with ... (truncated N chars, full result in <path>). Retyping from it silently drops everything past the cap.
2. Escape leakage — inside the JSON the field is escaped: newlines are literal \n, quotes are \". Hand-copying (or reflowing) it often ships those escapes as literal text in the saved file, so the markdown renders as one line with visible \n.

Context / Trigger conditions

• A Workflow / background Agent finished; its result contains a long markdown/string field you want to save as a .md (a next-session prompt, a synthesized report, generated copy).
• The <task-notification> says full result in /private/tmp/.../tasks/<task-id>.output.
• You're tempted to Write the content by retyping it from what you can see.

Solution

The full, unescaped result is always persisted to the output file named in the notification (.../tasks/<task-id>.output, a JSON envelope {summary, agentCount, logs, result}). Parse it and write the field — let json.load do the unescaping; never retype.

OUT="/private/tmp/.../tasks/<task-id>.output"   # path from the <task-notification>
python3 - "$OUT" <<'PY'
import json, sys
r = json.load(open(sys.argv[1]))["result"]
# navigate to the field (e.g. result.synthesis.next_prompt_markdown)
doc = r["synthesis"]["next_prompt_markdown"]
open("docs/handoffs/the_doc.md", "w").write("<your header>\n\n" + doc + "\n")
PY

• Prepend your own header in the same script (provenance line, run id) rather than editing after.
• If you also want a human-readable provenance/evidence doc from the other structured fields (e.g. each investigator's current_state/files_to_touch), build it in the SAME python pass — you already have the parsed object.
• This also works for a foreground Agent whose final text you saved, and for resuming from a killed run via the agent-*.jsonl transcripts.