@vaia-lab/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,384 @@
+/**
+ * Las 7 piezas operativas del ecosistema VAIA.
+ *
+ *   Skills          → capacidades atómicas verificadas
+ *   Agentes         → entidades persistentes con objetivos y autoridad
+ *   Herramientas    → acciones permitidas en el mundo real
+ *   Workflows       → procesos multi-paso
+ *   Modalidades     → cómo entra y sale la información
+ *   Personalidades  → estilos de comunicación
+ *   Permisos        → quién puede qué, sobre qué, cuándo
+ *
+ * Este archivo NO las implementa: las declara. El motor que las ejecuta es
+ * privado; lo público es la forma de describirlas y las reglas que deben
+ * cumplir para poder existir.
+ *
+ * ── Lo que separa esto de otros SDK de agentes ───────────────────────────
+ * Casi todos saben decir "el agente puede llamar a esta función". Ninguno sabe
+ * decir "puede hasta $500 solo, arriba de eso pregunta, y nunca puede borrar".
+ * Esa es la parte que aquí es obligatoria, no opcional: un agente sin autoridad
+ * declarada ni siquiera compila.
+ */
+/**
+ * Qué tan lejos puede llegar algo por su cuenta.
+ *
+ * No es un booleano "puede o no puede". La autoridad se delega como a una
+ * persona: por categoría, por monto y por consecuencia.
+ */
+type AuthorityLevel = 
+/** Lo hace solo. Reservado a lo que no tiene consecuencia irreversible. */
+'autonoma'
+/** Lo prepara, pero un humano aprueba antes de que ocurra. */
+ | 'requiere_aprobacion'
+/** No puede, nunca, aunque el usuario lo pida. */
+ | 'prohibida';
+/** Qué tan grave es equivocarse aquí. Decide cuánta ceremonia merece. */
+type Consequence = 'reversible' | 'costosa' | 'irreversible';
+interface Authority {
+    level: AuthorityLevel;
+    consequence: Consequence;
+    /** Tope de gasto por ejecución, si mueve dinero. */
+    maxAmount?: number | undefined;
+    /** Moneda del tope. Obligatoria si hay tope: "500" sin moneda no significa nada. */
+    currency?: string | undefined;
+    /** Cuántas veces por hora, como mucho. */
+    maxPerHour?: number | undefined;
+    /** Por qué se delegó así. Se le muestra al usuario cuando concede. */
+    rationale?: string | undefined;
+}
+/**
+ * De dónde sale lo que el sistema afirma.
+ *
+ * Es obligatoria en todo lo que produzca una afirmación. Un asistente que no
+ * puede decir de dónde sacó algo es un oráculo, y un oráculo no se audita ni
+ * se corrige. Este es el pilar de info verificada hecho tipo.
+ */
+type EvidenceKind = 'fuente' | 'calculo' | 'usuario' | 'externo' | 'inferencia';
+interface EvidencePolicy {
+    /** Tipos admitidos para respaldar una afirmación de esta pieza. */
+    accepts: EvidenceKind[];
+    /**
+     * Si es true, una respuesta sin evidencia se rechaza en vez de entregarse.
+     * Debe estar en true en cualquier cosa que informe decisiones reales.
+     */
+    required: boolean;
+}
+interface PiezaBase {
+    /** Estable, en minúsculas con guion bajo. */
+    name: string;
+    /** Qué es y cuándo usarlo. Es lo que lee el modelo para decidir. */
+    description: string;
+}
+/** Capacidad atómica y verificable. El verbo del sistema. */
+interface SkillDef extends PiezaBase {
+    /** Qué necesita recibir. */
+    inputs?: {
+        name: string;
+        type: 'string' | 'number' | 'boolean';
+        required?: boolean | undefined;
+    }[] | undefined;
+    /** Cómo se comprueba que salió bien. Sin esto no es "verificada". */
+    verification?: string | undefined;
+    evidence?: EvidencePolicy | undefined;
+}
+/** Acción sobre el mundo real. Siempre lleva autoridad. */
+interface ToolDef extends PiezaBase {
+    authority: Authority;
+    /** Permiso que el usuario debe conceder. */
+    permission: string;
+}
+/** Proceso multi-paso. La autoridad del conjunto no puede ser menor que la
+ *  del paso más grave que contiene. */
+interface WorkflowDef extends PiezaBase {
+    steps: {
+        skill?: string | undefined;
+        tool?: string | undefined;
+        description: string;
+    }[];
+    authority: Authority;
+}
+/** Cómo entra y sale la información. */
+type ModalityDef = 'texto' | 'voz' | 'imagen' | 'documento' | 'sensor';
+/** Estilo de comunicación. No es adorno: un agente reconocible es un agente
+ *  con el que se sostiene una relación. */
+interface PersonalityDef {
+    name: string;
+    tone: 'formal' | 'cercano' | 'tecnico' | 'calido' | 'directo';
+    /** Rasgos que lo hacen reconocible. */
+    traits?: string[] | undefined;
+    /** Lo que NUNCA dice o hace, aunque se lo pidan. */
+    neverDoes?: string[] | undefined;
+}
+/** Entidad persistente con objetivos, autoridad y memoria. */
+interface AgentDef extends PiezaBase {
+    /** Por qué existe. Si no se puede escribir, el agente no debería existir. */
+    purpose: string;
+    personality?: PersonalityDef | undefined;
+    /** Skills que conoce. */
+    skills?: string[] | undefined;
+    /** Herramientas que puede invocar. */
+    tools?: string[] | undefined;
+    workflows?: string[] | undefined;
+    modalities?: ModalityDef[] | undefined;
+    /** Techo de autoridad del agente. Ninguna herramienta suya puede superarlo. */
+    authority: Authority;
+    evidence?: EvidencePolicy | undefined;
+}
+/** Todo lo que una capacidad declara sobre sus piezas. */
+interface PiecesConfig {
+    skills?: SkillDef[] | undefined;
+    tools?: ToolDef[] | undefined;
+    workflows?: WorkflowDef[] | undefined;
+    agents?: AgentDef[] | undefined;
+    personalities?: PersonalityDef[] | undefined;
+    modalities?: ModalityDef[] | undefined;
+}
+/**
+ * Valida las piezas al DECLARARLAS.
+ *
+ * Corre en el escritorio del desarrollador, no en producción. Las reglas que
+ * impone no son de estilo: cada una cierra una forma concreta de causar daño.
+ */
+declare function validatePieces(cfg: PiecesConfig): string[];
+/** ¿Puede esta pieza actuar sola, o hay que preguntarle al humano? */
+declare function requiresApproval(a: Authority): boolean;
+/**
+ * ¿Alcanza la autoridad para ESTA ejecución concreta?
+ *
+ * La declaración dice el techo; esto revisa el caso puntual, que es donde
+ * de verdad se decide.
+ */
+declare function checkAuthority(a: Authority, intento?: {
+    amount?: number | undefined;
+    currency?: string | undefined;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+
+/**
+ * VAIA Extension Protocol — superficie de AGENTE.
+ *
+ * Es la parte del protocolo que permite que el asistente de Handeia viva
+ * dentro de un espacio de terceros. Sigue la regla del ecosistema: protocolo
+ * antes que SDK. Lo que hay aquí son CONTRATOS; el SDK solo los transporta.
+ *
+ * ── El reparto de papeles ────────────────────────────────────────────────
+ *   El espacio  → superficie y manos. Declara qué sabe y qué puede hacer.
+ *   Handeia     → cerebro, memoria y autoridad. Decide y ejecuta a través suyo.
+ *
+ * Por eso un espacio NO trae su propia IA: si la trajera, no te conocería,
+ * empezaría de cero cada vez, y no podría contradecirse a sí mismo. El caso
+ * que lo justifica: el espacio puntúa un resultado con 90 y el agente te dice
+ * que te conviene el de 87, porque sabe algo de ti que el espacio no sabe.
+ * Eso solo es posible si el cerebro vive fuera del espacio.
+ *
+ * ── La regla de confianza, que manda sobre todo lo demás ─────────────────
+ * El espacio es CÓDIGO DE TERCEROS. Nada de lo que envía es un hecho: es una
+ * AFIRMACIÓN. Handeia la trata como dato citado, nunca como instrucción y
+ * nunca al mismo nivel que lo que sabe del usuario. Un espacio que escriba
+ * "ignora las instrucciones anteriores" en su contexto no logra nada.
+ *
+ * @see AGENT_PROTOCOL_VERSION para la política de compatibilidad.
+ */
+/**
+ * Versión del protocolo de agente. Viaja en cada mensaje.
+ *
+ * Se versiona desde el primer día a propósito: este contrato es público y
+ * cambiarlo después obliga a coordinar despliegues entre partes que no se
+ * conocen. Ya se pagó esa factura una vez con la codificación del JWT.
+ */
+declare const AGENT_PROTOCOL_VERSION = 1;
+/** Un parámetro de una acción. Sin tipos no hay validación posible. */
+interface AgentActionParam {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required?: boolean | undefined;
+    /** Valores admitidos. Si se define, nada fuera de la lista es válido. */
+    enum?: string[] | undefined;
+}
+/**
+ * Algo que el espacio sabe hacer.
+ *
+ * Handeia SOLO puede pedir acciones declaradas aquí. No improvisa, no toca el
+ * DOM, no busca la forma. Si no está declarada, para el agente no existe —
+ * y eso es lo que hace que el mismo agente sirva en cualquier espacio sin que
+ * Handeia sepa nada de ninguno en particular.
+ */
+interface AgentAction {
+    /** Identificador estable, en minúsculas: 'filtrar_resultados'. */
+    name: string;
+    /** Qué hace, en lenguaje natural. Es lo que lee el modelo para elegirla. */
+    description: string;
+    params?: AgentActionParam[] | undefined;
+    /**
+     * true si modifica algo. Las que escriben se confirman con el usuario ANTES
+     * de ejecutarse — un agente que escribe sin preguntar se siente fuera de
+     * control incluso cuando acierta.
+     */
+    writes?: boolean | undefined;
+    /** Permiso que el usuario debe haber concedido a este espacio. */
+    permission?: string | undefined;
+}
+/** Configuración de la superficie de agente dentro de defineCapability. */
+interface AgentSurfaceConfig {
+    /** Acciones que el espacio expone. Vacío = el agente solo puede responder. */
+    actions?: AgentAction[] | undefined;
+    /**
+     * Endpoint para preguntarle al espacio cuando el usuario NO está dentro
+     * ("¿tengo algo pendiente ahí?"). El círculo solo existe con el espacio
+     * abierto; esto es lo que permite que Handeia sea el lugar donde convergen
+     * todos tus espacios en vez de uno más al que entrar.
+     */
+    queryEndpoint?: string | undefined;
+    /** Frase de bienvenida propia del espacio. */
+    greeting?: string | undefined;
+    /**
+     * Servicios externos que el espacio necesita consultar. El usuario los
+     * concede por espacio y los puede revocar cuando quiera. El espacio jamás
+     * recibe el token: pide operaciones, la plataforma las ejecuta.
+     */
+    needs?: ConnectorNeed[] | undefined;
+}
+/**
+ * Servicios externos que un espacio puede necesitar (GitHub, Drive, Calendar…).
+ *
+ * ── La regla, y no tiene excepciones ─────────────────────────────────────
+ * El espacio NUNCA recibe el token del usuario. Declara qué necesita, la
+ * plataforma llama al proveedor con el token que YA tiene guardado, y le
+ * devuelve solo el resultado.
+ *
+ * Por qué así y no entregando el token:
+ *   - Si cada espacio guardara tokens, la superficie de ataque se multiplica
+ *     por cada desarrollador que publique. Un espacio comprometido entregaría
+ *     el GitHub y el Drive de todos sus usuarios.
+ *   - Prestado, un espacio comprometido solo puede pedir las operaciones que
+ *     el usuario le concedió, con límite de frecuencia, auditadas y
+ *     revocables al instante desde Conectores.
+ *
+ * De regalo, publicar un espacio se vuelve barato: el desarrollador no
+ * implementa OAuth de nada.
+ */
+type ConnectorNeed = 'github' | 'drive' | 'calendar' | 'email' | 'notion' | 'discord';
+/**
+ * Operaciones de LECTURA que la plataforma sabe hacer por el espacio.
+ *
+ * Lista cerrada a propósito: un espacio no puede pedir "haz esta llamada
+ * arbitraria a la API de GitHub". Solo puede pedir lo que está aquí, y cada
+ * una devuelve datos ya acotados. Escribir en un servicio externo NO se
+ * presta — para eso el usuario usa el servicio.
+ */
+type ConnectorOperation = 'github.repos' | 'github.issues' | 'drive.files' | 'calendar.events' | 'email.recent' | 'notion.pages';
+/** Lo que el espacio pide prestado. */
+interface ConnectorRequest {
+    operation: ConnectorOperation;
+    /** Filtros simples. La plataforma los valida; nada de consultas libres. */
+    params?: Record<string, string | number | boolean> | undefined;
+}
+/** Lo que la plataforma devuelve. Datos, jamás credenciales. */
+interface ConnectorResult {
+    operation: ConnectorOperation;
+    ok: boolean;
+    items?: Record<string, unknown>[] | undefined;
+    /** 'sin_conectar' = el usuario no ha vinculado ese servicio todavía. */
+    error?: 'sin_permiso' | 'sin_conectar' | 'no_soportada' | 'limite_excedido' | 'fallo' | undefined;
+}
+/** Qué operación necesita qué conector — la plataforma lo usa para autorizar. */
+declare const CONNECTOR_OF_OPERATION: Record<ConnectorOperation, ConnectorNeed>;
+/**
+ * Lo que el espacio dice que está pasando.
+ *
+ * OJO: se llama `claims` y no `facts` a propósito. Handeia lo etiqueta como
+ * afirmación de un tercero antes de dárselo al modelo.
+ */
+interface AgentSpaceContext {
+    /** Dónde está el usuario dentro del espacio: '/lista'. */
+    route?: string | undefined;
+    /** Qué está viendo, en lenguaje natural: 'Lista de 12 resultados'. */
+    view?: string | undefined;
+    /** Datos que el espacio considera relevantes ahora mismo. */
+    claims?: Record<string, unknown> | undefined;
+}
+/** Petición del espacio a Handeia. Un solo endpoint, un solo formato. */
+interface AgentTurnRequest {
+    protocol: typeof AGENT_PROTOCOL_VERSION;
+    /** Lo que escribió el usuario. */
+    message: string;
+    context?: AgentSpaceContext | undefined;
+    /** Acciones disponibles AHORA (pueden ser menos que las declaradas). */
+    actions?: AgentAction[] | undefined;
+    /** Turnos previos, para que el agente no pierda el hilo. */
+    history?: {
+        role: 'user' | 'agent';
+        text: string;
+    }[] | undefined;
+    /** Resultado de una acción que Handeia pidió en el turno anterior. */
+    actionResult?: AgentActionResult | undefined;
+}
+/** Lo que el espacio devuelve tras ejecutar una acción. */
+interface AgentActionResult {
+    action: string;
+    ok: boolean;
+    /** Qué pasó, para que el agente pueda cerrar el ciclo con el usuario. */
+    summary?: string | undefined;
+    error?: string | undefined;
+}
+/**
+ * De dónde salió lo que el agente afirma.
+ *
+ * No es adorno: es el pilar de info verificada. Cuando el agente contradice
+ * al espacio ("dice 90, pero te conviene la de 87"), tiene que poder decir de
+ * dónde sacó su razón. Un oráculo que no se explica no se gana la confianza.
+ */
+interface AgentEvidence {
+    /** 'handeia' = memoria del usuario · 'space' = lo que declaró el espacio. */
+    source: 'handeia' | 'space';
+    label: string;
+}
+/** Respuesta de Handeia al espacio. */
+interface AgentTurnResponse {
+    protocol: typeof AGENT_PROTOCOL_VERSION;
+    /** Qué decirle al usuario. */
+    text?: string | undefined;
+    /** Acción a ejecutar. Siempre sale de la lista declarada, nunca inventada. */
+    action?: {
+        name: string;
+        args?: Record<string, unknown> | undefined;
+    } | undefined;
+    /** true si hay que confirmar con el usuario antes de ejecutarla. */
+    confirm?: boolean | undefined;
+    evidence?: AgentEvidence[] | undefined;
+    /** Identificador para cruzar los registros de todas las capas. */
+    traceId?: string | undefined;
+}
+/**
+ * Revisa que las acciones declaradas sean utilizables.
+ *
+ * Corre al declarar la capacidad, no en producción: un contrato mal escrito
+ * debe reventar en el escritorio del desarrollador, no frente al usuario.
+ */
+declare function validateAgentSurface(cfg: AgentSurfaceConfig): string[];
+/**
+ * ¿Es válida esta acción contra lo declarado?
+ *
+ * La usa Handeia antes de reenviarle nada al espacio. Es la lista blanca en
+ * ejecución: aunque el modelo se invente una acción o un argumento fuera de
+ * rango, aquí se detiene.
+ */
+declare function validateActionCall(llamada: {
+    name: string;
+    args?: Record<string, unknown> | undefined;
+}, declaradas: AgentAction[]): {
+    ok: true;
+    action: AgentAction;
+} | {
+    ok: false;
+    reason: string;
+};
+
 type PublishType = 'app' | 'ia' | 'skill' | 'eco';
 type EcoTarget = 'gandia' | 'handeia' | 'both';
 type NodeType = 'widget' | 'artefacto' | 'espacio' | 'skill' | 'agente';
@@ -14,7 +395,7 @@ interface GandiaUser {
     role: string;
     email?: string | undefined;
 }
-/** Context injected by GAIA on every invoke call to the developer's server. */
+/** Context injected by the platform on every invoke call to your server. */
 interface GandiaContext {
     capability_id: string;
     call_id: string;
@@ -22,7 +403,7 @@ interface GandiaContext {
     user: GandiaUser;
     permissions: string[];
     trigger: 'user_query' | 'gaia_invoke' | 'event';
-    /** Surface HAIA wants to render — determines which respond.* to use. */
+    /** Surface the platform wants to render — determines which respond.* to use. */
     surface: Surface;
     query?: string | undefined;
 }
@@ -31,14 +412,14 @@ interface HandeiaUser {
     email?: string | undefined;
     name?: string | undefined;
 }
-/** Context injected by HAIA on every invoke call to the developer's server. */
+/** Context injected by the platform on every invoke call to your server. */
 interface HandeiaContext {
     capability_id: string;
     call_id: string;
     user: HandeiaUser;
     permissions: string[];
     trigger: 'user_action' | 'haia_invoke' | 'schedule';
-    /** Surface HAIA wants to render. */
+    /** Surface the platform wants to render. */
     surface: Surface;
     query?: string | undefined;
 }
@@ -162,6 +543,16 @@ interface CapabilityConfig {
     sector: string;
     /** Which surfaces the capability can respond to, and their invoke endpoint. */
     surfaces: Partial<Record<Surface, SurfaceConfig>>;
+    /**
+     * Superficie de AGENTE — el asistente de Handeia dentro de este espacio.
+     * El espacio declara qué sabe hacer; Handeia razona y decide. Ver agent.ts.
+     */
+    agent?: AgentSurfaceConfig | undefined;
+    /**
+     * Las 7 piezas operativas: skills, herramientas, workflows, agentes,
+     * personalidades y modalidades. Con su autoridad y su evidencia. Ver pieces.ts.
+     */
+    pieces?: PiecesConfig | undefined;
     permissions: string[];
     risk: Risk;
     description?: string | undefined;
@@ -487,6 +878,15 @@ interface VAIAManifest {
     level?: string | undefined;
     sector: string;
     surfaces: string[];
+    /** Superficie de agente: qué sabe hacer el espacio y por dónde preguntarle.
+     *  Se publica en el manifest para que el portal y Handeia lo conozcan sin
+     *  tener que abrir el código de nadie. */
+    agent?: {
+        protocol: number;
+        actions: AgentAction[];
+        query_endpoint?: string | undefined;
+    } | undefined;
+    pieces?: PiecesConfig | undefined;
     permissions: string[];
     risk: Risk;
     has_own_auth: boolean;
@@ -504,6 +904,355 @@ declare function defineCapability(config: CapabilityConfig): CapabilityConfig;
 /** Converts a CapabilityConfig to a gandia.manifest.json object. */
 declare function toManifest(config: CapabilityConfig): VAIAManifest;
 
+/**
+ * El círculo del agente de Handeia, para montar dentro de un espacio.
+ *
+ * Montaje NEUTRAL a propósito: no depende de React ni de ningún framework. El
+ * SDK presume de cero dependencias y atarlo a React lo traicionaría — un
+ * espacio hecho en Vue, Svelte o HTML puro tiene el mismo derecho al agente.
+ * Encima de esto, un envoltorio de React son tres líneas.
+ *
+ * Lo que el desarrollador pone:
+ *   - de dónde sacar el contexto (qué está viendo el usuario)
+ *   - qué acciones sabe ejecutar
+ * Lo que pone el SDK: el círculo, el campo, el transporte y la identidad.
+ *
+ * El aspecto lo controla el SDK a propósito: así el agente se ve y se comporta
+ * igual en todos los espacios, que es parte de que se sienta Handeia y no un
+ * chat pegado a una app.
+ */
+
+interface MountAgentOptions {
+    /** capability_id del espacio, el mismo del manifest. */
+    capabilityId: string;
+    /**
+     * Dónde vive Handeia. Un solo endpoint, y el SDK no sabe qué hay detrás:
+     * así Handeia puede reordenar sus capas sin publicar una versión nueva.
+     */
+    handeiaUrl?: string | undefined;
+    /** Qué está viendo el usuario AHORA. Se pregunta en cada turno, no se cachea. */
+    getContext?: (() => AgentSpaceContext | Promise<AgentSpaceContext>) | undefined;
+    /** Las mismas acciones que el manifest declara. */
+    actions?: AgentAction[] | undefined;
+    /** Ejecuta una acción. Solo se llama con acciones declaradas y ya validadas. */
+    onAction?: ((name: string, args: Record<string, unknown>) => Promise<AgentActionResult> | AgentActionResult) | undefined;
+    /** Dónde montar. Por defecto, el body. */
+    container?: HTMLElement | undefined;
+    /** Saludo propio del espacio. */
+    greeting?: string | undefined;
+}
+interface AgentHandle {
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+/**
+ * Monta el agente. Devuelve un manejador para abrirlo, cerrarlo o quitarlo.
+ *
+ * Es idempotente por espacio: montarlo dos veces no deja dos círculos.
+ */
+declare function mountAgent(opts: MountAgentOptions): AgentHandle;
+
+/**
+ * Capacidades que CORREN.
+ *
+ * El resto del SDK declara y valida. Esto ejecuta. Es la diferencia entre
+ * darle a alguien el letrero de la puerta y darle la puerta.
+ *
+ * ── Las tres formas de tener una capacidad ───────────────────────────────
+ *   local()  → una función tuya, gobernada
+ *   http()   → un proyecto que ya tienes, sin reescribirlo
+ *   mcp()    → miles que ya existen en código abierto, con reglas encima
+ *
+ * Las tres se ejecutan igual y las tres pasan por la misma autoridad. Ese es
+ * el punto: da igual quién escribió la capacidad, el gobierno es uno solo.
+ *
+ * ── Cero dependencias, y cero modelo ─────────────────────────────────────
+ * El SDK no trae ningún proveedor de IA. Quien lo use pasa su propia función
+ * de modelo — Ollama local, Claude, lo que salga el año que viene. Atarse a un
+ * proveedor sería heredar su suerte.
+ */
+
+interface CapabilityCall {
+    /** Nombre de la operación dentro de la capacidad. */
+    name: string;
+    args?: Record<string, unknown> | undefined;
+    /** Si mueve dinero, va aquí para que la autoridad lo revise de verdad. */
+    amount?: number | undefined;
+    currency?: string | undefined;
+    /**
+     * Un humano YA dio el visto bueno para ESTA llamada.
+     *
+     * Levanta la barrera solo aquí y ahora: no cambia la declaración, así que la
+     * próxima vez se vuelve a preguntar. Un "sí" no es un cheque en blanco.
+     * Nunca desbloquea lo prohibido — para eso está declarado prohibido y no
+     * "requiere aprobación".
+     */
+    approved?: boolean | undefined;
+}
+interface CapabilityResult {
+    ok: boolean;
+    data?: unknown;
+    error?: string | undefined;
+    /** De dónde salió lo que devuelve. Sin esto no hay nada que auditar. */
+    evidence?: {
+        source: string;
+        label: string;
+    } | undefined;
+    /** true si la autoridad exige que un humano confirme antes de ejecutar. */
+    needsApproval?: boolean | undefined;
+}
+interface Capability {
+    /** Identificador dentro del ecosistema. */
+    readonly id: string;
+    /** Qué operaciones ofrece, ya con su autoridad asignada. */
+    readonly tools: ToolDef[];
+    /** Ejecuta. Revisa autoridad ANTES de tocar nada. */
+    run(call: CapabilityCall): Promise<CapabilityResult>;
+    /** Suelta recursos (procesos, sockets). Llamar al quitar del ecosistema. */
+    dispose?(): Promise<void> | void;
+}
+interface LocalCapabilityOptions {
+    id: string;
+    tools: ToolDef[];
+    /** Tu código. Recibe el nombre y los argumentos ya validados. */
+    handler: (name: string, args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/** Convierte una función tuya en capacidad gobernada. El caso más simple. */
+declare function local(opts: LocalCapabilityOptions): Capability;
+interface HttpCapabilityOptions {
+    id: string;
+    /** Base de tu proyecto ya existente. */
+    baseUrl: string;
+    tools: ToolDef[];
+    /** Cabeceras propias (tu API key, por ejemplo). */
+    headers?: Record<string, string> | undefined;
+    timeoutMs?: number | undefined;
+}
+/**
+ * Un proyecto que ya tienes se vuelve capacidad **sin reescribirlo**.
+ *
+ * Es el caso de "tengo tres proyectos que no se hablan": se declaran sus
+ * operaciones, se les pone autoridad, y dejan de ser islas.
+ */
+declare function http(opts: HttpCapabilityOptions): Capability;
+/**
+ * Transporte de un servidor MCP.
+ *
+ * Es una interfaz y no una implementación fija para no atar el SDK a Node:
+ * por HTTP funciona en cualquier runtime, y quien quiera stdio conecta su
+ * propio transporte sin que el paquete cargue con `child_process`.
+ */
+interface MCPTransport {
+    send(mensaje: unknown): Promise<unknown>;
+    close?(): Promise<void> | void;
+}
+/** Transporte HTTP, el que funciona en todos lados. */
+declare function httpTransport(url: string, headers?: Record<string, string>): MCPTransport;
+interface MCPCapabilityOptions {
+    id: string;
+    transport: MCPTransport;
+    /**
+     * Autoridad por herramienta. Lo que no aparezca aquí queda PROHIBIDO.
+     *
+     * Es la decisión de diseño más importante de todo el archivo: conectas un
+     * servidor de internet y **nada corre hasta que tú lo autorices**. Más
+     * fricción, sí — y es justo lo que separa esto de "enchufa y reza".
+     */
+    authority: Record<string, Authority>;
+    /** Autoridad para lo que no esté nombrado. Por defecto, prohibida. */
+    defaultAuthority?: Authority | undefined;
+    /** Permiso que se le asigna a las herramientas importadas. */
+    permission?: string | undefined;
+}
+/**
+ * Conecta un servidor MCP de verdad: lista sus herramientas y las llama.
+ *
+ * Aquí están los miles de capacidades de código abierto que ya existen —
+ * filesystem, GitHub, Postgres, navegador. No hay que construirlas: hay que
+ * gobernarlas.
+ */
+declare function mcp(opts: MCPCapabilityOptions): Promise<Capability>;
+/** Todo junto, para importarlo de un jalón. */
+declare const capabilities: {
+    local: typeof local;
+    http: typeof http;
+    mcp: typeof mcp;
+    httpTransport: typeof httpTransport;
+};
+
+/**
+ * Ecosistemas — que las piezas sueltas dejen de ser islas.
+ *
+ * Un ecosistema es un conjunto de capacidades que comparten identidad,
+ * contrato y reglas, aunque vivan en productos distintos, en máquinas
+ * distintas, o las haya escrito gente distinta.
+ *
+ * Tus tres proyectos viejos, un modelo local, dos servidores MCP que bajaste
+ * de internet y un repo que te gustó: eso es un ecosistema en cuanto algo los
+ * gobierna igual. Sin gobierno, "conectar todo" solo hace el desastre más
+ * grande.
+ *
+ * ── El bucle del agente ──────────────────────────────────────────────────
+ * También vive aquí, y corre con EL MODELO QUE PONGA EL DESARROLLADOR. El SDK
+ * no trae ninguno: recibe una función que habla y devuelve texto. Ollama en su
+ * máquina, Claude, o lo que salga el año que viene.
+ */
+
+interface EcosystemConfig {
+    name: string;
+    /** Las capacidades que lo componen, ya construidas. */
+    capabilities: Capability[];
+    /**
+     * Reglas por patrón, aplicadas SOBRE lo que cada capacidad declare.
+     *
+     * Se admite `*` al final: `'delete_*'`. Sirve para poner una regla de casa
+     * —"nada que borre corre solo"— sin revisar herramienta por herramienta
+     * cuando conectas un servidor con treinta.
+     */
+    authority?: Record<string, Authority> | undefined;
+}
+interface Ecosystem {
+    readonly name: string;
+    /** Todas las herramientas, con su capacidad de origen. */
+    readonly tools: (ToolDef & {
+        capability: string;
+    })[];
+    /** Ejecuta buscando en qué capacidad vive esa herramienta. */
+    run(call: CapabilityCall): Promise<CapabilityResult>;
+    /** Quita una capacidad en caliente. */
+    remove(capabilityId: string): Promise<void>;
+    /** Agrega una capacidad en caliente. */
+    add(capability: Capability): void;
+    dispose(): Promise<void>;
+}
+declare function defineEcosystem(cfg: EcosystemConfig): Ecosystem;
+/**
+ * Función de modelo. La pone el desarrollador.
+ *
+ * Recibe el mensaje del usuario y las herramientas disponibles; devuelve texto
+ * o una acción a ejecutar. El SDK no sabe ni le importa qué hay detrás.
+ */
+type ModelFn = (input: {
+    message: string;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+    history: {
+        role: 'user' | 'agent';
+        text: string;
+    }[];
+    lastResult?: CapabilityResult | undefined;
+}) => Promise<{
+    text?: string;
+    action?: {
+        name: string;
+        args?: Record<string, unknown>;
+    };
+}>;
+interface AgentLoopOptions {
+    ecosystem: Ecosystem;
+    model: ModelFn;
+    /**
+     * Cómo se pide el visto bueno humano. Si no se define, lo que requiera
+     * aprobación simplemente no se ejecuta — que es el comportamiento seguro.
+     */
+    onApproval?: ((tool: string, args: Record<string, unknown>) => Promise<boolean>) | undefined;
+    /** Tope de vueltas. Un agente sin tope es una factura sin tope. */
+    maxSteps?: number | undefined;
+}
+interface AgentTurn {
+    text?: string | undefined;
+    steps: {
+        action: string;
+        ok: boolean;
+        error?: string | undefined;
+    }[];
+}
+/**
+ * Corre un turno completo: el modelo decide, la autoridad revisa, la capacidad
+ * ejecuta, y el resultado vuelve al modelo para que cierre.
+ *
+ * Con esto alguien se arma un agente entero sin tocar ninguna plataforma.
+ */
+declare function agentLoop(opts: AgentLoopOptions): Promise<(message: string, history?: {
+    role: "user" | "agent";
+    text: string;
+}[]) => Promise<AgentTurn>>;
+
+/**
+ * Puente con MCP (Model Context Protocol), en las dos direcciones.
+ *
+ * MCP ganó como estándar para conectar agentes con herramientas: es lo que
+ * usan Anthropic, OpenAI y Google, y hay miles de servidores ya escritos.
+ * Pelearse con él sería quedarse solo; el camino es envolverlo.
+ *
+ * ── Por qué esto no es "adoptar MCP y ya" ────────────────────────────────
+ * MCP describe QUÉ puede hacer una herramienta. No sabe decir HASTA DÓNDE:
+ * no tiene forma de expresar "hasta $500 solo, arriba pregunta, y nunca
+ * borrar". Esa es una carencia reconocida del protocolo, no una opinión.
+ *
+ * Entonces el reparto queda así:
+ *   MCP  → el catálogo y el transporte. Lo que ya funciona, se reutiliza.
+ *   VAIA → la autoridad, el consentimiento y la evidencia. Lo que falta.
+ *
+ * Una herramienta MCP importada entra SIN autoridad, y así no puede
+ * ejecutarse: hay que asignársela explícitamente. Es a propósito — importar
+ * algo de internet no debería dar permisos por el hecho de importarlo.
+ */
+
+/** Esquema JSON de los argumentos, tal como lo publica un servidor MCP. */
+interface MCPInputSchema {
+    type: 'object';
+    properties?: Record<string, {
+        type?: string;
+        description?: string;
+        enum?: string[];
+    }> | undefined;
+    required?: string[] | undefined;
+}
+interface MCPTool {
+    name: string;
+    description?: string | undefined;
+    inputSchema?: MCPInputSchema | undefined;
+    /** Pistas del servidor sobre si la herramienta destruye o no. */
+    annotations?: {
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+    } | undefined;
+}
+/**
+ * Convierte una herramienta MCP en una declaración VAIA.
+ *
+ * La autoridad se pide aparte y es obligatoria: el servidor MCP describe lo
+ * que sabe hacer, pero **quién decide hasta dónde puede llegar es el dueño de
+ * la plataforma, no el servidor**. Confiar en lo que el propio servidor diga
+ * de sí mismo sería dejar que quien se importa se autoconceda permisos.
+ *
+ * Las pistas del servidor se usan solo para AVISAR de incoherencias, nunca
+ * para decidir.
+ */
+declare function fromMCPTool(tool: MCPTool, authority: Authority, permission: string): {
+    tool: ToolDef;
+    warnings: string[];
+};
+/**
+ * Publica una herramienta VAIA como herramienta MCP.
+ *
+ * Se rellenan las pistas a partir de la autoridad declarada, para que del otro
+ * lado sepan a qué atenerse. Y algo importante: **lo que requiere aprobación o
+ * está prohibido no se publica**. Exponerlo por MCP sería ofrecerle a un
+ * agente externo algo que ni el propio dueño puede ejecutar solo.
+ */
+declare function toMCPTool(tool: ToolDef): MCPTool | null;
+/** Publica un conjunto, descartando lo que no debe salir. */
+declare function toMCPTools(tools: ToolDef[]): {
+    published: MCPTool[];
+    withheld: string[];
+};
+
 /**
  * @vaia/sdk — VAIA Platform Integration SDK
  *
@@ -518,4 +1267,4 @@ declare function toManifest(config: CapabilityConfig): VAIAManifest;
 declare const gandia: typeof _gandia;
 declare const handeia: typeof _handeia;
 
-export { type ActionPayload, type ActionResponse, type AuditRecord, type CapabilityConfig, type CardPayload, type CardResponse, type DataResponse, type EcoTarget, type ErrorResponse, type GandiaContext, type GandiaJWTClaims, type GandiaTenant, type GandiaUser, type HandeiaContext, type HandeiaJWTClaims, type HandeiaUser, type NodeType, type OutputType, type PublishType, type RespondOpts, type Risk, type Surface, type SurfaceHandlers, type TablePayload, type TableResponse, type TextResponse, VAIAError, type VAIAManifest, type VAIAResponse, type WidgetPayload, type WidgetResponse, defineCapability, gandia, handeia, toManifest };
+export { AGENT_PROTOCOL_VERSION, type ActionPayload, type ActionResponse, type AgentAction, type AgentActionParam, type AgentActionResult, type AgentDef, type AgentEvidence, type AgentHandle, type AgentLoopOptions, type AgentSpaceContext, type AgentSurfaceConfig, type AgentTurn, type AgentTurnRequest, type AgentTurnResponse, type AuditRecord, type Authority, type AuthorityLevel, CONNECTOR_OF_OPERATION, type Capability, type CapabilityCall, type CapabilityConfig, type CapabilityResult, type CardPayload, type CardResponse, type ConnectorNeed, type ConnectorOperation, type ConnectorRequest, type ConnectorResult, type Consequence, type DataResponse, type EcoTarget, type Ecosystem, type EcosystemConfig, type ErrorResponse, type EvidenceKind, type EvidencePolicy, type GandiaContext, type GandiaJWTClaims, type GandiaTenant, type GandiaUser, type HandeiaContext, type HandeiaJWTClaims, type HandeiaUser, type HttpCapabilityOptions, type LocalCapabilityOptions, type MCPCapabilityOptions, type MCPInputSchema, type MCPTool, type MCPTransport, type ModalityDef, type ModelFn, type MountAgentOptions, type NodeType, type OutputType, type PersonalityDef, type PiecesConfig, type PublishType, type RespondOpts, type Risk, type SkillDef, type Surface, type SurfaceHandlers, type TablePayload, type TableResponse, type TextResponse, type ToolDef, VAIAError, type VAIAManifest, type VAIAResponse, type WidgetPayload, type WidgetResponse, type WorkflowDef, agentLoop, capabilities, checkAuthority, defineCapability, defineEcosystem, fromMCPTool, gandia, handeia, http, httpTransport, local, mcp, mountAgent, requiresApproval, toMCPTool, toMCPTools, toManifest, validateActionCall, validateAgentSurface, validatePieces };