Getting WriterAgent ready for real users

[Augusto-Zolet]

Hi Keith. I have been using WriterAgent daily, driving it through the MCP server on real legal documents. I also ran live experiments in a sandbox branch to try solutions before proposing them. If we align on the items below, I would split the work into a few focused branches for review (my suggested split is at the end).

A heads up on why this is a lot at once. Starting this week we will have real users on WriterAgent and I will be onboarding them myself, so I have been pushing hard to get the system ready for real use now. That is why so many fixes, changes and new features land together. Most of them are things a first time user would hit in the first hour, so I would rather have them ready than trickle them out.

1. Bug fixes

Problems that exist on master today. Every proposed fix was tested live in the sandbox and worked.

#	Problem on master	Impact	Proposed fix
B1	search_in_document only scans top level paragraphs. Text inside table cells, text boxes, drawing shapes, page headers and footers, and comments comes back as "no matches"	The model tells the user the text does not exist when it does.	Use the native find API (body, table cells, text frames, headers and footers) plus sweeps for floating shapes and for comments. Each match reports where it lives (body, table X cell B2, shape name, header or footer with the page style, comment author)
B2	apply_document_content answers "old_content not found in document. Try a shorter, unique substring" when the text lives inside a floating drawing shape	Misleading. The model retries blindly and fails again	Detect the shape case. With review mode off, edit the shape text in place (formatting preserved). With review mode on, return a clear message routing to the shapes toolset, because shape text cannot carry tracked changes
B3	A failed rich HTML edit can modify the document while returning an error. The edit path deletes the target first and imports HTML after. With review recording off there is no rollback when the import throws	Status says error but the document changed (the original text was deleted). Silent corruption risk	Run the delete plus import inside one grouped undo context in all modes and roll back on failure. Error must mean "document untouched"
B4	set_image_properties says crop in its description but there is no crop parameter and no crop code	The model calls a capability that does not exist and gets nothing	Implement real crop via the GraphicCrop struct, in mm per edge. Edges you do not pass keep their current value. get_image_info reports the current crop
B5	get_document_tree and the nearby context reads silently SAVE the user's file. They create hidden navigation bookmarks and then call doc.store() whenever the document has a location	Merely asking for the outline of an open document persists every unsaved manual edit (and any pending tracked changes) to disk, without the user ever choosing to save	Drop the store call. The bookmarks live in the document model and are persisted whenever the user next saves normally. Verified live, reading the outline no longer touches the file on disk
B6	list_open_documents reports is_active false for every document, including the truly active one (an object identity compare between two distinct proxy wrappers that are never equal)	With several documents open a client has no way to tell which one a call without document_url will hit	Compare the stable runtime uid instead of object identity. Verified live
B7	search_in_document with an invalid regex returns ok with count 0, indistinguishable from "text not in the document" (the underlying search finds nothing silently)	The model concludes the text does not exist and gives the user a wrong answer	When regex is on and nothing matched, try compiling the pattern. If it does not parse, return a clear INVALID_REGEX error suggesting regex false for a literal search
B8	delete_comment with a wrong name or author returns ok with deleted 0	False success. The agent tells the user a comment was deleted when nothing happened	A miss is now an error that points to list_comments
B9	Running the test suites together fails several tests that pass when run alone, and every full run drops a MagicMock folder in the repo root. One test swaps in a fake uno module and then deletes it in teardown instead of restoring the shared one, so later tests that import uno break. A separate cleanup sweep points one directory too high and never removes the litter	This hides real signal. Failures that look like a stable baseline are actually one test sabotaging the ones after it, and the repo keeps collecting junk folders	Restore the previous module with patch.dict instead of deleting it, and route mocked config writes to a temp dir so nothing lands on disk. Fix the cleanup sweep to target the repo root. The full suite drops from 23 failures to 6, all remaining ones environment dependent
B10	apply_document_content and apply_style with target='selection' silently append at the END of the document when the selection cannot be resolved. The resolver caught any failure and moved the cursor to the document end, then reported ok	Over MCP a client that never set a selection gets its content dumped at the end of the document with no error. Silent misplacement	Resolve the explicit selection, fall back to the view cursor, and raise a clear error only when both are unavailable. Never append at the end
B11	track_changes_accept and track_changes_reject by index never work. They call getAnchor() on the redline, but redline objects from getRedlines() have no getAnchor at all (they expose RedlineStart and RedlineEnd instead), so every call dies in the fallback with "Failed to select tracked change"	Accepting or rejecting a specific change by index, the exact thing track_changes_list exists for, always fails	Select the range built from RedlineStart to RedlineEnd instead. Verified live end to end, accept keeps the inserted text and clears the redline, reject removes it. The guard that refuses to resolve the agent's own pending edits stays

Technical note on B1. doc.findAll crashes LibreOffice (SIGABRT inside the bulk range creation) whenever the search pattern matches text that lives inside a floating drawing shape. I isolated a minimal repro (a five paragraph document with one floating shape, findAll on the shape text aborts on the very first call, while body and text box matches are fine), so this looks like an upstream LibreOffice bug. The proposed search iterates findFirst plus findNext instead, same coverage, no crash.

2. Quality of life improvements

#	Proposal	Problem it solves	How
Q1	Reads flag pending tracked changes	get_document_content hides deletions and gives no sign that edits are waiting for review. The model can misread the text or treat pending edits as mistakes to fix	When redlines exist, add a tracked_changes list (insertion or deletion plus the text) and a short note saying they are pending the user decision and the agent must not resolve them. Additive, the content field is unchanged
Q2	Edit results carry the live review status	Guidance is delivered once at connect. If the user toggles review mode later, the model works with stale rules	Every successful edit result includes review_mode and pending_review plus a one line reminder. Tool results are the only channel that is fresh on every call
Q3	list_open_documents answers an empty list	With LibreOffice open and no document, the tool errors with NO_DOCUMENT_OPEN. A listing tool should be able to say "none open"	Let this tool run without a document and return an empty documents array
Q4	Friendly image positioning	hori_orient and vert_orient only accept raw UNO integers	Accept left, center, right, top, bottom (integers still work). Values resolved from the live UNO enum, never hardcoded
Q5	New MCP manual	See details below	See details below
Q6	Change the default port 8765	See details below	See details below
Q7	Edit results echo the edited passage	After an edit the model keeps working on the stale text it read before, and its only remedy is a full get_document_content round trip just to see how one passage ended up. The sidebar refreshes its injected document context automatically after each edit, an MCP client has no such channel	Every successful apply_document_content returns an edited_context field carrying the touched paragraph plus its neighbors as they now read (in record and wait that text includes the pending tracked change). A few lines per result, never the whole document. full_document rewrites return no echo by design
Q8	Insert before or after a match	The most common petition edit ("add a paragraph after clause 3.2") forced resending the whole clause as a replacement. In review mode that renders as a tracked delete plus reinsert of text nobody touched, so the user reviews a diff that strikes out untouched text	apply_document_content gains position (replace, before, after) for target search. Before and after INSERT next to the match and leave the matched text untouched, so the review record contains only the genuinely new text
Q9	Every result says which document it acted on	Without document_url each call targets whatever window the user has focused, and focus can change between two calls. Editing the wrong document reported plain ok with no clue	Every result of a call that reached a document now echoes document (name and uid), and the manual gains a multi document rule (always pass document_url when several documents are open)
Q10	Errors that teach the next step	Several dead ends confirmed live. A wrong document_url named an internal HTTP header the client never saw. A mistyped tool name returned INTERNAL_ERROR, which reads as a server crash. A wrong style name died in a raw UNO exception with no hint. Truncated reads gave no machine readable signal	Errors now point to the recovery path. Wrong document_url and no document open point to list_open_documents. Unknown tool gets its own code and points to the tool list. apply_style validates the name first and answers with a "did you mean" plus valid style names. Truncated reads carry truncated true
Q11	list_open_documents shows unsaved changes	A client cannot tell whether a document has edits waiting to be saved	Each entry gains a modified flag (doc.isModified). The agent uses it to remind the user to save, since it never saves itself
Q12	apply_document_content dry_run	Before a replace the model has no cheap way to see how many times old_content matches and where, and search uses a slightly different matcher	dry_run returns the match count and each match's location without editing, using the same resolver the edit uses
Q13	apply_style to every occurrence	apply_style only styled the first match, so styling a defined term everywhere was impossible, and a match inside a table cell failed	Add all_matches and occurrence, and build each match's cursor in its own text object so table cells work
Q14	track_changes_list shows text and location	Entries carried only type, author and date, but accept and reject take an index, so mapping a request onto a change was guesswork. The recording flag also misled, it reflects the document toggle, so it reads false while review mode is recording agent edits	Each entry now carries the change text and where it lives, and the result reports agent_review_mode alongside recording so the two flags cannot be confused
Q15	add_comment highlights the passage	The comment anchored to a zero width point, always the first match, always signed WriterAgent, and list_comments showed an empty anchor preview so the agent could not tell which passage a comment covers	It now spans the matched text so the user sees what it covers, with occurrence and author options, and list_comments reports the covered span (falling back to the enclosing paragraph for old point comments)
Q16	insert_page_break at a chosen place	It only broke at the user's cursor, which is arbitrary over MCP	Add before_text and after_text so a headless client places the break deterministically
Q17	regex and case in the edit path	old_content was always literal and case handling was an uncontrolled fallback, so search with options then replace did not line up with search_in_document	Add regex and case_sensitive to the search path via a direct match, opt in, the default matcher unchanged

Q5 in detail. The manual the external agent gets

On master the two agents are very unequal. The internal sidebar agent carries a rich behavior manual inside its system prompt (how to use the tools, confirm edits, and the rest), rebuilt every turn. An MCP client gets three sentences at connect (workflow, doc type filtering, a threading note) and nothing more, so an external model learns the tool behavior by trial and error, with no idea about the review modes, how to confirm an edit, navigating large documents, or concurrency. On top of that, even a longer connect message would not arrive, Claude Desktop stores the instructions text but does not read it and Claude Code truncates it (around 2 KB). So the external agent is the one flying blind, and that is what this proposal fixes.

The proposal keeps one canonical manual and delivers it in layers.

Layer	What	When it reaches the model
Lean instructions	The few invariants plus a pointer to the manual tool	Once at connect
Rich tool descriptions	Per tool usage rules	On every tools list
get_guidance(topic)	One manual section on demand (editing, editing html, review modes, search, navigation, images, concurrency)	Whenever the model asks
Just in time	Live review status inside every edit result (Q2)	On every edit

I tested this in the sandbox and the on demand flow works well (topic list, aliases, one section at a time).

One design point worth calling out.

I think the guidance should be built from reusable pieces with a single source of truth, and the base should be your original chat system prompt, not a new text. Your prompt is already partly organized as separate named pieces in the code. The proposal completes that organization. It keeps your text, updates it in place with the new behavior (the three review modes, search reach, text in shapes, a stale snapshot warning), and adds a few new pieces written in the same style. Each consumer then assembles the same pieces and adds only what belongs to its channel.

The sidebar assembly is hybrid, to keep the per turn cost down. Its ambient prompt keeps your original pieces plus the review modes piece, because that one is a safety rule the model must know before it acts (a weak model never asks first, so it must not depend on the model deciding to look something up). The reference pieces (search reach, navigation, images) stay out of the ambient prompt and the sidebar pulls them on demand through the same get_guidance tool the MCP uses. Net ambient growth stays around 2 KB instead of 3.3 KB. The MCP serves the same pieces one topic at a time through get_guidance and adds its own extras, for example the HTTP 429 concurrency rule, which the in process sidebar never needs. The Calc and Draw sidebar prompts embed the same app neutral piece (confirm edits by structured fields, re-read before targeted edits) that a Calc or Draw MCP session gets, so the single source covers every document type. Update a rule in one place and every consumer sees it, so the guidances can never drift apart.

I tested this arrangement in the sandbox. The MCP side was verified live against the running server, and the prompt assemblies are pinned by unit tests (I did not run a full sidebar chat session on the new prompt). Nothing of your prompt is thrown away or rewritten from scratch. It stays the base and gains the pieces it misses today (it currently does not explain the review modes, search reach, or text in shapes). Tests pin that every shared piece appears identically in its assemblies and that the reference pieces stay out of the ambient sidebar prompt, so a drift or a leak would fail the suite.

Q6 in detail. The default port

Fact	Detail
Real collision	On my machine a Claude Code session viewer took port 8765 and WriterAgent became unreachable until I figured it out
Anki Connect	Starts an HTTP server on port 8765 on localhost whenever Anki is running. Every Anki user collides with WriterAgent
claude explorer	A popular Claude Code history viewer, also defaults to 8765

Proposal. Pick a less common default (a high port with no popular tool sitting on it), keep it configurable, and add a short bind retry with a clear log line when the port is busy, so a collision never looks like a silently dead server.

3. New features

F1. get_image with page render (lazy image perception)

Aspect	Detail
Problem	The model has no way to actually look at the document. It cannot see one specific embedded image, and it cannot check what a page looks like (layout, letterhead, where things landed)
Proposal	One get_image tool with the two modes below. Vision tokens stay lazy, the model only pays when it decides to look
Sandbox result	Both modes work. For the page mode, a fully native render path works. Jump the view cursor to the page and use the writer png export filter. No external binary, no PDF step. It rendered a real 20 page petition faithfully (letterhead, columns, images, shapes), and out of range pages return a clear error with the real page count
Technical note	The XRenderable route reported 1 page for a 20 page document no matter which options I passed, and its bitmaps proved build dependent. The export filter route is the reliable one

The two modes.

Mode	How it is called	What comes back
One embedded image	get_image with the graphic name (or selection=true for the currently selected image)	That single picture, as a native MCP image block
Whole page	get_image with page=N	A PNG of the entire rendered page with everything on it (text, tables, images, shapes, letterhead)

F2. report_bug (agent callable feedback)

Aspect	Detail
Problem	When a tool misbehaves, the feedback dies inside the chat. Users rarely go file an issue by hand
Proposal	A report_bug tool the agent itself calls with summary, details and category (bug, ux, feature). Nothing gets published automatically

One honest point here. I want these reports to actually reach us instead of dying on the user machine, and I do not know the best way to do it. The ideal in my head is issues created automatically on the project GitHub. From what I read that would need a small relay you host (a token cannot ship inside the extension, anyone could extract and abuse it), so I want your take here. And the sidebar agent should be able to call this tool too, not only MCP clients.

F3. Plug and play connection (stdio bridge)

Aspect	Detail
Problem	The MCP server lives inside LibreOffice. A client configured with the HTTP URL connects once at startup. If LibreOffice is not running yet, the connection fails and the user has to restart the client. Real papercut with Claude Desktop and Claude Code. For non technical users this matters a lot, they cannot debug a dead connection, they just feel the product is broken and give up
Proposal	A small stdio bridge script (pure stdlib, no dependencies) that the client launches. It forwards every request to the HTTP server, answers the handshake locally while LibreOffice is down, returns an empty tool list instead of an error, and emits a tools list changed notification the moment LibreOffice comes up
Additive	Yes. The direct HTTP config keeps working exactly as today, the bridge is opt in
Sandbox result	Tested end to end, including a real client session. The client connected with LibreOffice closed, and the tools appeared by themselves after opening LibreOffice, no client restart

F4. undo and redo for the agent

Aspect	Detail
Problem	With review mode off (the default) a bad agent edit is unrecoverable by the agent. Its own error results encourage a retry, but there is no rollback, only the user's manual Ctrl+Z. Curiously the tools already exist in the code, deliberately unregistered
Proposal	Expose undo and redo (XUndoManager, all document types) with a strong caution in the description. The undo stack is shared with the user's own edits, so the model is told to undo only the steps it just caused and to tell the user what it undid
Sandbox result	Registered and tested live. A bad insert was undone cleanly and the result reports undone count plus can_undo and can_redo

F5. Table structure editing

Aspect	Detail
Problem	There was no way to edit a table's structure. Adding a row to a fee table meant rewriting the whole document, and cell text could only be reached by search and replace
Proposal	A tables specialized domain over the native table API. list_tables, get_table_cells (a row by row matrix), set_table_cell by A1 address, and insert or delete row and column. One honest limit in this first version, cell text edits are plain edits, not tracked changes, even when review mode is on (cell redlines are a separate, harder problem)
Sandbox result	Verified live on a real petition with nine tables. Read the matrix, set a cell and read it back, grew a table from two rows to three and back, and got a clear error for an out of range cell

F6. set_selection

Aspect	Detail
Problem	target='selection' was a trap for a headless client. Nothing could set a selection, so content landed wherever the user's cursor happened to be, and a failure appended at the document end (fixed as B10)
Proposal	A set_selection tool that selects a passage by search text (with occurrence) or by character range and highlights it for the user, so a following edit with target='selection' acts on it
Sandbox result	Selecting by text works and reports the selected text. One honest caveat, the selection is transient view state, so for a headless flow set_selection and the edit that uses it should be consecutive, and reading the selection back across separate calls is not reliable

Observations for later (no code, just findings)

Observation	Detail
Modal dialogs freeze the MCP	Tool calls run on the main thread. Any modal dialog (recovery prompt, repair question) blocks it, and the client just hangs with no answer. The server could detect this state and reply with a clear "LibreOffice is waiting for a user action on screen" error
Large replace all in review mode can hang	A replace all that matches many passages while review mode is recording tracked changes can be heavy enough that LibreOffice's watchdog aborts the process. The replace itself completes and returns, the abort comes after. Worth a soft cap or a warning when a single call would record dozens of tracked changes

Open question. A fully autonomous mode would need save, create and open

Today the agent never saves. That is on purpose. The user always owns persistence, and the new modified flag on list_open_documents lets the agent tell the user when a document has unsaved changes instead of saving it. Every workflow stays assisted. The agent prepares the work and the user reviews and saves.

I want to be explicit about what that choice costs, because it is the one thing standing between the current assisted mode and a fully unattended one. To batch process many documents with no human in the loop (open the next file, fill it from a template, save it, move to the next) the agent would need three abilities it does not have today. Saving the document (store and storeToURL for export). Creating a new document, optionally from a template. Opening an existing file for editing. Those three together are exactly what turns an assisted agent into an autonomous one, and none of them alone is enough.

I did not build them, because letting the agent write to disk on its own is a product decision more than a feature. My instinct is to keep the default assisted and put any autonomous ability behind an explicit opt in that is off by default, with opening files limited to paths the user named so a document can never instruct the agent to open something. But this is your call. Do you want WriterAgent to offer an autonomous mode at all, and if so how careful should the opt in be.

Closing and suggested branch split

Everything above came from daily use on real documents plus live experiments in a sandbox branch. That branch is a sandbox, it will not be PRed as is. If we agree on the items, I suggest deriving the work into four branches. Each one is a coherent review unit and they barely touch the same files, so they can land in any order.

Branch	Contents	Why together
Search and edit reliability	B1, B2, B3, B5, B7, B8, B10, B11, Q1, Q2, Q7, Q8, Q12, Q13, Q14, Q15, Q16, Q17, F4, F6	Same subsystem (search plus the edit, read and recovery pipeline). Together they make search, edits, reads, comments, styles, tracked changes and mistakes trustworthy
Tables	F5	A new specialized domain over the table API. Isolated, it barely touches the rest
Images	B4, Q4, F1	Same tool family. The crop fix and the friendly positioning change the same tool, and get_image lives next door
MCP experience	B6, Q3, Q5, Q6, Q9, Q10, Q11, F2, F3	How an external agent connects, learns the tools and recovers from errors. Manual, port, bridge, feedback, document targeting, the unsaved flag and error texts

B9 is test suite hygiene, independent of the four branches. It can land on its own or ride with whichever you take first.

I know this is a lot at once. I would really value your take, especially on anything you would do differently.

[KeithCu]

Hi @Augusto-Zolet Thank you very much for all of your work and fixes. You have been very busy!

Please submit them as 4 PRs, you can put B9 in the branch with the rest of the bug fixes.

I'm not sure I'd do anything differently yet, but when I see the changes I'll have more ideas and will just fix it / talk to you then.

[KeithCu]

@Augusto-Zolet Wow, this is an amazing set of PRs. People talk about Vini Jr. but you are the Brazilian MVP! I'll make a new GH release with these fixes and my other changes soon.

Update: I made a new release. Let me know how it goes with your users.

[KeithCu]

That's very nice of you to help your Dad. Hopefully Claude + WriterAgent help him save time. Now that you fixed so many issues, it should go much more smoothly.

[KeithCu]

BTW, it would be fine to move to another mcp port. Which one would you recommend?

Also regarding errors. For now I think it's fine if we wait for people to give us feedback. We will miss some errors, but if the product is useful enough to people, they will take the time. The Report bug does make it easy, maybe it could dig up the latest error and surrounding context in the log file by default which could be useful.

Also it might be fine to have have the MCP server start LibreOffice. I wouldn't mind adding that and it would make it simpler. What do you think about that?

[KeithCu]

@Augusto-Zolet Okay I requested a new release on the LO extension website (0.8.49) and a new version GitHub with all of your changes. It's an awesome release! We'll have to see what to add next. What do you think?

[KeithCu]

@Augusto-Zolet It took a few days for them to review it but the new build is up there: https://extensions.libreoffice.org/en/extensions/show/99526

I've talked to LibreOffice lead developers (ESC) and they are interested in shipping LibrePy.oxt, but I don't have feedback yet so I'm working on getting the =PY() into Collabora Office also: https://forum.collaboraonline.com/t/py-numpy-inside-collabora/4844