Adeu DOCX Engine v1.4.0

This release introduces major improvements to how the Adeu engine projects complex MS Word domain structures (like definitions, footnotes, and cross-references) into editable Markdown. It significantly hardens the Track Changes engine with new validation rules, structural boundary protections, and improved diffing heuristics.

Major Features & Capabilities

Domain Gaps & Semantic Projection (The "Structural Appendix")

To solve domain visibility gaps without adding new MCP tools, read_docx now projects a strictly defined semantic dialect of Markdown, concluding with a deterministic "Language Server (LSP)" hover panel appended to the bottom of the document.

• Symbol Table (Defined Terms): The engine now structurally extracts defined legal terms (via typography and glossary scanning) and projects them into an index.
• Semantic Diagnostics (Linter): Statically analyzes the plain-text projection to map term usages, automatically generating high-signal warnings for:
  • Duplicate Definitions: Terms defined multiple times.
  • Possible Typos: Detects capitalized phrases within a Levenshtein distance of 1-2 from a valid term (with strict false-positive pruning for short acronyms and stop-words).
    • Unused Definitions: Terms defined but never used in the document text.
• Named Anchors & Dependencies: Extracts a deterministic dependency map of Bookmark IDs and which clauses/paragraphs point to them.

Advanced Structural Editability

• Multi-Level Lists: OOXML list levels (<w:ilvl>) now natively map to standard Markdown indentation (4 spaces per level) on read. The engine parses leading spaces on write to explicitly inject list levels, allowing seamless list editing via Markdown.
• Bi-directional Footnotes/Endnotes: Footnotes and endnotes are now projected inline using stable OOXML IDs (e.g., [^fn-3]) and appended at the bottom of the document. Modifying the footnote content natively applies tracked changes inside footnotes.xml.
• External Link Retargeting: Links project as [Text](url). Editing the display text applies redlines. Editing the URL executes a silent retargeting operation in the DOCX relationship files without emitting redlines.

Enhanced Track Changes & Redline Engine

• Diff Hunk Coalescing: Adjacent textual diff hunks separated only by short runs of stable tokens (≤ 4 words) within the same paragraph are now mathematically coalesced into a single unified edit hunk. This prevents fragmented redlines across single clauses.
• Paragraph Break Tracking: When multi-paragraph text is inserted (\n\n), the engine explicitly injects an <w:ins> marker inside the <w:pPr><w:rPr> of the newly created paragraph, ensuring Word natively tracks the paragraph break itself.
• Global Acceptance: The accept_all_revisions operation now sweeps the entire package array, successfully resolving redlines inside generic XML parts (Headers, Footers, and Footnotes).

Safety & Validation Improvements (Strict Refusals)

The engine now intercepts and strictly rejects unsafe edits via BatchValidationError to prevent silent template or dependency corruption:

• Read-Only Cross-References: Cross-references project as [~Text~](#_Ref). Modifying the display text or hash via text replacement is strictly rejected. Edits must target the source heading/paragraph instead.
• Structural Boundary Violations: Modifications targeting the Read-Only Structural Appendix boundary, internal anchors ({#_BookmarkName}), or attempting to fabricate/delete link/footnote syntax via text replacement are explicitly rejected.
• Nested Redline Fragmentation: Edits that strictly target text inside an active <w:ins> authored by a different user are rejected to prevent nested redline corruption.
• Heading Depth Limits: Markdown heading depths are strictly clamped to a maximum of 6 to prevent generating unstyled XML blocks (e.g., Heading 7).
• Multi-Author Sanitization Awareness: When executing a full document sanitization with auto-acceptance (accept_all=True), if multiple distinct authors are detected in pending track changes, a high-visibility warning is injected into the Sanitize Report to alert the user of potential "silent smuggles."

Bug Fixes & Refinements

• Table Cell Comment Anchoring: Fixed an issue where comments attached to table row substitutions were incorrectly anchored to the first cell. The engine now uses heuristic cell matching to bypass whitespace drift and accurately anchor comments to the semantically modified cell.
• Contiguous Orphan Comment Sweep: Fixed an issue where comment anchors wrapping across adjacent, paired redline tags (w:ins + w:del) leaked into the document body after acceptance.
• Empty Ghost Insertions: The engine no longer generates self-closing ghost <w:ins/> tags when tracking empty string insertions.
• Live Word Identity Warnings: Live COM batch executions will now proactively surface a warning in the tool response when the requested author_name is forcefully overridden by the host OS M365 identity to maintain a predictable audit trail for Agents.
• XML Proxy Serialization: Fixed serialization corruptions on generic XML parts by properly re-binding part._element = part._adeu_element and safely injecting custom namespaces directly at the document root to bypass lxml alias artifacts.

v1.3.0: Native UI Integrations & Advanced Email Workflows

Adeu v1.3.0 brings significant enhancements to the MCP UI experience and introduces a powerful suite of new email capabilities. Agents can now draft replies, manage local attachments, and seamlessly launch native desktop applications directly from your chat window.

Update
Already running Adeu? Pick up v1.3.0 via one of:

# Claude Desktop (re-run init; restart Claude afterwards)
uvx adeu init

# uvx users (clears cached older versions)
uvx --refresh --from adeu adeu-server

# pip users
pip install --upgrade adeu

New to Adeu? See the README for full install instructions.

Native File Opening (MCP UI)

• open_local_file Tool: Added a new system-level tool that securely launches the native OS default application (Microsoft Word, PDF readers, etc.) for a given file path across Windows, macOS, and Linux.
• One-Click Open: The custom Adeu Markdown UI inside Claude Desktop now features an "Open in Native App" button, allowing you to instantly pop open the document the agent is reviewing without leaving your workflow.
• Smart Collapsing: The Markdown UI now starts collapsed by default for large documents, saving valuable screen real estate in your chat window while remaining fully readable.

Advanced Email Agent Workflows

• Drafting & Replies: Introducing the create_email_draft tool. Agents can now compose new emails or thread replies using Markdown, saving them directly to your native draft box (Outlook/Gmail).
• Local Attachment Hand-off: search_and_fetch_emails now accepts a working_directory. When an agent reads an email, its attachments are automatically downloaded directly to your local project folder. Agents can immediately chain this with read_docx or validate_documents on the downloaded files, and even attach local files back to outgoing drafts.
• Context Optimization: Giant email provider IDs are now securely minified into cached short IDs (e.g., msg_abc123), saving significant token overhead. We've also added heuristic stripping of trailing quoted replies (Outlook/Gmail dividers) to keep the LLM context window focused on the actual message content.
• Rich Email UI: Completely revamped rendering for the Email Inbox MCP App. It now beautifully displays thread history, inline AI Strategy Briefs, and nested attachment lists showing local file paths, while aggressively pruning messy HTML quotes for a cleaner reading experience.

v1.2.0: The Live Word Update

Adeu v1.2.0 brings agents onto the Microsoft Word canvas. Instead of round-tripping a DOCX through disk, agents can read, edit, and comment on the document you have open — in real time, with full Tracked Changes fidelity.

Update

Already running Adeu? Pick up v1.2.0 via one of:

# Claude Desktop (re-run init; restart Claude afterwards)
uvx adeu init

# uvx users (clears cached older versions)
uvx --refresh --from adeu adeu-server

# pip users
pip install --upgrade adeu

New to Adeu? See the README for full install instructions.

Live Word Integration (MCP)

Unified tools: On Windows, omitting the file path on read_docx or process_document_batch routes the command to the active Word document. Same tool surface, same DocumentChange types, no new API to learn.

Live Tracked Changes: ModifyText, AcceptChange, RejectChange, and ReplyComment all apply natively against the active document. Revisions appear in the Review Pane instantly, attributed to the agent.

Comment rescue: Comments anchored to replaced text are automatically re-anchored instead of destroyed.

Richer new_text on Both Paths

process_document_batch now accepts full Markdown structure in new_text:

• # Title through ###### H6 for heading styles
• **bold** and _italic_ for run formatting
• \n\n for real paragraph breaks
• Multi-paragraph inserts tracked as one logical revision

Disk ↔ Live Parity

The same document reads identically from disk or from the live canvas, so an agent that reads one way and edits the other sees matching text.

• Coalescing of fragmented runs that Word produces in live memory
• Consistent heading rendering whether the file was last saved by Word or is still in memory
• Correct handling of manually-formatted section titles (all-caps bold paragraphs, signature-block headings)

Full Changelog: v1.1.0...v1.2.0

v1.1.0: The Sanitize Update

Adeu v1.1.0 introduces a surgical DOCX metadata scrubber that safely prepares documents for the counterparty.

Word documents leak information. Track changes reveal negotiation strategies, resolved comments expose internal deliberations, and XML metadata leaks author names, file server paths, and editing timelines. Adeu fixes this by stripping dangerous metadata while mathematically preserving complex Track Changes and proving what it did.

Agentic Integrations (MCP)

• New sanitize_docx Tool: AI agents can now sanitize documents. An agent can draft a redline using process_document_batch and follow up with sanitize_docx to present you with a safe, outbound-ready document and its audit report.
• Robust validate_documents Tool: Improved path parsing to gracefully accept JSON-encoded strings. This resolves common LLM escaping hallucinations with absolute file paths (especially on Windows).

DOCX Metadata Scrubber (adeu sanitize)

A powerful new CLI command to prepare your documents before sending them externally.

• Keep Markup (--keep-markup): The standard pre-send workflow. Preserves existing track changes and open comments (intended for the counterparty). Strips resolved comments (internal notes) and all metadata. Unifies author names.
• Baseline Recomputation (--baseline): For when Track Changes were turned off, or to collapse multiple rounds of markup. Computes a word-level diff against an original document and reconstructs a pristine redline delta.
• Full Scrub: For signature and deal closing. Strips all history. Includes a safety gate that blocks the scrub if unresolved track changes exist (unless explicitly bypassed with --accept-all).

Transparent Audit Reports

Adeu generates a comprehensive audit report (--report). It shows what was stripped, warns about internal hyperlink targets, and details exactly what markup will be visible to the recipient.

Full Changelog: v1.0.0...v1.1.0

Release v0.9.0 - API Unification & Reliability

This release marks a major stabilization of the Adeu MCP interface and Python SDK. We have completely overhauled the way AI agents interact with documents, moving from fragmented, multi-step tool calls to a unified, reliable batch-processing pipeline.

Key Features & Agentic Improvements

• Unified Flat API (DocumentChange): The LLM now interacts with a single, flat list of operations represented by a discriminated union. This dramatically improves LLM structured output reliability compared to managing separate arrays for edits and actions.
• The "Commit & Negotiate" Pipeline: Replaced fragmented endpoints with a single powerful MCP tool: process_document_batch. Agents can now execute search-and-replace edits (modify), accept/reject existing redlines (accept, reject), and reply to comments (reply) in a single, atomic tool call.
• Search-and-Replace First: Pure insertions and deletions are intentionally hidden from the LLM at the API level. All text modifications must now be executed as a search-and-replace (ModifyText), ensuring the LLM always provides sufficient anchoring context for our fuzzy matcher.
• Pre-Flight Validation (BatchValidationError): The engine now performs an exhaustive dry-run validation of all text edits in a batch before touching the XML. If an edit fails to anchor, the entire batch is rejected with explicit, positive error logging, allowing the agent to self-correct.

MCP Tool Changes (Claude Desktop)

• Added: process_document_batch - The single entry point for all document modifications.
• Removed: apply_edits_as_markdown, apply_structured_edits, manage_review_actions. These have been consolidated into the batch processor.
• Updated Prompts: The recommended System Prompt in the README.md has been updated. Agents should now be instructed to use type: "modify", "accept", "reject", or "reply" within the batch tool.

Migration Guide for SDK Builders

If you are using the RedlineEngine in your own Python applications, update your data models:

Old (v0.8.x):

from adeu import DocumentEdit, ReviewAction

edits = [DocumentEdit(target_text="Old", new_text="New")]
actions = [ReviewAction(action="ACCEPT", target_id="Chg:1")]

engine.apply_review_actions(actions)
engine.apply_edits(edits)

New (v0.9.0):

from adeu import ModifyText, AcceptChange

changes = [
    AcceptChange(target_id="Chg:1"),
    ModifyText(target_text="Old", new_text="New")
]

# The engine handles the safe ordering (actions first, rebuild DOM, then edits)
engine.process_batch(changes)

CLI Updates

• The adeu apply and adeu markup commands now expect the new List[DocumentChange] JSON format.
• Backwards Compatibility: The CLI includes a fallback adapter. If you pass an older JSON file structured with {"actions": [...], "edits": [...]}, Adeu will automatically up-convert it to the new flat format at runtime.

Reliability & Testing

• Added test_server.py to cover end-to-end MCP tool execution.
• Extensive testing added for the process_document_batch pipeline to prevent cascading misanchors when accepting/rejecting changes dynamically shifts the Virtual DOM.

v0.7.1

Adeu v0.7.1

6 issues fixed.

---

Ambiguous match detection: The engine now scans the full document before writing. Duplicate target strings trigger a hard stop with a report showing every occurrence in context. The file on disk is never touched on failure.

Atomic batch processing: Edits and review actions (accept/reject/reply) in a single batch now execute in one document lifecycle. No more cross-invocation state loss or cascading misanchors.

Surgical edits inside insertions: Changing text within a tracked insertion now produces a precise, word-level redline. Previously the entire insertion was replaced.

Nested insertion visibility: The mapper now correctly indexes text inside multi-round nested tracked-change structures.

Comment sync on accept/reject: Accepting or rejecting a change now cleans up all four comment XML parts. No more orphaned comments or Review pane desyncs.

Paragraph boundary preservation: Heading and clause insertions at paragraph boundaries no longer collapse adjacent paragraphs.

---

Upgrade note: Callers relying on first-match behaviour will now receive an error on ambiguous targets. Include sufficient surrounding context in target_text to disambiguate.

v0.7.0

v0.7.0

4 bug fixes discovered through real-world contract redlining.

Bug Fixes

• Tab normalization — get_run_text() now normalizes literal \t characters to spaces, consistent with how <w:tab/> elements are handled. Previously this caused spurious track changes showing tab deletions and space insertions.

• Bold/italic inheritance bleed — Replacing formatted text with plain text no longer incorrectly inherits the deleted run's bold or italic properties. _apply_run_props() now accepts a suppress_inherited flag that explicitly turns off formatting carried over via deepcopy of the anchor run's rPr.

• Markdown marker leaking into diffs — _trim_common_context() now backtracks prefix and suffix trim points to avoid leaving unbalanced ** or _ markers in the edit delta. It also absorbs balanced outer wrappers (e.g. **Bold** → **Bolder** now diffs as Bold → Bolder).

• Overlapping edit detection — apply_edits() now tracks occupied character ranges across both the indexed and heuristic edit paths. When a second edit targets a range already covered by an applied edit, it is skipped rather than applied on top of shifted indices, preventing document corruption.

Thank you @sarturko-maker for the reports!