feat: agent remote configuration (overlay, apply modes, safeguards)

[ccf-lisa]

Summary

Agent remote configuration on the Agents page. Users with agent:configure can:

• see what each agent instance runs;
• edit the agent's overlay inline;
• review the per-instance outcome before saving;
• browse history and revert.

The API is compliance-framework/api#465. Where the design and that code differ, this PR follows the code.

Important

Ship with or after compliance-framework/api#465.

• This PR moves /admin/agents and its nav entry to agent:read.
• The Configuration tab detects an older API (a 404 with no body on GET …/config) and shows an "unsupported" notice.

What's in it

Configuration tab

• Header: the desired revision and a sync summary, with chips for instances that have problems.

• Instance picker: stale instances are collapsed.

• Per-instance notice:

  • the mode, and why a revision was rejected;
  • file warnings.

• Views:

  • Effective: summary cards with provenance, or YAML;
  • File and Overlay: copy and download.

• Plugins as tabs: one tab per plugin (ARIA tablist, arrow/Home/End keys, a scrollable strip for many plugins), so the selected plugin's card gets the full width. Tab labels show new / pending / removal / removed / disabled. Add plugin sits next to the strip and selects the new plugin's tab.

• Inline editing on the Effective view: a ✏️ pencil on each editable field (source, schedule, enabled, labels, policy_data, config keys, verbosity, agent evidence, policy sources as OCI references or local paths). Row actions (edit, remove, reset, reorder) sit right next to the item they act on.

• Three-state field access over the reporting instances (fresh and reported), mirroring the API's Classify + WillApply per instance:

  • all would apply the change: pencil only;
  • some would not: pencil + 🛡 shield, whose tooltip names the instances and why;
  • none would (e.g. all in report mode, no matching overridable_config_flags): read-only, with the reasons;
  • forbidden (🔒): api.*, daemon and remote_config.*, never changeable remotely.

  With no reporting instance yet, fields stay editable without a shield. Without agent:configure everything is read-only.

• Add-plugin gating: the same three states for adding plugins.<name>: before a source is known, whether each instance could install a new plugin (apply_all; apply_safe with trusted_sources, or only by reusing a source its file already uses); in the dialog, the concrete source is classified per instance (already used / trusted / untrusted / local). None → the action (or the dialog's Add) is disabled. A new plugin's tab, card and fields keep the shield.

• policy_data: a structured tree instead of a JSON blob: objects as collapsible groups, lists as lists, masked •••• values and ${env:NAME} references marked; deep or large containers start collapsed. Each key and list item has its own pencil / remove / add, and an edit keeps the value's JSON type. Type changes go through the Raw JSON view (a toggle). Both views record a minimal merge patch: only the changed pointers, null for a removed file key, a changed list written whole, and an entry is dropped when a value is set back to the file value. A list edit shows as one element change in the pending count, the inline markers, per-item undo and the review rows. Lists holding a masked value are locked in the tree (saving them would copy the mask).

• Pending-changes bar: edits collect in a per-agent draft behind a sticky bar ("N pending changes · Review & save · Discard").

• Advanced: edit the raw overlay as YAML, using the same review flow.

• Review & save:

  • Per instance: a diff of merge(base, current) against merge(base, draft), with safety tags, a will-apply summary, and non-blocking file-origin warnings.
  • Save outcomes: 201, 200 (no-op), 409 (keep or discard my draft), 422, 403 and 413.

• Secrets notice: placeholders such as ${env:NAME} are recommended for secrets, because overlays are readable by agent:read.

• History: revisions with "Load more", view, diff against the previous or the current revision, and Revert.

• Lib badge: each plugin card shows a neutral "agent vX" badge, the agent library its binary was built with (diagnostics only).

• Layout: the Configuration tab has a single page scrollbar, and the pending-changes bar sticks to the bottom of the page scroll.

Validation

• The API is the validator. The UI calls POST …/config/preview (debounced, 1.5 s). Its overlay errors and per-instance results appear at the matching fields.
• Review & save is disabled while a preview is pending or reports errors. A failed live preview (network or 5xx) shows an error and a Retry button but doesn't disable Review, because Review runs its own preview.
• Client-side checks cover only what the API can't see: YAML/JSON parsing (no aliases or << merge keys), masked •••• values (never sent), and boolean coercion in config/labels; numbers there must be quoted. The plugin-name pattern (O6) is also checked client-side, mirroring the API's PluginNamePattern.

Access (R40)

• Route and nav: use agent:read. CRUD and keys are hidden unless the user has admin:manage, and keys are never fetched for non-admins.
• Editing, saving and reverting need agent:configure.

Follows the API's security-review contract

• An unset remote_config.mode is report by default (with credentials): the report-mode text says so, and the locked-keys panel shows it.
• Masked values (••••) can appear under any key and at any depth; the UI recognises them by value everywhere.
• Instance details no longer carry policy bundles: policyBundles, PolicyBundleReport and PolicyFileReport are removed; "Report truncated" now means the agent's file (base) was dropped.

Notable decisions

• The editor drawer was removed. Its job is now done by inline editing and the raw YAML dialog (R69–R71).
• Inline policy bundles are out of scope. The API no longer accepts policy_bundles, so there is no policy authoring UI; policies come from OCI or local sources.
• Removed during the final review:
  • the client-side copies of the API's overlay rules;
  • the old plugin-library gate mirror;
  • the ?fixtures demo mode.

Testing

• make reviewable (prettier, vue-tsc --build, eslint src/, Vitest: 173 files, 1528 tests) and make build pass. The unit suite ran 8× in a row with no unhandled errors (specs that render PrimeVue tabs now unmount after each test).
• Visual check against the local-dev API (nothing saved): plugin tabs, field states, add-plugin gating, per-item policy_data edits (the API preview accepted them), element-level review rows, single page scroll.
• End to end against api#465 on the local-dev RC stack (before inline bundles were removed): inline edits, review and save, and rejects across instances. Not re-run since the removal.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 6296e088-35b4-40b0-9697-e332b7187a99

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gusfcarvalho]

Approving at 6a149fa. The four inline threads are all non-blocking; one is a product question (NEEDS-DECISION).

Verified locally:

• vue-tsc --build, eslint src/, prettier --check src/, Vitest (168 files, 1497 tests) and vite build all pass.
• CI is green.
• The client matches the contract in api#465 (agent_config.go):
  • stop paths and casing;
  • If-Match: "<rev>";
  • 200/201, 409 current-revision, 422 body keys read raw (not camelCased), 403, 413 and 428;
  • validated / R59 warnings treated as non-blocking;
  • PolicyOnlyChange parity, including R22 and R58;
  • totalPages.

Security checks:

• No v-html; PrimeVue tooltips escape by default.
• The mask is refused before PUT and preview.
• __proto__ is handled.
• Keys and admin UI wait for permission hydration.

[ccf-lisa]

PR approved. Marking ready for e2e.

[gusfcarvalho]

Blocking: R61 (policy-author Revert/Clear gating; owner decision); see thread

[ccf-lisa]

R61 is addressed in 8c873f0. The Divergences section of the PR body is now out of date: it says "Revert and Clear overlay require agent:configure in the UI (stricter than the API)", and that is no longer a divergence. Both controls are now enabled for configure-policy users whenever the change is policy-only (policyOnlyGate, which uses the same rule and the same validation bases as the API). lisa cannot edit the PR body, so a maintainer should please remove that item.

[gusfcarvalho]

R61 verified at 8c873f0 (incremental review of 6a149fa..8c873f0). This supersedes my REQUEST_CHANGES.

Checked:

• policyOnlyGate wraps isPolicyOnlyChange and firstNonPolicyPath (with a generic fallback for R22/R58 refusals), so its result matches the API's D18 check in save().
• Revert:
  • full is always enabled;
  • none is disabled;
  • policy-only is decided per revision against loadValidationBases(), which follows the API's ValidationBases and is memoised per load. It fails closed: disabled while checking, and on any detail or revision load error. openRevert is guarded by the same decision.
  • Decisions reset when the desired overlay or the role changes.
• Clear overlay: configure users are always enabled; policy-only users go through policyOnlyGate(validationBases, original, {}) and are disabled while details load.
• The 403 path is unchanged.
• No regression for agent:configure users.

Local checks: vue-tsc, eslint, prettier, Vitest (168 files, 1510 tests) and vite build pass; CI is green; the lockfile is unchanged. I removed the obsolete Divergences item from the PR body.

[ccf-lisa]

Round 2: UI rework from the e2e feedback (design §13)

New head cd6edba (merged main first, in its own commit). Built against api#465 6c801a3 and agent#95 f88bde9.

What changed

• R70: the editor drawer is gone. The drawer, its form sections and their specs are deleted. The Configuration tab now has Policies and Advanced: raw YAML in its header. The YAML dialog edits the overlay and feeds the pending draft. Clear overlay lives there and keeps the R61 gate.

• R69: inline editing and one pending draft.

  • The Effective view has a ✏️ next to every editable field: plugin source, enabled, schedule, protocol, policies, each config key, labels, policy_data, verbosity and agent_evidence.*. There is also Add / Remove plugin.
  • Scalar fields get a small editor with Apply / Use file value / Agent default (R56). Maps, JSON and policy lists reuse the existing editors.
  • All edits, from the tab or the Policies view, go to one draft per agent and user (draftRegistry). It is kept in memory for the session and survives navigation between the two views.
  • A sticky bar shows N pending changes · Review & save · Discard, with per-change undo. Review reuses the preview panel and saves one revision with If-Match and the 409 flow. R58/R61 policy-only gating disables it.

• R71: field states.

  • ✏️ editable.
  • 🛡 restricted: the tooltip names each fresh apply_safe instance that will not apply the change, and why (missing trusted_sources, overridable_config_flags or allow_inline_policies).
  • 🔒 forbidden: muted with no pencil (api.*, daemon, remote_config.*). The YAML dialog marks forbidden keys and blocks Apply. The API's locked-key 422 stays authoritative.

• R68: Policies view at /admin/agents/:id/policies (needs agent:read; editing needs configure or configure-policy). It has three columns:

  • inline bundles and the sources plugins load;
  • a file tree showing inherited / overridden / added / deleted / dropped files, with View / Override / Delete / Restore / Add file;
  • a full-height CodeMirror editor and a validation panel that runs the preview.

  Create bundle starts from a source plugins use, another source, or from scratch. Assign to plugins is also here.

• R62/R64: Override pre-fills the current vendor source.

  • It uses the inline entry's extends.artifact-digest when that report extends the same source; otherwise the direct source report's digest.
  • With no digest, a 404, or an extends mismatch, it asks to confirm and then starts from the module template (title, description, violation contains {…} if {…}, labels), never a body-less stub.
  • When vendor tests cover the overridden package, it offers to delete them.
  • View shows the vendor file read-only.
  • The tooltip now says vendor tests that no longer compile reject the revision.

• R63 (UI): PolicyError.code shows as labelled markers in the editor, in the validation panel and in the review. Browser-side contract hints (missing title, contract keys defined as functions, literal types, …) cover authored modules. Add file uses the template.

• R66: assigning a bundle that extends S replaces S at the same index by default (the R22 swap, which policy-only users may make). Adding it alongside is an explicit choice and warns about duplicate evidence. Unassigning puts S back.

Checks

• vue-tsc --build, eslint, prettier --check, Vitest (172 files, 1528 tests) and vite build all pass.
• New specs cover:
  • Override pre-fill, the 404 and no-digest fallbacks, and an extends mismatch;
  • the template and the vendor-test delete offer;
  • View and Add file;
  • contract markers and API codes in the validation panel;
  • the draft accumulating across the tab and the Policies view, saved as one revision;
  • the pending bar, review/save and 409;
  • inline pencil edits per field type, and Apply on an untouched field writing nothing;
  • forbidden and restricted states;
  • policy-only gating in the bar and the view;
  • swap-by-default, alongside, unassign and delete/undo;
  • the raw YAML dialog (forbidden keys, coercion, R61 Clear);
  • the route, and the ?agent=&tab=config deep link.

Bundle sizes (vite build, raw / gzip)

chunk	before	after
AgentsView	21.2 / 6.4 kB	21.7 / 6.6 kB
AgentConfigTab	126.5 / 41.3 kB	72.8 / 20.9 kB
AgentConfigEditorDrawer	86.2 / 26.2 kB	removed
shared workspace (js-yaml, validation, inline editors)	n/a	101.9 / 35.8 kB
AgentPoliciesView (route)	n/a	56.5 / 18.4 kB
ReviewSaveDialog (async)	n/a	19.8 / 6.8 kB
RawOverlayDialog (async)	n/a	5.1 / 2.3 kB
CodeEditor / CodeMergeView (async)	46.4 / 29.3 kB	unchanged

Deviations and notes

• The module template uses "TODO: …" strings and a false violation body, so it parses and passes the contract checks as written. A literal { … } body would block the save.
• Pending drafts live in memory, not in sessionStorage. A reload starts clean, and beforeunload warns first.
• Restricted (🛡) only lists apply_safe restrictions. Report-mode and off-mode hosts are already called out by the instance notice.
• Deferred (low): a refresh re-fetches every instance detail; contract hints are recomputed for every bundle on each keystroke; the Policies route ignores an in-place :id change (nothing in the UI navigates that way).

The decisions are recorded in the lisa-design git note.

[gusfcarvalho]

Approving round 2 at cd6edba (incremental review of 8c873f0..cd6edba, §13 R62–R71). Nothing is blocking; I left two non-blocking threads.

Checks: npm ci, vue-tsc --build, eslint, prettier, Vitest (172 files, 1528 tests) and vite build all pass. CI is green. The merge of main (#316) is clean: no conflict hunks, and it only touches ControlStatementMetadata.vue.

Verified:

• Security:
  • No v-html / innerHTML in the new code. Vendor Rego, API and report text render as text or in CodeMirror, and tooltips escape.
  • "••••" is never sent:
    • inline text editors don't start from the mask and reject it as input;
    • map rows show it only as a placeholder;
    • policy_data and bundle data go through replacingPatch;
    • raw YAML Apply feeds a draft whose client issues block Review;
    • refuseMasked still guards PUT and preview.
  • New writes go through setAt/setOwn, so __proto__ stays safe.
  • Drafts are keyed by user id and agent id.
  • Forbidden keys: canEditPointer refuses them, raw YAML blocks Apply on locked keys, and client validation marks them as blocking.
• R56: "file value" omits the key; "agent default", Auto and Remove write null (via makeAbsent); per-change undo goes through revertPointer. delete[] is written as the whole list, and the vendor-test delete offer adds the inherited tests the overridden package covers.
• R62: Override uses extends.artifact-digest when the report extends the same source, else the direct source's digest. A miss, 404 or error goes to a confirm and then the template.
• R58/R61: configure-policy users can only edit /policy_bundles/** and /plugins/*/policies. Review & save is gated by isPolicyOnlyChange over the validation bases. Clear overlay in the raw dialog keeps policyOnlyGate.
• Regressions: none. The drawer is fully removed with no dead imports or routes. The new route is gated on agent:read. The 409 flow (keep / discard / reload) and 422/403/413 handling carry over to ReviewSaveDialog. Hydration is unchanged: ready follows ensurePermissions.

Deviations:

• (a) The "TODO: …" template with a false violation body is acceptable. It parses and passes R63, the confirm explains it, and the evidence is visibly titled "TODO…". It does mean an untouched override always passes; consider a warning hint while the TODO markers remain.
• (b) In-memory drafts with a beforeunload guard are acceptable. They survive in-app navigation and keep overlay edits out of browser storage.
• (c) Listing only apply_safe reasons on the restricted shield matches R71; report-mode and off-mode hosts are covered by the instance notice.