---
title: API reference
summary: Every exported entrypoint, package, and command.
canonical: https://docs.caveman.so/docs/agent-sdk/reference
license: Apache-2.0
capability: agent-sdk
updated: 2026-09-16T21:32:40-07:00
basis: inferred
---

# API reference

> Every exported entrypoint, package, and command.
Every entrypoint `@caveman-ai/agent` publishes, the values each one exports, the sibling packages, and the `caveman-agent` commands. Signatures are from the 0.2.0 source; type-only exports are named in the group they belong to rather than listed one by one.

```ts
import { agent, auto, run, schema, tool } from "@caveman-ai/agent";
import { createAgentServer } from "@caveman-ai/agent/serve";
import { SqlDurableStore } from "@caveman-ai/agent/durable";
```

## Entrypoints

| Import path | What is behind it |
|---|---|
| `@caveman-ai/agent` | The runtime: definitions, tools, runs, receipts, memory, compaction, context IR. |
| `/build` | `defineBuild`, `compile`, the lock parsers and the digest helpers. |
| `/compiler` | The profiled compiler and its capability lattice. |
| `/profile` | Workload profiles built from normalized trajectories. |
| `/serve` | The Node session server. |
| `/serve-handler` | The same server as a web-standard `fetch(Request)` handler. |
| `/durable` | Journals, stores and the replay validators. |
| `/code` | The coding agent, its sessions, and its bill formatting. |
| `/command-session` | The command-session runtime behind interactive clients. |
| `/execution-backend` | Local and HTTP execution backends for tool code. |
| `/plugins` | Skill and plugin loading (`agent-environment`). |
| `/compaction` | The compaction primitives and the evaluation harness. |
| `/memory` | The memory engine, adapters and the file store helpers. |
| `/connect` | Caveman Connect: provider data through one tool. |
| `/programmatic-tools` | The `caveman_code` runtime. |
| `/adapters` | Observability adapters for other harnesses. |
| `/wire` | `createCavemanTransport`, a spend ceiling on your own fetch. |
| `/model-boundary` | Middleware around the provider call. |
| `/model-usage` | Usage parsing and accounting status. |
| `/input` | `AgentInput` parts, limits and encoders. |
| `/run-receipt` | The receipt schema id and its parser. |
| `/catalog` | Public price catalog lookups and digests. |
| `/claude` | `runClaudeAgent`, the Claude harness. |
| `/testing` | `fauxModel` and `scriptedStream`. |
| `/cache-engine` | The cache planner's internals. Not part of the runtime's own exports. |

## Define an agent

| Export | Signature |
|---|---|
| `agent` | `agent(options): AgentDefinition` |
| `subagent` | `subagent(options): ToolDefinition` |
| `tool` | `tool(options): ToolDefinition` |
| `schema` | TypeBox builders: `object`, `array`, `string`, `number`, `integer`, `boolean`, `literal`, `union`, `optional`, `null`, `any` |
| `auto` | `auto(): Auto` |
| `AUTO` | The symbol an `Auto` carries. |
| `file` | `file(path: string): FileSource` |
| `context` | `context(options): ContextDefinition` |
| `memory` | `memory(options): MemoryDefinition` |
| `memoryTTLMilliseconds` | `memoryTTLMilliseconds(value: string): number` |
| `output` | `output(options): OutputDefinition` |
| `artifact` | `artifact(options?): ArtifactDefinition` |
| `evalFixture`, `eval` | `evalFixture(options): EvalDefinition`, and the same function under `eval` |
| `assertQualityGrader` | `assertQualityGrader(grader: unknown): asserts grader is QualityGrader` |
| `applyAgentDefinitionTransforms` | `applyAgentDefinitionTransforms(definition, transforms): AgentDefinition` |
| `shellTools` | `shellTools(options: ShellToolsOptions): ToolDefinition[]` |
| `routine` | `routine(original, impl, opts?): ToolDefinition` |
| `routineOutcomes` | `routineOutcomes(): readonly RoutineOutcomeCount[]` |
| `loadAgentDir` | `loadAgentDir(rootDir, options?): Promise<AgentDefinition>` |
| `composeAgentDir` | `composeAgentDir(input: AgentDirModules): AgentDefinition` |
| `AGENT_DIR_ENTRY` | `".caveman/agent-dir-entry.mjs"` |

Types: `AgentDefinition`, `AgentDefinitionTransform`, `AgentOutput`, `AgentDirConfig`, `AgentDirContextValue`, `AgentDirModules`, `AgentDirRunDefaults`, `ToolDefinition`, `ToolOptions`, `ToolEffect`, `ToolResultPolicy`, `ToolExecutionContext`, `ArtifactDefinition`, `OutputDefinition`, `ContextDefinition`, `ContextKind`, `ContextStability`, `CacheRegion`, `SafetyClass`, `PrivacyClass`, `RecoveryKind`, `MemoryDefinition`, `EvalDefinition`, `EvalSplit`, `EvalGuardrail`, `QualityGrader`, `FileSource`, `Auto`, `ShellToolName`, `ShellToolsOptions`.

## Run

| Export | Signature |
|---|---|
| `run` | `run(definition, input, options?): Promise<RunResult<AgentOutput<D>>>` |
| `stream` | `stream(definition, input, options?): AsyncGenerator<CavemanRunEvent>` |
| `runLocked` | `runLocked(definition, input, build, options?): Promise<RunResult>` |
| `createConversation` | `createConversation(): Conversation` |
| `AgentRunController` | Queue, steering and interrupt handle for an active run. |
| `CavemanRunError` | `Error` with `code` and the partial `receipt`. |
| `agentStaticContextDiagnostics` | `agentStaticContextDiagnostics(definition, rootDir?): Promise<AgentStaticContextDiagnostics>` |
| `verifySandboxConformance` | `verifySandboxConformance(): Promise<boolean>` |
| `decideToolCall` | `decideToolCall(policy, input): Promise<ToolCallDenial \| undefined>` |
| `TOOL_POLICY_TIMEOUT_MS` | The ceiling a tool policy has to answer within. |
| `resolveEgressPolicy` | `resolveEgressPolicy(policy: SandboxEgressPolicy): ResolvedEgressPolicy` |
| `egressAllowed` | `egressAllowed(policy, host, port): boolean` |

Types: `RunOptions`, `RunResult`, `CavemanRunEvent`, `ConversationState`, `RunBudget`, `RunStopReason`, `BudgetDenomination`, `BudgetController`, `BudgetTranche`, `BudgetExhaustionContext`, `BudgetExhaustionHandler`, `ModelCallRouter`, `ModelCallRouteInput`, `ModelCallRouteDecision`, `RunBreakers`, `BreakerEvent`, `ToolCallPolicy`, `ToolCallPolicyInput`, `ToolCallDecision`, `ToolCallDenial`, `SandboxEgress`, `SandboxEgressPolicy`, `ResolvedEgressPolicy`.

## Receipts and budget

| Export | Signature |
|---|---|
| `renderReceipt` | `renderReceipt(receipt: ReceiptLike): string` |
| `AGENT_RUN_RECEIPT_SCHEMA` | `"caveman.agent.run-receipt.v1"` |
| `defineRunReceipt` | `defineRunReceipt(value: unknown): RunReceipt` |
| `validateRunReceipt` | The same parser under a name that reads better at a check. |
| `createBudgetController` | `createBudgetController(): BudgetController` |
| `OUTPUT_CLAMP_FLOOR_TOKENS` | `256` |

Types: `RunReceipt`, `ReceiptCall`, `ReceiptTool`, `ReceiptCompaction`, `ReceiptResume`, `ReceiptLike`, `ReceiptPrintCall`.

## Memory

| Export | Signature |
|---|---|
| `MemoryEngine` | The engine class: `remember`, `recall`, `search`, `searchSessions`, `forget`, `link`, `consolidate`, `beginTurn`, `endTurn`, `flush`, `endSession`. |
| `createMemoryEngine` | `createMemoryEngine(options: CreateMemoryEngineOptions): MemoryEngine` |
| `createMemoryWorkflow` | `createMemoryWorkflow(engine, sessionId)` |
| `createFileMemoryAdapter` | `createFileMemoryAdapter(config?: { root?: string }): MemoryStorageAdapter` |
| `createInMemoryMemoryStorage` | `createInMemoryMemoryStorage(): MemoryStorageAdapter` |
| `createSparseEmbeddingAdapter` | `createSparseEmbeddingAdapter(dimensions?): MemoryEmbeddingAdapter` |
| `openAICompatibleMemoryEmbedding` | `openAICompatibleMemoryEmbedding(options): MemoryEmbeddingAdapter` |
| `completionMemorySidecar` | `completionMemorySidecar(options): MemorySidecarAdapter` |
| `emptyMemoryState` | `emptyMemoryState(): MemoryState` |
| `packVector` | `packVector(adapter, input): MemoryVector` |
| `cosine` | `cosine(first, second): number` |

`@caveman-ai/agent/memory` adds `memoryFilePath`, `readMemoryState` and the other file-store helpers. Types: `MemoryRecord`, `MemoryState`, `MemoryScope`, `MemoryHit`, `MemoryRecall`, `MemoryStorageAdapter`, `MemoryEmbeddingAdapter`, `MemorySidecarAdapter`, `MemoryRuntimeConfig`, `MemoryStoreConfig`, `MemoryAmbientOptions`.

## Compaction

| Export | Signature |
|---|---|
| `SUMMARY_SCHEMA_VERSION` | `2` |
| `normalizeCompaction` | `normalizeCompaction(options?): NormalizedCompaction` |
| `summarizationInstruction` | `summarizationInstruction(previous, sources?): string` |
| `parseContextSummary` | `parseContextSummary(text): ContextSummary \| undefined` |
| `renderSummary` | `renderSummary(summary): Record<string, unknown>` |
| `validateContextSummaryTransition` | `validateContextSummaryTransition(summary, previous, sources): ContextSummaryValidation` |
| `latestContextSummary` | `latestContextSummary(messages): ContextSummary \| undefined` |
| `contextSummarySources` | `contextSummarySources(messages, indexes): readonly ContextSummarySource[]` |
| `evaluateContextSummary` | Grades one capsule against its sources. |
| `evaluateContextSummaryStability` | Grades a sequence of capsules for drift. |
| `runContextCompactionHarness` | Runs a fixture set through the compaction path. |

`@caveman-ai/agent/compaction` adds the message-level primitives: `planCompaction`, `evictMessage`, `evictionCitation`, `elidedDigest`, `newContextMessages`, `pinnedContentSurvives`, `messageText`, `messageTokens`, `messagesTokens`, `CONTEXT_SEED_MAX_CHARS`.

## Context, profiles and the compiler

| Export | Signature |
|---|---|
| `lowerContext` | `lowerContext(options): LoweredContext` |
| `contextBill` | `contextBill(ir): Record<string, number>` |
| `appendRuntimeContextSegment` | `appendRuntimeContextSegment(lowered, segment): ContextSegment` |
| `contextIRToWire`, `contextIRFromWire` | Wire form of a Context IR, in both directions. |
| `sha256`, `stableStringify` | The digest and the canonical serialization the locks use. |
| `opaquePayload` | `opaquePayload(input: Uint8Array): boolean` |
| `normalizeTrajectory`, `parseNormalizedTrajectory` | Trajectory IR in and out. |
| `TRAJECTORY_IR_SCHEMA_VERSION` | `1` |
| `createWorkloadProfile`, `createCompilerWorkloadProfile`, `parseWorkloadProfile`, `workloadSplitSHA256` | Workload profiles from trajectories. |
| `WORKLOAD_PROFILE_SCHEMA_VERSION` | `1` |
| `compileProfiled`, `compileProfiledNativePi`, `planNativePiCandidates`, `nativePiCompilerTarget`, `capabilityManifestFor`, `assertProfiledBuildTarget`, `executeCompiledPipeline` | The profiled compiler. |
| `PROFILED_COMPILER_VERSION`, `PROFILED_COMPILER_SHA256`, `TARGET_CAPABILITY_LATTICE` | Compiler identity and what each harness can lower. |

## Input

| Export | Value |
|---|---|
| `normalizeAgentInput` | `normalizeAgentInput(input): NormalizedAgentInput` |
| `defineAgentInputEncoder`, `encodeAgentInput` | Encode parts for a provider that wants its own shape. |
| `AGENT_INPUT_MAX_PARTS` | `64` |
| `AGENT_INPUT_MAX_TEXT_BYTES` | `1048576` |
| `AGENT_INPUT_MAX_BASE64_BYTES_PER_PART` | `33554432` |
| `AGENT_INPUT_MAX_BASE64_BYTES_TOTAL` | `67108864` |
| `AGENT_INPUT_MAX_URL_LENGTH` | `8192` |
| `AGENT_INPUT_MAX_MIME_LENGTH` | `127` |
| `AGENT_INPUT_MAX_FILE_NAME_LENGTH` | `255` |

## Tool runtimes and transports

| Export | Signature |
|---|---|
| `localExecutionBackend` | `localExecutionBackend(): ExecutionBackend` |
| `httpExecutionBackend` | `httpExecutionBackend({ url, token }): ExecutionBackend` |
| `PROGRAMMATIC_TOOL_NAME` | `"caveman_code"` |
| `createProgrammaticToolRuntime` | `createProgrammaticToolRuntime(definition, options?)` |
| `programmaticToolInstructions`, `programmaticToolMetadata`, `createProgrammaticToolErrorWrapper`, `ProgrammaticSpeculationScope` | The rest of the programmatic surface. |
| `createConnect` | `createConnect(options: ConnectOptions): ConnectIntegration` |
| `ConnectRuntime`, `executeConnectTool`, `connectEnvironment`, `resolveConnectBinary`, `compareConnectEfficiency` | The Connect runtime and its helpers. |
| `createModelBoundary`, `captureModelBoundary` | Middleware around the provider call. |
| `MODEL_BOUNDARY_MAX_MIDDLEWARE`, `MODEL_BOUNDARY_MAX_ID_LENGTH`, `MODEL_BOUNDARY_MAX_CONTEXT_STRING_LENGTH` | `64`, `64`, `512` |
| `defineModelUsage`, `modelUsageAccountingStatus`, `requireCompleteModelUsage` | Parse and classify provider usage. |

## Durable stores at the root

`DiskDurableStore`, `HttpDurableStore`, `durableInputIsReplayable` and `durableRunSummary` are re-exported from the root. Everything else durable lives at `/durable`.

## `@caveman-ai/agent/serve`

| Export | Signature |
|---|---|
| `createAgentServer` | `createAgentServer(options: AgentServerOptions): AgentServer` |

Types: `AgentServerOptions`, `AgentServer`, `RecoveryReport`.

## `@caveman-ai/agent/serve-handler`

| Export | Signature |
|---|---|
| `createAgentHandler` | `createAgentHandler(options: AgentHandlerOptions): AgentHandler` |
| `INSTANCE_LOCK_RUN_ID` | `"caveman.instance.lock"` |

Types: `AgentHandlerOptions`, `AgentHandler`, `WebSocketLike`, `RecoveryReport`, `Principal`.

## `@caveman-ai/agent/durable`

| Export | What it is |
|---|---|
| `DiskDurableStore` | `new DiskDurableStore(root)`. Journal on disk, `0o700` directories and `0o600` files. |
| `SqlDurableStore` | `new SqlDurableStore({ sql, dialect })`. One `exec` method is the whole database dependency. |
| `ObjectDurableStore` | The same contract over S3, R2 or GCS. |
| `HttpDurableStore` | A journal behind an HTTP endpoint. |
| `DurableJournal` | The append-only journal itself. |
| `DurableToolCoordinator` | Tool intent and settlement across attempts. |
| `DURABLE_JOURNAL_VERSION` | `2` |
| `validateDurableRunId` | Rejects a run id that cannot be a journal key. |
| `durableToolIdempotencyKey`, `durableToolArgsSHA256` | The stable key an idempotent tool receives, and the digest behind it. |
| `durableConversationCheckpoint`, `durableConversationMessagesSHA256` | Bind a conversation to a journal by digest. |
| `durableInputIsReplayable`, `MULTIMODAL_DURABLE_INPUT_PREFIX` | Whether an input can be replayed, and the marker for encoded multimodal input. |
| `durableRunSummary`, `analyzeJournal` | Read a journal back: attempts, spend and what was in flight. |
| `validateReplayResult`, `validateReplayReceipt` | Check a replayed outcome against the run it claims to be. |
| `durableCancelRequest`, `requestDurableCancel`, `settleCancelledRun`, `DURABLE_CANCELLED_CODE` | Cancellation, recorded in the journal. |
| `scheduleDurableWake`, `nextDurableWake`, `durableRunIsDue`, `MAX_DURABLE_SLEEP_MS` | Durable timers. |

## `@caveman-ai/agent/code`

| Export | What it is |
|---|---|
| `createCodingAgent` | `createCodingAgent(options?): CodingAgent`. A workspace agent with the six shell tools. |
| `startCodingSession`, `runCodingSession`, `runCodingTurn`, `streamCodingTurn`, `classifyTurnFailure` | The session loop and one turn of it. |
| `sessionBill`, `formatTurnBill`, `formatSessionBill` | Per-turn and per-session accounting, as text. |
| `summarizeCodingTaskAttempts` | Economics across attempts at one task. |
| `proveRecovery`, `formatRecoveryProof`, `RECOVERABLE_CODING_TRANSFORMS` | Byte-exact recovery proof for the transforms a coding session may use. |
| `defaultCodingPlan`, `codingModelsAtProviderBaseURL` | The plan and the model list a session starts from. |
| `CODING_TOOL_OUTPUT_CAPS`, `capOutput` | Output caps for shell tools, and the function that applies one. |
| `CODING_RUN_BREAKERS` | The breaker set a coding run uses. |
| `OBSERVE_ONLY_BANNER` | The banner an observe-only session prints. |
| `AgentRunController`, `createCommandSessionRuntime`, `createProgrammaticToolRuntime`, `programmaticToolInstructions`, `PROGRAMMATIC_TOOL_NAME` | Re-exported so a coding client needs one import. |

## CLI

```bash
caveman-agent dev [entry] [prompt]
caveman-agent serve [dir] [--port N] [--host H] [--locked]
caveman-agent build [config] [--verbose] [--accept-prefix-shrink]
caveman-agent check [config]
caveman-agent doctor [--json]
caveman-agent register
caveman-agent connect [provider|providers|connections|status|doctor|...]
caveman-agent --version
```

Captured from `caveman-agent help` at 0.2.0. `--accept-prefix-shrink` resets the frozen-prefix baseline, and writes a new one only once a build completes.

## Sibling packages

| Package | On npm | What it is |
|---|---|---|
| `@caveman-ai/create-agent` | 0.1.0 | The initializer. `npm create @caveman-ai/agent@latest`, bin `create-caveman-agent`. |
| `@caveman-ai/evals` | checkout only | Deterministic and model-assisted graders. `grade(grader, value, deps?)`. An unknown grader type, or an option of the wrong type, returns a failed verdict naming the problem rather than a pass. |
| `@caveman-ai/react` | checkout only | `useAgent` and `useSession`, streaming a run or a session over Server-Sent Events. |
| `@caveman-ai/adapter-kit` | checkout only | Adapter manifests and the registry other harnesses register through. |
| `@caveman-ai/adapter-conformance` | checkout only | Deterministic conformance reports for those adapters. |
| `@caveman-ai/coding-agent` | checkout only | The interactive coding agent and the `caveman-code` CLI. |
| `@pebble-agent/protocol` | checkout only | The PEBBLE wire and storage contract: turn events, session entries, JSONL-RPC framing. Frozen at v1. |

`@caveman-ai/agent` itself is 0.1.0 on npm; these pages document 0.2.0 from source. A checkout-only package reaches you as a dependency of the workspace `@caveman-ai/agent` you [install from the checkout](/docs/agent-sdk/install#build-from-the-checkout).

The cache planner under `src/cache-planner/` is deliberately not re-exported from the runtime: it is reachable only through the `/cache-engine` subpath while its public shape is being decided.