Execution Agent file operations
This plugin provides EA's bounded plain-text reads, new-file creation and range
editing. It is enabled by default and prepares handlers only for a request whose
frozen root contract is execution_agent. SUPER retains its existing tools and
authoring behavior. This plugin's own global/model restrictions and request
permissions apply independently of whether the legacy filesystem plugin is
installed or permitted.
Operations
read_text: path, optional line bounds, an exact locator, or an explicit byte window. Without a selector, reads lines 1–120 or EOF within the 24,000-byte output budget. Explicit line bounds are one-based and keep their requested range. The body has no line prefixes. Coverage, total lines and truncation are explicit. A fully returned window carries a request-localrange_ref; a truncated window does not.max_bytesalone caps the default preview (1–24,000 bytes) without selecting a byte range. It cannot combine with explicit line or locator controls. For a sub-line window, set zero-basedstart_byteand optionallymax_bytes(1–24,000; default 24,000). This mode cannot combine with line/locator controls. The start must be a UTF-8 character boundary; the end backs off to one. A budget too small for the next character fails. Returnedstart_byteand exclusiveend_byteidentify exactly the observed window;next_byteis present only when more file content follows. This complete selected window gets arange_refeven when more file content follows. Offset EOF returns an empty range; past EOF fails.create_text: create a new UTF-8 file, including missing parent directories. Existing files are rejected. EA selects the path and accepted content objective; its dedicated author returns the exact new text once.edit_text: select a path and a requiredrange_refreturned byread_text. The adapter supplies exactly that observed range; the author returns its complete replacement as plain text. Content outside the selected range stays unchanged. There is no JSON patch mode or implicit last-read selection.
Unrelated reads cannot change the selected range binding. Missing, stale, wrong-path or unavailable references fail before content authoring or mutation. An empty file has an empty observed range that can be filled. Empty replacement text deletes the selected range; identical replacement text is reported as unchanged.
The plugin does not call a model, choose edit locations, or repair generated content. The separate EA file author owns the one content-generation invocation. An ordinary read needs no additional model invocation.
Source, evidence and lifetime
The adapter reads the target internally to capture its revision before authoring,
and binds the prepared bytes to it. This safety snapshot is not projected into
model context. Explicitly selected range text is passive data, not an instruction.
Range references belong to the current request, exact path, revision and window.
They are not conversation memory or permanent file identifiers.
Byte selections use the same retained range state and authoring contract as line
selections. Byte offsets are converted to internal string offsets before binding.
They add no compaction index, implicit full-file context or cross-request memory.
The input-schema change requires republishing saved automations that depend on
the previous read_text contract, through the existing dependency check.
Successful mutations return bounded committed-file snapshots through ordinary canonical tool results. The existing EA evidence and verified-compaction contracts remain authoritative. Events contain only bounded presentation metadata; they are not another source of execution state or model context.
Prepared bindings and range references use the existing plugin request-state mechanism during an approval wait. Resume executes the captured payload without reauthoring. A changed target or unavailable/stale reference fails before writing. Legacy exact-edit bindings can be decoded but cannot execute; selecting a fresh range is required. Their presence does not invalidate separate range/create approvals. State is bounded and disposed with the request; old range references may be evicted. After a mutation, read a fresh range before another edit of that file.
Bounds and safety
- Valid UTF-8 text, preserving BOM, CRLF and final-newline bytes.
- Files up to 1 MiB; generated content up to 256 KiB per invocation.
- One explicitly selected range per edit and 32 retained observed windows.
- Existing root/path, symlink and atomic-write protections apply.
- Cancellation, permissions, approvals and result events use the runtime's existing execution lifecycle.
Local adapter and runtime tests cover source binding, source drift, approval restore, exact bytes, bounded evidence and SUPER isolation. These tests do not establish live-model task quality or browser behavior.