docuhand 0.1.0.dev1__py3-none-any.whl

docuhand/__init__.py

@@ -0,0 +1,3 @@
+"""DocuHand — give your AI agent hands to operate real Word & WPS documents."""
+
+__version__ = "0.1.0.dev1"

docuhand/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

docuhand/_compat.py

@@ -0,0 +1,28 @@
+"""Chinese-Windows stdio fix.
+
+On Chinese Windows, Python's stdout/stderr default to the GBK codec. An MCP
+stdio server writes JSON-RPC over stdout, so any non-GBK-encodable character
+(a Chinese path, a curly quote in a document) raises UnicodeEncodeError and
+kills the protocol stream. This is the invisible bomb behind most broken
+MCP servers on CJK Windows machines.
+
+We reconfigure both streams to UTF-8 *before* the MCP SDK writes anything.
+Every entrypoint (``docuhand serve``, ``python -m docuhand``) calls this at
+import time of :mod:`docuhand.server`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def fix_stdio() -> None:
+    for name in ("stdout", "stderr"):
+        stream = getattr(sys, name, None)
+        if stream is None or not hasattr(stream, "reconfigure"):
+            continue
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            # Never let a cosmetics fix break startup.
+            pass

docuhand/engine/__init__.py

@@ -0,0 +1,38 @@
+"""Engine package: dedicated COM STA worker + Office engine with Word/WPS failover."""
+
+from __future__ import annotations
+
+import atexit
+
+from .com_thread import ComWorker
+from .office_app import OfficeEngine, sniff_format
+
+_worker = ComWorker()
+_engine = OfficeEngine()
+
+# A timed-out STA is abandoned wholesale; engine state that lived on that
+# thread is void — reset it so the next call relaunches cleanly on a fresh
+# STA thread. invalidate() only writes plain attributes (GIL-atomic), it
+# never touches COM objects.
+_worker.set_abandon_hook(_engine.invalidate)
+
+
+def get_worker() -> ComWorker:
+    return _worker
+
+
+def get_engine() -> OfficeEngine:
+    return _engine
+
+
+def _shutdown() -> None:
+    """Quit the hidden Word/WPS instance on its own STA thread at exit."""
+    try:
+        _worker.submit(_engine.shutdown, timeout=15.0)
+    except Exception:
+        pass  # process teardown must never hang on a sick COM app
+
+
+atexit.register(_shutdown)
+
+__all__ = ["ComWorker", "OfficeEngine", "get_engine", "get_worker", "sniff_format"]

docuhand/engine/com_thread.py

@@ -0,0 +1,88 @@
+"""Dedicated STA thread for all COM work — architecture decision #1.
+
+Why this exists:
+- The MCP server runs on an asyncio event loop; calling COM from it explodes
+  with RPC_E_WRONG_THREAD.
+- Naive "one thread per call" COM usage launches a fresh WINWORD.EXE per
+  call — the instance explosion.
+- One long-lived single-threaded-apartment thread with a serial work queue
+  fixes both: every COM operation happens on the same STA, fully serialized.
+
+Timeout policy: a stuck call (Word showing a modal first-run / activation /
+recovery dialog) cannot be interrupted safely. On timeout we *abandon* that
+thread and its queue entirely (daemon thread; dies with the process) and
+lazily build a fresh STA thread on the next submit. Any engine state that
+lived on the abandoned STA is void and is reset via the abandon hook.
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import threading
+from typing import Any, Callable
+
+from ..errors import ComCallTimeoutError
+
+_DEFAULT_TIMEOUT_S = float(os.environ.get("DOCUHAND_COM_TIMEOUT", "90"))
+
+
+class ComWorker:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._queue: queue.SimpleQueue | None = None
+        self._thread: threading.Thread | None = None
+        self._on_abandon: Callable[[], None] | None = None
+
+    def set_abandon_hook(self, fn: Callable[[], None]) -> None:
+        self._on_abandon = fn
+
+    def submit(self, fn: Callable[..., Any], /, *args: Any, timeout: float = _DEFAULT_TIMEOUT_S) -> Any:
+        """Run fn(*args) on the STA thread; raise on timeout (and abandon)."""
+        with self._lock:
+            if self._queue is None or self._thread is None or not self._thread.is_alive():
+                self._queue = queue.SimpleQueue()
+                self._thread = threading.Thread(
+                    target=self._run,
+                    args=(self._queue,),
+                    name="docuhand-com-sta",
+                    daemon=True,
+                )
+                self._thread.start()
+        work_queue = self._queue
+
+        box: queue.SimpleQueue = queue.SimpleQueue()
+        work_queue.put((fn, args, box))
+        try:
+            ok, payload = box.get(timeout=timeout)
+        except queue.Empty:
+            self._abandon()
+            raise ComCallTimeoutError(timeout) from None
+        if ok:
+            return payload
+        raise payload
+
+    def _abandon(self) -> None:
+        with self._lock:
+            self._queue = None
+            self._thread = None
+        if self._on_abandon:
+            try:
+                self._on_abandon()
+            except Exception:
+                pass
+
+    @staticmethod
+    def _run(work_queue: queue.SimpleQueue) -> None:
+        import pythoncom
+
+        pythoncom.CoInitialize()  # STA — the whole point of this thread
+        try:
+            while True:
+                fn, args, box = work_queue.get()
+                try:
+                    box.put((True, fn(*args)))
+                except BaseException as exc:  # propagate to submit()'s caller
+                    box.put((False, exc))
+        finally:
+            pythoncom.CoUninitialize()

docuhand/engine/com_utils.py

@@ -0,0 +1,56 @@
+"""Shared COM guard helpers — leaf module, no engine imports (no cycles).
+
+``_g``: guard a single metadata probe — one engine lacking a property must
+never fail the whole operation (the seed of docs/wps-vs-word.md).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+OLE2_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+
+
+def _g(fn: Callable[[], Any], default: Any = None) -> Any:
+    try:
+        return fn()
+    except Exception:
+        return default
+
+
+def _short_exc(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {str(exc)[:200]}"
+
+
+def _looks_encrypted(exc: BaseException) -> bool:
+    text = str(exc).lower()
+    return "password" in text or "密码" in text
+
+
+def _looks_like_arg_mismatch(exc: BaseException) -> bool:
+    return isinstance(exc, TypeError) or "paramet" in str(exc).lower()
+
+
+def file_claims_encrypted(path: str) -> bool | None:
+    """Header sniff: can this file really be COM-password-encrypted?
+
+    True  → OLE2 with the FIB fEncrypted bit set: genuinely a password .doc.
+    False → container rules it out (plain zip can't be COM-encrypted): a
+            "password" error on it means the file is CORRUPT, not encrypted.
+    None  → OLE2 without the bit — could be a normal .doc or an encrypted
+            OOXML wrapper; treat encryption reports as genuine (safe default).
+    """
+    from pathlib import Path
+
+    try:
+        with open(Path(path), "rb") as f:
+            head = f.read(16)
+    except OSError:
+        return None
+    if head[:8] != OLE2_MAGIC:
+        return False
+    try:
+        flags = int.from_bytes(head[0x0A:0x0C], "little")
+        return bool(flags & 0x0001)
+    except Exception:
+        return None

docuhand/engine/container_guard.py

@@ -0,0 +1,166 @@
+"""Pre-COM container validation — the deterministic corrupt-file gate.
+
+Why this exists (found the hard way, 2026-09-11): handing a structurally
+broken file to Word/WPS via COM can pop a MODAL "file is corrupt" dialog.
+DisplayAlerts=0 does not suppress it; FileValidation=1 (the documented
+"skip validation" switch) made it WORSE on WPS: 88s hang vs 3s clean error
+without it. The only airtight fix is to never hand a broken container to
+the engine: validate the container structure in pure Python first and
+reject trash with a structured OPEN_FAILED before any COM call. A modal
+dialog cannot appear for a file the engine never sees.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+
+import olefile
+
+# Container magic bytes — defined here (not imported from office_app) to
+# keep the dependency direction one-way: office_app → container_guard.
+OLE2_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+ZIP_MAGIC = b"PK\x03\x04"
+
+# A valid legacy .doc MUST carry a WordDocument stream (or the 6.x-era
+# WordDocument alias); the WPS writer may additionally expose bindings,
+# but this stream is the constant across Word 97-2019 and WPS.
+_WORD_STREAMS = ("worddocument", "1table", "0table")
+
+
+def validate_container(path: str) -> tuple[bool, str]:
+    """Return (ok, reason). ok=True → safe to hand to the COM engine.
+
+    Extension-agnostic: the container decides, not the filename.
+    Files that are NOT office containers at all (rtf/txt/html disguised as
+    .doc) pass through: the engines open those natively without dialogs.
+    """
+    p = Path(path)
+    try:
+        with open(p, "rb") as f:
+            head = f.read(8)
+    except OSError as exc:
+        return False, f"unreadable: {exc}"
+
+    if head[:4] == ZIP_MAGIC:
+        # OOXML family: a real .docx is a structurally valid zip with
+        # [Content_Types].xml. Anything else is corrupt — and Word/WPS may
+        # react to it with the modal we must avoid.
+        try:
+            size = p.stat().st_size
+        except OSError as exc:
+            return False, f"unreadable: {exc}"
+        if size < 60:  # a zip EOCD alone is 22B; no real .docx is this small
+            return False, "zip container truncated"
+        try:
+            with zipfile.ZipFile(p) as z:
+                bad = z.testzip()
+                if bad is not None:
+                    return False, f"corrupt zip member: {bad}"
+                names = set(z.namelist())
+                if "[Content_Types].xml".lower() not in {n.lower() for n in names}:
+                    return False, "zip lacks [Content_Types].xml (not an OOXML document)"
+        except NotImplementedError:
+            # exotic compression method — unusual but a real, openable docx
+            return True, ""
+        except zipfile.BadZipFile as exc:
+            return False, f"not a valid zip container: {exc}"
+        except OSError as exc:
+            return False, f"unreadable: {exc}"
+        return True, ""
+
+    if head[:8] == OLE2_MAGIC:
+        # Legacy .doc family: must be a parseable compound file carrying a
+        # WordDocument stream. 8 bytes of OLE magic + garbage otherwise.
+        try:
+            size = p.stat().st_size
+        except OSError as exc:
+            return False, f"unreadable: {exc}"
+        if size < 512:  # OLE header alone is 512B; no real .doc is smaller
+            return False, "OLE2 container truncated"
+        try:
+            if not olefile.isOleFile(p):
+                return False, "OLE2 header present but compound file is malformed"
+            with olefile.OleFileIO(p) as ole:
+                # listdir() entries are [storage, ..., stream] path tuples
+                streams = {
+                    entry[-1].lower()
+                    for entry in ole.listdir()
+                    if entry and isinstance(entry[-1], str)
+                }
+                if not ({"worddocument"} & streams):
+                    # Not a Word doc — could be Excel .xls binary or legacy
+                    # WPS .wps. The engines still open those natively without
+                    # modals, so pass them through rather than mislabel.
+                    return True, ""
+                # sanity: WordDocument stream must be readable/non-empty
+                data = ole.openstream("WordDocument").read(64)
+                if not data:
+                    return False, "WordDocument stream is empty"
+        except OSError as exc:
+            return False, f"malformed OLE2 compound file: {exc}"
+        except Exception as exc:  # defensive: olefile raises varied parse errors
+            return False, f"OLE2 parse error: {exc}"
+        return True, ""
+
+    # RTF / plain text / HTML / unknown disguised as .doc: the engines
+    # convert these through their native converters, no modals observed.
+    # (Verified: Word opens truncated-OLE2 as text-repair silently, and
+    # plain garbage as an encoded-text recovery — neither prompts.)
+    return True, ""
+
+
+# --- encryption pre-flight ---------------------------------------------------
+
+_ENCRYPTED_OOXML_STREAMS = ("encryptedpackage", "encryptedsummaryinformation")
+
+
+def _fib_is_encrypted(stream_head: bytes) -> bool:
+    """FIB check on the first bytes of a WordDocument stream.
+
+    FibBase layout: wIdent must be 0xA5EC (little-endian ``EC A5``); the
+    flags word lives at stream offset 0x0A and **fEncrypted = 0x0100**.
+    (Gotcha recorded in docs/pitfalls.md #9: the FIB is at the start of
+    the WordDocument *stream* — file offset 0x0A is the CFB header's
+    CLSID, and the bit is 0x0100, not 0x0001.)
+    """
+    if len(stream_head) < 12 or stream_head[0:2] != b"\xec\xa5":
+        return False
+    flags = int.from_bytes(stream_head[0x0A:0x0C], "little")
+    return bool(flags & 0x0100)
+
+
+def detect_encryption(path: str) -> bool:
+    """True → the document will demand a password from any engine.
+
+    Two container-level tells, both deterministic and COM-free:
+    - OOXML-style encryption: an OLE2 CFB carrying an ``EncryptedPackage``
+      stream (Word's "Encrypt with password" on a .docx produces exactly
+      this — the file stops being a zip).
+    - Legacy .doc: the FIB inside the WordDocument stream has fEncrypted
+      set (see :func:`_fib_is_encrypted`).
+
+    Non-OLE2 containers (zip/rtf/text) cannot carry a COM password request
+    → False. Parse trouble → False: validate_container already rejects
+    structurally broken files before this runs.
+    """
+    p = Path(path)
+    try:
+        with open(p, "rb") as f:
+            head = f.read(8)
+    except OSError:
+        return False
+    if head[:8] != OLE2_MAGIC:
+        return False
+    try:
+        if not olefile.isOleFile(p):
+            return False
+        with olefile.OleFileIO(p) as ole:
+            names = {entry[-1].lower() for entry in ole.listdir() if entry}
+            if names.intersection(_ENCRYPTED_OOXML_STREAMS):
+                return True
+            if "worddocument" not in names:
+                return False
+            return _fib_is_encrypted(ole.openstream("WordDocument").read(16))
+    except Exception:
+        return False

docuhand/engine/convert_plan.py

@@ -0,0 +1,43 @@
+"""Pure planning for convert_documents — zero COM, fully unit-testable.
+
+Kept out of the tool layer so CI can verify the naming/classification rules
+without an Office installation. The engine only sees finished (source,
+target, wd_format) triples.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# SaveFormat constants — locale-independent numbers (docs/pitfalls.md #1):
+# wdFormatDocument = 0 (legacy .doc), wdFormatXMLDocument = 16 (.docx).
+TO_FORMATS: dict[str, int] = {"doc": 0, "docx": 16}
+SOURCE_EXTENSIONS = {".doc", ".docx"}
+
+
+def normalize_to_format(to_format: str) -> str:
+    """Accept 'docx', '.DOCX', ' doc ' → canonical key of TO_FORMATS."""
+    fmt = (to_format or "").strip().lower().lstrip(".")
+    if fmt not in TO_FORMATS:
+        raise ValueError(f"Unsupported to_format: {to_format!r} (use 'docx' or 'doc')")
+    return fmt
+
+
+def resolve_target(source: Path, to_format: str, output_dir: Path | None = None) -> Path:
+    """Same stem, new extension; relocated when output_dir is given.
+
+    Never returns the source path itself: the extension always differs, so
+    an in-place conversion can never clobber its own source.
+    """
+    target = source.with_suffix("." + to_format)
+    if output_dir is not None:
+        target = Path(output_dir) / target.name
+    return target
+
+
+def classify_source(extension: str, to_format: str) -> str:
+    """One of 'convert' | 'already_target' | 'unsupported_source'."""
+    ext = (extension or "").lower()
+    if ext not in SOURCE_EXTENSIONS:
+        return "unsupported_source"
+    return "already_target" if ext == "." + to_format else "convert"

docuhand/engine/edit_plan.py

@@ -0,0 +1,71 @@
+"""Pure planning for edit_open_document — operation validation, zero COM.
+
+An edit batch is a list of small operations executed in order against one
+open document. Everything is validated BEFORE any COM call happens so a
+bad batch never reaches the engine mid-way.
+
+Operations (v0.1):
+- replace_all   {find, replace}          literal find→set two-step (pitfall #14)
+- insert_text   {text, where}            where: start|end
+- save          {}                       explicit save checkpoint
+v0.2 reserved: set_bookmark, apply_style, delete_range.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+MAX_OPS = 50
+MAX_FIND_LEN = 500
+MAX_TEXT_LEN = 100_000
+
+KNOWN_OPS = {"replace_all", "insert_text", "save"}
+
+
+def validate_operations(operations: Any) -> list[dict[str, Any]]:
+    """Validate the op batch up-front; raises ValueError on any problem."""
+    if not isinstance(operations, list) or not operations:
+        raise ValueError("operations must be a non-empty list of edit operations")
+    if len(operations) > MAX_OPS:
+        raise ValueError(f"at most {MAX_OPS} operations per call (got {len(operations)})")
+    clean: list[dict[str, Any]] = []
+    for i, op in enumerate(operations):
+        if not isinstance(op, dict):
+            raise ValueError(f"operations[{i}] must be an object")
+        kind = op.get("op")
+        if kind not in KNOWN_OPS:
+            raise ValueError(
+                f"operations[{i}].op must be one of {sorted(KNOWN_OPS)} (got {kind!r})"
+            )
+        if kind == "replace_all":
+            find = op.get("find")
+            replace = op.get("replace", "")
+            if not isinstance(find, str) or not find:
+                raise ValueError(f"operations[{i}].find must be a non-empty string")
+            if len(find) > MAX_FIND_LEN:
+                raise ValueError(f"operations[{i}].find exceeds {MAX_FIND_LEN} chars")
+            if not isinstance(replace, str):
+                raise ValueError(f"operations[{i}].replace must be a string")
+            if len(replace) > MAX_TEXT_LEN:
+                raise ValueError(f"operations[{i}].replace exceeds {MAX_TEXT_LEN} chars")
+            clean.append({"op": "replace_all", "find": find, "replace": replace})
+        elif kind == "insert_text":
+            text = op.get("text")
+            where = op.get("where", "end")
+            if not isinstance(text, str) or not text:
+                raise ValueError(f"operations[{i}].text must be a non-empty string")
+            if len(text) > MAX_TEXT_LEN:
+                raise ValueError(f"operations[{i}].text exceeds {MAX_TEXT_LEN} chars")
+            if where not in ("start", "end"):
+                raise ValueError(f"operations[{i}].where must be 'start' or 'end'")
+            clean.append({"op": "insert_text", "text": text, "where": where})
+        else:  # save
+            clean.append({"op": "save"})
+    return clean
+
+
+def summarize_ops(operations: list[dict[str, Any]]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for op in operations:
+        counts[op["op"]] = counts.get(op["op"], 0) + 1
+    return counts

docuhand/engine/extraction.py

@@ -0,0 +1,175 @@
+"""Content extraction: text / tables / outline from legacy .doc via COM.
+
+Tables come out as row-major string matrices with merged-cell repeats
+(Horizontal/VerticalMerge cells repeat their origin text, which keeps the
+grid rectangular — documented, lossless for data, and simple for JSON).
+Runs on the STA worker with the same failover contract.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from ..errors import (
+    EngineUnavailableError,
+    FileNotFoundError,
+    OpenFailedError,
+    PasswordProtectedError,
+)
+from .com_utils import _g, _short_exc
+from .container_guard import detect_encryption, validate_container
+from .wd_constants import WD_DO_NOT_SAVE_CHANGES
+
+
+def _clean_cell(text: str | None) -> str:
+    """Cell text arrives with trailing \\r\\a markers — strip control noise."""
+    if not text:
+        return ""
+    return text.replace("\x07", "").replace("\r", " ").replace("\n", " ").strip()
+
+
+def _extract_tables(doc: Any, max_tables: int = 100) -> list[dict[str, Any]]:
+    tables: list[dict[str, Any]] = []
+    try:
+        count = int(_g(lambda: doc.Tables.Count, 0) or 0)
+    except Exception:
+        count = 0
+    for ti in range(min(count, max_tables)):
+        table = _g(lambda ti=ti: doc.Tables.Item(ti + 1))
+        if table is None:
+            continue
+        rows_n = int(_g(lambda table=table: table.Rows.Count, 0) or 0)
+        cols_n = int(_g(lambda table=table: table.Columns.Count, 0) or 0)
+        grid: list[list[str]] = []
+        # Cell-by-cell read: row-major, tolerant of vertical merges (which
+        # break row.Range.Cells iteration ordering on some engines).
+        for r in range(1, rows_n + 1):
+            row_cells: list[str] = []
+            for c in range(1, cols_n + 1):
+                # Cell.Range.Text — the portable path. Pitfall #15: on
+                # WPS-as-Word 12 Cell.Text itself does not exist (AttributeError)
+                # and Range indirection is required; the marker strip below
+                # cleans the \r\x07 cell terminator that comes with it.
+                cell_text = _g(lambda table=table, r=r, c=c: table.Cell(r, c).Range.Text, "")
+                row_cells.append(_clean_cell(cell_text))
+            grid.append(row_cells)
+        tables.append(
+            {
+                "index": ti + 1,
+                "rows": rows_n,
+                "columns": cols_n,
+                "data": grid,
+            }
+        )
+    return tables
+
+
+def _extract_outline(doc: Any, max_items: int = 200) -> list[dict[str, Any]]:
+    """Headings via paragraph outline levels (locale-independent numbers)."""
+    items: list[dict[str, Any]] = []
+    try:
+        paras = doc.Paragraphs
+        total = int(_g(lambda: paras.Count, 0) or 0)
+    except Exception:
+        total = 0
+    for i in range(min(total, 2000)):  # hard scan cap
+        para = _g(lambda i=i: paras.Item(i + 1))
+        if para is None:
+            continue
+        level = _g(lambda para=para: para.OutlineLevel, 10)
+        if not isinstance(level, int) or level < 1 or level > 9:
+            continue  # body text is level 10
+        text = _g(lambda para=para: para.Range.Text, "")
+        text = (text or "").replace("\r", "").replace("\x07", "").strip()
+        if not text:
+            continue
+        items.append({"level": level, "text": text[:200]})
+        if len(items) >= max_items:
+            break
+    return items
+
+
+def extract_content_from_doc(doc: Any, what: str) -> dict[str, Any]:
+    """Run the extraction selectors on an already-open document."""
+    payload: dict[str, Any] = {"what": what}
+    if what in ("text", "all"):
+        text = _g(lambda: doc.Content.Text, "") or ""
+        payload["text"] = text
+        payload["text_chars"] = len(text)
+    if what in ("tables", "all"):
+        tables = _extract_tables(doc)
+        payload["tables"] = tables
+        payload["tables_count"] = len(tables)
+    if what in ("outline", "all"):
+        items = _extract_outline(doc)
+        payload["outline"] = items
+        payload["outline_count"] = len(items)
+    return payload
+
+
+def extract_content(
+    engine: Any,
+    worker: Any,
+    path: str,
+    what: str,
+) -> dict[str, Any]:
+    """Full tool flow with failover: probe order, open RO, extract, close.
+
+    ``engine``/``worker`` come from the caller (tools layer) so this module
+    stays import-cycle-free and testable with fakes.
+    """
+    t0 = time.perf_counter()
+    src = Path(path).expanduser().resolve()
+    if not src.exists():
+        raise FileNotFoundError(str(src))
+    ok, reason = validate_container(str(src))
+    if not ok:
+        raise OpenFailedError(str(src), "container pre-check", f"structurally invalid container: {reason}")
+    if detect_encryption(str(src)):
+        raise PasswordProtectedError(str(src), "container pre-check")
+
+    order = engine._engine_order()
+    attempts: list[dict[str, str]] = []
+    launch_failures = 0
+
+    for engine_name, progid in order:
+        try:
+            app = engine._ensure_app(progid, engine_name)
+        except Exception as exc:
+            launch_failures += 1
+            attempts.append({"engine": engine_name, "stage": "launch", "error": _short_exc(exc)})
+            engine._discard_app()
+            continue
+        try:
+            doc = engine._open_read_only(app, str(src))
+            try:
+                payload = extract_content_from_doc(doc, what)
+            finally:
+                try:
+                    doc.Close(WD_DO_NOT_SAVE_CHANGES)
+                except Exception:
+                    pass
+        except PasswordProtectedError:
+            raise
+        except Exception as exc:
+            attempts.append({"engine": engine_name, "stage": "extract", "error": _short_exc(exc)})
+            engine._discard_app()
+            continue
+
+        payload.update(
+            {
+                "ok": True,
+                "tool": "extract_content",
+                "path": str(src),
+                "engine": engine_name,
+                "engine_version": engine._engine_version,
+                "duration_ms": round((time.perf_counter() - t0) * 1000),
+            }
+        )
+        return payload
+
+    if launch_failures == len(order):
+        raise EngineUnavailableError(attempts)
+    raise OpenFailedError(str(src), "word→wps failover exhausted", "; ".join(a["error"] for a in attempts))