Sdk

askRunic and storeResult — the entire agent-facing contract.

@runic-labs/sdk is the only package most integrations need to import directly. It wraps @runic-labs/cache and @runic-labs/ledger behind two functions.

npm install @runic-labs/sdk

pnpm add @runic-labs/sdk

yarn add @runic-labs/sdk

bun add @runic-labs/sdk

Module-level functions

For the common case — one agent process, default file-backed storage — use the free functions directly:

import { askRunic, storeResult } from "@runic-labs/sdk";

`askRunic(decision)`

Checks whether this exact decision has already been resolved.

PropType

decisionDecision

{ intent: string; params: Record<string, unknown> }

TypeDecision

Returns Promise<CachedEntry | null> — null on a miss, or the cached entry (and logs a hit to the ledger) on a hit.

PropType

signature?string

The normalized signature this entry is keyed on.

Typestring

artifact?unknown

Whatever was passed to storeResult() originally.

Typeunknown

tokensSpent?number

What producing this artifact cost the first time.

Typenumber

createdAt?number

Epoch ms when this entry was first stored.

Typenumber

lastUsedAt?number

Epoch ms of the most recent hit.

Typenumber

hitCount?number

Number of times this entry has been reused.

Typenumber

stale?boolean

Advisory only — Runic never acts on this itself.

Typeboolean

`storeResult(decision, artifact, tokensSpent)`

Records a freshly-generated artifact for a decision, and logs what it cost so a future hit knows how much it saved.

PropType

decisionDecision

Same shape as askRunic's argument.

TypeDecision

artifactunknown

Whatever you want returned on a future cache hit.

Typeunknown

tokensSpentnumber

Agent-reported cost of producing this artifact. Runic never measures this itself.

Typenumber

Returns Promise<void>.

`createRunicClient(options?)`

Use this instead of the module-level functions when you need multiple independent clients — most commonly for tests, or when explicitly choosing in-memory storage:

import { createRunicClient } from "@runic-labs/sdk";
import { createCache, MemoryCacheStore } from "@runic-labs/cache";
import { createLedger, MemoryLedgerStore } from "@runic-labs/ledger";

const runic = createRunicClient({
  cache: createCache(new MemoryCacheStore()),
  ledger: createLedger(new MemoryLedgerStore()),
});

await runic.askRunic({ intent: "summarize_pr", params: { repo, pr } });
await runic.storeResult({ intent: "summarize_pr", params: { repo, pr } }, artifact, tokensUsed);

PropType

cache?Cache

Defaults to a file-backed cache under .runic/ if omitted.

TypeCache

ledger?Ledger

Defaults to a file-backed ledger under .runic/ if omitted.

TypeLedger

Returns a RunicClient with the same askRunic / storeResult shape as the module-level functions, scoped to whatever cache/ledger instances you passed in.