@vaia-lab/sdk 0.2.0 → 0.4.0

package/dist/index.js

@@ -23,10 +23,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;
 }
@@ -70,9 +72,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)",
@@ -90,6 +90,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);
@@ -449,9 +452,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)",
@@ -469,6 +470,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);
@@ -552,6 +556,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"];
@@ -568,6 +720,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) {
@@ -582,6 +748,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,
@@ -596,14 +772,304 @@ function toManifest(config) {
   };
 }
 
+// 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;
 export {
+  AGENT_PROTOCOL_VERSION,
+  CONNECTOR_OF_OPERATION,
   VAIAError,
+  agentLoop,
+  capabilities,
+  checkAuthority,
   defineCapability,
+  defineEcosystem,
+  fromMCPTool,
   gandia,
   handeia,
-  toManifest
+  http,
+  httpTransport,
+  local,
+  mcp,
+  requiresApproval,
+  toMCPTool,
+  toMCPTools,
+  toManifest,
+  validateActionCall,
+  validateAgentSurface,
+  validatePieces
 };
-//# sourceMappingURL=index.js.map