@runic-labs/cache

Signaturbasierter Artefaktspeicher – im Arbeitsspeicher und dateibasiert.

@runic-labs/cache ordnet eine normalisierte Entscheidungssignatur dem dafür erzeugten Artefakt zu. Die meisten Integrationen benötigen dieses Paket nicht direkt – @runic-labs/sdk kapselt es –, aber es ist nützlich für benutzerdefinierte Store-Konfigurationen oder zur Untersuchung der Cache-Interna.

npm install @runic-labs/cache

pnpm add @runic-labs/cache

yarn add @runic-labs/cache

bun add @runic-labs/cache

`signature(decision)`

Normalisiert eine Decision und gibt ihre SHA-256-Signatur zurück. Objektschlüssel in params werden rekursiv sortiert, sodass die Schlüsselreihenfolge den Hash nie beeinflusst. Den vollständigen Algorithmus findest du unter So funktioniert es.

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

Wenn kein Store übergeben wird, wird standardmäßig ein FileCacheStore unter .runic/cache.json (oder $RUNIC_HOME/cache.json) verwendet.

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

Speicher-Backends

`MemoryCacheStore`

Nur im Arbeitsspeicher, lebt für die Lebensdauer des Prozesses. Wird sowohl von Benchmarks als auch von Tests verwendet, sodass Ausführungen eigenständig und reproduzierbar sind.

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

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

`FileCacheStore`

Speichert in einer JSON-Datei, sodass ein CLI-Prozess und ein Agent-Prozess denselben Cache ohne laufenden Server lesen können.

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

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

Eine beschädigte oder nur teilweise geschriebene Datei wird als leer behandelt, statt einen Fehler auszulösen – ein Absturz während des Schreibens sollte niemals den nächsten Lesevorgang beeinträchtigen.

Deinen eigenen `CacheStore` implementieren

Beide integrierten Stores implementieren dieselbe kleine Schnittstelle, sodass ein Redis- oder SQLite-basierter Store ein direkter Ersatz ist:

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 wird intern bei jedem Cache-Treffer aufgerufen, um hitCount und lastUsedAt zu erhöhen – implementiere es als Lesen-Ändern-Schreiben für den von dir gewählten zugrunde liegenden Store.

Weiter

Ledger – die passende Abrechnungsebene für ausgegebene/gesparte Werte
SDK – der Vertrag mit zwei Funktionen, den die meisten Integrationen tatsächlich verwenden

@runic-labs/cache

signature(decision)

createCache(store?)