athena-python-docx 0.15.2__tar.gz → 0.15.4__tar.gz

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/CLAUDE.md

@@ -338,6 +338,13 @@ Issue numbers reference `python-openxml/python-docx`.
   `"endnotes"` / `"comments"` / `"all"`. Routes through
   `FindReplace`.
 
+- **`Document.find_text(pattern, *, regex=False, match_case=False,
+  whole_word=False, in_=None, max_results=20, context_chars=80)
+  -> dict`** — fast bounded text search for large-doc inspection.
+  Returns `{count, matches, truncated}` with context snippets instead
+  of exporting the whole `.docx` or walking every paragraph/run through
+  live SDK reads. Routes through `FindText`.
+
 - **`Document.iter_runs(*, in_=None, limit=None, offset=None)
   -> list[dict]`** — server-side run enumeration for large-doc
   inspection. Use this when an agent needs to sample or inspect runs

athena_python_docx-0.15.4/DOCX_EXEC_LAB.md

@@ -0,0 +1,189 @@
+# DocX Execution Lab
+
+`scripts/docx_exec_lab.py` is a headless runner for quickly testing
+`athena-python-docx` snippets against Athena SuperDocument assets. It
+shortens the debug loop by running local SDK code directly against a
+chosen DOCX Studio API, capturing stdout/stderr/errors/timings, and
+optionally exporting the result to `.docx` for assertions.
+
+Use this before waiting on a full Agent -> Daytona -> preview cycle when
+debugging SDK behavior such as large-document replacement, table fills,
+unsupported OOXML internals, or export fidelity.
+
+## Inputs
+
+The runner accepts code from `--code-file` or stdin. It injects:
+
+- `ATHENA_DOCX_ASSET_ID` - the asset id passed with `--asset-id`
+- `ATHENA_DOCX_BASE_URL` and `DOCX_STUDIO_BASE_URL` - when `--base-url` is set
+- `DOCX_EXEC_LAB_OUTPUT_DIR` - output folder for the run
+- `DOCX_EXEC_LAB_EXPORT_PATH` - export target when `--export-docx` is set
+
+Authentication is read from the normal SDK environment, usually:
+
+```bash
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+```
+
+Do not commit API keys. Use shell env vars or your local secret manager.
+
+## Run Against A PR Preview
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+
+uv run python scripts/docx_exec_lab.py \
+  --base-url "https://docx-studio-pr21665-preview.previews.athenaintel.com" \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/find_replace_literal.py \
+  --timeout 30 \
+  --output-dir /tmp/docx-lab-find-replace \
+  --export-docx \
+  --assert-stdout-contains "Replacements made:" \
+  --assert-docx-text-contains "[Purchaser]"
+```
+
+The script writes structured JSON to `<output-dir>/result.json` and
+prints the same JSON to stdout. The JSON includes success flags,
+duration, stdout, stderr, exit code, error text, code path, asset id, and
+artifact paths.
+
+## Run Against Staging
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-staging-api-key>"
+export ATHENA_DOCX_BASE_URL="https://docx-studio.stg.athenaintel.com"
+
+uv run python scripts/docx_exec_lab.py \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/fast_table_fill.py \
+  --timeout 30 \
+  --output-dir /tmp/docx-lab-table-fill \
+  --export-docx \
+  --assert-stdout-contains "Filled 4 table rows" \
+  --assert-docx-text-contains "LOW (NYSE)"
+```
+
+## Run Against Local DOCX Studio
+
+Start DOCX Studio locally, then point the runner at that base URL:
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<local-or-dev-api-key>"
+
+uv run python scripts/docx_exec_lab.py \
+  --base-url "http://localhost:3001" \
+  --asset-id "asset_..." \
+  --code-file scripts/docx_exec_lab_examples/find_replace_literal.py \
+  --output-dir /tmp/docx-lab-local \
+  --export-docx
+```
+
+## Local UI With SuperDoc Embed
+
+The lab also includes a local-only HTML UI that wraps the same headless
+runner and iframes Olympus's existing SuperDoc embed route.
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_API_KEY="<your-staging-api-key>"
+
+uv run python scripts/docx_exec_lab_server.py --open
+```
+
+Defaults:
+
+- DOCX Studio API: `https://docx-studio.stg.athenaintel.com`
+- Agora embed-token API: `https://agora-staging.athenaintel.com`
+- Olympus iframe host: `https://staging-app.athenaintel.com`
+
+The UI accepts an `asset_id`, Python code, and optional assertions. The
+right pane can mint an editable embed token through staging Agora and
+iframe the returned `https://staging-app.athenaintel.com/embed/{token}`
+URL, so changes render in the real Olympus/SuperDoc viewer.
+
+If the staging Agora URL differs, pass:
+
+```bash
+uv run python scripts/docx_exec_lab_server.py \
+  --agora-base-url "https://..." \
+  --olympus-base-url "https://staging-app.athenaintel.com" \
+  --docx-base-url "https://docx-studio.stg.athenaintel.com"
+```
+
+The page also has an API key field. Values entered there are sent only
+to the local server for that request and are not written to `result.json`.
+
+## Use Stdin For One-Off Repros
+
+```bash
+cd docx-studio/python-sdk
+
+printf '%s\n' \
+  'import os' \
+  'from docx import Document' \
+  'doc = Document(os.environ["ATHENA_DOCX_ASSET_ID"])' \
+  'print(doc.asset_id)' \
+  | uv run python scripts/docx_exec_lab.py \
+      --asset-id "asset_..." \
+      --base-url "https://docx-studio-pr21665-preview.previews.athenaintel.com" \
+      --assert-stdout-contains "asset_"
+```
+
+## Export Assertions
+
+When `--export-docx` is set, the snippet must leave an open global
+variable named `doc`. The lab calls:
+
+```python
+doc.export_docx("<output-dir>/exported.docx")
+```
+
+Then `--assert-docx-text-contains` extracts text from the exported Word
+XML and checks for expected content. This catches "the command returned
+success but the document did not change" failures.
+
+If a snippet needs custom export behavior, pass `--export-path` without
+`--export-docx` and write `os.environ["DOCX_EXEC_LAB_EXPORT_PATH"]`
+inside the snippet. The lab records that file if it exists.
+
+## Table Fill Guidance
+
+Use the fast cell text path for bulk table values:
+
+```python
+table = doc.add_table(rows=len(rows), cols=2, style="Table Grid")
+for row_index, (label, value) in enumerate(rows):
+    table.cell(row_index, 0).text = label
+    table.cell(row_index, 1).text = value
+doc.save()
+```
+
+Avoid reading `cell.paragraphs[0].runs[0]` inside the fill loop. That
+interleaves writes with remote reads, flushes pending operations, and is
+much slower on real assets.
+
+## Opt-In Real Asset Smoke
+
+The unit tests do not require network access. A real export smoke is
+available but skipped unless explicitly enabled:
+
+```bash
+cd docx-studio/python-sdk
+
+export ATHENA_DOCX_LAB_RUN_INTEGRATION=1
+export ATHENA_DOCX_LAB_ASSET_ID="asset_..."
+export ATHENA_DOCX_API_KEY="<your-api-key>"
+export ATHENA_DOCX_BASE_URL="https://docx-studio-pr21665-preview.previews.athenaintel.com"
+
+uv run pytest tests/test_docx_exec_lab.py -m integration -q
+```
+
+Use disposable or test assets for mutation snippets.

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.15.2
+Version: 0.15.4
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>
@@ -67,6 +67,15 @@ uv pip install -e ".[dev]"
 uv run pytest tests/ -x
 ```
 
+## DocX Execution Lab
+
+For fast local repros against real Athena document assets, use the
+headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
+Python snippet with this checkout of `athena-python-docx`, captures
+stdout/stderr/errors/timings, and can export the resulting `.docx` for
+text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
+an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+
 ## Environment variables
 
 Required when connecting to Keryx (set by Athena backend when executing in Daytona):

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/README.md

@@ -40,6 +40,15 @@ uv pip install -e ".[dev]"
 uv run pytest tests/ -x
 ```
 
+## DocX Execution Lab
+
+For fast local repros against real Athena document assets, use the
+headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
+Python snippet with this checkout of `athena-python-docx`, captures
+stdout/stderr/errors/timings, and can export the resulting `.docx` for
+text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
+an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+
 ## Environment variables
 
 Required when connecting to Keryx (set by Athena backend when executing in Daytona):

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/docx/__init__.py

@@ -6,11 +6,11 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.15.2"
+__version__ = "0.15.4"
 
-from docx._execution import begin_execution
 from docx.api import Document
 from docx._buffer import flush_all
+
 # Re-exports python-docx ships at docx top-level for convenience.
 from docx.shared import Emu, Inches, Pt, Cm, Mm, Twips, Length, RGBColor
 
@@ -24,7 +24,6 @@ __all__ = [
     "Twips",
     "Length",
     "RGBColor",
-    "begin_execution",
     "flush_all",
     "__version__",
 ]

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/docx/_batching.py

@@ -11,17 +11,11 @@ import concurrent.futures
 import threading
 from typing import Any, Coroutine, TypeVar
 
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
 from docx.errors import OperationTimeoutError
 
 T = TypeVar("T")
 
-# Default per-op timeout. Individual Superdoc SDK calls should complete well
-# under this — the value is a safety net so a WebSocket stall, Keryx downtime,
-# or pathological large-document remote-read loop surfaces an actionable SDK
-# error instead of wedging the calling thread until the outer Daytona
-# INSTRUCTION_TIMEOUT_SECONDS kill.
-DEFAULT_OP_TIMEOUT_SECONDS: float = 60.0
-
 _loop: asyncio.AbstractEventLoop | None = None
 _thread: threading.Thread | None = None
 _lock = threading.Lock()

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/docx/_buffer.py

@@ -21,9 +21,9 @@ best-effort coalesce — if the loop thread races us we just flush twice
 (or zero times; the next loop-thread call drains it).
 
 `flush_all` is a process-wide hook used by the Daytona sandbox prelude to
-make sure pending writes hit Keryx before the sandbox is suspended. It walks
-a weak-ref registry so dead Workbook instances don't keep their buffers
-alive.
+make sure pending writes hit Keryx and server-side edit sessions are
+checkpointed before the sandbox is suspended. It walks a weak-ref registry
+so dead Document instances don't keep their buffers alive.
 """
 
 from __future__ import annotations
@@ -39,6 +39,7 @@ from docx._execution import (
     current_execution_id,
     is_stale_execution,
 )
+from docx._timeouts import timeout_for_commands
 from docx.commands import Command, is_response_bearing, must_flush_immediately
 from docx.errors import DocxError, FlushAllError
 
@@ -113,6 +114,7 @@ def _extract_partial_results(exc: BaseException) -> list[Any]:
                 out.append(result)
     return out
 
+
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
 
@@ -178,11 +180,12 @@ def _unregister(buffer: "CommandBuffer") -> None:
 
 
 def flush_all(*, strict: bool = False) -> None:
-    """Flush every live CommandBuffer in this process.
+    """Flush and checkpoint every live CommandBuffer in this process.
 
     Used by the Daytona sandbox prelude after user code returns, so
-    buffered mutations make it to Keryx before the sandbox is suspended.
-    Safe to call when no Buffers exist (no-op).
+    buffered mutations make it to Keryx and server-side edit sessions are
+    durably released before the sandbox is suspended. Safe to call when no
+    Buffers exist (no-op).
 
     By default, failures are logged and swallowed for backwards
     compatibility with existing local scripts. The executor calls
@@ -214,27 +217,48 @@ def flush_all(*, strict: bool = False) -> None:
                     sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
             continue
         try:
-            buf.flush()
+            buf.commit()
         except Exception as e:  # noqa: BLE001
-            msg = f"buffer {buf.asset_id} flush failed: {e}"
+            msg = f"buffer {buf.asset_id} flush/commit failed: {e}"
             if strict:
                 failures.append(msg)
             else:
                 sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
 
     if failures:
-        raise FlushAllError(failures)
+        raise FlushAllError(failures=failures)
 
 
 # ---------------------------------------------------------------------------
 # CommandBuffer
 # ---------------------------------------------------------------------------
 
-# Idle window before a pure-mutation buffer auto-flushes. Short by design —
-# the SDK's main consumer is agent code that fires sequential property
-# setters within milliseconds of each other; we just need to coalesce those
-# without holding writes back from Keryx for human-perceptible time.
-DEFAULT_AUTO_FLUSH_SECONDS: float = 0.1
+
+def _default_auto_flush_seconds() -> float:
+    """Return the transparent-batching idle window.
+
+    A very small window streams single edits quickly, but it can also flush
+    generated table-population loops halfway through the loop. That is painful
+    on large legal documents because each partial table batch can take longer
+    than the normal client timeout. Keep the default human-fast while giving
+    agent code enough room to coalesce common loops; allow local override for
+    debugging.
+    """
+    import os
+
+    raw = os.environ.get("ATHENA_DOCX_AUTO_FLUSH_SECONDS")
+    if raw is None:
+        return 1.0
+    try:
+        return max(float(raw), 0.0)
+    except ValueError:
+        return 1.0
+
+
+# Idle window before a pure-mutation buffer auto-flushes. Agent-generated
+# loops commonly perform dozens of property setters; a 1s window still feels
+# live while avoiding mid-loop table flushes on large documents.
+DEFAULT_AUTO_FLUSH_SECONDS: float = _default_auto_flush_seconds()
 
 
 class CommandBuffer:
@@ -305,6 +329,12 @@ class CommandBuffer:
         with self._lock:
             return len(self._pending)
 
+    @property
+    def pending_timeout_seconds(self) -> float:
+        with self._lock:
+            pending = list(self._pending)
+        return timeout_for_commands(commands=pending)
+
     @property
     def is_stale_for_current_execution(self) -> bool:
         return is_stale_execution(self._execution_id)
@@ -470,18 +500,35 @@ class CommandBuffer:
         _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
 
+    def commit(self) -> None:
+        """Flush pending commands and release the server-side edit session.
+
+        The HTTP command response tells us docx-studio applied the batch to its
+        pooled SuperDoc handle. Releasing the handle closes the collaboration
+        session without discard on the server, which is the durability
+        checkpoint for asset-backed document edits.
+        """
+        self._assert_current_execution()
+        self.flush()
+        release_asset = getattr(self._client, "release_asset", None)
+        if callable(release_asset):
+            release_asset(self._asset_id)
+
     def close(self) -> None:
         """Flush and disable. Idempotent."""
         if self._closed:
             return
         try:
             if self.is_stale_for_current_execution:
+                pending: list[Command]
                 with self._lock:
                     self._cancel_timer_locked()
+                    pending = self._pending
                     self._pending = []
                     self._proxy_id_refs = {}
+                _ptc_emit_end_batch(pending, is_error=True)
             else:
-                self.flush()
+                self.commit()
         finally:
             self._closed = True
             _unregister(self)
@@ -553,6 +600,8 @@ class CommandBuffer:
             self._timer = None
 
     def _auto_flush(self) -> None:
+        if self.is_stale_for_current_execution:
+            return
         try:
             self.flush()
         except Exception as e:  # noqa: BLE001

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/docx/_http_doc.py

@@ -38,6 +38,7 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from docx._buffer import CommandBuffer
+from docx._timeouts import timeout_for_commands
 from docx.commands import (
     BlocksList,
     BookmarksGet,
@@ -86,6 +87,7 @@ from docx.commands import (
     FieldsRefresh,
     Find,
     FindReplace,
+    FindText,
     FootnotesDelete,
     FootnotesGet,
     FootnotesList,
@@ -210,9 +212,7 @@ def _looks_like_block_not_found(err_obj: dict) -> bool:
         return False
     lower = msg.lower()
     if "not found" in lower:
-        return 'block "' in lower or (
-            'block ' in lower and ' was not found' in lower
-        )
+        return 'block "' in lower or ("block " in lower and " was not found" in lower)
     if "invalid_target" in lower or "invalid target" in lower:
         # "Expected paragraph:<id> but found tableCell:<id>" — the new
         # variant of the § 13 cell-inner-paragraph addressing gap.
@@ -323,7 +323,7 @@ _TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
 
 _TABLE_CLIENT_ID_HINT: str = (
     "\n\nHint: this looks like a stale client-side table UUID "
-    '(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution '
+    "(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution "
     "raised before the SDK could rewrite the Table proxy's id from the "
     "client UUID to the real SuperDoc id, OR the table belongs to a "
     "prior execution whose state has been discarded. Recover by calling "
@@ -521,8 +521,7 @@ def _http_post_json(
         if is_remote_disconnect:
             n_commands = (
                 len(body.get("commands", []))
-                if isinstance(body, dict)
-                and isinstance(body.get("commands"), list)
+                if isinstance(body, dict) and isinstance(body.get("commands"), list)
                 else 0
             )
             hint = (
@@ -608,13 +607,9 @@ def _http_post_json(
             if _looks_like_block_not_found(err_obj):
                 cmd_type = err_obj.get("type")
                 paragraph_targeting = (
-                    isinstance(cmd_type, str)
-                    and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
-                )
-                table_query = (
-                    isinstance(cmd_type, str)
-                    and cmd_type in _TABLE_QUERY_COMMANDS
+                    isinstance(cmd_type, str) and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
                 )
+                table_query = isinstance(cmd_type, str) and cmd_type in _TABLE_QUERY_COMMANDS
                 if paragraph_targeting:
                     hint = _CELL_PARAGRAPH_HINT
                 elif table_query:
@@ -704,6 +699,24 @@ class HttpClient:
         except Exception:  # noqa: BLE001
             pass
 
+    def release_asset(self, asset_id: str) -> None:
+        """Ask docx-studio to close its pooled SuperDoc session for ``asset_id``.
+
+        Command POSTs only prove that the server accepted and applied the
+        mutation batch to its live SuperDoc handle. The durable checkpoint for
+        collaborative sessions happens when that handle is closed without
+        discard, so ``Document.save()`` and the Daytona ``flush_all`` cleanup
+        call this endpoint after draining the command buffer.
+        """
+        url: str = f"{self._base_url}/docs/{asset_id}/session/release"
+        _http_post_json(
+            session=self._session,
+            url=url,
+            api_key=self._api_key,
+            body={},
+            timeout=30.0,
+        )
+
     def execute_batch(
         self,
         asset_id: str,
@@ -749,6 +762,7 @@ class HttpClient:
             url=url,
             api_key=self._api_key,
             body=body,
+            timeout=timeout_for_commands(commands=commands),
         )
         applied = resp.get("applied")
         # An empty applied list paired with an `error` field is the
@@ -881,7 +895,6 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "track_changes.list": TrackChangesList,
     "track_changes.get": TrackChangesGet,
     "track_changes.decide": TrackChangesDecide,
-
     # --- Athena-extension ops (v0.11.0) -----------------------------------
     # Mirror the dotted-path style of the upstream-parity routes above:
     # ``hyperlinks.create`` matches SuperDoc's ``doc.hyperlinks.create``.
@@ -928,6 +941,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "sdt.delete": ContentControlsDelete,
     "sections.set_columns": SetSectionColumns,
     "find_replace": FindReplace,
+    "find_text": FindText,
     "iter_runs": IterRuns,
     "export_pdf": ExportPDF,
     "numbering.get": NumberingGet,
@@ -968,6 +982,7 @@ _FIELD_RENAMES: dict[str, dict[str, str]] = {
     # path-proxy snake-case transform leaves `in` as a Python keyword
     # collision; rename to `in_` here so the dataclass accepts it.
     "find_replace": {"in": "in_"},
+    "find_text": {"in": "in_"},
     "iter_runs": {"in": "in_"},
     "numbering.list": {"in": "in_"},
 }
@@ -983,9 +998,7 @@ def _build_command(op: str, params: dict[str, Any]) -> Command:
         )
 
     # Convert param keys camelCase → snake_case to match dataclass fields.
-    snake_params: dict[str, Any] = {
-        _camel_to_snake(k): v for k, v in params.items()
-    }
+    snake_params: dict[str, Any] = {_camel_to_snake(k): v for k, v in params.items()}
 
     # Apply per-op renames (e.g. find: type → node_type).
     renames = _FIELD_RENAMES.get(op)

athena_python_docx-0.15.4/docx/_timeouts.py

@@ -0,0 +1,32 @@
+"""Timeout budgets for SDK operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_OP_TIMEOUT_SECONDS: float = 60.0
+
+# Large document-wide primitives can be intentionally expensive while still
+# being the safest path for agents. Keep the normal SDK budget tight, but give
+# these one-shot commands enough room to finish on dense legal documents.
+LONG_RUNNING_COMMAND_TIMEOUT_SECONDS: float = 300.0
+
+_LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
+    {
+        "FindReplace",
+        # Plain ``cell.text = value`` table fills are buffered as TableSetCell
+        # commands. On dense legal documents, SuperDoc can spend well over the
+        # ordinary 60s budget committing a table batch even when the Python code
+        # uses the fast no-read cell path.
+        "TableSetCell",
+    }
+)
+
+
+def timeout_for_commands(*, commands: list[Any]) -> float:
+    """Return the HTTP timeout budget for a batch of command objects."""
+    for command in commands:
+        command_type = getattr(command, "type", type(command).__name__)
+        if command_type in _LONG_RUNNING_COMMAND_TYPES:
+            return LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
+    return DEFAULT_OP_TIMEOUT_SECONDS

{athena_python_docx-0.15.2 → athena_python_docx-0.15.4}/docx/client.py

@@ -23,6 +23,7 @@ from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
 from docx._execution import assert_current_execution, current_execution_id
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
 from docx.errors import (
     AuthenticationError,
     DocumentClosedError,
@@ -99,6 +100,21 @@ class Session:
     def is_open(self) -> bool:
         return self._opened and not self._closed
 
+    @property
+    def pending_timeout_seconds(self) -> float:
+        handle = self._doc_handle
+        buffer = getattr(handle, "buffer", None) if handle is not None else None
+        timeout = (
+            getattr(buffer, "pending_timeout_seconds", DEFAULT_OP_TIMEOUT_SECONDS)
+            if buffer is not None
+            else DEFAULT_OP_TIMEOUT_SECONDS
+        )
+        if isinstance(timeout, bool):
+            return DEFAULT_OP_TIMEOUT_SECONDS
+        if isinstance(timeout, (int, float)):
+            return float(timeout)
+        return DEFAULT_OP_TIMEOUT_SECONDS
+
     async def open(self) -> None:
         """Construct the HTTP client + buffered doc handle.
 
@@ -215,8 +231,8 @@ class Session:
         handle = self._doc_handle
         buffer = getattr(handle, "buffer", None) if handle is not None else None
         if buffer is not None:
-            buffer.flush()
-        _log_info(f"Saved {self._asset_id} (buffer drained)")
+            buffer.commit()
+        _log_info(f"Saved {self._asset_id} (buffer drained and session released)")
 
     async def close(self) -> None:
         """Close the session. Idempotent."""