fix(documents): keep AI document writes when citation parsing fails

Draft
PO
10d ago
+77-0

Problem

  • A user can lose a document that the AI creates. A linkedom TypeError in citation parsing escapes resolveDocumentCitations and fails the full workspace_create_items call (also workspace_edit_item).
  • Error tracking shows 1 occurrence in 30 days. The input that triggers the crash is unknown, and the exception carries no data to reproduce it.

Origin

  • Error tracking: issue
  • First signal: 2026-11-08
  • Inbox report: open
  • Task started by: auto-start, after the report was rated P3 and ready to fix

Changes

  • resolveDocumentCitations catches a failure in the citation read or apply step and passes the original HTML on.
  • parseDocumentAiHtml already turns each unresolved <citation> into its plain-text label, so the write continues with labels in place of links.
  • The failure goes to recordOperationalFailure as document_citation_resolution, with html_length, html_sha256, operation_id and workspace_id. The next occurrence gives an input fingerprint, not only a stack.
  • New test in create-items.test.ts: citation parsing throws → the document is created and the citation is plain text. The test fails without the fix.
BeforeAfter
Citation parse throwsTool call fails, document lostDocument saved, citations as plain labels
Diagnosis dataStack onlyHTML length + SHA-256 per failure

[!WARNING]
parseDocumentAiHtml parses the same HTML with linkedom again. If the crash is deterministic for that input, the second parse can also throw. In that case workspace_create_items returns a per-item invalid_initial_content failure in place of a failed tool call. The model sees the failure and can retry, and other items in the batch continue. This fix does not guarantee that the document is saved in that case.

Testing

  • vp check: format, lint and typecheck pass.
  • vp test --run --project=node: all pass except src/integrations/posthog/build.test.ts. That test also fails on unchanged main in the sandbox, because of missing VITE_POSTHOG_* env.
  • Skipped: the workers test project and ciBuild. They need the Cloudflare runtime and build env, which the sandbox does not have.

Agent context

  • I did not find the trigger input. A short probe with <template> and mis-nested markup parsed cleanly, which matches the report's fuzzing result.
  • The catch is in the caller, not in readDocumentCitationRefs / applyDocumentCitationLocations. One catch covers both calls and has the workspace context for telemetry. It also covers the ref-index lookup, because a citation is not worth the full write.

Created with PostHog Desktop from this inbox report.

šŸ¤– Generated with Claude Code


Autofix with [code]smith
Open in [code]smith Ā· Need help on this PR? Tag @codesmith-bot with what you need.