> ## Documentation Index
> Fetch the complete documentation index at: https://nekzus-32.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LiopClient

> Enrutando intenciones e inyectando lógica autónoma vía el Logic-Injection-on-Origin Protocol

La clase `LiopClient` es el orquestador para los Nodos Agentes. Conecta tu aplicación de Node.js o edge a la red P2P descentralizada, valida identidades criptográficas y despacha cargas de lógica WebAssembly directamente a los Nodos de Datos (Servidores) remotos.

A diferencia de los clientes REST tradicionales que solo hacen un `<fetch>` a endpoints JSON estáticos, un `LiopClient` literalmente empuja sus funciones de lógica a través de internet para ser ejecutadas de manera nativa en el servidor.

## Inicialización y Configuración

El cliente acepta configuración TLS opcional para comunicación gRPC segura.

```typescript theme={null}
import { LiopClient } from "@nekzus/liop";
import type { LiopTlsOptions } from "@nekzus/liop";

const tlsConfig: LiopTlsOptions = {
  // Opcional: credenciales TLS para gRPC
};

const client = new LiopClient(tlsConfig);
```

### Opciones de Configuración

Al crear un `LiopClient`, puedes proporcionar:

* **`tls?` (`LiopTlsOptions`)**: Credenciales TLS opcionales para comunicación gRPC segura. Si se omite, se usa transporte inseguro (adecuado para desarrollo local).

## Conexión a la Malla (Mesh)

A diferencia de MCP, que requiere una tubería stdio directa o una URL de SSE preconfigurada, LIOP utiliza ruteo peer-to-peer descentralizado. El SDK se encarga de atravesar NATs automáticamente.

```typescript theme={null}
// Conectarse al backbone de la red P2P
await client.connect();

// O conectar a un nodo bootstrap específico
await client.connect("/ip4/127.0.0.1/tcp/4001/p2p/PEER_ID", {
  meshConfig: {
    bootstrapNodes: ["/ip4/1.2.3.4/tcp/4001"],
    identityPath: "~/.liop/identity.json"
  }
});

// Verificar el estado después de la conexión
console.log("Mesh conectado:", client.getServerInfo());
```

## Llamando a una Capacidad del Servidor (Tool)

Usa `resolveCapability()` para descubrir servidores en la DHT, luego invoca herramientas con `callTool()` mediante un objeto `CallToolRequest`:

```typescript theme={null}
// Descubrir herramientas disponibles en la malla
const tools = await client.discoverTools();
console.log("Herramientas disponibles:", tools);

// Resolver una capacidad a un peer específico
const target = await client.resolveCapability("execute_complex_sql");

// Invocar la herramienta
const result = await client.callTool({
  name: "execute_complex_sql",
  arguments: { 
    query: "SELECT * FROM petabytes_table WHERE anomaly_detected = true" 
  }
});

console.log(result.content[0].text);
```

<Tip>
  Para control fino sobre el payload WASM enviado al servidor, usa el segundo parámetro de `callTool()` para pasar un `Buffer` binario.
</Tip>

## Creando Watchdogs (Suscripciones Push) \[PLANIFICADO]

> **Esta funcionalidad está en el roadmap pero aún no está implementada en la versión actual del SDK.**

Los Watchdogs permiten suscripciones push persistentes. En lugar de hacer polling manual con `callTool()`, podrás desplegar un módulo watcher persistente que empuje eventos asíncronos a través de canales QUIC multiplexados de vuelta al agente. Sigue el progreso en el [repositorio de GitHub](https://github.com/Nekzus/LIOP).

## Validación Criptográfica (El Escudo ZK)

Aunque la capa de red está cifrada usando AES-256-GCM simétrico, el `LiopClient` por diseño duda del origen de la ejecución.

Cuando `callTool` retorna desde el Nodo de Datos remoto, el cliente realiza la verificación ZK internamente mediante su `LiopVerifier` integrado cuando existen recibos en el flujo de ejecución. El resultado expuesto de `callTool` se mantiene compatible con MCP (`content`/`isError`). También puedes verificar manualmente cuando dispones de artefactos de prueba crudos:

```typescript theme={null}
// El cliente verifica automáticamente los ZK receipts durante callTool().
// Para verificación manual, usa la instancia pública del verificador:
const isValid = await client.verifier.verifyZkReceipt(
  wasmPayload, 
  remoteImageIdHex, 
  zkReceiptBuffer
);

if (!isValid) {
  throw new Error("Inconsistencia Matemática (Hack Detectado)");
}
```

*Nota: El adaptador `LiopMcpBridge` ejecuta automáticamente esta validación de forma nativa.*

## Gestión del Ciclo de Vida

Siempre cierra el cliente de forma ordenada para liberar recursos de malla:

```typescript theme={null}
try {
  await client.connect();
  // ... llamadas
} finally {
  await client.close();
}
```

## Manejo de Errores y Rechazos Zero-Trust

Debido a que el Servidor impone un sandbox `WASI` estricto y utiliza el *Guardian Cero-Tiempo* para inspeccionar tu carga `.wasm` ANTES de la ejecución, tu cliente debe estar preparado para manejar rechazos del sandbox.

```typescript theme={null}
try {
  await client.callTool({ name: "read_file", arguments: { path: "/etc/passwd" } });
} catch (error) {
  if (error instanceof Error) {
    console.error("Ejecución en Sandbox Detenida:", error.message);
  }
}
```

`LiopError` y `ErrorCode` están exportados por el SDK y pueden usarse en aplicaciones que normalizan o reenvuelven errores del protocolo. En runtime actual, algunos caminos siguen arrojando instancias nativas de `Error` según el contexto.