@8xlabsai/hekaya-shared-types

WebSocket protocol + shared TypeScript types for the Hekaya AI sales-agent platform. Used by the embeddable widget runtime, the orchestrator, the Chrome extension recorder, and the dashboard — keeps the wire format consistent across all five surfaces.

Install

pnpm add @8xlabsai/hekaya-shared-types
# or
npm install @8xlabsai/hekaya-shared-types
# or
yarn add @8xlabsai/hekaya-shared-types

Quickstart

Type a custom WebSocket client that talks to the Hekaya orchestrator:

import type {
  ClientToServer,
  ServerToClient,
  AgentResponse,
  AgentAction,
  SelectorTuple,
} from '@8xlabsai/hekaya-shared-types';

const ws = new WebSocket('wss://api.hekaya.ai/ws?session=...');

ws.onmessage = (event) => {
  const msg: ServerToClient = JSON.parse(event.data);

  if (msg.type === 'agent_response') {
    const reply = msg as AgentResponse;
    console.log('reply:', reply.delta);
    reply.actions?.forEach(handleAction);
  } else if (msg.type === 'agent_demo_offer') {
    console.log('demo offer:', msg.demo_slug, msg.demo_kind);
  } else if (msg.type === 'escalation') {
    console.log('escalation:', msg.kind);
  }
};

function handleAction(action: AgentAction): void {
  // resolve selector tuple, execute step, send action_ack
}

function send(msg: ClientToServer): void {
  ws.send(JSON.stringify(msg));
}

What's exported

• WebSocket frames — VisitorMessage, SessionStart, SessionContext, ActionAck, PersonaSwitch, DemoStart, DemoEvent, AgentResponse, AgentDemoOffer, AgentVoiceTurn, Escalation.
• Discriminated unions — ClientToServer, ServerToClient.
• Action shapes — AgentAction (kinds: navigate / highlight / click / fill / scroll / wait), SelectorTuple (3-tier), Selector (5 kinds: aria_role_text / data_attr / text / css / xpath).
• Citation + bilingual narration — Citation, narration { ar, en }.

Versioning

Semver. Major bump = wire-protocol breaking change (rare; coordinated with widget + orchestrator).

Source

Monorepo: github.com/8xlabs-ai/hekaya.ai → packages/shared-types/.

License

MIT