Apache-2.0

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.

typescript

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#

terminal

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.

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.