CompanyOS Agent SPA Overlay

CompanyOS Agent SPA Overlay

Goal

Agents should be able to point users to concrete UI areas without relying only on text. The overlay is for short-lived visual hints like “look at this field”, “check this tab”, or “this layout component is relevant”.

Current Implementation

• Tool: mark_spa_elements
• Supporting tool: inspect_layout_json
• Client action: spa_agent_overlay
• Persistence: not persisted as domain data; the tool result remains visible in chat history and can be shown again from the tool card.
• Supported target kinds: field, tab, row, col, component, layout_path, selector
• Preferred targets are field identifiers or layout_path values returned by inspect_layout_json. CSS selectors are a fallback for UI areas that do not expose structured targets yet.
• inspect_layout_json returns the raw module layout JSON and a derived list of markable targets. This lets agents understand the layout while avoiding guessed DOM selectors.

Example payload shape:

{
  "targets_json": "[{\"kind\":\"field\",\"identifier\":\"price\",\"label\":\"Preis\",\"note\":\"Bitte diesen Wert prüfen.\",\"tone\":\"warning\"}]",
  "title": "Bitte prüfen",
  "summary": "Der Agent markiert die relevanten Stellen im Formular."
}

When layout elements do not have identifiers, use a structural target:

{
  "targets_json": "[{\"kind\":\"layout_path\",\"layout_path\":\"tabs.0.rows.0.cols.0.components.0\",\"label\":\"Relevant component\"}]"
}

The SPA renders a temporary overlay, opens the target tab when the target includes a tab-backed layout path, scrolls the first found target into view, and shows unresolved target counts if a selector or identifier cannot be found on the current screen.

Boundaries

• The tool does not update data.
• The tool does not infer business meaning.
• Field targets are validated against the current module when context is available. If the named thing is not a real field, agents should inspect the layout and use a layout target instead.
• The tool should not hardcode system-specific module or field identifiers in Brezel API core.
• Agents should still explain in text why a marked UI area matters.
• Structural layout_path targets are stable for the currently rendered layout version, but explicit layout identifiers are still better for long-lived references.

Follow-Ups

• Add structured target identifiers to more reusable SPA primitives when needed.
• Consider a detail-view variant for longer agent walkthroughs.
• Keep this generic; domain-specific tours or onboarding flows belong in the system or app layer, not Brezel API core.