Portal Copilot Module Contract
Portal Copilot Module Contract
Section titled “Portal Copilot Module Contract”Portal Copilot must be portable like an analytics tag: a host page adds a small runtime island plus data-copilot-* annotations, and the agent only receives the registered interaction manifest. It must not scrape the whole DOM or infer controls from arbitrary buttons and inputs.
Host Integration
Section titled “Host Integration”- Mount the dock once in the shell.
- Annotate surfaces and widgets with the common data contract.
- Route all mutations through host-provided HITL approval.
- Keep identity, policy, and model keys server-side.
Required attributes:
data-copilot-binding: stable widget/action id.data-copilot-kind: one ofscroll,highlight,draft_fill.data-copilot-label: short user-visible action label.data-copilot-description: agent-facing description of what the widget/action means.
Optional attributes:
data-copilot-value-hint: expected input shape fordraft_fill.data-copilot-widget-role: domain role such asproject-name,approval-comment,deployment-channel.data-copilot-surface: owning surface key.
Standard Actions
Section titled “Standard Actions”scroll: move the viewport to a registered widget.highlight: one-shot visual highlight on a registered widget.draft_fill: propose replacing a registered input value. The replacement is previewed in the dock and only applied after human approval.
Runtime Boundaries
Section titled “Runtime Boundaries”- The browser registry exposes only registered bindings.
- The server recomputes principal and OPA policy before enabling capabilities.
- The browser sends a compact interaction manifest; it does not invent tool calls.
- The server returns
tool_calls, and the browser only executes them after HITL approval. - LangGraph/LLM keys come from OpenBao refs and never reach the browser.
- Conversation archives are scoped by tenant/user owner key. Cross-user replay is invalid.
Extraction Target
Section titled “Extraction Target”When split into a standalone repository, keep these packages:
@fractalops/copilot-registry: browser annotation registry and HITL executor.@fractalops/copilot-dock: React dock UI.fractalops-portal-copilot-mcp: MCP tools for capability listing and server-side action proposal.fractalops-portal-copilot-policy: OPA input schema and fail-closed policy helpers.