Files

T

Yichen Jiang b77fb9036c refactor(agent-presets,web): copy-only preset authoring with a path to the files

The web YAML editor is gone. agentPreset.write (arbitrary composition
text) became agentPreset.copy { from, agentPreset, name? }: a host-side
whole-directory copy of ids the host resolves itself — symlinks
dereferenced, modes re-tightened to owner-only with owner-execute kept,
metadata rewritten to keep the source's description but never its name or
roster order. No composition text or path crosses the wire in either
authoring direction, and the entryListSchema/!!js concern dissolves with
assertComposition itself.

The settings section becomes: a read-only viewer over shipped
compositions, a copy dialog (id + optional display name) as the only
create entry, delete for custom rows, and a location action leading into
the preset's own files — agentPreset.openDocument { agentPreset } resolves
the directory host-side and opens it natively, or answers
{ opened: false, path } for the row to show as text where the deployment
has no desktop. agentPreset.list reports hasDocument beside authorable;
the gateway's nativeOpen config pins the capability where
canOpenNativePath platform detection would mislead. The privileged set is
now read/copy/openDocument/remove.

With files as the only composition editor, standing mounts grew
stamp-keyed generations: ensureStanding compares the composition file's
mtime+size and starts the next generation for later sessions, while every
joined session keeps the generation it runs on.

New keyless web lane (agent-preset-authoring, overlay pins
nativeOpen: false so goldens render one branch on every platform) drives
view/copy/reveal/delete end to end; the real-composition CLI e2e switches
to copy semantics.

2026-08-08 22:35:26 +08:00

4.4 KiB

Raw Blame History

Agent Note: Copy-only preset authoring, and the way into a preset's files

Status: implemented

English | 中文

Problem

The agent-preset settings page carried a web YAML editor: agentPreset.write accepted arbitrary composition text, the page held a textarea with no completion, highlighting, or diff, and the shape check leaned on the Loader's own entryListSchema — whose dialect includes !!js, so "shape-checked text" was still arbitrary code on the next mount. Weak as an editor, wide as a capability, and the source of the editor-vs-roster races the section had to defend against.

Decision

Authoring is a host-side copy, and files are the editor. agentPreset.write became agentPreset.copy { from, agentPreset, name? }: two ids the host resolves against its own roots plus an optional display name, whole-directory cp (symlinks dereferenced, modes re-tightened to owner-only with owner-execute kept), metadata rewritten to keep the source's description but never its name or order. The page becomes: read-only viewer over shipped compositions, copy dialog as the only create entry (no blank "new preset" — writing YAML from nothing is not a thing people do), delete for custom rows, and a location action that leads to the files — agentPreset.openDocument { agentPreset } resolves the directory host-side and opens it natively, or answers { opened: false, path } for the row to show as text where the deployment has no desktop (hasDocument on list, pinned by the gateway's nativeOpen config where canOpenNativePath platform detection would mislead, e.g. e2e and containers).

Consequences

No composition text and no path crosses the browser wire in either authoring direction; the entryListSchema/!!js concern dissolves with assertComposition itself (deleted). The privileged set is now read/copy/openDocument/remove — none accepts a filesystem target.
With the editor gone, hand-editing agent.cordis.yml is the ONLY composition edit, so the standing-mount layer grew stamp-keyed generations: ensureStanding compares the file's mtime+size and starts the next generation for later sessions (standing-mounts note, updated in place). Without this, an edited file would serve stale compositions until process restart.
A copy is a full snapshot that drifts from an upgraded shipped source — accepted; the preset layer has no patch semantics (that is the bundle layer's cordis.patch.yml), and the shipped set itself pays the same cost (cordis/code are full copies of standard) for one-file readability.
read dropped writable (no editor to gate) and builtin directories are never opened (openDocument refuses non-user trust like remove): the install is overwritten by upgrades, and pointing an editor into it invites edits an upgrade silently discards.

Load-bearing details

Copy target refusal is two checks on purpose. The roster check refuses any id a root supplies — a user directory named like a shipped preset would be shadowed, so "create" would land a file nothing ever lists; the disk check (PresetExistsError before cp with errorOnExist as the race backstop) refuses a directory occupying the name without being a preset, which discovery cannot see.
The revealed path is response-direction disclosure, loopback-pinned. The invariant "no browser payload can select an arbitrary filesystem target" is about the request direction; showing the resolved directory to the loopback user is the fallback the plan requires. It never rides the unprivileged list.
The e2e lane pins nativeOpen: false (agent-preset-authoring.overlay.yml) — both so goldens render the same branch on macOS dev and headless Linux CI, and so test runs never pop a real file manager. The revealed directory is tokenized as {{presetRoot}} by the lane itself, since normalizeAria only knows the workspace cwd.

Alternatives considered

Keeping write with a better editor (CodeMirror etc.): still arbitrary capability over the wire, still the race source, and still a worse editor than the user's own. Patch-semantics copies ("standard plus this diff"): no such layer exists below the bundle plane, and the repo's own shipped presets chose full copies deliberately. Browser-side host.openPath with a returned path: breaks the README's no-arbitrary-target invariant the moment the path is a request parameter.

4.4 KiB Raw Blame History