Agent Sidecars

Agent Sidecars connect Nova with external agent runtimes such as Claude, Codex, or Gemini. A sidecar is a companion runtime: the provider agent runs next to Nova while Nova keeps the browser surface, visible conversation, approvals, work context, and saved session together.

Users work through the Agent Panel. They choose a provider, give a goal, watch the transcript, answer approval prompts, stop a run when needed, and reopen or continue saved conversations later.

Sidecars do not make agent work invisible or uncontrolled. Nova binds agent work to tabs, permissions, task context, workspaces, Agent Awareness Gates, and visible user decisions.

In short

Agent Sidecars let Nova use provider agents without hiding the work from the user.
The Agent Panel shows provider state, transcript, tool cards, approvals, stop controls, and the conversation archive.
Provider setup stays explicit: the required CLI or account must be available before Nova can start a provider.
Sensitive or state-changing work can require approval, tab binding, AAG checks, or stricter permission settings.
Workspaces, logs, and archives make sessions easier to resume and review.

What sidecars connect

A sidecar connects an external provider runtime with Nova’s browser-aware work surface.

Provider runtime Nova can start a supported provider agent when the required local setup is available. If the provider is missing, outdated, signed out, or degraded, Nova shows that state before work starts.
Agent Panel The panel is the visible place for prompts, provider status, answers, tool cards, approvals, stop controls, archive, and diagnostics.
Browser tools and context Sidecars use Nova’s browser and MCP tools for page reading, navigation, input, and progress reporting. Page perception, tab state, permissions, and user control stay in the same product surface.
Approvals and safety Sensitive actions can require explicit approval. Domain permissions, autonomy settings, AAG, emergency stop, and tab claims keep the agent from acting as if every action were already allowed.
Workspace and memory context Nova prepares agent workspaces, instructions, and relevant context so a provider agent starts with the right local orientation instead of an empty shell.
Archive and logs Conversations, events, exports, and bounded diagnostics let users review what happened and continue a session later.

When this matters

Use Agent Sidecars when an AI agent needs to act inside the browser instead of only chatting about a page. Typical cases are reviewing a website, filling a multi-step form, mapping a platform, running a quality pass, resuming a previous task, or asking an agent to use Nova’s learning, task, and safety context while the user keeps oversight.

Important terms

These terms keep the agent layer separate from the browser page itself.

Agent Sidecar: A local provider runtime that Nova starts or coordinates so an AI agent can work with Nova tools.
Provider: The external agent runtime or account, such as Claude, Codex, or Gemini.
Agent Panel: Nova’s visible control surface for the provider, transcript, approvals, stop controls, archive, and diagnostics.
Transcript: The visible conversation and event stream of the current agent session.
Approval: A user decision before a sensitive, high-impact, or state-changing action continues.
Workspace: The prepared working area and instruction context that helps the provider agent understand the current Nova task.
Tab claim: A reservation that links agent work to a specific tab or work context.

How it works

A sidecar run is a visible loop between user goal, provider agent, Nova tools, and user control.

Prepare the provider Nova checks whether the selected provider is available, signed in, compatible, and ready enough to start.
Start from the Agent Panel The user chooses a provider, writes a goal, and starts the turn from the shared panel instead of handing the page to an invisible worker.
Nova adds context Nova can provide instructions, workspace files, tab state, permissions, and tool bundles such as nova.tools_bundle so the agent knows the available surface.
The agent uses Nova tools The sidecar can read page state, navigate, click, type, inspect context, or report progress through the available Nova tools and policies.
The user stays in control When a step needs approval, the panel can show an approval card. The user can allow, deny, stop, or interrupt work.
Review or resume work Conversation events, archive entries, exports, and workspaces make important sessions easier to inspect and continue later.

Provider readiness

Provider setup is visible because a sidecar can only work when its runtime can start safely.

Area	What Nova shows	Why it matters
Provider status	Ready, missing, unsupported, degraded, signed out, or otherwise blocked state.	The user can see why a provider can or cannot start.
Version and path	Detected version, executable location, and last scan time when available.	Provider clients change over time; Nova surfaces setup drift instead of failing silently.
Diagnostics	Copyable diagnostic text and targeted repair actions where Nova can guide the fix.	Setup problems are easier to solve when the visible error names the next action.
Permissions	Approval choices, autonomy mode, domain rules, and persistent grants where allowed.	Browser-changing work runs with intentional, scoped agent rights.

Limits and safety

Agent Sidecars do not bypass Nova’s normal safety model. They do not make provider accounts, passwords, destructive actions, or browser state automatically safe. A provider can be unavailable, a session can be stopped, an approval can be denied, and stale or unsafe page context can block or slow the next step.

Example

A user asks Codex to inspect a settings page. Nova opens the Agent Panel, provides browser tools and current tab context, and shows the transcript as work progresses. If the agent wants to type into a sensitive field or navigate away from the claimed tab, Nova can require approval or stop the action before it changes the page.

Agent Tools

MCP tools for agents. These variables and tool names are intended for agents and integrators. They are not normal user controls in the interface.

Variable	Meaning
`nova.get_instructions`	Returns agent-facing instructions for the current mode, task, and tool context.
`nova.tools_bundle`	Loads the relevant Nova tool group before active browser or task work begins.
`nova.permission_prompt`	Lets an agent ask for explicit user approval for a sensitive or state-changing step.
`nova.tab_claim`	Reserves a tab for a scoped agent task so another agent does not silently take over.
`nova.tab_release`	Releases a reserved tab when the scoped work is done or abandoned.
`nova.tabs`	Lists visible tabs so an agent can orient itself before acting.
`nova.set_active_tab`	Moves the active browser target deliberately instead of relying on stale tab assumptions.
`nova.get_onboarding`	Prepares agent-facing onboarding information for local tool/client setup.
`nova.install_onboarding`	Installs agent reference files when the user chooses to set them up through Nova.
`targetId`	Canonical browser target identifier used by tab-scoped tools and claim checks.
`agentId`	Agent identity used to claim, release, and authorize scoped tab work.
`ownerAgentId`	Agent that currently owns a claim, goal, or scoped work record.
`sidecarSessionId`	Session binding for embedded sidecar requests and persisted claim ownership.
`sourceKind`	Origin class of the request, such as embedded or external.
`role`	Agent role stored with a claim or work owner record.
`claim`	Auto-claim result object returned by tab creation or scoped claim flows.
`claim.state`	Tri-state claim outcome: claimed, failed, or unknown.
`leaseMs`	Claim or goal lease duration in milliseconds.
`leaseRemainingMs`	Remaining claim lease time reported for direct roundtrips.
`leaseExpiresAtUtc`	Absolute UTC expiry time for the current claim or goal lease.
`heartbeatAtUtc`	Last observed heartbeat for the owning sidecar session.
`claimedAtUtc`	UTC timestamp when the target was claimed.
`claimHint`	Machine-readable conflict guidance when a claim blocks an action.
`claimHint.suggestedAction`	Recommended next step for resolving the claim conflict.
`claimHint.retryAgentId`	Agent identity that should be used for a clean retry when available.
`claimHint.overrideAvailable`	Signals whether a controlled reclaim or override path exists.
`claimHint.tokenRequired`	Signals whether the conflict requires a finalization token.
`claimHint.requiresLocalTakeover`	Signals that local user or sidecar takeover is required before retry.
`claimHint.nextStep`	Short machine-readable next action for the blocked agent.
`resolution.tool`	Recovery tool suggested for an owner-mismatch reclaim path.
`resolution.args.targetId`	Target argument prefilled for the suggested reclaim call.
`resolution.args.agentId`	Agent argument prefilled for the suggested reclaim call.
`resolution.args.reclaimReason`	Reason template for a controlled tab reclaim.
`finalizationToken`	Token that can authorize a controlled release from another bound session.
`releaseState`	Stable release result such as released, expired_cleanup, or not_claimed_noop.
`releaseAuthorization`	Explains whether release was owner_session, token_override, or not_applicable.
`hadActiveClaim`	Indicates whether the release path observed an active claim.
`released`	Boolean release outcome kept visible for existing clients.
`finalized`	Boolean finalization outcome kept visible beside release metadata.
`claim.owner_mismatch`	Reason code for a wrong agent identity on a claimed target.
`claim.session_mismatch`	Reason code for the same agent identity from a different bound session.
`claim.reclaim_required_after_resume`	Resume-mode reason requiring a sidecar to claim the target again before mutation.
`projectRoot`	Absolute worktree path selected for onboarding installation.
`bootstrapNow.steps`	Immediate setup steps returned by onboarding guidance.
`bootstrapNow.note`	Short setup note returned with onboarding guidance.
`files[]`	Onboarding reference files prepared for review or installation.
`files[].sha256`	Checksum for an onboarding file so clients can detect drift.
`edits[]`	Action-shaped edit plan for installing onboarding references.
`preserveOtherContent`	Instruction that onboarding edits should not overwrite unrelated user content.
`verify[]`	Verification steps for confirming onboarding setup.
`bundles[]`	Bundles recommended by onboarding guidance.
`risk_level`	Optional permission prompt risk level used for user-facing approval context.
`retryAfterMs`	Suggested wait time before retrying a transient tab activation or claim-related state.