Open Companion surface

# Open Companion surface

Use openSurface on the sealed CompanionChromeHostContext handle to open hydrated canvases from your host page — billing, settings, bundle dashboards — without conversational intent theater.

Overview

Host API — handle.openSurface({ command_id, params? }) on widget or CompanionChrome imperative ref.

Server hydrate — POST /v1/companion/open-surface resolves command → canvas payload + renderer.

Policy ceiling — admin chrome_policy gates capabilities; host cannot bypass with URL hacks.

Prefer explicit command_id (e.g. platform.billing) over chat ?intent= query strings.

Embed host (widget)

const handle = HUMAN.Companion.init({
  agentsCallUrl: '/api/ask-human',
  buildAgentInput: () => ({ deployment_id: 'dep_xxx' }),
});
await handle.openSurface({ command_id: 'platform.billing' });

Command Plane product CTAs use the same contract: /companion?command= (billing, marketplace, org.dashboard, live sessions, …) — never chat-intent query theater.

React (CompanionChrome)

const handleRef = useRef(null);
// Later:
await handleRef.current?.openSurface({ command_id: 'platform.billing', params: { tab: 'usage' } });

Extension renderer

export function renderUsagePanel(host: CompanionChromeHostContext, data: UsagePayload) {
  return (
     host.openSurface({ command_id: 'acme.usage.detail', params: { id: data.id } })}>
      Drill down
    
  );
}

Related

Chrome Host API guide

Embed documentation

Extension SDK — Chrome Host API