sava-agent-core

Developer Preview. El paquete ya está siendo preparado para publicación pública. La API raíz está gobernada por semver y por la prueba de superficie pública; lo experimental sigue explícitamente separado. Ver docs/API_FREEZE.md.

sava-agent-core es una librería TypeScript ESM para construir agentes gobernables que pueden planificar, ejecutar, verificar, persistir y auditar acciones reales en entornos local, nube o dispositivo.

Qué incluye hoy

• Kernel reusable para tools, transportes, policies, verification, memory, tasks y audit.
• Runtime reusable con AgentBase, AgentLoop, sesiones, supervision timeline y stores en memoria o archivo.
• Capa cognitiva con SavaAgentCognitivo para interpretar objetivos, evaluar viabilidad y detectar gaps de capacidades.
• Portable Execution Base para montar agentes de ejecución segura sobre toolsets propios con roles observe, act, verify y report.
• Entry points separados para runtime y SQLite, sin acoplar el barrel principal a Node 22.

Qué no intenta ser

• No es una app final de chat ni una UI cerrada.
• No está acoplado a un proveedor LLM concreto.
• No publica herramientas de negocio, verticales o integraciones privadas dentro del paquete base.

Instalación

npm install sava-agent-core

Requisitos:

• Node.js 18 o superior
• Node.js 22 o superior solo si usas el entry point SQLite: sava-agent-core/sqlite
• ESM only

Entry points públicos

| Import | Uso | | --- | --- | | sava-agent-core | Kernel principal, runtime, cognitive y portable execution | | sava-agent-core/runtime | Tipos y piezas del loop reusable | | sava-agent-core/experimental | Superficie experimental; no congelada | | sava-agent-core/sqlite | Stores SQLite con requisito de Node 22 |

Ejemplo mínimo

import { createSavaAgentCognitivo } from 'sava-agent-core';

const cognitive = createSavaAgentCognitivo();

const result = cognitive.reason({
  message: 'construye una app android compilable para pruebas internas',
  availableCapabilities: ['file_read', 'file_search', 'file_write', 'process_run', 'mobile_sdk_access'],
  context: {
    environment: 'windows',
    shell: 'powershell',
    detectedTools: ['gradle', 'adb'],
  },
});

console.log(result.status);
console.log(result.viability.overallStatus);
console.log(result.operatorClosure.nextAction);

Si necesitas un ejemplo ejecutable end to end usando la base de ejecución portable, el repo incluye examples/execution-base-consumer.ts.

Ejemplo ejecutable incluido

Desde el repo:

npx tsx examples/execution-base-consumer.ts snapshot
npx tsx examples/execution-base-consumer.ts diagnose
npx tsx examples/execution-base-consumer.ts preview

Ese ejemplo usa únicamente exportaciones oficiales del paquete y muestra cómo montar una base de ejecución portable sobre un conjunto de tools propio.

Estructura del repo

• src/: implementación fuente del paquete
• examples/: ejemplos ejecutables sobre la API pública
• prototypes/: exploración y material experimental fuera del contrato semver
• docs/: documentación pública y notas de arquitectura
• tests/: validación de superficie pública, comportamiento y build

Calidad y validación

El criterio de aceptación del repo es:

npm run check

Ese comando ejecuta typecheck, lint, tests y build. El CI corre la misma validación en Node 18, 20 y 22, además de npm pack --dry-run.

Documentación pública

• docs/API_FREEZE.md
• docs/QUICKSTART.md
• docs/KERNEL_BOUNDARIES.md
• docs/ECOSYSTEM.md
• docs/ARQUITECTURA_V0.2.md

Notas de publicación

• El paquete publicado solo incluye dist mediante la propiedad files de package.json.
• examples, prototypes y docs forman parte del repo, no del artefacto npm.
• Cualquier cambio deliberado en la API pública debe actualizar tests/api-surface.test.ts y docs/API_FREEZE.md.

Licencia

MIT