fix(extract): address code review — markdown-to-file, spatial response guard, leaner write

- Honor outputPath for markdown output (large docs would overflow context inline)
- Reject 2xx responses lacking output.elements before writing, so a non-extraction
  body can't overwrite the target file
- Write the raw response body for spatial output instead of re-stringifying
  (drops a copy of large payloads, preserves all API fields)
- Extract writeToResolvedPath helper (de-dupes mkdir-p), drop redundant
  includeWords coalesce and the resolvedOutputPath casts
- Add tests for markdown-to-file and the non-spatial-body guard

🔮 View transcript: https://nutrient-agentlogs.dev/s/duk4x9tr3rmlnxta7c4bwk6o

Author: jdrhyne

README.md

@@ -217,7 +217,7 @@ The `data_extractor` and `query_extraction` tools wrap the standalone [DWS Data
 | `agentic`              | Spatial or Markdown | Yes (VLM)          | 18 credits    |
 
 - **Spatial** output returns typed elements (paragraphs, tables, key-value regions, formulas, pictures, handwriting) with bounding boxes, confidence scores, and reading order. Because the element list can be large, it is written to `outputPath` and the tool returns a content-free summary (element counts, low-confidence flags, page geometry).
-- **Markdown** output returns whole-document Markdown inline — useful for RAG and search indexing.
+- **Markdown** output returns whole-document Markdown inline, or writes it to `outputPath` when provided (recommended for large documents) — useful for RAG and search indexing.
 
 Use `query_extraction` to pull just the elements you need from a saved spatial file — filter by `pages`, `region` (bounding box), `minConfidence`, or `elementTypes` — so coordinates and values enter the conversation only when you ask for them.
 

src/dws/extract.ts

@@ -72,6 +72,17 @@ function summarizeSpatial(response: ExtractionResponse, outputPath: string, byte
   ].join('\n')
 }
 
+/** Writes `data` to `resolvedPath`, creating parent directories as needed. */
+async function writeToResolvedPath(resolvedPath: string, data: string): Promise<void> {
+  const outputDir = path.dirname(resolvedPath)
+  try {
+    await fs.promises.access(outputDir)
+  } catch {
+    await fs.promises.mkdir(outputDir, { recursive: true })
+  }
+  await fs.promises.writeFile(resolvedPath, data)
+}
+
 /**
  * Calls the Nutrient DWS Data Extraction API (`POST /extraction/parse`).
  *
@@ -105,9 +116,10 @@ export async function performExtractCall(
     )
   }
 
-  // Resolve the output path first (fail early on a sandbox escape, before any API call).
+  // Resolve any provided output path first (fail early on a sandbox escape,
+  // before the API call). Required for spatial, optional for markdown.
   let resolvedOutputPath: string | undefined
-  if (format === 'spatial' && outputPath) {
+  if (outputPath) {
     try {
       resolvedOutputPath = await resolveWriteFilePath(outputPath)
     } catch (error) {
@@ -129,7 +141,7 @@ export async function performExtractCall(
 
   const instructions: Record<string, unknown> = {
     mode,
-    output: format === 'spatial' ? { format, includeWords: includeWords ?? false } : { format },
+    output: format === 'spatial' ? { format, includeWords } : { format },
   }
   if (language && mode !== 'text') {
     instructions.options = { language }
@@ -155,20 +167,30 @@ export async function performExtractCall(
       if (typeof markdown !== 'string') {
         return createErrorResponse('Error: the Data Extraction API did not return markdown output.')
       }
+      // Honor outputPath for markdown too — a large document returned inline
+      // would overflow the conversation. Only return inline when no path given.
+      if (resolvedOutputPath) {
+        await writeToResolvedPath(resolvedOutputPath, markdown)
+        return createSuccessResponse(`Wrote ${Buffer.byteLength(markdown)} bytes of Markdown to ${resolvedOutputPath}.`)
+      }
       return createSuccessResponse(markdown)
     }
 
-    // Spatial: write the full result to disk, return a content-free summary.
-    const outputDir = path.dirname(resolvedOutputPath as string)
-    try {
-      await fs.promises.access(outputDir)
-    } catch {
-      await fs.promises.mkdir(outputDir, { recursive: true })
+    // Spatial. The early guard guarantees outputPath was provided.
+    if (!resolvedOutputPath) {
+      return createErrorResponse('Error: spatial output requires outputPath.')
     }
-    const json = JSON.stringify(parsed, null, 2)
-    await fs.promises.writeFile(resolvedOutputPath as string, json)
-
-    return createSuccessResponse(summarizeSpatial(parsed, resolvedOutputPath as string, Buffer.byteLength(json)))
+    // Guard against a 2xx response that is not a spatial result, so we never
+    // overwrite the target file with a non-extraction body.
+    if (!Array.isArray(parsed.output?.elements)) {
+      return createErrorResponse(
+        'Error: the Data Extraction API response did not contain a spatial element list (output.elements). Nothing was written.',
+      )
+    }
+    // Write the raw response body: avoids re-serializing a potentially large
+    // payload and preserves every field the API returned.
+    await writeToResolvedPath(resolvedOutputPath, body)
+    return createSuccessResponse(summarizeSpatial(parsed, resolvedOutputPath, Buffer.byteLength(body)))
   } catch (error) {
     return handleApiError(error)
   }

src/index.ts

@@ -176,7 +176,7 @@ Returns: subscription type, total credits, used credits, and remaining credits.`
 
 Output formats:
 • spatial — typed elements (paragraphs, tables, key-value pairs, formulas, pictures, handwriting) with bounding boxes, confidence scores, and reading order. Written to outputPath (the list can be large); retrieve slices with the query_extraction tool.
-• markdown — whole-document Markdown, returned inline. Good for RAG and search indexing.
+• markdown — whole-document Markdown. Returned inline, or written to outputPath when provided (recommended for large documents). Good for RAG and search indexing.
 
 Processing modes (cost per page): text = fast Markdown, no OCR (1 credit); structure = OCR spatial (1.5 credits); understand = AI-augmented, default (9 credits); agentic = VLM-augmented (18 credits).
 

tests/extract.test.ts

@@ -101,6 +101,40 @@ describe('performExtractCall', () => {
     expect(post).toHaveBeenCalledOnce()
   })
 
+  it('writes markdown to a file when outputPath is given, returning a summary not the content', async () => {
+    const input = await writeInput()
+    const outName = `out-${counter}.md`
+    const { client } = mockClient({ output: { markdown: '# Big Document\n\nlots of text' } })
+
+    const result = await performExtractCall(
+      extractArgs({ filePath: input, mode: 'text', format: 'markdown', outputPath: outName }),
+      client,
+    )
+
+    expect(result.isError).toBeFalsy()
+    const summary = text(result)
+    expect(summary).toContain('Wrote')
+    expect(summary).toContain(outName)
+    expect(summary).not.toContain('lots of text')
+    const written = await fs.promises.readFile(path.join(sandboxDir, outName), 'utf-8')
+    expect(written).toBe('# Big Document\n\nlots of text')
+  })
+
+  it('rejects a 2xx response with no spatial element list without writing the file', async () => {
+    const input = await writeInput()
+    const outName = `out-${counter}.json`
+    const { client } = mockClient({ status: 200, output: { markdown: 'oops wrong shape' } })
+
+    const result = await performExtractCall(
+      extractArgs({ filePath: input, mode: 'structure', format: 'spatial', outputPath: outName }),
+      client,
+    )
+
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('output.elements')
+    await expect(fs.promises.access(path.join(sandboxDir, outName))).rejects.toThrow()
+  })
+
   it('writes spatial output to a file and returns a content-free summary', async () => {
     const input = await writeInput()
     const outName = `out-${counter}.json`