Skip to main content
HUMΛN

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/companion/ask',
  buildAgentInput: () => ({ deployment_id: 'dep_xxx' }),
});

await handle.openSurface({ command_id: 'platform.billing' });

Command Plane billing links use the same contract: /companion?command=platform.billing.

React (CompanionChrome)

const handleRef = useRef<CompanionChromeHandle | null>(null);

<CompanionChrome imperativeRef={handleRef} agentsCallUrl="/api/companion/call" mode="platform" />

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

Extension renderer

export function renderUsagePanel(host: CompanionChromeHostContext, data: UsagePayload) {
  return (
    <button type="button" onClick={() => host.openSurface({ command_id: 'acme.usage.detail', params: { id: data.id } })}>
      Drill down
    </button>
  );
}

← All patterns