@vaia-lab/sdk 0.1.3 → 0.3.0

package/dist/index.cjs

@@ -21,11 +21,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AGENT_PROTOCOL_VERSION: () => AGENT_PROTOCOL_VERSION,
+  CONNECTOR_OF_OPERATION: () => CONNECTOR_OF_OPERATION,
   VAIAError: () => VAIAError,
+  agentLoop: () => agentLoop,
+  capabilities: () => capabilities,
+  checkAuthority: () => checkAuthority,
   defineCapability: () => defineCapability,
+  defineEcosystem: () => defineEcosystem,
+  fromMCPTool: () => fromMCPTool,
   gandia: () => gandia,
   handeia: () => handeia,
-  toManifest: () => toManifest
+  http: () => http,
+  httpTransport: () => httpTransport,
+  local: () => local,
+  mcp: () => mcp,
+  mountAgent: () => mountAgent,
+  requiresApproval: () => requiresApproval,
+  toMCPTool: () => toMCPTool,
+  toMCPTools: () => toMCPTools,
+  toManifest: () => toManifest,
+  validateActionCall: () => validateActionCall,
+  validateAgentSurface: () => validateAgentSurface,
+  validatePieces: () => validatePieces
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -47,10 +65,12 @@ __export(gandia_exports, {
 // src/crypto.ts
 var enc = new TextEncoder();
 function hexToBytes(hex) {
-  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
-  const bytes = new Uint8Array(hex.length / 2);
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error("Invalid hex string");
+  }
+  const bytes = new Uint8Array(new ArrayBuffer(hex.length / 2));
   for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
   }
   return bytes;
 }
@@ -94,9 +114,7 @@ async function verify(request, secret) {
   const sigHeader = headers.get("x-gandia-signature") ?? "";
   const tsHeader = headers.get("x-gandia-timestamp") ?? "";
   const callId = headers.get("x-gandia-call-id") ?? "";
-  if (headers.get(PROBE_HEADER) === "1") {
-    return { ctx: buildProbeCtx(callId), raw: rawBody };
-  }
+  const esProbe = headers.get(PROBE_HEADER) === "1";
   if (!sigHeader || !tsHeader) {
     throw new VAIAError(
       "Faltan headers de autenticaci\xF3n (X-Gandia-Signature, X-Gandia-Timestamp)",
@@ -114,6 +132,9 @@ async function verify(request, secret) {
   if (!valid) {
     throw new VAIAError("Firma HMAC inv\xE1lida", "HMAC_INVALID", 401);
   }
+  if (esProbe) {
+    return { ctx: buildProbeCtx(callId), raw: rawBody };
+  }
   let body;
   try {
     body = JSON.parse(rawBody);
@@ -198,14 +219,28 @@ __export(jwt_exports, {
 
 // src/jwt-utils.ts
 var enc2 = new TextEncoder();
-function b64urlEncode(data) {
-  const str2 = typeof data === "string" ? data : String.fromCharCode(...new Uint8Array(data));
-  return btoa(str2).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+var utf8Strict = new TextDecoder("utf-8", { fatal: true });
+var utf8Loose = new TextDecoder("utf-8");
+var latin1 = new TextDecoder("latin1");
+var JWT_PAYLOAD_VERSION = 2;
+function bytesToB64url(bytes) {
+  let bin = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
-function b64urlDecode(str2) {
+function b64urlToBytes(str2) {
   const padded = str2.replace(/-/g, "+").replace(/_/g, "/");
   const pad = padded.length % 4;
-  return atob(pad ? padded + "=".repeat(4 - pad) : padded);
+  const bin = atob(pad ? padded + "=".repeat(4 - pad) : padded);
+  const out = new Uint8Array(new ArrayBuffer(bin.length));
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function textToB64url(text) {
+  return bytesToB64url(enc2.encode(text));
 }
 async function importHMACKey2(secret) {
   return crypto.subtle.importKey(
@@ -216,13 +251,33 @@ async function importHMACKey2(secret) {
     ["sign", "verify"]
   );
 }
-var HEADER = b64urlEncode(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+var HEADER = textToB64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
 async function jwtSign(payload, secret) {
-  const body = b64urlEncode(JSON.stringify(payload));
+  const body = textToB64url(JSON.stringify({ ...payload, v: JWT_PAYLOAD_VERSION }));
   const unsigned = `${HEADER}.${body}`;
   const key = await importHMACKey2(secret);
   const sig = await crypto.subtle.sign("HMAC", key, enc2.encode(unsigned));
-  return `${unsigned}.${b64urlEncode(sig)}`;
+  return `${unsigned}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+function decodePayload(body) {
+  const bytes = b64urlToBytes(body);
+  let sonda;
+  try {
+    sonda = JSON.parse(latin1.decode(bytes));
+  } catch {
+    throw new VAIAError("JWT payload inv\xE1lido", "JWT_PAYLOAD_INVALID", 401);
+  }
+  const version = typeof sonda["v"] === "number" ? sonda["v"] : 1;
+  if (version < 2) return sonda;
+  try {
+    return JSON.parse(utf8Strict.decode(bytes));
+  } catch {
+    try {
+      return JSON.parse(utf8Loose.decode(bytes));
+    } catch {
+      throw new VAIAError("JWT payload inv\xE1lido", "JWT_PAYLOAD_INVALID", 401);
+    }
+  }
 }
 async function jwtVerify(token, secret) {
   const parts = token.split(".");
@@ -232,17 +287,16 @@ async function jwtVerify(token, secret) {
   const [header, body, sig] = parts;
   const unsigned = `${header}.${body}`;
   const key = await importHMACKey2(secret);
-  const sigBytes = Uint8Array.from(b64urlDecode(sig), (c) => c.charCodeAt(0));
-  const valid = await crypto.subtle.verify("HMAC", key, sigBytes, enc2.encode(unsigned));
-  if (!valid) {
-    throw new VAIAError("Firma JWT inv\xE1lida", "JWT_SIGNATURE_INVALID", 401);
-  }
-  let payload;
+  let valid;
   try {
-    payload = JSON.parse(b64urlDecode(body));
+    valid = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), enc2.encode(unsigned));
   } catch {
-    throw new VAIAError("JWT payload inv\xE1lido", "JWT_PAYLOAD_INVALID", 401);
+    throw new VAIAError("JWT malformado", "JWT_MALFORMED", 401);
   }
+  if (!valid) {
+    throw new VAIAError("Firma JWT inv\xE1lida", "JWT_SIGNATURE_INVALID", 401);
+  }
+  const payload = decodePayload(body);
   if (typeof payload.exp === "number" && Date.now() / 1e3 > payload.exp) {
     throw new VAIAError("JWT expirado", "JWT_EXPIRED", 401);
   }
@@ -440,9 +494,7 @@ async function verify3(request, secret) {
   const sigHeader = headers.get("x-handeia-signature") ?? "";
   const tsHeader = headers.get("x-handeia-timestamp") ?? "";
   const callId = headers.get("x-handeia-call-id") ?? "";
-  if (headers.get(PROBE_HEADER2) === "1") {
-    return { ctx: buildProbeCtx2(callId), raw: rawBody };
-  }
+  const esProbe = headers.get(PROBE_HEADER2) === "1";
   if (!sigHeader || !tsHeader) {
     throw new VAIAError(
       "Faltan headers de autenticaci\xF3n (X-Handeia-Signature, X-Handeia-Timestamp)",
@@ -460,6 +512,9 @@ async function verify3(request, secret) {
   if (!valid) {
     throw new VAIAError("Firma HMAC inv\xE1lida", "HMAC_INVALID", 401);
   }
+  if (esProbe) {
+    return { ctx: buildProbeCtx2(callId), raw: rawBody };
+  }
   let body;
   try {
     body = JSON.parse(rawBody);
@@ -543,6 +598,154 @@ async function fromUrl2(url, secret) {
   return verify4(token, secret);
 }
 
+// src/agent.ts
+var AGENT_PROTOCOL_VERSION = 1;
+var CONNECTOR_OF_OPERATION = {
+  "github.repos": "github",
+  "github.issues": "github",
+  "drive.files": "drive",
+  "calendar.events": "calendar",
+  "email.recent": "email",
+  "notion.pages": "notion"
+};
+var NOMBRE_ACCION = /^[a-z][a-z0-9_]{1,48}$/;
+function validateAgentSurface(cfg) {
+  const errores = [];
+  const vistos = /* @__PURE__ */ new Set();
+  for (const accion of cfg.actions ?? []) {
+    if (!NOMBRE_ACCION.test(accion.name)) {
+      errores.push(`Acci\xF3n "${accion.name}": el nombre debe ser min\xFAsculas, n\xFAmeros o guion bajo.`);
+    }
+    if (vistos.has(accion.name)) {
+      errores.push(`Acci\xF3n "${accion.name}": declarada dos veces.`);
+    }
+    vistos.add(accion.name);
+    if (!accion.description?.trim()) {
+      errores.push(`Acci\xF3n "${accion.name}": falta la descripci\xF3n, que es lo que el agente lee para elegirla.`);
+    }
+    if (accion.writes && !accion.permission) {
+      errores.push(`Acci\xF3n "${accion.name}": modifica datos, as\xED que necesita un permiso declarado.`);
+    }
+    for (const p of accion.params ?? []) {
+      if (!p.name?.trim()) errores.push(`Acci\xF3n "${accion.name}": un par\xE1metro no tiene nombre.`);
+      if (!p.description?.trim()) {
+        errores.push(`Acci\xF3n "${accion.name}", par\xE1metro "${p.name}": falta la descripci\xF3n.`);
+      }
+    }
+  }
+  if (cfg.queryEndpoint && !cfg.queryEndpoint.startsWith("/")) {
+    errores.push('queryEndpoint debe ser una ruta de tu propio servidor, empezando por "/".');
+  }
+  return errores;
+}
+function validateActionCall(llamada, declaradas) {
+  const action = declaradas.find((a) => a.name === llamada.name);
+  if (!action) return { ok: false, reason: `La acci\xF3n "${llamada.name}" no est\xE1 declarada por el espacio.` };
+  const args = llamada.args ?? {};
+  for (const p of action.params ?? []) {
+    const v = args[p.name];
+    if (v === void 0 || v === null) {
+      if (p.required) return { ok: false, reason: `Falta el par\xE1metro obligatorio "${p.name}".` };
+      continue;
+    }
+    if (typeof v !== p.type) {
+      return { ok: false, reason: `El par\xE1metro "${p.name}" debe ser ${p.type}.` };
+    }
+    if (p.enum && !p.enum.includes(String(v))) {
+      return { ok: false, reason: `El par\xE1metro "${p.name}" no admite el valor "${String(v)}".` };
+    }
+  }
+  const permitidos = new Set((action.params ?? []).map((p) => p.name));
+  for (const k of Object.keys(args)) {
+    if (!permitidos.has(k)) return { ok: false, reason: `El par\xE1metro "${k}" no est\xE1 declarado.` };
+  }
+  return { ok: true, action };
+}
+
+// src/pieces.ts
+var NOMBRE = /^[a-z][a-z0-9_]{1,48}$/;
+var ORDEN = {
+  prohibida: 0,
+  requiere_aprobacion: 1,
+  autonoma: 2
+};
+function validatePieces(cfg) {
+  const errores = [];
+  const vistos = /* @__PURE__ */ new Set();
+  const revisarNombre = (pieza, name) => {
+    if (!NOMBRE.test(name)) errores.push(`${pieza} "${name}": el nombre debe ser min\xFAsculas, n\xFAmeros o guion bajo.`);
+    if (vistos.has(name)) errores.push(`"${name}": hay dos piezas con el mismo nombre.`);
+    vistos.add(name);
+  };
+  const revisarAutoridad = (pieza, a) => {
+    if (a.consequence === "irreversible" && a.level === "autonoma") {
+      errores.push(`${pieza}: una acci\xF3n irreversible no puede ser aut\xF3noma \u2014 como m\xEDnimo requiere aprobaci\xF3n.`);
+    }
+    if (a.maxAmount !== void 0) {
+      if (a.maxAmount <= 0) errores.push(`${pieza}: el tope de gasto debe ser mayor que cero.`);
+      if (!a.currency) errores.push(`${pieza}: hay tope de gasto pero no se declar\xF3 la moneda.`);
+    }
+    if (a.consequence === "costosa" && a.level === "autonoma" && a.maxAmount === void 0) {
+      errores.push(`${pieza}: es aut\xF3noma y cuesta dinero, as\xED que necesita un tope declarado.`);
+    }
+  };
+  for (const s2 of cfg.skills ?? []) {
+    revisarNombre("Skill", s2.name);
+    if (!s2.description?.trim()) errores.push(`Skill "${s2.name}": falta la descripci\xF3n, que es lo que el modelo lee para elegirla.`);
+    if (s2.evidence?.required && (s2.evidence.accepts?.length ?? 0) === 0) {
+      errores.push(`Skill "${s2.name}": exige evidencia pero no declara qu\xE9 tipos acepta.`);
+    }
+  }
+  for (const t of cfg.tools ?? []) {
+    revisarNombre("Herramienta", t.name);
+    if (!t.description?.trim()) errores.push(`Herramienta "${t.name}": falta la descripci\xF3n.`);
+    if (!t.permission?.trim()) errores.push(`Herramienta "${t.name}": toca el mundo real, as\xED que necesita un permiso declarado.`);
+    revisarAutoridad(`Herramienta "${t.name}"`, t.authority);
+  }
+  for (const w of cfg.workflows ?? []) {
+    revisarNombre("Workflow", w.name);
+    if ((w.steps?.length ?? 0) === 0) errores.push(`Workflow "${w.name}": no tiene pasos.`);
+    revisarAutoridad(`Workflow "${w.name}"`, w.authority);
+  }
+  const porNombre = new Map((cfg.tools ?? []).map((t) => [t.name, t]));
+  for (const a of cfg.agents ?? []) {
+    revisarNombre("Agente", a.name);
+    if (!a.purpose?.trim()) {
+      errores.push(`Agente "${a.name}": falta el prop\xF3sito \u2014 para qu\xE9 existe.`);
+    }
+    revisarAutoridad(`Agente "${a.name}"`, a.authority);
+    for (const nombreTool of a.tools ?? []) {
+      const tool = porNombre.get(nombreTool);
+      if (!tool) {
+        errores.push(`Agente "${a.name}": usa la herramienta "${nombreTool}", que no est\xE1 declarada.`);
+        continue;
+      }
+      if (ORDEN[tool.authority.level] > ORDEN[a.authority.level]) {
+        errores.push(
+          `Agente "${a.name}": su herramienta "${nombreTool}" tiene m\xE1s autoridad que \xE9l. Ninguna pieza puede superar el techo de su agente.`
+        );
+      }
+    }
+  }
+  return errores;
+}
+function requiresApproval(a) {
+  return a.level !== "autonoma";
+}
+function checkAuthority(a, intento = {}) {
+  if (a.level === "prohibida") return { ok: false, reason: "Esta acci\xF3n est\xE1 prohibida para esta pieza." };
+  if (intento.amount !== void 0) {
+    if (a.maxAmount === void 0) return { ok: false, reason: "Mueve dinero pero no hay tope declarado." };
+    if (intento.currency && a.currency && intento.currency !== a.currency) {
+      return { ok: false, reason: `Moneda distinta a la declarada (${a.currency}).` };
+    }
+    if (intento.amount > a.maxAmount) {
+      return { ok: false, reason: `Excede el tope declarado (${a.maxAmount} ${a.currency ?? ""}).`.trim() };
+    }
+  }
+  return { ok: true };
+}
+
 // src/define.ts
 function defineCapability(config) {
   const required = ["id", "name", "version", "target", "type", "sector", "permissions", "risk"];
@@ -559,6 +762,20 @@ function defineCapability(config) {
   if (Object.keys(config.surfaces).length === 0) {
     throw new Error(`[@vaia/sdk] defineCapability: 'surfaces' no puede estar vac\xEDo. Define al menos un surface con su endpoint.`);
   }
+  if (config.pieces) {
+    const errores = validatePieces(config.pieces);
+    if (errores.length > 0) {
+      throw new Error(`[@vaia/sdk] defineCapability: piezas inv\xE1lidas:
+  - ${errores.join("\n  - ")}`);
+    }
+  }
+  if (config.agent) {
+    const errores = validateAgentSurface(config.agent);
+    if (errores.length > 0) {
+      throw new Error(`[@vaia/sdk] defineCapability: superficie de agente inv\xE1lida:
+  - ${errores.join("\n  - ")}`);
+    }
+  }
   return config;
 }
 function toManifest(config) {
@@ -573,6 +790,16 @@ function toManifest(config) {
     level: config.level,
     sector: config.sector,
     surfaces,
+    // El agente viaja en el manifest para que el portal y Handeia sepan qué
+    // puede hacer este espacio sin abrir su código.
+    agent: config.agent ? {
+      protocol: AGENT_PROTOCOL_VERSION,
+      actions: config.agent.actions ?? [],
+      query_endpoint: config.agent.queryEndpoint
+    } : void 0,
+    // Las piezas viajan al manifest: el portal necesita mostrar qué autoridad
+    // pide una capacidad ANTES de que alguien la instale.
+    pieces: config.pieces,
     permissions: config.permissions,
     risk: config.risk,
     has_own_auth: config.has_own_auth ?? false,
@@ -587,15 +814,507 @@ function toManifest(config) {
   };
 }
 
+// src/agent-mount.ts
+var HANDEIA_POR_DEFECTO = "https://handeia.com";
+var RUTA_TURNO = "/api/agent/space";
+var CSS = `
+.hdi-agent-root{position:fixed;z-index:2147483000;bottom:20px;right:20px;font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+.hdi-agent-orb{width:44px;height:44px;border-radius:9999px;border:0;cursor:pointer;background:#000;color:#fff;display:flex;align-items:center;justify-content:center;box-shadow:0 10px 30px -6px rgba(0,0,0,.4);transition:transform .15s}
+.hdi-agent-orb:hover{transform:scale(1.05)}
+.hdi-agent-orb:active{transform:scale(.95)}
+.hdi-agent-panel{position:absolute;bottom:56px;right:0;width:min(360px,calc(100vw - 40px));background:#fff;color:#111;border:1px solid rgba(0,0,0,.09);border-radius:18px;box-shadow:0 24px 60px -18px rgba(0,0,0,.32);overflow:hidden;display:flex;flex-direction:column;max-height:min(60vh,460px)}
+.hdi-agent-head{display:flex;align-items:center;gap:8px;padding:12px 14px;border-bottom:1px solid rgba(0,0,0,.06);font-size:12.5px;font-weight:600}
+.hdi-agent-dot{width:7px;height:7px;border-radius:9999px;background:#8b5cf6}
+.hdi-agent-log{flex:1;overflow-y:auto;padding:12px 14px;display:flex;flex-direction:column;gap:10px;font-size:13px;line-height:1.55}
+.hdi-agent-turn{white-space:pre-wrap}
+.hdi-agent-q{font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:rgba(0,0,0,.34)}
+.hdi-agent-form{display:flex;gap:8px;padding:10px 12px;border-top:1px solid rgba(0,0,0,.06)}
+.hdi-agent-input{flex:1;border:1px solid rgba(0,0,0,.12);border-radius:10px;padding:8px 10px;font:inherit;font-size:13px;outline:none}
+.hdi-agent-input:focus{border-color:rgba(0,0,0,.34)}
+.hdi-agent-send{border:0;border-radius:10px;padding:0 12px;background:#000;color:#fff;cursor:pointer;font-size:12.5px}
+.hdi-agent-confirm{display:flex;gap:8px;margin-top:4px}
+.hdi-agent-btn{border:1px solid rgba(0,0,0,.14);background:#fff;border-radius:9999px;padding:5px 12px;font-size:12px;cursor:pointer}
+.hdi-agent-btn-primary{background:#000;color:#fff;border-color:#000}
+@media (prefers-color-scheme:dark){
+.hdi-agent-orb{background:#fff;color:#000}
+.hdi-agent-panel{background:#171717;color:#f5f5f5;border-color:rgba(255,255,255,.13)}
+.hdi-agent-head,.hdi-agent-form{border-color:rgba(255,255,255,.1)}
+.hdi-agent-q{color:rgba(255,255,255,.5)}
+.hdi-agent-input{background:transparent;color:inherit;border-color:rgba(255,255,255,.16)}
+.hdi-agent-send{background:#fff;color:#000}
+.hdi-agent-btn{background:transparent;color:inherit;border-color:rgba(255,255,255,.18)}
+.hdi-agent-btn-primary{background:#fff;color:#000}
+}`;
+function el(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== void 0) n.textContent = text;
+  return n;
+}
+function mountAgent(opts) {
+  if (typeof document === "undefined") {
+    throw new Error("[@vaia-lab/sdk] mountAgent solo corre en el navegador.");
+  }
+  const base = (opts.handeiaUrl ?? HANDEIA_POR_DEFECTO).replace(/\/$/, "");
+  const contenedor = opts.container ?? document.body;
+  const previo = contenedor.querySelector(".hdi-agent-root");
+  if (previo) previo.remove();
+  if (!document.getElementById("hdi-agent-css")) {
+    const estilo = el("style");
+    estilo.id = "hdi-agent-css";
+    estilo.textContent = CSS;
+    document.head.appendChild(estilo);
+  }
+  const raiz = el("div", "hdi-agent-root");
+  const orbe = el("button", "hdi-agent-orb");
+  orbe.type = "button";
+  orbe.setAttribute("aria-label", "Abrir asistente de Handeia");
+  orbe.textContent = "\u2726";
+  const panel = el("div", "hdi-agent-panel");
+  panel.hidden = true;
+  panel.setAttribute("role", "dialog");
+  panel.setAttribute("aria-label", "Asistente de Handeia");
+  const cabeza = el("div", "hdi-agent-head");
+  cabeza.appendChild(el("span", "hdi-agent-dot"));
+  cabeza.appendChild(el("span", void 0, "Handeia"));
+  const registro = el("div", "hdi-agent-log");
+  if (opts.greeting) registro.appendChild(el("div", "hdi-agent-turn", opts.greeting));
+  const forma = el("form", "hdi-agent-form");
+  const entrada = el("input", "hdi-agent-input");
+  entrada.type = "text";
+  entrada.placeholder = "Preg\xFAntale a Handeia\u2026";
+  entrada.autocomplete = "off";
+  const enviar = el("button", "hdi-agent-send", "Enviar");
+  enviar.type = "submit";
+  forma.append(entrada, enviar);
+  panel.append(cabeza, registro, forma);
+  raiz.append(panel, orbe);
+  contenedor.appendChild(raiz);
+  const historial = [];
+  const decir = (texto, clase = "hdi-agent-turn") => {
+    const n = el("div", clase, texto);
+    registro.appendChild(n);
+    registro.scrollTop = registro.scrollHeight;
+    return n;
+  };
+  async function turno(mensaje, actionResult) {
+    let context;
+    try {
+      context = await opts.getContext?.();
+    } catch {
+      context = void 0;
+    }
+    let res;
+    try {
+      res = await fetch(`${base}${RUTA_TURNO}`, {
+        method: "POST",
+        // La identidad va en la cookie de sesión de Handeia. El espacio nunca
+        // toca ni ve el token del usuario.
+        credentials: "include",
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+        body: JSON.stringify({
+          protocol: AGENT_PROTOCOL_VERSION,
+          capId: opts.capabilityId,
+          message: mensaje,
+          context,
+          actions: opts.actions ?? [],
+          history: historial.slice(-12),
+          actionResult
+        })
+      });
+    } catch {
+      decir("No pude comunicarme con Handeia. Revisa tu conexi\xF3n.");
+      return;
+    }
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      decir("Handeia respondi\xF3 algo que no pude leer.");
+      return;
+    }
+    if (!res.ok || data.ok === false) {
+      decir(
+        data.error === "no_autenticado" ? "Inicia sesi\xF3n en Handeia para usar el asistente." : data.error === "espacio_no_instalado" ? "Este espacio no est\xE1 instalado en tu Handeia." : "Handeia no pudo responder ahora mismo."
+      );
+      return;
+    }
+    if (data.text) {
+      decir(data.text);
+      historial.push({ role: "agent", text: data.text });
+    }
+    if (!data.action) return;
+    if (!opts.onAction) {
+      decir("Esto requiere una acci\xF3n que este espacio todav\xEDa no sabe ejecutar.");
+      return;
+    }
+    const ejecutar = async () => {
+      let resultado;
+      try {
+        resultado = await opts.onAction(data.action.name, data.action.args ?? {});
+      } catch (e) {
+        resultado = { action: data.action.name, ok: false, error: e instanceof Error ? e.message : "fall\xF3" };
+      }
+      await turno(mensaje, resultado);
+    };
+    if (data.confirm) {
+      const fila = el("div", "hdi-agent-confirm");
+      const si = el("button", "hdi-agent-btn hdi-agent-btn-primary", "Hacerlo");
+      const no = el("button", "hdi-agent-btn", "Cancelar");
+      si.type = "button";
+      no.type = "button";
+      si.onclick = () => {
+        fila.remove();
+        void ejecutar();
+      };
+      no.onclick = () => {
+        fila.remove();
+        decir("Cancelado.");
+      };
+      fila.append(si, no);
+      registro.appendChild(fila);
+      registro.scrollTop = registro.scrollHeight;
+      return;
+    }
+    await ejecutar();
+  }
+  forma.onsubmit = async (e) => {
+    e.preventDefault();
+    const texto = entrada.value.trim();
+    if (!texto) return;
+    entrada.value = "";
+    decir(texto, "hdi-agent-q");
+    historial.push({ role: "user", text: texto });
+    enviar.disabled = true;
+    try {
+      await turno(texto);
+    } finally {
+      enviar.disabled = false;
+      entrada.focus();
+    }
+  };
+  const abrir = () => {
+    panel.hidden = false;
+    entrada.focus();
+  };
+  const cerrar = () => {
+    panel.hidden = true;
+  };
+  orbe.onclick = () => panel.hidden ? abrir() : cerrar();
+  const alTeclear = (e) => {
+    if (e.key === "Escape") cerrar();
+  };
+  document.addEventListener("keydown", alTeclear);
+  return {
+    open: abrir,
+    close: cerrar,
+    destroy: () => {
+      document.removeEventListener("keydown", alTeclear);
+      raiz.remove();
+    }
+  };
+}
+
+// src/capabilities.ts
+async function conAutoridad(tools, call, ejecutar) {
+  const tool = tools.find((t) => t.name === call.name);
+  if (!tool) {
+    return { ok: false, error: `La operaci\xF3n "${call.name}" no est\xE1 declarada en esta capacidad.` };
+  }
+  const permitido = checkAuthority(tool.authority, {
+    amount: call.amount,
+    currency: call.currency
+  });
+  if (!permitido.ok) return { ok: false, error: permitido.reason };
+  if (tool.authority.level === "prohibida") {
+    return { ok: false, error: `"${call.name}" est\xE1 prohibida.` };
+  }
+  if (tool.authority.level !== "autonoma" && !call.approved) {
+    return { ok: false, needsApproval: true, error: "Requiere aprobaci\xF3n humana antes de ejecutarse." };
+  }
+  try {
+    return await ejecutar();
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : "La capacidad fall\xF3." };
+  }
+}
+function local(opts) {
+  return {
+    id: opts.id,
+    tools: opts.tools,
+    run: (call) => conAutoridad(opts.tools, call, async () => ({
+      ok: true,
+      data: await opts.handler(call.name, call.args ?? {}),
+      evidence: { source: "local", label: opts.id }
+    }))
+  };
+}
+function http(opts) {
+  const base = opts.baseUrl.replace(/\/$/, "");
+  return {
+    id: opts.id,
+    tools: opts.tools,
+    run: (call) => conAutoridad(opts.tools, call, async () => {
+      const res = await fetch(`${base}/${call.name}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json; charset=utf-8", ...opts.headers },
+        body: JSON.stringify(call.args ?? {}),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 15e3)
+      });
+      const texto = await res.text();
+      if (!res.ok) return { ok: false, error: `${opts.id} respondi\xF3 ${res.status}` };
+      let data;
+      try {
+        data = JSON.parse(texto);
+      } catch {
+        data = texto;
+      }
+      return { ok: true, data, evidence: { source: "http", label: `${opts.id}/${call.name}` } };
+    })
+  };
+}
+function httpTransport(url, headers) {
+  return {
+    async send(mensaje) {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json", ...headers },
+        body: JSON.stringify(mensaje),
+        signal: AbortSignal.timeout(2e4)
+      });
+      if (!res.ok) throw new VAIAError(`Servidor MCP respondi\xF3 ${res.status}`, "MCP_HTTP_ERROR", 502);
+      return res.json();
+    }
+  };
+}
+var PROHIBIDA = { level: "prohibida", consequence: "irreversible" };
+async function mcp(opts) {
+  let siguienteId = 1;
+  const rpc = async (method, params) => {
+    const r = await opts.transport.send({
+      jsonrpc: "2.0",
+      id: siguienteId++,
+      method,
+      ...params ? { params } : {}
+    });
+    if (r?.["error"]) {
+      const e = r["error"];
+      throw new VAIAError(e?.message ?? "Error del servidor MCP", "MCP_ERROR", 502);
+    }
+    return r?.["result"] ?? {};
+  };
+  await rpc("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "@vaia-lab/sdk", version: "0.3.0" }
+  });
+  const listadas = (await rpc("tools/list"))["tools"] ?? [];
+  const tools = listadas.map((t) => ({
+    name: normalizar(t.name),
+    description: t.description?.trim() || `Herramienta MCP "${t.name}".`,
+    authority: opts.authority[t.name] ?? opts.defaultAuthority ?? PROHIBIDA,
+    permission: opts.permission ?? `mcp:${opts.id}`
+  }));
+  const original = new Map(listadas.map((t) => [normalizar(t.name), t.name]));
+  return {
+    id: opts.id,
+    tools,
+    run: (call) => conAutoridad(tools, call, async () => {
+      const nombreReal = original.get(call.name) ?? call.name;
+      const r = await rpc("tools/call", { name: nombreReal, arguments: call.args ?? {} });
+      return {
+        ok: !r["isError"],
+        data: r["content"] ?? r,
+        error: r["isError"] ? "La herramienta MCP devolvi\xF3 un error." : void 0,
+        evidence: { source: "mcp", label: `${opts.id}/${nombreReal}` }
+      };
+    }),
+    dispose: () => opts.transport.close?.()
+  };
+}
+function normalizar(n) {
+  return n.toLowerCase().replace(/[^a-z0-9_]/g, "_").replace(/_+/g, "_").slice(0, 48);
+}
+var capabilities = { local, http, mcp, httpTransport };
+
+// src/ecosystem.ts
+function coincide(patron, nombre) {
+  if (patron === "*") return true;
+  if (patron.endsWith("*")) return nombre.startsWith(patron.slice(0, -1));
+  return patron === nombre;
+}
+var ORDEN2 = { prohibida: 0, requiere_aprobacion: 1, autonoma: 2 };
+function aplicarReglas(tool, reglas) {
+  if (!reglas) return tool;
+  let resultado = tool.authority;
+  for (const [patron, regla] of Object.entries(reglas)) {
+    if (!coincide(patron, tool.name)) continue;
+    if (ORDEN2[regla.level] < ORDEN2[resultado.level]) resultado = regla;
+    else if (regla.maxAmount !== void 0 && (resultado.maxAmount === void 0 || regla.maxAmount < resultado.maxAmount)) {
+      resultado = { ...resultado, maxAmount: regla.maxAmount, currency: regla.currency ?? resultado.currency };
+    }
+  }
+  return { ...tool, authority: resultado };
+}
+function defineEcosystem(cfg) {
+  const caps = new Map(cfg.capabilities.map((c) => [c.id, c]));
+  const recopilar = () => [...caps.values()].flatMap(
+    (c) => c.tools.map((t) => ({ ...aplicarReglas(t, cfg.authority), capability: c.id }))
+  );
+  let tools = recopilar();
+  return {
+    name: cfg.name,
+    get tools() {
+      return tools;
+    },
+    async run(call) {
+      const due\u00F1o = [...caps.values()].find((c) => c.tools.some((t) => t.name === call.name));
+      if (!due\u00F1o) {
+        return { ok: false, error: `Ninguna capacidad de "${cfg.name}" declara "${call.name}".` };
+      }
+      const conReglas = tools.find((t) => t.name === call.name);
+      if (conReglas && conReglas.authority.level === "prohibida") {
+        return { ok: false, error: `"${call.name}" est\xE1 prohibida por las reglas de ${cfg.name}.` };
+      }
+      if (conReglas && conReglas.authority.level !== "autonoma" && !call.approved) {
+        return { ok: false, needsApproval: true, error: "Requiere aprobaci\xF3n humana antes de ejecutarse." };
+      }
+      return due\u00F1o.run(call);
+    },
+    add(capability) {
+      caps.set(capability.id, capability);
+      tools = recopilar();
+    },
+    async remove(capabilityId) {
+      const c = caps.get(capabilityId);
+      if (!c) return;
+      await c.dispose?.();
+      caps.delete(capabilityId);
+      tools = recopilar();
+    },
+    async dispose() {
+      for (const c of caps.values()) await c.dispose?.();
+      caps.clear();
+      tools = [];
+    }
+  };
+}
+async function agentLoop(opts) {
+  const maxSteps = opts.maxSteps ?? 6;
+  return async function turno(message, history = []) {
+    const steps = [];
+    let lastResult;
+    for (let i = 0; i < maxSteps; i++) {
+      const salida = await opts.model({
+        message,
+        tools: opts.ecosystem.tools.map((t) => ({ name: t.name, description: t.description })),
+        history,
+        lastResult
+      });
+      if (!salida.action) return { text: salida.text, steps };
+      let resultado = await opts.ecosystem.run(salida.action);
+      if (resultado.needsApproval && opts.onApproval) {
+        const aprobado = await opts.onApproval(salida.action.name, salida.action.args ?? {});
+        if (aprobado) {
+          resultado = await ejecutarAprobado(opts.ecosystem, salida.action);
+        } else {
+          resultado = { ok: false, error: "El usuario no lo autoriz\xF3." };
+        }
+      }
+      steps.push({ action: salida.action.name, ok: resultado.ok, error: resultado.error });
+      lastResult = resultado;
+    }
+    return { text: "No pude completarlo en los pasos disponibles.", steps };
+  };
+}
+async function ejecutarAprobado(eco, action) {
+  const t = eco.tools.find((x) => x.name === action.name);
+  if (!t) return { ok: false, error: "La herramienta ya no existe." };
+  if (t.authority.level === "prohibida") {
+    return { ok: false, error: "Prohibida: ni con aprobaci\xF3n se ejecuta." };
+  }
+  return eco.run({ ...action, approved: true });
+}
+
+// src/mcp.ts
+function fromMCPTool(tool, authority, permission) {
+  const warnings = [];
+  if (tool.annotations?.destructiveHint && authority.consequence === "reversible") {
+    warnings.push(
+      `"${tool.name}": el servidor MCP la marca como destructiva, pero se declar\xF3 como reversible. Rev\xEDsalo.`
+    );
+  }
+  if (tool.annotations?.readOnlyHint === false && authority.level === "autonoma") {
+    warnings.push(
+      `"${tool.name}": escribe y se le dio autoridad aut\xF3noma. Aseg\xFArate de que sea lo que quieres.`
+    );
+  }
+  if (!tool.description?.trim()) {
+    warnings.push(`"${tool.name}": el servidor MCP no la describe, as\xED que el agente no sabr\xE1 cu\xE1ndo usarla.`);
+  }
+  return {
+    tool: {
+      // Prefijo para que se vea de dónde viene y no choque con lo propio.
+      name: normalizarNombre(`mcp_${tool.name}`),
+      description: tool.description?.trim() || `Herramienta MCP "${tool.name}" (sin descripci\xF3n del servidor).`,
+      authority,
+      permission
+    },
+    warnings
+  };
+}
+function toMCPTool(tool) {
+  if (tool.authority.level !== "autonoma") return null;
+  return {
+    name: tool.name,
+    description: tool.description,
+    annotations: {
+      readOnlyHint: tool.authority.consequence === "reversible",
+      destructiveHint: tool.authority.consequence === "irreversible",
+      idempotentHint: false
+    }
+  };
+}
+function toMCPTools(tools) {
+  const published = [];
+  const withheld = [];
+  for (const t of tools) {
+    const m = toMCPTool(t);
+    if (m) published.push(m);
+    else withheld.push(t.name);
+  }
+  return { published, withheld };
+}
+function normalizarNombre(n) {
+  return n.toLowerCase().replace(/[^a-z0-9_]/g, "_").replace(/_+/g, "_").slice(0, 48);
+}
+
 // src/index.ts
 var gandia = gandia_exports;
 var handeia = handeia_exports;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_PROTOCOL_VERSION,
+  CONNECTOR_OF_OPERATION,
   VAIAError,
+  agentLoop,
+  capabilities,
+  checkAuthority,
   defineCapability,
+  defineEcosystem,
+  fromMCPTool,
   gandia,
   handeia,
-  toManifest
+  http,
+  httpTransport,
+  local,
+  mcp,
+  mountAgent,
+  requiresApproval,
+  toMCPTool,
+  toMCPTools,
+  toManifest,
+  validateActionCall,
+  validateAgentSurface,
+  validatePieces
 });
-//# sourceMappingURL=index.cjs.map