@vaia-lab/sdk 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VAIA Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,225 +1,181 @@
 # @vaia-lab/sdk
 
-VAIA Platform Integration SDK — connect your app, agent, or skill to [Gandia-7](https://gandia7.com) and [Handeia](https://handeia.com).
+**Agents with declared authority.** Connect your app to [Gandia-7](https://gandia7.com) and [Handeia](https://handeia.com), and let an assistant operate inside it — without writing the AI, and without giving it more power than you meant to.
 
-Zero runtime dependencies · Works in Node 18+, Edge, Bun, Deno · TypeScript-first
-
----
-
-## Install
+Zero dependencies · Node 18+, Edge, Bun, Deno · TypeScript-first
 
 ```bash
-npm install @vaia-lab/sdk
+npm i @vaia-lab/sdk
+npx vaia init
 ```
 
 ---
 
-## Quick start (Next.js — Gandia-7)
+## The problem it solves
+
+Most agent SDKs can say *"the agent may call this function."*
+
+None of them can say *"it may pay up to $500 on its own, above that it asks, and it may never delete."*
+
+That second sentence is the difference between a demo and something you let run on real data. Here it's mandatory: **a piece without declared authority does not compile.**
 
 ```ts
-// app/api/gandia/invoke/route.ts
-import { gandia, VAIAError } from '@vaia-lab/sdk'
-
-export const runtime = 'edge'
-
-export async function POST(req: Request) {
-  try {
-    const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
-    gandia.require(ctx, 'read:students')
-
-    const data = await myDb.getStudents(ctx.tenant.id)
-
-    return gandia.respond.surface(ctx.surface, {
-      card:  () => ({ title: 'Alumnos', value: data.length }),
-      table: () => ({ columns: ['nombre', 'riesgo'], rows: data }),
-      text:  () => `${data.length} alumnos en ${ctx.tenant.name}`,
-    })
-  } catch (err) {
-    if (err instanceof VAIAError) return gandia.respond.error(err.message, err.status)
-    throw err
-  }
-}
+tools: [{
+  name: 'pay_invoice',
+  description: 'Pays a pending invoice.',
+  permission: 'write:payments',
+  authority: {
+    level: 'autonoma',            // autonoma | requiere_aprobacion | prohibida
+    consequence: 'costosa',       // reversible | costosa | irreversible
+    maxAmount: 500,
+    currency: 'MXN',
+    rationale: 'Small recurring invoices. Anything larger gets human review.',
+  },
+}]
 ```
 
----
+### Rules you cannot opt out of
 
-## API Reference
+| rule | why |
+|---|---|
+| **Irreversible is never autonomous** | Doesn't rely on the model behaving well — it relies on the config being **impossible to write** |
+| Autonomous spending needs **a cap and a currency** | A bare `500` means nothing, and guessing the currency is how money disappears |
+| No piece may **exceed its agent's ceiling** | Otherwise you declare a limited agent and slip it a tool that does what the agent can't |
+| A tool **without a permission** is rejected | No permission means no one to ask for consent, and no one to revoke it from |
 
-### `gandia.verify(request, secret)`
+Validation happens **when you declare**, not in production. A bad contract breaks on your desk, not in front of your user.
+
+---
 
-Verifies the HMAC-SHA256 signature on an incoming invoke call from Gandia-7.
+## The agent inside your app
 
-- Checks `X-Gandia-Signature`, `X-Gandia-Timestamp` (replay window ±5 min)
-- Returns `{ ctx: GandiaContext, raw: string }`
-- Throws `VAIAError` (status 401) if invalid
+You declare what you can do. The assistant reasons with that **plus what it knows about the user, which you never see**.
 
 ```ts
-const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
-// ctx.tenant.id, ctx.tenant.name, ctx.tenant.sector
-// ctx.user.id, ctx.user.role
-// ctx.permissions  → ['read:students', 'read:grades']
-// ctx.surface      → 'card' | 'table' | 'text' | 'widget' | 'action' | 'data'
-// ctx.query        → user's original question (if trigger = 'user_query')
+agent: {
+  actions: [
+    { name: 'filter_results', description: 'Narrows the visible list.',
+      params: [{ name: 'city', type: 'string', description: 'City to filter by.' }] },
+  ],
+}
 ```
 
-### `gandia.require(ctx, permission)`
-
-Throws `VAIAError` (403) if the context doesn't have the required permission.
-
 ```ts
-gandia.require(ctx, 'write:alerts')           // single
-gandia.requireAll(ctx, 'read:students', 'read:grades')  // all
-const ok = gandia.can(ctx, 'read:health')     // boolean check
+mountAgent({
+  capabilityId: 'com.my-app',
+  getContext: () => ({ route: location.pathname, claims: { visible: 12 } }),
+  onAction: async (name, args) => run(name, args),
+})
 ```
 
-### `gandia.respond.surface(surface, handlers, opts?)`
+**Why the agent doesn't live in your app:** if it brought its own AI, it wouldn't know the user, it would start from zero every session, and — most importantly — **it could never disagree with itself**. This way, if your app scores one option 90 and another 87, the assistant can still recommend the 87, because it knows something about the user your app has no business knowing.
 
-Multi-surface responder — GAIA tells you which surface it wants via `ctx.surface`.
+**What it deliberately cannot do:** it may only request actions you declared. It doesn't improvise, doesn't touch the DOM, doesn't find workarounds. Anything that writes gets confirmed with the user first.
 
-```ts
-return gandia.respond.surface(ctx.surface, {
-  card:  () => ({ title: 'Riesgo', value: 72, unit: '%', trend: 'up' }),
-  table: () => ({ columns: ['alumno', 'score'], rows }),
-  text:  () => `El riesgo promedio es 72%`,
-}, { audit: { data_sources: ['supabase:students'], records_accessed: 120 } })
-```
+---
 
-Available surfaces: `card` · `table` · `text` · `widget` · `action` · `data`
+## Borrowed connectors
 
-### `gandia.respond.*` — individual builders
+Your app needs the user's GitHub or Drive. **You implement no OAuth, and you never receive their token.**
 
 ```ts
-gandia.respond.card({ title, value, unit, trend, subtitle, color })
-gandia.respond.table({ columns, rows, total })
-gandia.respond.text(content, { markdown: true })
-gandia.respond.widget({ url, height, width })
-gandia.respond.action({ type, label, params, confirm })
-gandia.respond.data(payload)
-gandia.respond.ok()
-gandia.respond.error(message, status, code?)
+agent: { needs: ['github', 'drive'] }
 ```
 
-All return a `Response` (Web API standard). For Express/Fastify use `gandia.make.*` instead (returns plain JSON object).
-
-### `gandia.jwt.verify(token, secret)`
+You request an operation, the platform runs it with the token it already holds, and hands you back a trimmed result.
 
-Verifies a Gandia-7 iframe JWT (`gandia_token` URL param). Use in iframe entry routes to skip your own login.
+> If every app stored tokens, the attack surface would multiply by every developer who ships. One compromised app would hand over the GitHub and Drive of all its users. Borrowed, it only reaches what the user granted — rate-limited, audited, and revocable instantly.
 
-```ts
-// In your iframe entry route:
-const claims = await gandia.jwt.fromUrl(request.url, process.env.GANDIA_KEY_SECRET!)
-// claims.sub         → user_id
-// claims.tenant_id   → institution id
-// claims.email       → user email (if available)
-// claims.permissions → what the user can do
-```
+Read-only. Writing to an external service is never lent: that's what the service itself is for.
 
 ---
 
-### `handeia.*`
+## MCP, wrapped
 
-Same API as `gandia.*` but for Handeia (personal platform). No tenant — just the user.
+MCP brings the catalog and the transport. This SDK brings the authority layer **MCP cannot express**.
 
 ```ts
-const { ctx } = await handeia.verify(req, process.env.HANDEIA_KEY_SECRET!)
-// ctx.user.id, ctx.user.email
-// ctx.permissions, ctx.surface, ctx.query
+const { tool, warnings } = fromMCPTool(mcpTool, authority, 'read:web')
 ```
 
+**Importing something from the internet grants it nothing.** Authority is assigned separately, always. The server's own hints only ever produce warnings — *"it flags this as destructive but you declared it reversible"* — never decisions.
+
+Outbound, `toMCPTool()` **withholds anything requiring approval**: exposing it would offer an external agent something even you can't run unattended.
+
 ---
 
-### `defineCapability(config)`
+## Use it without our platform
 
-Declares your capability metadata in code. The Shazam engine reads this with 100% confidence — no manual confirmation needed in the Developer Portal.
+**Ten of the thirteen exports need no account, no network and no keys.** The authority layer is not tied to Gandia-7 or Handeia — it works with any LLM, any framework, any stack.
 
 ```ts
-// vaia.config.ts
-import { defineCapability } from '@vaia-lab/sdk'
-
-export default defineCapability({
-  id: 'mx.monitor-riesgo-academico',  // reverse-domain
-  name: 'Monitor de Riesgo Académico',
-  version: '1.0.0',
-  target: 'gandia',           // 'gandia' | 'handeia' | 'both'
-  type: 'app',                // 'app' | 'ia' | 'skill' | 'eco'
-  level: 'artefacto',         // 'widget' | 'artefacto' | 'espacio'
-  sector: 'educacion',
-  surfaces: {
-    card:  { endpoint: '/api/gandia/invoke' },
-    table: { endpoint: '/api/gandia/invoke' },
-    text:  { endpoint: '/api/gandia/invoke' },
-  },
-  permissions: ['read:students', 'read:grades', 'write:alerts'],
-  risk: 'medium',
-})
-```
+import { validatePieces, checkAuthority, fromMCPTool } from '@vaia-lab/sdk'
 
-Generate `gandia.manifest.json`:
+// Validate your agent's tools at build time — with your own runtime
+const errors = validatePieces({ tools: myTools })
+if (errors.length) throw new Error(errors.join('\n'))
 
-```bash
-# Compile vaia.config.ts first, then:
-npx vaia-sdk manifest
-
-# Validate existing manifest:
-npx vaia-sdk manifest --validate
+// Gate a call before it happens, wherever your agent runs
+const ok = checkAuthority(tool.authority, { amount: 900, currency: 'MXN' })
+if (!ok.ok) return askHuman(ok.reason)
 ```
 
+| works standalone | needs the platform |
+|---|---|
+| `defineCapability` · `toManifest` | `gandia.verify` · `handeia.jwt` |
+| `validatePieces` · `checkAuthority` · `requiresApproval` | `mountAgent` |
+| `validateAgentSurface` · `validateActionCall` | |
+| `fromMCPTool` · `toMCPTool` · `toMCPTools` | |
+
+Bring your own model. Bring your own orchestrator. Keep the guardrails.
+
 ---
 
-## Error handling
+## Identity, without a second login
 
-All verification functions throw `VAIAError` on failure:
+Your app opens from Gandia-7 or Handeia with the user's session already resolved.
 
 ```ts
-import { VAIAError } from '@vaia-lab/sdk'
-
-try {
-  const { ctx } = await gandia.verify(req, secret)
-  // ...
-} catch (err) {
-  if (err instanceof VAIAError) {
-    // err.message → human-readable message (Spanish)
-    // err.code    → machine-readable: 'HMAC_INVALID', 'JWT_EXPIRED', 'PERMISSION_DENIED', etc.
-    // err.status  → HTTP status: 401, 403, 400, 422
-    return gandia.respond.error(err.message, err.status, err.code)
-  }
-  throw err
-}
+const claims = await handeia.jwt.fromUrl(request.url, process.env.HANDEIA_KEY_SECRET!)
 ```
 
-### Error codes
+And to verify a call genuinely came from the platform:
 
-| Code | Status | When |
-|---|---|---|
-| `MISSING_AUTH_HEADERS` | 401 | X-Gandia-Signature or X-Gandia-Timestamp missing |
-| `TIMESTAMP_OUT_OF_RANGE` | 401 | Timestamp outside ±5 min window |
-| `HMAC_INVALID` | 401 | Signature doesn't match |
-| `BODY_PARSE_ERROR` | 400 | Body is not valid JSON |
-| `JWT_MALFORMED` | 401 | JWT doesn't have 3 parts |
-| `JWT_SIGNATURE_INVALID` | 401 | JWT signature check failed |
-| `JWT_EXPIRED` | 401 | JWT exp claim is in the past |
-| `PERMISSION_DENIED` | 403 | Missing required permission |
-| `SURFACE_NOT_SUPPORTED` | 422 | No handler for requested surface |
+```ts
+const { ctx } = await gandia.verify(request, process.env.GANDIA_KEY_SECRET!)
+gandia.require(ctx, 'read:students')
+```
+
+Constant-time HMAC comparison, ±5 min window, and the health probe **requires a signature too**.
+
+---
+
+## The 7 pieces
+
+`skills` · `tools` · `workflows` · `agents` · `personalities` · `modalities` · `permissions`
+
+All declared, all validated, all carried in the manifest — so the portal can show **what authority a capability asks for before anyone installs it**.
 
 ---
 
 ## CLI
 
 ```bash
-npx vaia-sdk manifest            # generate gandia.manifest.json
-npx vaia-sdk manifest --validate # validate existing manifest
-npx vaia-sdk sign payload.json   # sign a payload (needs GANDIA_KEY_SECRET)
-npx vaia-sdk version             # SDK version
+npx vaia init       # drops a ready vaia.config.ts — no account, no keys, no network
+npx vaia manifest   # generates the manifest from your config
+npx vaia sign       # signs a payload for testing
 ```
 
 ---
 
-## Publishing
+## Security
 
-Publication to npm is done manually by the VAIA team via `npm login` + `npm publish`.
+See [SECURITY.md](./SECURITY.md) — what the SDK guarantees, and what's on you, such as deduplicating `call_id` if replay within the window matters to you.
 
----
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). What's open is **how to declare responsible agents**; the engines that run them are private.
 
 ## License
 
-MIT — VAIA
+MIT

package/dist/agent-1bVw0eB8.d.cts

@@ -0,0 +1,222 @@
+/**
+ * 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;
+};
+
+export { type AgentSurfaceConfig as A, CONNECTOR_OF_OPERATION as C, type AgentAction as a, AGENT_PROTOCOL_VERSION as b, type AgentActionParam as c, type AgentActionResult as d, type AgentEvidence as e, type AgentSpaceContext as f, type AgentTurnRequest as g, type AgentTurnResponse as h, type ConnectorNeed as i, type ConnectorOperation as j, type ConnectorRequest as k, type ConnectorResult as l, validateAgentSurface as m, validateActionCall as v };