AGENTS.md

1# packages/sdk/typescript — TypeScript SDK (`@caveman-ai/sdk`)
2 
3Single-file SDK (`src/index.ts`) exported as an ES module. Provides `Cave` (main client),
4`CaveTrace` (per-request tracing), and BM25-backed tool-search against the gateway. No runtime
5dependencies — only `devDependencies` for TypeScript.
6 
7## Layout
8 
9- `src/index.ts` — entire SDK; exports `Cave`, `CaveTrace`, `CaveOptions`, `CaveTool`, `ToolSearchResult`, `CompressOptions`, `CompressResult`, and the `ContextPack*` types
10- `tests/tool-search.test.ts` — type-level assertions compiled by `tsc --noEmit`
11- `tests/tool-search.runtime.mjs` — runtime tests using `node:test` + global fetch mock (imports from `dist/`)
12- `tests/runtime-policy.runtime.mjs` + `tests/runtime-policy.test.ts` — the runtime-policy client; drives every section of `../../parity/runtime-policy.fixtures.json` (fetch wire, signature cases, all `assignment_vectors` with exact float equality, all `guard_cases` — the shared operator truth table lives in the fixture, not in this file — and all `decision_cases`). Iterate the arrays; never hard-code their counts
13- `tests/parity.runtime.mjs` — cross-language conformance suite; drives `../../parity/fixtures.json` (shared with sdk-python). Same fixtures, two languages → a field in one SDK and not the other fails CI.
14- `tests/trace-continuity.runtime.mjs` — trace/span id minting + which requests carry `x-cave-trace-id` / `x-cave-parent-span-id`; mirrors the Python `tests/test_trace_continuity.py`
15- `tsconfig.json` / `tsconfig.test.json` — separate configs; test config covers `tests/`. Both extend the **repo-root** `../../../tsconfig.base.json`.
16 
17## Key APIs
18 
19- `new Cave(options)` — requires `apiKey`, `baseURL`, `agent`
20- `cave.trace(opts, fn)` — wraps a callback with a `CaveTrace`; sends tool-call spans to `/sdk/v1/events`. The trace mints `traceId` (32 lowercase hex) + a root `spanId` (16 lowercase hex) with the exporter's RNG; `opts.traceId`/`opts.spanId` continue an inbound trace and a value that isn't the exact hex shape is replaced rather than sent. Every provider call made **through the trace** carries `x-cave-trace-id` + `x-cave-parent-span-id`. Generic `/sdk/v1/*` calls and provider clients built off the `Cave` carry neither; the sole SDK-endpoint exception is `CaveTrace.tool`, whose `/sdk/v1/events` call carries the trace id and root parent span id
21- `CaveTrace.exporter({serviceName?})` → an `OTelExporter` whose `defaultTraceId` is the trace's, so SDK spans and the gateway's request rows join one trace. MIRRORS the Python `Trace.exporter`
22- `cave.tools({ catalog, strategy })` — returns `{ initial, strategy, search(query, opts?) }`. **`search()` is async** (returns `Promise<ToolSearchResult>`); breaking change from 1.0 which was sync. `opts.ranker` (`"bm25"`|`"embeddings"`) is passed through to the gateway verbatim; `opts.toolSessionId` sends `session_id` so provider callbacks can re-inject called deferred tools. The SDK never computes similarity
23- `cave.toolSearch(catalog, query, opts?)` — direct variant, same contract (incl. `ranker` / `toolSessionId`). Schema-token counters are estimates; `tokenBasis` discloses the counter and `basis` is always `"inferred"`
24- `cave.compress(payload, opts?)` → `Promise<CompressResult>`; POSTs `/sdk/v1/compress`, maps the Engine report. **Byte-safe pass-through** on any transport/parse problem (original input, `ratio:0`, no handle); `tokenCountBasis` discloses the counter and `basis` is always `"inferred"`. The SDK delegates — it never reimplements a compressor
25- `cave.context.pack(query, items, options)` → `Promise<ContextPackResult>`; connected-only POST to `/sdk/v1/context/pack`. Lossy selector over caller-owned items, never CCR/ledger; returns exact `deferredIds`. Transport or malformed-report failure returns all original items with zero inferred savings
26- `CaveTrace.context.expand(sourceRef)` — the GET half of `checkpoint()`; `GET /sdk/v1/checkpoints/{ref}/expand` returns the stored `{source_ref, version, messages, checkpoint}`
27- `cave.openai/anthropic/gemini/vertex()` — thin provider clients; proxied through gateway; each exposes a `.raw` fetch escape hatch (mirrors the Python `Provider.raw`). `cave.bedrock({region, endpoint?})` is a no-network first-party route descriptor: Runtime defaults to `/bedrock`; explicit Mantle returns `/bedrock/anthropic`; `sdkOnly:false` mirrors Python's `sdk_only`
28- `cave.prompts.internalBrevity({style, preserveErrorsVerbatim?, preserveCodeVerbatim?})` — output-style snippet (`style:"none"` → `""`); MIRRORS the Python `cave.prompts.internal_brevity`
29- `CaveTrace.model.openai.responses.create(body, {cave:{latencyClass, toolSessionId}})` — passing a `latencyClass` hint sets the `x-cave-async` header (`"true"` unless `"interactive"`); passing `toolSessionId` sets `x-cave-tool-session`. Mirrored by the Python `responses.create(body, latency_class=..., tool_session_id=...)`
30- `CaveTrace.artifacts.page()` — sends versioned `{value, options, workflow}`; gateway stores only JSON `value`. `artifacts.get(id)` performs authenticated retrieval. `strategy:"verbatim"` bypasses storage. Mirrored by Python.
31- `CaveTrace.context.checkpoint()` — POSTs to `/sdk/v1/checkpoints`; gateway persists it (Valkey) + returns a reversible `source_ref` (expand via `GET /sdk/v1/checkpoints/{ref}/expand`)
32- `cave.exporter({serviceName?})` → `OTelExporter`; `recordSpan(...)` maps current GenAI fields to `gen_ai.*`, `export()` POSTs OTLP/JSON to standard `/v1/traces` (headers via `otlpHeaders()`; legacy `/otlp/v1/traces` remains server-only compatibility)
33- `cave.runtimePolicy({publicKey?, autoRefreshSeconds?, killEnv?})` → `RuntimePolicyClient`. `refresh()` is the only network call (`GET /sdk/v1/runtime-policy`, std headers minus content-type); it Ed25519-verifies the bundle **string's** exact bytes before parsing, TOFU-pins the key **the moment the signature verifies** (before the schema/sequence checks, so a rejected-but-signed bundle cannot open a downgrade window), rejects a regressed `sequence`, and keeps last-known-good on any failure. The fetch carries a 30s `AbortSignal.timeout` (mirrors Python's `timeout=30`); an `autoRefreshSeconds` tick that lands mid-refresh is skipped, not stacked. `decide(taskFamily, {unitKey, context, trace})` is **synchronous, local-only, and never throws**; holdout suppresses onto the fallback path and a missing unit key or invalid experiment never guesses an arm. `kill()` latches locally, `killEnv` is re-read per decide, `state()` snapshots. Routing only — no savings vocabulary anywhere. MIRRORS the Python `cave.runtime_policy()`
34- `cave.retryLoopBreaker(threshold=3)` → `RetryLoopBreaker`; `.record(name, args)` throws `RetryLoopError` after `threshold` consecutive identical tool calls; `.guard(name, args, fn)` records then runs `fn`
35- `cave.jobs` → reserved `JobsClient` surface. Every method fails locally with `cave_async_jobs_unavailable`; it performs no network request until durable encrypted request storage, credential custody, and a draining worker exist. MIRRORS the Python `Cave.jobs`
36 
37## Conventions
38 
39- Tests: type assertions in `.test.ts` (compiled only), runtime in `.runtime.mjs` (run against `dist/`)
40- Build before runtime tests: `pnpm build && pnpm test:node`
41- Request body keys are `snake_case` to the gateway; response mapped to `camelCase` in `ToolSearchResult`
42- `x-cave-workflow` header defaults to `defaultWorkflow ?? "unlabeled-workflow"`; never omit it
43- Deferred tool-search session handoff uses request `session_id`, result `sessionId`, and provider header `x-cave-tool-session`; update sdk-python + parity fixtures with any change
44 
45## Gotchas
46 
47- **byte-safe**: SDK sends request bodies to the gateway verbatim; no rewriting allowed. `compress()` is the one path that yields smaller bytes and it **delegates** to the Engine — on any problem it passes the original through
48- **context packing is connected-only and intentionally lossy**: it sends item bytes to gateway, never runs in local wrap, and relies on caller retaining every item named by `deferredIds`. It chooses what enters window; cache-optimal assembly chooses placement
49- **mirror sdk-python**: every field/method exists in both, enforced by the shared parity suite — a divergence is a CI failure, not a convention slip. Change one SDK, change both **and** the fixtures
50- published as `@caveman-ai/sdk`; the workspace name stays `@caveman-ai/sdk` until the npm redirect plan lands
51- `strategy:"deferred"` initial set = `alwaysLoad` tools + up to `initialToolCount` (default 8); never returns the full catalog without a `search()` call
52- `reductionPct` rounds to one decimal; `savedTokens` is derived (`full - sent`), not from the gateway response
53 
54See ../../../CLAUDE.md (root)
55