@runic-labs/cache

Almacenamiento de artefactos con claves de firma, en memoria y basado en archivos.

@runic-labs/cache asigna una firma de decisión normalizada al artefacto producido para ella. La mayoría de las integraciones no necesitan este paquete directamente — @runic-labs/sdk lo envuelve —, pero resulta útil para configuraciones de almacenamiento personalizadas o para inspeccionar los componentes internos de la caché.

npm install @runic-labs/cache

pnpm add @runic-labs/cache

yarn add @runic-labs/cache

bun add @runic-labs/cache

signature(decision)

Normaliza una Decision y devuelve su firma SHA-256. Las claves de objeto en params se ordenan recursivamente, por lo que el orden de las claves nunca afecta al hash. Consulta Cómo funciona para ver el algoritmo completo.

import { signature } from "@runic-labs/cache";

signature({ intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } });
// => same hash regardless of param key order

createCache(store?)

import { createCache, FileCacheStore, defaultCacheFilePath } from "@runic-labs/cache";

const cache = createCache(new FileCacheStore({ filePath: defaultCacheFilePath() }));

De forma predeterminada, usa un FileCacheStore en .runic/cache.json (o $RUNIC_HOME/cache.json) si no se proporciona ningún almacenamiento.

Backends de almacenamiento

MemoryCacheStore

Solo en memoria; permanece durante la vida del proceso. Se usa tanto en las pruebas comparativas como en los tests, por lo que las ejecuciones son autónomas y repetibles.

import { createCache, MemoryCacheStore } from "@runic-labs/cache";

const cache = createCache(new MemoryCacheStore({ staleAfterMs: 60_000 }));

FileCacheStore

Persiste en un archivo JSON para que un proceso de CLI y un proceso de agente puedan leer la misma caché sin un servidor en ejecución.

import { createCache, FileCacheStore } from "@runic-labs/cache";

const cache = createCache(new FileCacheStore({ filePath: "./my-agent/.runic/cache.json" }));

Un archivo corrupto o escrito parcialmente se trata como vacío en lugar de generar un error; un fallo durante la escritura nunca debería impedir la siguiente lectura.

Implementar tu propio CacheStore

Ambos almacenamientos integrados implementan la misma interfaz pequeña, por lo que un almacenamiento respaldado por Redis o SQLite es un reemplazo directo:

interface CacheStore {
  get(signature: string): CachedEntry | null;
  set(signature: string, artifact: unknown, meta: { tokensSpent: number }): CachedEntry;
  touch(signature: string): CachedEntry | null;
  list(): CachedEntry[];
  clear(): void;
}

touch se llama internamente en cada acierto de caché para incrementar hitCount y lastUsedAt; impleméntalo como una operación de lectura-modificación-escritura sobre el almacenamiento de respaldo que elijas.

Siguiente

• Libro mayor — la capa de contabilidad correspondiente de gasto/ahorro
• SDK — el contrato de dos funciones que la mayoría de las integraciones usa realmente