Graphene.OfficeTool 1.26.8.18

OfficeTool

Agent tool for Office documents (DOCX / XLSX / PPTX) used by AIOrchestrator: create/open, view (outline/text/annotated/stats/issues), path-based DOM get/query/set/add/remove/move/swap, validate, batch, schema-driven help, template merge, save/restore — one document open at a time.

The class AIOrchestrator.API.OfficeTool is an agent tool: its public methods become LLM-callable tools via reflection + XML docs (see OfficePorting.md and the Agent Tools Guide).

It is a plugin: hosts load it dynamically from their Tools/ folder (startup scan + hot-add watcher) — see the plugin architecture doc shipped with AIOffice (Tools/ToolPluginArchitecture.md). It also ships as the NuGet package Graphene.OfficeTool for hosts that reference tools statically (e.g. AgentBridge).

Engine: vendored OfficeCLI

The document engine (OfficeCli.Core + OfficeCli.Handlers) is vendored byte-identical from the OfficeCLI project (Apache-2.0) as a separate Library project (ExternalDependencies/officecli, officecli.dll) that this adapter references — deterministic JSON output, path-based addressing (/slide[1]/shape[2]), schema-driven property validation, template merge, dump/batch round-trip and HTML rendering, without the CLI shell.

Do not edit files under ExternalDependencies/officecli/: they are upstream-copied (fidelity rules in VENDOR.md). The only allowed operations are DELETE (Program.cs, sync-exclude.txt) and the csproj transform Exe → Library + InternalsVisibleTo (applied automatically by the sync).

Adapter: generated surface

OfficeTool.cs is the minimal adapter (state, Dispose, helpers — no engine code): its public method surface is regenerated by update-vendor.ps1 from the deterministic analysis of the vendored CLI commands (which methods must be exposed, per vendor version). The adapter reaches the engine's internal APIs through the InternalsVisibleTo grant added by the sync transform; the sandbox boundary (SandboxPath.Resolve/ToAgent) is preserved in every generated method. Do not edit the block between the @@ADAPTER_SURFACE markers by hand.

Quick start (library use)

using OfficeCli.Handlers;               // DocumentHandlerFactory
using OfficeCli.Core;                   // IDocumentHandler, CliException

using var handler = DocumentHandlerFactory.Open("/tmp/report.docx", editable: true);
var outline = handler.ViewOutline();
var json    = handler.Get("/body/p[1]", depth: 1);
handler.Set("/body/p[1]", new Dictionary<string, object?> { ["bold"] = "true" });
handler.Save();

Updating from upstream

The vendor tracks the stable release (the "Source code (zip)" asset of https://github.com/iOfficeAI/OfficeCLI/releases), never the repository branch.

.\update-vendor.ps1                 # latest release: sync + analysis + generation + build + tests
.\update-vendor.ps1 -Tag v1.0.144   # pin a specific release

The updater vendors the release byte-identical, converts the vendored csproj to Library, regenerates the adapter surface (methods + XML docs) from the deterministic command analysis, verifies embedded-resource parity and the LoadSkill contract, builds the plugin and runs the OfficeTool.Tests harness. Nothing is committed or pushed — review, fix reported gaps (new commands need a template in update-vendor.ps1, nothing else), then commit (CI publishes the NuGet package). Full procedure: VENDOR.md.

Repository layout