Document Editor Plugin

The Document Editor plugin provides DOCX document editing tools via a dynamic tool-injection pattern. When the user asks the agent to edit a document, doc_open loads the file and conditionally injects a full suite of editing tools into the LLM's available tool set.

Overview

The Document Editor plugin:

1. Always registers a doc_open tool so the agent can open DOCX files
2. When a document is opened, injects 13 editing tools (read, search, replace, table editing, etc.)
3. When the document is closed, removes the editing tools from the tool set
4. Provides a download endpoint so users can retrieve edited documents via the UI
5. Emits UI events for transcript cards (e.g., file-saved notifications)

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.doc_editor
    class: DocEditorPlugin
    args:
      enabled: true
      target_agents: "main"  # "main", "subagent", or "all" (default: "main")

Configuration Parameters

• enabled (optional): Whether the plugin is enabled (default: true)
• target_agents (optional): Which agents receive the tools — "main", "subagent", or "all" (default: "main")

Tool Reference

Always Available

Tool	Description
doc_open	Open a DOCX file for editing. Triggers injection of editing tools.

Injected When Document Is Open

Tool	Description
doc_read_structure	Read the document's paragraph/heading structure
doc_read_section	Read content of a specific section
doc_search	Search for text within the document
doc_replace_text	Replace text content
doc_insert_paragraph	Insert a new paragraph
doc_delete_paragraph	Delete a paragraph
doc_list_tables	List all tables in the document
doc_edit_table_cell	Edit a specific table cell
doc_read_headers_footers	Read headers and footers
doc_set_property	Set document properties (title, author, etc.)
doc_python	Execute arbitrary python-docx code for advanced edits
doc_save	Save the document (emits plugin.doc_editor.file_saved UI event)
doc_close	Close the document and remove editing tools

How It Works

Tool Injection Pattern

The plugin uses the onPromptAssemble hook (priority 10) to dynamically manage tools:

1. Before every LLM call, the hook checks whether the current session has an open document
2. If no document is open: only doc_open is in the tool list
3. When doc_open is called: the plugin records the session as having an open document
4. On the next LLM turn: onPromptAssemble sees the open session and injects all 13 editing tools
5. When doc_close is called: the session is cleared and editing tools are removed on the next turn

This pattern keeps the tool set clean — the LLM only sees editing tools when they are relevant.

Session State

• _open_sessions: Tracks which session IDs have an open document
• _editing_tools: Caches tool instances per session to avoid redundant creation
• Callbacks (_on_doc_opened, _on_doc_closed) are passed to tool constructors so doc_open/doc_close can update plugin state

UI Integration

The plugin provides:

• A UI manifest with a x-doc-editor-card custom element for transcript cards
• A plugin.doc_editor.file_saved event emitted when documents are saved
• An API router (/doc-editor/...) for download endpoints

Example Interaction

User: Open the report.docx file and update the title to "Q4 Summary"

Agent calls: doc_open(path="report.docx")
  → Plugin state: session marked as open, editing tools injected

Agent calls: doc_read_structure()
  → Returns document outline with headings and paragraphs

Agent calls: doc_replace_text(old="Q3 Report", new="Q4 Summary")
  → Text replaced in document

Agent calls: doc_save()
  → Document saved, UI shows file-saved card with download link

Agent calls: doc_close()
  → Plugin state: session cleared, editing tools removed

Testing

Run the document editor tests with:

python -m unittest tests.test_doc_editor_plugin -v