@runic-labs/cache

Armazenamento de artefatos indexado por assinatura — em memória e baseado em arquivos.

@runic-labs/cache mapeia uma assinatura de decisão normalizada para o artefato produzido por ela. A maioria das integrações não precisa deste pacote diretamente — @runic-labs/sdk o encapsula — mas ele é útil para configurações personalizadas de armazenamento ou para inspecionar os detalhes internos do cache.

npm install @runic-labs/cache

pnpm add @runic-labs/cache

yarn add @runic-labs/cache

bun add @runic-labs/cache

`signature(decision)`

Normaliza uma Decision e retorna sua assinatura SHA-256. As chaves de objeto em params são ordenadas recursivamente para que a ordem das chaves nunca afete o hash. Consulte Como funciona para ver o 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() }));

Por padrão, usa um FileCacheStore em .runic/cache.json (ou $RUNIC_HOME/cache.json) se nenhum armazenamento for informado.

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 armazenamento

`MemoryCacheStore`

Somente em memória; permanece ativo durante toda a vida do processo. É usado tanto por benchmarks quanto por testes, para que as execuções sejam autocontidas e reproduzíveis.

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

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

`FileCacheStore`

Persiste em um arquivo JSON para que um processo de CLI e um processo de agente possam ler o mesmo cache sem um servidor em execução.

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

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

Um arquivo corrompido ou parcialmente gravado é tratado como vazio em vez de gerar um erro — uma falha durante a gravação nunca deve derrubar a próxima leitura.

Implementando seu próprio `CacheStore`

Ambos os armazenamentos integrados implementam a mesma interface pequena, portanto um armazenamento baseado em Redis ou SQLite é um substituto direto:

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 é chamado internamente a cada acerto no cache para incrementar hitCount e lastUsedAt — implemente-o como uma operação de leitura-modificação-gravação no armazenamento de suporte que você escolher.

Próximos passos

Ledger — a camada correspondente de contabilização de gastos/economias
SDK — o contrato de duas funções que a maioria das integrações realmente usa

@runic-labs/cache

signature(decision)

createCache(store?)