jiangnangenius/floe-agent/floe-office

Office document workflow

• Word (.docx): document.createWord generates a real OOXML document; document.office.inspect returns stable field IDs; document.office.updateText edits those fields (use only explicit IDs from inspect; never guess).
• Workbook (.xlsx): document.createWorkbook builds a spreadsheet from sheet JSON. To read cell values quickly use document.readSheet (read-only TSV). To edit use document.office.inspect first — it returns the editable field/formula IDs that document.office.updateText consumes. Do not treat readSheet output as editable IDs.
• PowerPoint (.pptx): document.presentation.createDeck creates a native 16:9 deck from slide titles, bullets and speaker notes, and can place positioned objects on each slide: text boxes, preset shapes, PNG/JPEG/GIF images and real editable bar/line/pie charts. Objects use EMU geometry (914400 EMU = 1 inch, canvas 12192000 x 6858000) or a layout preset full/left/right/top/bottom/center; explicit EMU overrides the preset. Charts embed a genuine Sheet1 workbook with cell references, so they remain editable charts rather than pictures. Limits: 100 slides, 32 objects per slide, 20 text lines of 2000 characters, shape presets rect/roundRect/ellipse/triangle/diamond/arrow/chevron/star5, colors #RRGGBB, 8 MiB images (imagePath is workspace-relative; imageBase64 is inline), 64 categories and 8 series with one finite value per category. Read existing slide text and notes with document.office.inspect, then edit exact returned IDs with document.office.updateText. document.presentation.createInline creates a chat table/chart/web result, not a slide-deck file.

Engine edits with an explicit capability boundary

document.office.edit is the single engine surface for Word/Excel/Presentation edits (paragraph styles/lists/alignment/table insert; Excel number formats, row/column insert-delete, freeze panes, sort, AutoFilter, go-to-cell, recalculation; slide duplicate/reorder/object alignment). Two apply modes exist and must not be confused:

1. Interactive: propose binds the exact saved sha256, the user confirms in the editor UI, and apply carries the single-use grant_id the UI minted. This commits the document through the live session.
2. Automatic (runtime-authorized copy): an apply without grant_id, only when the runtime approved that exact call, runs a service-owned engine session on an isolated copy and writes a verified <name>.edited.<ext> copy. The original document is never modified; the copy is reopened and checked against the proposal's expectations, and sourceUnchanged=true must be observed before reporting success. A model cannot mint the authorization, and confirmed=true in arguments creates nothing. Automatic execution has no user selection: the original selection-relative commands remain refused. Use the explicit-target commands below for supported saved-package operations; use the interactive editor when an operation still depends on its current selection.

• Exact saved targets: call document.office.edit action=read and consume exactTargets; follow target_offset/nextOffset while hasMore is true. Use the returned immutable baseSHA256, actual paragraph member/index, worksheet member/name/tab index or slide member/shape IDs. Slide rows each describe one supported shape; combine 2–100 returned shape IDs with the same slide member into one target for alignment. Never infer identities from the first sheet or a screenshot. Commands word.exactStyle, word.exactBulletList, word.exactNumberedList, word.exactAlignment, excel.exactSort, excel.exactAutoFilter and pptx.exactAlignObjects carry the target as a JSON-encoded string in arguments.target. Use actual returned styleID, bounded range such as A1:C8, and the command's typed arguments. Sorting treats every selected row as data and uses the first column as its key; do not silently include a header. Exact commands use the runtime-authorized automatic copy path, not an interactive grant. Unsupported groups, formulas/objects or geometry are explicit failures. A saved target is invalid after its source revision changes; read again.
• Recalculation honesty: excel.recalculate is verified against the reopened package only. The check reads each formula cell's persisted cached value, result type and error code and recomputes supported dependencies rather than trusting their cached values (SUM/MIN/MAX/COUNT/AVERAGE, bounded IF comparisons and ROUND, direct and cross-sheet references, constant arithmetic). A missing cache, a stale cache, or an inconsistent error is a failure; unsupported formula shapes are reported as unverified, never claimed as verified. There is no full spreadsheet engine here, so do not promise recalculation for shapes outside that bounded set.
• Never state that an engine edit landed from a dispatch acknowledgement, a screenshot or a PDF rewrite. An engine capability that the pinned bundle does not expose (for example in-place picture replacement) is reported unavailable and uses the package-level path instead.
• Because automatic engine edits run off the visible editor, a presentation may not produce its required visible render; that case fails with a bounded, explicit result instead of a claimed success.

Revision safety

• Use the sha256 returned by inspection as expectedSHA256 for document.office.updateText and package-level edits; re-inspect after a conflict instead of dropping the check.
• document.office.edit proposals bind the exact revision; apply refuses when the file changed. replaceImage is package-level, reopens the package to verify the new bytes and refuses while a live editor holds unsaved edits.
• Always reopen/inspect the saved artifact to verify, and save to a new file unless overwrite was explicitly requested.

Long-running Office work

• Submit genuinely long package work (document.office.updateText, document.office.edit action=export) through jobs.submit; the job freezes its task workspace and declared base revision, and a stale revision or a path outside the task workspace is refused before the job is persisted. An eligible submission from a delegated child uses the same effective parent capability ceiling; delegation itself and main-run-only capabilities can never be deferred, and a job can never run in another task or environment.
• An authorized automatic apply is inline by default: its authority is bound to the approving call and must never be deferred. When the app has registered the authorized Office job adapter, apply may also be submitted through jobs.submit: the submission consumes the runtime approval for that exact jobs.submit call before any durable record exists, freezes the proposal revision and concrete commands into a service-owned operation, and the job writes the verified copy on the frozen task workspace. A model-authored confirmation or grant-looking string authorizes nothing, and apply stays refused as a job when no adapter is installed.
• Closing a view never cancels a job; process loss marks an unfinished job interrupted, so treat its outcome as UNKNOWN and inspect existing outputs (read-only) before resubmitting. Cancellation is cooperative and truthful: a running job reports cancelling=true until its processor stops and its staging cleanup completes, then becomes cancelled; it never deletes or rewrites the source, and a job that finished first keeps its actual result.

File conversion without model rewriting

Use document.convert with inputPath, outputPath and format to convert existing Markdown, DOCX, HTML, RTF and text files offline. Do not read the whole file into the model and regenerate it just to change format. Markdown/Word/HTML preserve supported semantic headings, lists, tables, links, emphasis and embedded/local images; RTF supports basic rich text. For PDF input or output use document.pdf.convert. Local images resolve relative to the source document inside its workspace. Download authorized remote images first; do not silently omit missing resources. Conversion writes a new file, returns a compact status/digest and preserves the source. Complex page layout and unsupported styles can differ; reopen and inspect the output.