@runic-labs/cache

Stockage d’artefacts indexé par signature — en mémoire et sur fichier.

@runic-labs/cache associe une signature de décision normalisée à l’artefact produit pour celle-ci. La plupart des intégrations n’ont pas besoin de ce package directement — @runic-labs/sdk l’encapsule — mais il est utile pour les configurations de stockage personnalisées ou l’inspection des mécanismes internes du cache.

npm install @runic-labs/cache

pnpm add @runic-labs/cache

yarn add @runic-labs/cache

bun add @runic-labs/cache

`signature(decision)`

Normalise une Decision et renvoie sa signature SHA-256. Les clés d’objet dans params sont triées récursivement afin que leur ordre n’affecte jamais le hachage. Consultez Fonctionnement pour l’algorithme complet.

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() }));

Utilise par défaut un FileCacheStore sous .runic/cache.json (ou $RUNIC_HOME/cache.json) si aucun stockage n’est fourni.

PropType

get(decision)?CachedEntry | null

Looks up a decision. Bumps hit stats on a hit.

TypeCachedEntry | null

set(decision, artifact, meta)?CachedEntry

Stores an artifact for a decision. meta = { tokensSpent }.

TypeCachedEntry

list()?CachedEntry[]

All entries currently in the store.

TypeCachedEntry[]

clear()?void

Removes all entries.

Typevoid

Backends de stockage

`MemoryCacheStore`

Uniquement en mémoire, il existe pendant toute la durée du processus. Utilisé à la fois par les benchmarks et les tests, afin que les exécutions soient autonomes et reproductibles.

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

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

`FileCacheStore`

Persiste dans un fichier JSON afin qu’un processus CLI et un processus d’agent puissent lire le même cache sans serveur en cours d’exécution.

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

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

Un fichier corrompu ou partiellement écrit est traité comme vide plutôt que de lever une erreur — un plantage pendant l’écriture ne devrait jamais empêcher la lecture suivante.

Implémenter votre propre `CacheStore`

Les deux stockages intégrés implémentent la même petite interface, donc un stockage basé sur Redis ou SQLite constitue un remplacement direct :

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 est appelé en interne à chaque accès réussi au cache afin d’incrémenter hitCount et lastUsedAt — implémentez-le comme une opération lecture-modification-écriture sur le stockage de votre choix.

Suite

Registre — la couche de comptabilisation correspondante des dépenses et économies
SDK — le contrat à deux fonctions que la plupart des intégrations utilisent réellement

@runic-labs/cache

signature(decision)

createCache(store?)