@7ots/cli 0.1.0

package/src/identity/schema.js

@@ -0,0 +1,262 @@
+/**
+ * Esquema de la identidad de un agente 7ots: quién es, cómo se ve, cómo suena y cómo se le contacta.
+ * Código puro (sin DOM ni Node): lo usan el widget, la tarjeta <ots-identity>, la cara
+ * (createFace), el proxy y el SDK de servidor.
+ *
+ *   {
+ *     id, name, role, tagline, seed, bio, language, languages[],
+ *     personality: { tone, traits[], instructions },          // instructions: privadas, solo servidor
+ *     look:    { kind: character|realistic|image, character: {…personaje 2D, ver src/character},
+ *                color, accent, emoji, image, avatar: { url, body, mood, cameraView },
+ *                face: { skin, eyes }, meetAvatar, meetScene },
+ *     voice:   { provider: auto|apuchat|elevenlabs|grok|fish|openai|browser, voiceId, model, style, lang, rate, pitch, browserVoice },
+ *     contact: { site, email, apuchat, meet, call, hours },
+ *   }
+ *
+ * La identidad NUNCA contiene secretos (las claves de apumail/apuchat/TTS viven en el servidor).
+ */
+
+import { normalizeCharacter } from '../character/Character.js';
+import { translator } from '../i18n/index.js';
+import '../i18n/messages/identity.js';
+
+export const LOOK_KINDS = ['character', 'realistic', 'image'];
+export const MEET_AVATARS = ['shibu', 'shino', 'fumiriya', 'victoria', 'vita', 'vivi', 'kuro', 'maya', 'ingrid', 'kenji', 'viktor', 'marcus', 'leo', 'mei', 'claire', 'doctor', 'amira'];
+export const MEET_SCENES = ['studio', 'beach', 'castle', 'space', 'sunset', 'forest', 'night', 'office', 'neon'];
+export const VOICE_PROVIDERS = ['auto', 'apuchat', 'elevenlabs', 'grok', 'fish', 'openai', 'browser'];
+/** Voces integradas de xAI (Grok) TTS; también admite ids de voces clonadas propias. */
+export const GROK_VOICES = ['eve', 'ara', 'leo', 'rex', 'sal'];
+export const OPENAI_VOICES = ['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse'];
+export const MOODS = ['neutral', 'happy', 'angry', 'sad', 'fear', 'disgust', 'love', 'sleep'];
+
+export const IDENTITY_DEFAULTS = Object.freeze({
+  id: 'asistente',
+  name: 'Asistente',
+  role: 'asistente virtual',
+  tagline: '',
+  seed: '',
+  bio: '',
+  language: 'es',
+  languages: [],
+  personality: { tone: 'cercano y claro', traits: [], instructions: '' },
+  look: {
+    kind: '', // character (2D editable) | realistic (3D .glb) | image (retrato). Vacío = se deduce
+    character: null, // personaje 2D (null = el de serie)
+    color: '#6d5dfc',
+    accent: '#22d3ee',
+    emoji: '',
+    image: '', // retrato (URL) para tarjetas, correo y vCard
+    avatar: { url: '', body: 'F', mood: 'neutral', cameraView: 'upper' }, // .glb 3D (vacío = el de serie)
+    face: { skin: '', eyes: '' }, // colores de la cara 2D
+    meetAvatar: 'vivi',
+    meetScene: '',
+  },
+  voice: { provider: 'auto', voiceId: '', model: '', style: '', lang: 'es-ES', rate: 1.05, pitch: 1, browserVoice: '' },
+  contact: { site: '', email: '', apuchat: '', meet: true, call: true, hours: '' },
+});
+
+/**
+ * Normaliza y valida una identidad (acepta objetos parciales). Nunca lanza: descarta lo inválido.
+ * @param {object} input
+ * @param {object} [base] identidad sobre la que se aplica (por defecto, los valores de serie)
+ */
+export function defineIdentity(input = {}, base = IDENTITY_DEFAULTS) {
+  const i = input && typeof input === 'object' ? input : {};
+  const b = base;
+  const look = { ...b.look, ...pick(i.look) };
+  const voice = { ...b.voice, ...pick(i.voice) };
+  const contact = { ...b.contact, ...pick(i.contact) };
+  const personality = { ...b.personality, ...pick(i.personality) };
+  const out = {
+    // El id es estable: solo cambia si se da uno explícito o si aún es el de serie.
+    id: slug(i.id) || (b.id !== IDENTITY_DEFAULTS.id ? b.id : slug(i.name)) || IDENTITY_DEFAULTS.id,
+    name: str(i.name ?? b.name, 60) || IDENTITY_DEFAULTS.name,
+    role: str(i.role ?? b.role, 120),
+    tagline: str(i.tagline ?? b.tagline, 160),
+    seed: String(i.seed ?? b.seed ?? '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 32), // semilla de randomIdentity
+    bio: str(i.bio ?? b.bio, 1200),
+    language: lang(i.language ?? b.language) || 'es',
+    languages: list(i.languages ?? b.languages, 12).map(lang).filter(Boolean),
+    personality: {
+      tone: str(personality.tone, 120),
+      traits: list(personality.traits, 12).map((t) => str(t, 40)).filter(Boolean),
+      instructions: str(personality.instructions, 4000),
+    },
+    look: {
+      kind: LOOK_KINDS.includes(look.kind) ? look.kind : look.avatar?.url ? 'realistic' : look.image ? 'image' : 'character',
+      character: normalizeCharacter(look.character || {}),
+      color: color(look.color) || IDENTITY_DEFAULTS.look.color,
+      accent: color(look.accent) || IDENTITY_DEFAULTS.look.accent,
+      emoji: str(look.emoji, 8),
+      image: url(look.image),
+      avatar: {
+        url: url(look.avatar?.url),
+        body: look.avatar?.body === 'M' ? 'M' : 'F',
+        mood: MOODS.includes(look.avatar?.mood) ? look.avatar.mood : 'neutral',
+        cameraView: ['full', 'mid', 'upper', 'head'].includes(look.avatar?.cameraView) ? look.avatar.cameraView : 'upper',
+      },
+      face: { skin: color(look.face?.skin), eyes: color(look.face?.eyes) },
+      meetAvatar: MEET_AVATARS.includes(String(look.meetAvatar).toLowerCase()) ? String(look.meetAvatar).toLowerCase() : 'vivi',
+      meetScene: MEET_SCENES.includes(String(look.meetScene).toLowerCase()) ? String(look.meetScene).toLowerCase() : '',
+    },
+    voice: {
+      provider: VOICE_PROVIDERS.includes(voice.provider) ? voice.provider : 'auto',
+      voiceId: str(voice.voiceId, 80),
+      model: str(voice.model, 80),
+      style: str(voice.style, 400),
+      lang: /^[a-z]{2,3}(-[A-Za-z]{2,4})?$/.test(String(voice.lang)) ? voice.lang : 'es-ES',
+      rate: num(voice.rate, 0.5, 2, 1.05),
+      pitch: num(voice.pitch, 0, 2, 1),
+      browserVoice: str(voice.browserVoice, 120),
+    },
+    contact: {
+      site: url(contact.site),
+      email: /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(String(contact.email || '')) ? String(contact.email).toLowerCase() : '',
+      apuchat: String(contact.apuchat || '').trim().replace(/^https?:\/\/[^/]+\//i, '').replace(/^@/, '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 32),
+      meet: contact.meet !== false,
+      call: contact.call !== false,
+      hours: str(contact.hours, 120),
+    },
+  };
+  return out;
+}
+
+// ───────────────────────────── salidas ─────────────────────────────
+
+/**
+ * Tarjeta pública: lo que cualquiera puede saber del agente y cómo contactarlo.
+ * @param {object} id                  identidad normalizada
+ * @param {{ email?: boolean, apuchat?: string|null, meet?: boolean }} [live]  canales que atiende el propio agente
+ */
+export function publicIdentity(id, live = {}) {
+  const apuchat = live.apuchat || id.contact.apuchat || '';
+  return {
+    '@type': '7ots/agent',
+    version: 1,
+    id: id.id,
+    name: id.name,
+    role: id.role,
+    tagline: id.tagline,
+    seed: id.seed || undefined,
+    bio: id.bio,
+    language: id.language,
+    languages: id.languages,
+    personality: { tone: id.personality.tone, traits: id.personality.traits }, // las instrucciones no son públicas
+    look: id.look,
+    voice: { provider: id.voice.provider, lang: id.voice.lang, rate: id.voice.rate, pitch: id.voice.pitch, browserVoice: id.voice.browserVoice },
+    contact: {
+      site: id.contact.site,
+      hours: id.contact.hours,
+      email: id.contact.email,
+      apuchat,
+      // meet: el agente entra en llamadas de meet.apuchat.com; call: se puede abrir una desde la web
+      meet: !!(id.contact.meet && apuchat && live.meet !== false),
+      call: !!(id.contact.call && live.meet),
+      // qué canales contesta el agente él solo (el resto los lee una persona o tu sistema)
+      answers: { email: !!live.email, apuchat: !!live.apuchat, meet: !!live.meet },
+    },
+  };
+}
+
+/** vCard 4.0 de la tarjeta pública. */
+export function toVCard(card, { baseUrl = '' } = {}) {
+  const esc = (s) => String(s || '').replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/([,;])/g, '\\$1');
+  const lines = ['BEGIN:VCARD', 'VERSION:4.0', 'KIND:individual', `FN:${esc(card.name)}`, `UID:urn:7ots:${card.id}`];
+  if (card.role) lines.push(`TITLE:${esc(card.role)}`);
+  if (card.bio || card.tagline) lines.push(`NOTE:${esc(card.tagline || card.bio)}`);
+  if (card.contact.email) lines.push(`EMAIL;TYPE=work:${card.contact.email}`);
+  if (card.contact.apuchat) lines.push(`IMPP;PREF=1:apuchat:${card.contact.apuchat}`);
+  if (card.contact.site) lines.push(`URL:${card.contact.site}`);
+  if (card.look.image) lines.push(`PHOTO:${card.look.image}`);
+  if (card.language) lines.push(`LANG:${card.language}`);
+  if (baseUrl) lines.push(`SOURCE:${baseUrl}`);
+  lines.push('END:VCARD');
+  return lines.join('\r\n') + '\r\n';
+}
+
+/**
+ * Líneas del system prompt que dan personalidad al agente (web y canales).
+ * Se redactan en el idioma de la identidad (`id.language`; uno sin catálogo usa inglés).
+ * @param {object} id  identidad normalizada
+ * @param {string} [locale]  fuerza otro idioma
+ */
+export function identityPrompt(id, locale = id.language) {
+  const p = id.personality;
+  const t = translator(locale || 'es');
+  return [
+    id.role ? t('identity.prompt.youAreRole', { name: id.name, role: id.role }) : t('identity.prompt.youAre', { name: id.name }),
+    id.bio ? t('identity.prompt.about', { bio: id.bio }) : '',
+    p.tone ? t('identity.prompt.tone', { tone: p.tone }) : '',
+    p.traits.length ? t('identity.prompt.traits', { traits: p.traits.join(', ') }) : '',
+    p.instructions,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Traduce la identidad a la configuración del widget (agent, avatar, voice, theme).
+ * Lo que el sitio pase explícitamente en init() manda sobre esto.
+ */
+export function identityToWidgetConfig(id) {
+  const a = id.look.avatar;
+  const kind = id.look.kind || 'character';
+  // El personaje 2D va siempre: es el avatar en modo 'character' y el respaldo si falla el 3D.
+  const avatar =
+    kind === 'realistic'
+      ? { mode: '3d', ...(a.url ? { url: a.url } : {}), body: a.body, mood: a.mood, cameraView: a.cameraView, character: id.look.character }
+      : kind === 'image' && id.look.image
+        ? { mode: '2d', image: id.look.image, face: id.look.face, mood: a.mood }
+        : { mode: '2d', character: id.look.character, mood: a.mood };
+  return {
+    agent: { name: id.name, role: id.role, language: id.language },
+    avatar,
+    voice: {
+      lang: id.voice.lang,
+      rate: id.voice.rate,
+      pitch: id.voice.pitch,
+      ...(id.voice.browserVoice ? { voice: id.voice.browserVoice } : {}),
+      ...(id.voice.provider === 'browser' ? { tts: 'browser' } : {}),
+    },
+    theme: { primary: id.look.color, accent: id.look.accent },
+  };
+}
+
+// ───────────────────────────── helpers ─────────────────────────────
+
+function pick(o) {
+  return o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+}
+function str(v, max) {
+  return v == null ? '' : String(v).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, '').trim().slice(0, max);
+}
+function list(v, max) {
+  if (typeof v === 'string') v = v.split(',');
+  return Array.isArray(v) ? v.slice(0, max) : [];
+}
+function slug(v) {
+  return String(v || '').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+}
+function lang(v) {
+  const m = String(v || '').trim().toLowerCase().match(/^[a-z]{2,3}/);
+  return m ? m[0] : '';
+}
+function color(v) {
+  const s = String(v || '').trim();
+  return /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(s) ? s : '';
+}
+function url(v) {
+  const s = String(v || '').trim();
+  if (!s) return '';
+  if (s.startsWith('/') && !s.startsWith('//')) return s.slice(0, 500); // ruta del propio sitio
+  try {
+    const u = new URL(s);
+    return u.protocol === 'https:' || u.protocol === 'http:' ? u.href.slice(0, 500) : '';
+  } catch {
+    return '';
+  }
+}
+function num(v, min, max, def) {
+  const n = Number(v);
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : def;
+}

package/src/index.js

@@ -0,0 +1,117 @@
+/**
+ * 7ots — asistente web proactivo, embebible en cualquier sitio.
+ *
+ *   import { init } from '@7ots/cli';            // ESM
+ *   const agent = SevenOts.init({...});      // <script> (build IIFE: dist/7ots.iife.js)
+ *
+ * Configuración (todo opcional salvo `endpoint` si usas el proxy incluido):
+ *
+ *   SevenOts.init({
+ *     endpoint: '/api/agent',                 // tu proxy (server/): el LLM y las claves viven allí
+ *     identity: true | '/url/identidad' | { name, role, look, voice, contact },  // quién es (ver src/identity/schema.js)
+ *     siteKey: 'pk_demo',                     // identificador público del sitio (no es secreto)
+ *     agent:   { name: 'Ana', role: 'asesora de ventas', siteName: 'Acme',
+ *                language: 'español', instructions: 'Ofrece siempre el plan anual…' },
+ *     avatar:  { url: '/avatars/ana.glb', body: 'F', mood: 'happy', cameraView: 'upper' } | false,
+ *     voice:   { tts: 'proxy' | 'browser' | false, stt: true, lang: 'es-ES' } | false,
+ *     auth:    { getToken: () => localStorage.getItem('jwt'), getUser: () => ({ name, email, plan }) },
+ *     mcp:     [{ url: '/mcp', name: 'acme', requiresAuth: true }],
+ *     actions: [{ name, description, parameters, handler, confirm, requiresAuth }],
+ *     templates: { producto: (data, { escape }) => `<h3>${escape(data.nombre)}</h3>` },
+ *     navigation: { allowedOrigins: ['https://docs.acme.com'], router: (url) => nextRouter.push(url) },
+ *     proactive: { level: 'quiet' | 'normal' | 'bold',   // preset de iniciativa; el visitante lo cambia en el menú
+ *                  dwellMs, idleMs, hesitationMs, exitIntent, selection, cooldownMs, maxPerSession,
+ *                  rules: [{ id, when: (snap) => bool, message }] } | false,
+ *     context:   { privateSelectors: ['.saldo'], ignoreSelectors: ['#cookie-banner'], extra: () => ({ carrito }) },
+ *     contact:   { apuchat: true, apumail: true | { categories } } | false,   // hub y claves: en el proxy
+ *     builtins:  { exclude: ['click'], confirmClicks: 'submit' | 'all' | 'none' },
+ *     pointer:   { speed: 1, visible: true } | false,   // ratón y teclado visibles del agente (Esc lo detiene)
+ *     pageTools: true | false,                         // [data-ots-tool] del HTML → herramientas
+ *     mode:      'panel' | 'companion',                // companion: el avatar se pasea por la página y señala
+ *     companion: { size: 150, idleHomeMs: 30000, follow: true, wanderMs, watchCursor },
+ *     theme:     { primary: '#e11d48', radius: 18, position: 'right', font: 'Inter, sans-serif' },
+ *     open: false,
+ *   });
+ *
+ * API devuelta: registerAction, registerMcp, registerTemplate, setAuthToken, ask, say,
+ * notify, setProactivity(level), setIdentity(identity), identity, open, close, reset,
+ * on(event, fn), destroy, y ui/auth/context/actions/bus.
+ *
+ * Módulo de identidad (sin el chat): quién es el agente, cómo se ve, cómo suena y cómo se le contacta.
+ *
+ *   const face = await SevenOts.createFace(el, { identity: '/api/agent/identity', endpoint: '/api/agent' });
+ *   face.say('Hola');                                   // cara + voz de la identidad, lip-sync
+ *   <ots-identity src="/api/agent/identity" face></ots-identity>   // tarjeta de contacto
+ *
+ * Personaje 2D y editor de avatar (estilo Pou: forma deformable, ojos, bocas, accesorios, estilos):
+ *
+ *   const ch = SevenOts.createCharacter(el, { preset: 'pirate' });  ch.mouth(0.6); ch.mood('happy');
+ *   SevenOts.createAvatarEditor(el, { value: identity.look, onChange: (look) => … });
+ *   <ots-avatar-editor></ots-avatar-editor>
+ */
+
+import { AgentWidget } from './core/AgentWidget.js';
+
+export { AgentWidget };
+export { EventBus } from './core/EventBus.js';
+export { AgentBrain } from './core/AgentBrain.js';
+export { ContextManager } from './context/ContextManager.js';
+export { ActionRegistry, validate } from './actions/ActionRegistry.js';
+export { createBuiltinActions, setFieldValue } from './actions/builtins.js';
+export { VirtualPointer } from './ui/VirtualPointer.js';
+export { PageTools } from './actions/PageTools.js';
+export { Companion, createCompanionActions } from './ui/Companion.js';
+export { AuthManager, decodeJwt } from './auth/AuthManager.js';
+export { McpClient } from './mcp/McpClient.js';
+export { UIManager } from './ui/UIManager.js';
+export { AvatarStage, MOODS, GESTURES, MOODS_2D, ALL_GESTURES, GESTURE_3D } from './avatar/AvatarStage.js';
+export { VoiceEngine } from './voice/VoiceEngine.js';
+export { ProxyLLM } from './llm/ProxyLLM.js';
+export { ApuchatBridge, createApuchatActions } from './integrations/apuchat.js';
+export { createApumailActions } from './integrations/apumail.js';
+export { defineIdentity, identityToWidgetConfig, publicIdentity, toVCard, IDENTITY_DEFAULTS, MEET_AVATARS, MEET_SCENES, OPENAI_VOICES, GROK_VOICES } from './identity/schema.js';
+export { randomIdentity, randomName, newSeed, cleanSeed } from './identity/random.js';
+import { createFace } from './identity/Face.js';
+import { IdentityCard } from './identity/ContactCard.js';
+import { defineIdentity } from './identity/schema.js';
+export { createFace, IdentityCard };
+export {
+  createCharacter, renderCharacter, normalizeCharacter, randomCharacter, applyPreset, DEFAULT_CHARACTER,
+  CHARACTER_MOODS, CHARACTER_GESTURES, CHARACTER_MORPHS, CHARACTER_EFFECTS, CHARACTER_GESTURE_ALIAS, VISEMES, textToVisemes, SHAPES, EYES, BROWS, MOUTHS, CHEEKS, PATTERNS, FINISHES, ACCESSORIES, ACCESSORY_GROUPS, PRESETS, partLabel,
+} from './character/Character.js';
+import { createAvatarEditor, AvatarEditor } from './character/AvatarEditor.js';
+import { renderCharacter as _renderCharacter, createCharacter as _createCharacter } from './character/Character.js';
+export { createAvatarEditor, AvatarEditor };
+
+export { t, translator, addMessages, addCatalog, resolveLocale, detectLocale, getLocale, setLocale, onLocaleChange, availableLocales, formatNumber, formatList, LOCALES, LOCALE_NAMES, DEFAULT_LOCALE } from './i18n/index.js';
+import { t as _t, translator as _translator, addMessages as _addMessages, setLocale as _setLocale, getLocale as _getLocale, LOCALES as _LOCALES } from './i18n/index.js';
+export const version = '0.1.0';
+
+let singleton = null;
+
+/**
+ * Crea (o devuelve) el agente de la página.
+ * @returns {ReturnType<AgentWidget['configure']>['api']}
+ */
+export function init(config = {}) {
+  if (singleton?.widget.isConnected) {
+    console.warn('[7ots] ya inicializado; se devuelve la instancia existente');
+    return singleton;
+  }
+  const el = document.createElement('ots-agent');
+  // Se inserta antes de configurar para que el Shadow DOM exista y el CSS se aplique.
+  (document.body || document.documentElement).appendChild(el);
+  el.configure(config);
+  singleton = el.api;
+  return singleton;
+}
+
+/** La instancia actual (o null). */
+export function get() {
+  return singleton;
+}
+
+// Global para el uso con <script> (y para depurar desde la consola).
+if (typeof window !== 'undefined') {
+  window.SevenOts = Object.assign(window.SevenOts || {}, { init, get, version, createFace, defineIdentity, createAvatarEditor, createCharacter: _createCharacter, renderCharacter: _renderCharacter, i18n: { t: _t, translator: _translator, addMessages: _addMessages, setLocale: _setLocale, getLocale: _getLocale, LOCALES: _LOCALES } });
+}

package/src/integrations/apuchat.js

@@ -0,0 +1,212 @@
+/**
+ * Integración Apuchat — derivar la conversación a una persona real.
+ *
+ * Flujo (sin claves en el navegador):
+ *
+ *   LLM → escalate_to_human({reason, summary})
+ *     → confirmación del usuario
+ *     → POST {endpoint}/contact/apuchat                 (proxy del sitio)
+ *         proxy → POST {hub}/api/video-call             crea un canal privado
+ *         proxy → entra al canal con la identidad del agente (relé)
+ *         proxy → POST {hub}/api/dm                     avisa al operador con su enlace
+ *         proxy ← {handoff_id, handoff_token, call_url_public}
+ *     → ApuchatBridge.join() → el widget pasa a "modo humano":
+ *         lo que escribe el usuario → POST {endpoint}/contact/apuchat/send
+ *         respuestas del operador  ← POST {endpoint}/contact/apuchat/wait (long-poll)
+ *     → Botón "Videollamada" abre call_url_public (voz/vídeo de apuchat).
+ *
+ * Todo pasa por el proxy: el hub no admite CORS desde sitios de terceros y las credenciales
+ * del canal no deben salir del servidor. El navegador solo guarda un id + token opacos del relé
+ * (en sessionStorage, para sobrevivir a navegaciones de página).
+ */
+
+import { acceptLanguage } from '../llm/ProxyLLM.js';
+import { translator } from '../i18n/index.js';
+import '../i18n/messages/widget.js';
+
+const MAX_MSG = 8192;
+
+export class ApuchatBridge {
+  /**
+   * @param {object} o
+   * @param {string} o.endpoint   proxy de 7ots (p. ej. '/api/agent')
+   * @param {string} [o.siteKey]
+   * @param {import('../core/EventBus.js').EventBus} o.bus
+   * @param {ReturnType<import('../core/storage.js').createStore>} o.store
+   * @param {(key: string, vars?: object) => string} [o.t]  traductor (avisos del chat; su `locale` va en Accept-Language)
+   */
+  constructor({ endpoint, siteKey, bus, store, t = translator() }) {
+    this.t = t;
+    this.base = `${endpoint.replace(/\/$/, '')}/contact/apuchat`;
+    this.siteKey = siteKey;
+    this.bus = bus;
+    this.store = store;
+    this.session = store.get('apuchat', null); // {id, token, since, call_url_public}
+    if (this.session && !this.session.token) this.session = null; // formato antiguo
+    this._stop = null;
+  }
+
+  get active() {
+    return !!this.session;
+  }
+
+  get callUrl() {
+    return this.session?.call_url_public || null;
+  }
+
+  /** Reanuda una sesión guardada (tras navegar de página). */
+  resume() {
+    if (this.session && !this._stop) this._loop();
+  }
+
+  /** @param {{handoff_id, handoff_token, call_url_public}} started  respuesta de /contact/apuchat */
+  join({ handoff_id, handoff_token, call_url_public }) {
+    this.session = { id: handoff_id, token: handoff_token, since: null, call_url_public: call_url_public || null };
+    this._save();
+    this._loop();
+    this.bus.emit('handoff:start', { callUrl: this.callUrl });
+  }
+
+  async send(text) {
+    if (!this.session) throw new Error('No hay conversación con una persona activa');
+    const res = await this._post('send', { text: String(text).slice(0, MAX_MSG) });
+    if (res.status === 404 || res.status === 410) {
+      this.end(this.t('widget.handoff.closed'));
+      throw new Error('canal cerrado');
+    }
+    if (!res.ok) throw new Error(`apuchat send ${res.status}`);
+  }
+
+  /** Long-poll (vía proxy) de mensajes del operador. */
+  _loop() {
+    let stopped = false;
+    const ctrl = new AbortController();
+    this._stop = () => {
+      stopped = true;
+      ctrl.abort();
+    };
+    const run = async () => {
+      let backoff = 1000;
+      while (!stopped && this.session) {
+        const s = this.session;
+        try {
+          const res = await this._post('wait', { since: s.since }, ctrl.signal);
+          if (res.status === 404 || res.status === 410) return this.end(this.t('widget.handoff.closed'));
+          if (!res.ok) throw new Error(`wait ${res.status}`);
+          const { messages = [], since, ended } = await res.json();
+          if (ended) return this.end(this.t('widget.handoff.closed'));
+          if (since != null) s.since = since;
+          for (const m of messages) this.bus.emit('handoff:message', { from: m.from, text: m.text });
+          this._save();
+          backoff = 1000;
+        } catch (err) {
+          if (stopped) return;
+          await new Promise((r) => setTimeout(r, backoff));
+          backoff = Math.min(backoff * 2, 15000);
+        }
+      }
+    };
+    run();
+  }
+
+  /** Termina el modo humano y vuelve al asistente. */
+  end(reason = '') {
+    this._stop?.();
+    this._stop = null;
+    if (!this.session) return;
+    const { id, token } = this.session;
+    this.session = null;
+    this.store.remove('apuchat');
+    // Best-effort: avisa al equipo y libera el relé (keepalive por si se cierra la página).
+    this._post('end', { id, token }, undefined, true).catch(() => {});
+    this.bus.emit('handoff:end', { reason });
+  }
+
+  /** Pausa el polling sin cerrar la sesión (antes de navegar). */
+  suspend() {
+    this._stop?.();
+    this._stop = null;
+  }
+
+  _post(path, data, signal, keepalive = false) {
+    const { id, token } = this.session || {};
+    return fetch(`${this.base}/${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(this.siteKey ? { 'X-Site-Key': this.siteKey } : {}), ...acceptLanguage(this.t.locale) },
+      body: JSON.stringify({ id, token, ...data }),
+      signal,
+      keepalive,
+    });
+  }
+
+  _save() {
+    this.store.set('apuchat', this.session);
+  }
+}
+
+/**
+ * Herramienta para el LLM + conexión del puente.
+ * @param {object} o
+ * @param {string} o.endpoint
+ * @param {string} [o.siteKey]
+ * @param {ApuchatBridge} o.bridge
+ * @param {() => Array<{from,text}>} o.getTranscript
+ * @param {(key: string, vars?: object) => string} [o.t]  traductor (por defecto, el del puente)
+ */
+export function createApuchatActions({ endpoint, siteKey, bridge, getTranscript, t = bridge?.t || translator() }) {
+  return [
+    {
+      name: 'escalate_to_human',
+      category: 'contact',
+      description:
+        'Conecta al usuario en vivo con una persona del equipo (chat en este mismo widget, con opción de videollamada) vía apuchat. ' +
+        'Úsalo si el usuario lo pide, si está frustrado, o si el caso requiere una persona (pagos, reclamaciones, excepciones). ' +
+        'Incluye un resumen para que la persona no tenga que volver a preguntar.',
+      parameters: {
+        type: 'object',
+        properties: {
+          reason: { type: 'string', description: 'Motivo en pocas palabras' },
+          summary: { type: 'string', description: 'Resumen del caso y lo que ya se intentó' },
+          urgency: { type: 'string', enum: ['baja', 'normal', 'alta'] },
+        },
+        required: ['reason', 'summary'],
+      },
+      confirm: () => t('widget.contact.humanConfirm'),
+      enabled: () => !bridge.active,
+      timeoutMs: 30000,
+      handler: async (args, { auth, ui }) => {
+        const user = auth?.publicUser() || null;
+        const res = await fetch(`${endpoint.replace(/\/$/, '')}/contact/apuchat`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...(siteKey ? { 'X-Site-Key': siteKey } : {}), ...acceptLanguage(t.locale) },
+          body: JSON.stringify({
+            reason: args.reason,
+            summary: args.summary,
+            urgency: args.urgency || 'normal',
+            user,
+            page: { url: location.href, title: document.title },
+            transcript: getTranscript().slice(-30),
+          }),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok) return { ok: false, error: body.error || `No se pudo contactar con soporte (HTTP ${res.status}). Ofrece dejar un correo.` };
+
+        bridge.join(body);
+        // Primer mensaje al operador, en el idioma del visitante (así sabe en cuál contestar).
+        await bridge
+          .send(t('widget.contact.handoffIntro', { name: user?.name || t('widget.contact.visitor'), reason: args.reason, summary: args.summary, url: location.href }))
+          .catch(() => {});
+        ui?.toast({ message: t('widget.contact.connected'), type: 'success' });
+        return {
+          ok: true,
+          data: {
+            connected: true,
+            operatorNotified: body.operatorNotified !== false,
+            note: 'El usuario ya está en el chat con una persona; tus próximos mensajes no serán necesarios hasta que vuelva. Despídete en una frase.',
+          },
+        };
+      },
+    },
+  ];
+}
+