caveman 的 @caveman-ai/agent 深度解析：带目录价守护、Token 账单与沙箱工具的 TypeScript 智能体框架

@caveman-ai/agent 是 caveman 仓库中 packages/agent 目录下的 TypeScript 智能体框架，它把"每次模型调用花掉了多少 token、上下文哪部分在消耗 token、能否换成更便宜的上下文方案"变成了一组可声明、可审计、可验证的工程原语。读完本篇，你将掌握：从 npm create 到 observe-only/optimized 双模式运行、maxCostUsd 目录价预算的预留-结算机制、三种沙箱模式（required/fixture/host）的真实内核边界、持久化记忆存储的原子写实现、Claude Agent SDK 通道的 fail-closed 设计，以及 eval 门控的 Cave Build 编译流程。以下内容以 packages/agent/README.md 为主体，所有实现细节均可在 packages/agent/src/ 下逐一对应。

快速开始：两条命令，零托管依赖

运行前置条件：Node.js 22.19+（packages/agent/package.json 中 engines.node 为 >=22.19.0）和一个受支持的 provider 凭据。

npm create @caveman-ai/agent@latest my-agent
cd my-agent
npm run dev

两条命令，不需要 Caveman 账号，也不需要任何托管 Caveman 服务——只需要 provider 凭据和网络。在一台从未装过 Caveman 的机器上，首次运行输出如下：

$ npm create @caveman-ai/agent@latest my-agent
$ cd my-agent && npm run dev

  cave: observe-only — engine/gateway unavailable; transforms and gateway
  telemetry off (provider usage and local context estimates remain available)

  agent > what does src/index.ts export?
  … model answers through your own provider credential, direct to the provider …

npm run dev 会在已安装时自动拉起本地 Cave Runtime。Runtime 不可用时，运行进入 observe-only 模式：走 provider 自己的 base URL、无 transform、无 gateway 遥测，RunResult.mode 为 "observe-only"。此时 provider 自报用量和本地上下文估算仍然可用，但不声明任何效率收益。要启用 Engine：

npm i -g @caveman-ai/cli && caveman start

之后同样的命令会以 mode: "optimized" 运行，经本地 gateway 路由并启用合格的 transform 与上下文遥测。Gateway 代理 anthropic、openai、google 三家；其他 provider 直连并报 observe-only。也可以在 RunOptions 里显式设 cave: "off" 选择 observe-only。携带 Cave Build 锁或候选 plan 的运行拒绝静默降级，直接抛 cave_gateway_required_for_locked_plan。

从源码结构看，框架只接受回环（loopback）runtime，且要求健康身份、运行状态、PID 和可执行文件归属四重校验全部通过；无关的本地监听端口永远不会收到 provider 流量，该次运行降级为 observe-only 直连。同时，本地结果一律标记 inferred，verified 节省额保持 $0，直到生产流量通过独立的 rollout 与 ledger 门槛——这是整个框架"诚实计量"基调的源头。

doctor：零 provider 调用的就绪检查

首次使用或部署前，先跑一个不发起任何模型请求的预检：

$ npx caveman-agent doctor          # 加 --json 获取机器可读报告
PASS node         Node 22.19.0
PASS sandbox      tool sandbox containment probe passed
WARN engine       Caveman engine not found — transforms disabled (observe-only)
WARN runtime_cli  Caveman runtime CLI unavailable — runs stay observe-only
WARN gateway      gateway not reachable at 127.0.0.1:8787 — telemetry off
...
run mode: observe-only (no transforms or gateway telemetry)
next: npm i -g @caveman-ai/cli && caveman start

缺失 Engine、runtime CLI 或 gateway 只是 WARN 且退出码为 0，因为 observe-only 运行本来就能工作；而 Node 版本不符、沙箱包含探针失败、配置非法或 lock 漂移则会导致检查失败。doctor 同时检查 engine 注册表、gateway 可达性、项目/配置加载、Context IR 与 provider 选择。CLI 完整命令面为 dev、build、check、doctor、register（caveman-agent 这个 bin 由 package.json 映射到 ./dist/cli.js）。

最小智能体：agent() 与 run()

import { agent, auto } from "@caveman-ai/agent";

export default agent({
  id: "support",
  instructions: "Answer from policy. Never invent policy.",
  model: auto(),
});

auto() 选择已配置/默认模型，解析顺序为：环境变量 CAVE_MODEL → .caveman/provider.json → 唯一受支持 provider 凭据的基线模型。它不做任务分类，也不在模型间路由。

从 src/index.ts 可以看到 agent() 并非简单的对象包装：agent id 必须匹配 ^[a-z0-9][a-z0-9_-]{0,95}$；工具名查重；cave_ 前缀被框架保留（用于恢复与记忆工具），声明冲突会直接抛错；sandbox 默认 "required"；reasoning 默认 "low"。返回的 definition 被 Object.freeze 冻结——定义是不可变的。

用代码运行：

import support from "./agent.js";
import { run } from "@caveman-ai/agent";

const result = await run(support, "Can I get a refund?");
console.log(result.text);
console.log(result.contextBill);

这一次运行在一台只有 Node 和 provider 凭据的机器上就能工作，返回 mode: "observe-only"；装上并启动 Caveman runtime 后，同一个调用返回 mode: "optimized"。

maxCostUsd：目录价预留，而非财务执法

RunOptions.maxCostUsd 为一次运行设置尽力而为的本地消费上限（USD，按公开目录价计）。它不是财务执法：没有 provider 发票、平台配额或跨进程预留。但一旦设置，每一次根调用和子孙调用的模型请求，在发出前都会按目录最坏价格向预算预留，调用结束后结算实测目录成本。预算耗尽时以 cave_run_cost_budget_exceeded 结束运行（发生在下一次模型调用之前），已发出的记录保留，不产生 run_end 结果。公开目录无法定价的模型无法被封顶：设置了上限的此类调用会 fail-closed，而不是当花 $0 处理——无法计量的上限不是上限。跑无定价模型时应留空该上限，改用声明的调用上限约束。

这个语义在 src/budget.ts 中有完整实现：callCeilingCost 对目录无法定价的模型返回 undefined，注释明确"对 USD 预算而言是硬停，绝不是零"。该文件还定义了 RunStopReason 全集（complete、budget_exhausted、deadline、loop_detected、no_progress、wallet_revoked、call_budget_exhausted），以及输出钳制下限 OUTPUT_CLAMP_FLOOR_TOKENS = 256——低于它，钳制出的调用买到的只是截断碎片而非进展，于是运行时进入耗尽阶梯而不是花这笔钱。

流式事件与调用上限

usageBasis 覆盖 provider 自报的聚合用量；reasoning 拆分有独立的 reasoningUsageBasis：当具备推理能力的 Pi 模型省略该可选拆分时，未解锁运行将其标记为 unavailable，而 Cave Build 与子代理核算则 fail-closed，绝不把缺失当零。

• 用 stream() 获得类型化的 run、context、Pi、completion 与 error 事件。
• 调用迭代器的 return() 会在会话所有权释放前中止在途的 provider/工具/子代理工作；终态的 run_end 与 run_error 事件在投递前释放所有权，手动消费者不会搁浅会话。
• 两个终态事件都携带 ledger：run_error.receipt 是失败前已花费的部分收据；promise 入口抛出的 CavemanRunError 的 receipt/cause 携带同一内容——花了钱再失败的运行永远不会丢失逐调用明细。
• 每次模型调用受 RunOptions.maxModelCalls 上限约束（工具调用受 maxToolCalls 约束，两者默认均为 64）；触到模型上限时运行以 stopReason: "call_budget_exhausted" 优雅结束，而不是抛异常。

多轮对话显式创建一个 conversation 并复用：

import { createConversation, run } from "@caveman-ai/agent";

const conversation = createConversation();
await run(support, "My order is late.", { conversation });
const followUp = await run(support, "What should I do next?", { conversation });

npm run dev 会自动做这件事：在监听的工程源码、配置、eval 或文件上下文变化之前，dev 复用一份完整的工程相对源码图的不可变暂存副本；reload 时替换快照，而成功的会话历史保留在父进程本地。执行中的定义、沙箱工具、声明的根/子文件源与 Cave Build 身份全部使用同一快照。定义、模型或 plan 变化会轮换缓存 epoch，且不重放陈旧的 prefix 字节；失败的回合回滚会话/缓存状态，同一会话的并发使用 fail-closed。一个 ESM 热重载的已知限制：Node ESM 无法在热重载后拆除旧模块图创建的 timer 或 listener，因此保持 agent 模块顶层无副作用，或在编辑了拥有进程资源的模块后重启 dev 命令。

沙箱模式三态：required、fixture、host

带工具且默认 sandbox: "required" 的程序化 agent 必须传 RunOptions.entryPath，指向导出 agent 定义的模块（CLI 会自动提供）。在 provider 流量之前，框架把完整工程源码图拷入逐次运行不可变的 staging，只从该快照导入工具，并在流结束时拆除 staging；框架拒绝在进程内运行此类工具。受信任的测试可以选入 sandbox: "fixture"。

host 是第三种模式，面向需要真实主机访问的交互式/编码 agent。它是显式选入、永不做默认：闭包在本进程运行、无工具 worker、无 entryPath 要求，effect: "write" 工具会执行而非被拦截。effect 声明仍然强制——host 模式改变的是执法，不是声明。host 模式 agent 不能位于 sandbox-required 祖先之下（子代理不能借此逃离根容器，源码错误码 cave_host_sandbox_nested_under_required）；host 运行的 agent 永不具备 lock 资格，compile 会在任何搜索运行前以 cave_host_sandbox_lock_ineligible 拒绝它。编码 agent 的锁定构建改为对 fixture 语料、以受包含的沙箱模式编译。

原生 Windows 支持普通 agent 运行、runtime/engine 启动，以及经 cmd.exe 的显式 sandbox: "host" 编码工具；但 sandbox: "required" 在原生 Windows 上保持 fail-closed，因为该包在那里没有经过验证的 OS 级网络隔离边界——生产沙箱工具请用 WSL2。doctor 会报告确切的 cave_sandbox_os_network_isolation_unavailable 失败与 WSL2 补救。生产环境绝不能用 fixture 模式顶替 required 沙箱。

真实的 required 模式边界在 SANDBOX_THREAT_MODEL.md 中按平台逐条列明，这份文件值得直接通读：

• Linux：unshare --user --map-root-user --net 新网络命名空间，无任何接口，IP 出口（TCP/UDP/DNS）不可能；
• macOS：sandbox-exec -p '(version 1)(allow default)(deny network*)'，内核级拒绝网络操作；
• 其他平台：fail-closed，工具根本不能运行。

之上叠加 Node 权限模型（--permission + --allow-fs-read/--allow-fs-write）：读限于暂存源码图、框架包根、依赖闭包与临时工作区，写限于工作区，child_process 整体拒绝（cave_sandbox_child_process_containment_unavailable）。威胁模型文件坦承两点：installNetworkDeny 的 monkeypatch 只是纵深防御、不是边界（new net.Socket().connect(...) 就绕过它）；Linux 网络命名空间不覆盖 unix domain socket（如 /var/run/docker.sock），该缺口已登记为 bwrap 迁移跟踪项。这种"点名真实边界、点名每个缺口"的诚实规则，是理解该包安全姿态的钥匙。

sandboxProfile.network: true 不是放行出口的手段：它请求的是无界出口，会 fail-closed 报 cave_sandbox_network_egress_unbounded（尚无 scoped-egress 机制，跟踪中的方案是父进程持有的 CONNECT 代理）。一个 live profile 最多请求一个运行时托管的 provider 凭据能力：ANTHROPIC_API_KEY、OPENAI_API_KEY 或 Google 能力（GEMINI_API_KEY 与 GOOGLE_API_KEY 互为别名）；签名、部署、bootstrap、数据库、云、loader 与环境变量名一律分类拒绝，子进程从固定基线环境（LANG、LC_ALL、PATH、TZ 与 fixture 标记）而非父环境展开中启动。

框架子代理可使用普通工具并继续委派子代理。CLI 自动传一次根入口；程序化运行在根上传一次 entryPath。框架保持后代路由私有，在沙箱重导入后校验根与被选工具的定义摘要，再在受限子进程中执行精确的子工具。后代模型调用在向 provider 发起调用前，向每个祖先的 maxCostUsd 上限预留目录最坏花费；每一轮必须报告完整用量与精确请求的 provider/model。

工具声明：effect 与 result policy 都是显式契约

import { schema, tool } from "@caveman-ai/agent";

const lookupPolicy = tool({
  name: "lookup_policy",
  description: "Read current refund policy.",
  input: schema.object({ region: schema.string() }),
  effect: "read",
  result: "auto",
  async execute({ region }) {
    return { region, refundWindowDays: 14 };
  },
});

input 同时接受 Standard Schema v1：实现 Standard JSON Schema v1 的库会自动转成 draft-07 provider schema（src/primitives.ts 中 tool() 会调用 standard.jsonSchema.input({ target: "draft-07" })）；仅有校验能力的 Standard Schema 库则显式传 inputJSONSchema。框架无论如何都在工具代码执行前运行 schema 校验器，包括异步校验与转换。工具名必须匹配 ^[a-zA-Z][a-zA-Z0-9_-]{0,127}$，timeoutMs 默认 30 秒。

Effect 四种：read、write、idempotent、external。

Result policy 五种：

policy	行为
auto	由锁定 plan 选择 inline、paging、压缩或精确 CCR
inline	结果留在当前上下文
page	暴露有界分页
compress	使用合格的锁定 transform
exact_ccr	仅在字节级精确恢复已存储后替换

上下文、记忆与输出

import { context, file, memory, output, schema } from "@caveman-ai/agent";

const playbook = context({
  id: "support.playbook",
  kind: "skill",
  source: file("./support.md"),
  stability: "build",
  safety: "S0",
  priority: "required",
});

const supportMemory = memory({
  namespace: "support",
  ttl: "30d",
  recallBudget: 1_200,
  consent: "local_only",
});

const answer = output({
  maxTokens: 500,
  schema: schema.object({ answer: schema.string() }),
});

Build-stable 上下文进入冻结 prefix；session 与 turn 上下文保持 live。运行时拒绝在稳定缓存区放易变数据，且在漂移或 transform 失败时 fail-open 回到 provider 可见的原始字节。Cave Build 只绑定静态 Context IR；eval 输入、用户回合、历史与工具结果保持为运行时证据，lock 永不依赖某一个 fixture prompt。

memory()：30 天是真实的 30 天

memory() 是持久、租户作用域的本地存储：ttl: "30d" 是真实的 30 天承诺——条目跨进程重启持久化，而非只活在一个进程生命里。实现刻意零依赖：src/memory-store.ts 用 node:fs 按命名空间一个 JSON 文件，原子"临时写 + rename"落盘，没有往包的紧依赖面里拉 SQLite 驱动。cave_memory_remember / cave_memory_search 工具读写它；超过声明 ttl 的记忆在读取时被逐出（从磁盘清除，不只是从响应里过滤）。召回的记忆永远保持 inferred basis——这里任何东西都不构成节省。

条目以 (tenant, agentId, namespace) 为键，同进程里两个声明相同 namespace 的 AgentDefinition 互不可见，嵌入服务可按租户隔离。RunOptions.memory 控制位置与归属：root 默认 CAVE_AGENT_MEMORY_ROOT，否则 ~/.caveman/agent-memory；tenant 默认单租户。源码中三个作用域分量都校验为不含 . 与路径分隔符的字字符集，防止逃逸出 memory root；文件以 0o600 写入、临时文件用 wx 标志拒绝已存在路径（因为记忆可能含 prompt、客户或工具结果数据），进程内按文件串行化读写，跨进程靠原子 rename 防撕裂文件，并发更新 last-writer-wins。只有 provenance: "local" + consent: "local_only" 被支持——共享后端配置在 memory() 构造时就被拒绝，而不是拖到工具调用时。

编码智能体：@caveman-ai/agent/code

新一代 caveman-code：构建在该框架上的交互式编码 agent，在一个 workspace 上提供 host-sandbox 的 read_file / grep / bash / edit_file 工具，是已弃用的 caveman-code fork 的继任者。

import { createCodingAgent, runCodingSession } from "@caveman-ai/agent/code";

const agent = createCodingAgent({ workspace: process.cwd() });
await runCodingSession({ agent });

默认 optimized，但 observe-only 会大声说出来。 Caveman engine 在场时，会话启动本地 Cave runtime 并以默认效率 plan 运行：每个 live-zone 段类型一条可恢复路由——tool_result 走 caveman.engine.terminal.v1，history 走 caveman.engine.text.v1——并注册 cave_retrieve，让模型能取回精确原始字节。只有 CCR 可恢复的 transform 合格；toon 是 force-only、默认永不路由；任何无恢复的有损类别都不进默认 plan。每种类型一条路由是刻意为之：两条路由匹配同一个运行时段会坍缩为 dynamic_route_ambiguous，该段原样通过。src/code.ts 中 defaultCodingPlan 的 plan_id 正是 caveman-code.default.recoverable-live-zone，且所有 fallback 均为 original。

runtime 不可达时会话降级为 observe-only——但绝不静默：打印 banner（engine/gateway 不可用、transform 与 gateway 遥测关闭、provider 用量与本地上下文估算仍可用、npm i -g @caveman-ai/cli && caveman start），记录到 session.notices，并在 prompt 与每一回合的账单上显示模式。携带 plan 的回合拒绝自行降级：抛 cave_gateway_required_for_locked_plan，且只有这一种失败允许不带 plan 重试一次。runtime 每会话探测一次而非每回合：答案钉在会话上——没有 runtime 的机器整个会话只付一次失败的启动尝试，一旦降级就一直降级。

Token 账单是 token 计数。 每回合后，会话打印 transform 前后的上下文 token（来自 RunResult.transformTrace）、标注 inferred (local estimate) 的节省 token、带 usageBasis 的 provider 用量，以及带 priceBasis 的 USD 花费。节省永不以货币表达；本地会话不铸造任何东西——verified 节省是平台证据，不是笔记本能产出的。

恢复是被证明的，不是被声称的。 /prove-recovery（以及首次压缩后的一行自动输出）取一条被记录的工具输出，跑过 plan 与 cave_retrieve 使用的同一 engine 压缩/取回对，报告 sha256 比较结果：

recovery proof: read_file:big.txt round-trip OK (sha256 match efac7be09c1a)

不匹配打印为 FAILED (sha256 mismatch)，plan 回退到原始正文。工具输出在压缩之前就被封顶（read_file 与 bash 24 KB，grep 16 KB，全部低于运行时 inline 工具结果上限），因此即使没装 engine，失控命令也吹不爆上下文。live 编码会话永不具备 lock 资格：host 模式让 compile 以 cave_host_sandbox_lock_ineligible 拒绝，会话做不出任何东西成为 Cave Build。内部可运行示例：examples/coding-agent（仅源码仓库）。

Evals 与 Cave Build：搜索之后的锁定

import { eval as defineEval } from "@caveman-ai/agent";

export const refund = defineEval({
  id: "refund",
  approved: true,
  input: "Can I get a refund?",
  quality: [
    { type: "contains", fragments: ["14 days"] },
    { type: "tool_called", tools: ["lookup_policy"] },
  ],
});

npm run build
npm run check

Build 对每个 approved fixture 执行五个种子的有限搜索。以下任一情况成立时不写 optimized lock：用量缺失、模型无定价、缓存回退、恢复失败、沙箱/隐私失败、质量下降、搜索不完整、成本上限超出。check 在模型调用前拒绝漂移。成功构建的输出依次给出：选定模型、reasoning、transform 路由、每任务基线与选定方案的公开目录成本、推断百分比变化、完成的 eval 证据，然后才打印 lock 身份。公开 run() 无法注入 plan 或 build 身份；npm run dev、build、check 才拥有已验证的 Cave Build 执行权。锁定/候选执行在 provider 流量前校验所选 provider、模型与 reasoning；每个 provider 回合必须返回精确的 provider/model 身份与算术完整的用量，框架从公开目录重算成本。

高级构建配置在 @caveman-ai/agent/build，Claude 公开执行在 @caveman-ai/agent/claude，@caveman-ai/agent/adapters 导出可执行的 Vercel AI SDK、Eve、Mastra 适配器。每个适配器要求 Cave Build 的 harness、适配器版本、上游版本、选定 plan 与 Context IR 全部匹配后才进入 provider 执行；运行时结果须携带终态文本、实际响应模型身份、完整 provider 用量、transform/恢复证据与可目录定价的模型。适配器重算成本；本地结果保持 inferred、verified 节省 $0。

Claude Agent SDK 通道

同一份 agent 定义可以走精确锁定的 Claude Agent SDK 通道：

import { runClaudeAgent } from "@caveman-ai/agent/claude";
import { fileURLToPath } from "node:url";
import support from "./agent.js";

const result = await runClaudeAgent(support, "Can I get a refund?", {
  entryPath: fileURLToPath(new URL("./agent.js", import.meta.url)),
  maxTurns: 8,
  maxBudgetUsd: 0.50,
});

• 公开通道永远未锁定，返回 claimBasis: "inferred"、verified 节省 $0。它禁用 Claude 内置工具与设置，把声明的 read+inline Caveman 工具映射进一个进程内 MCP server，复用与 Pi 相同的不可变源码快照与沙箱执行器，强制声明的模型/reasoning/输出 schema，并经 Caveman Anthropic 代理发送请求。
• Memory 与框架子代理在 Claude 通道 fail-closed（等价语义尚未存在）；write/idempotent/external 工具以及 auto/page/compress/CCR 结果在 SDK/工具执行前被拒绝，防止副作用之后恢复不可用。
• 框架在添加自己的 content-blind 显式透传元数据之前剥离继承的 x-cave-* 头；调用方无法注入 Cave Plan 或 Cave Build 身份。
• 公开通道默认 16 回合。maxTurns 与 maxBudgetUsd 设置显式 SDK 上限；声明的 output({ maxTokens }) 成为 SDK 任务 token 预算与终态 provider 用量上限。reasoning 对模型能力敏感：Haiku 4.5 用固定 manual thinking、无 effort；已知自适应模型用 adaptive thinking 加声明 effort；未知能力在 provider 花费前失败。manual thinking 要求 maxTokens 高于其 1,024/4,096/8,192 token 的 low/medium/high 预算。
• 锁定的 Agent SDK 报告聚合输出 token 但没有权威 thinking-token 拆分，因此结果暴露 reasoningUsageBasis: "unavailable"；reasoningTokens: 0 是非证据占位符，不能读作实测为零。

许可提醒：包锁定 @anthropic-ai/claude-agent-sdk 0.3.220 与 Claude Code 2.1.220 身份（见 package.json 依赖），Anthropic SDK 非 MIT，其 README 指向 Anthropic 商业条款并描述数据收集；框架源码保持 MIT，但使用 Claude 通道的用户必须自行审查 Anthropic 条款与数据政策。

框架适配器与审计边界

适配器直接接受精确锁定的上游对象：Vercel ToolLoopAgent 7.0.43、Eve ClientSession 0.29.2、Mastra Agent 1.55.0（与 package.json 的 peerDependencies 完全一致，且均为 optional peer——只装你用的 lane）：

npm install @caveman-ai/agent ai@7.0.43
npm install @caveman-ai/agent @mastra/core@1.55.0
npm install @caveman-ai/agent eve@0.29.2

Eve 0.29.2 要求 Node.js 24+；基础 SDK、Vercel、Mastra lane 维持包最低 Node.js 22.19。适配器启动时读取已安装框架包版本，在模型执行前拒绝缺失或漂移的版本。三个适配器都透传 abort 信号；Mastra processor 重试强制为零；Eve 聚合持久 step.completed 用量并校验 session.started 运行时身份——由于 Eve 0.29.2 省略 reasoning-token 用量，只有 reasoning: "none" 的 Cave Build 能在其上执行；Vercel 与 Mastra 的 reasoning build 需要显式的 provider 自报 reasoning 用量。动态 Eve 模型身份、模型漂移、用量缺失、终态失败、无定价模型与版本漂移一律拒绝。Pi lock 永远不能授权 Claude 或第三方执行。适配器身份要求显式的 built-bundle 与依赖锁的 SHA-256 值——函数源码文本从不构成制品身份。

安全审计边界（检查于 2026-08-10）：发货的运行时依赖以 npm audit --omit=dev 通过零告警；完整可选适配器/开发图有一条来自 Mastra 精确 @ai-sdk/provider-utils 3.0.30 兼容依赖的上游低危资源消耗告警——最新 Mastra 1.57.0 仍锁定该版本，不存在已修补的 3.x 发布。发布 CI 拒绝任何运行时告警以及全图任何 high/critical 告警。

公开表面与适用边界

• 核心：agent、run、stream、createConversation、auto；tool、schema、artifact、subagent；context、file、memory、output；eval；Context IR 类型与降级助手；verifySandboxConformance（配合 createBudgetController 与 RunReceipt 等预算类型一起从 src/index.ts 导出）
• runClaudeAgent（@caveman-ai/agent/claude，仅 unlocked/inferred）
• createCodingAgent、startCodingSession、runCodingTurn、runCodingSession、defaultCodingPlan、proveRecovery（@caveman-ai/agent/code）
• createVercelAISDKAdapter、createEveAdapter、createMastraAdapter（@caveman-ai/agent/adapters）
• CLI：dev、build、check、doctor、register；doctor 不发起任何模型请求，人类可读输出恒打印 verified savings: $0

前提与限制：Node.js 22.19+（Eve 通道 24+）；框架包 MIT 许可，Claude Agent SDK 使用受其依赖 README 链接的 Anthropic 条款约束；sandbox: "required" 目前仅在 Linux/macOS 有真实内核边界，原生 Windows 保持 fail-closed，生产沙箱工具走 WSL2。这套框架的贯穿性设计可以概括为一句话：每一个数字都标注自己的 basis（inferred 还是 verified），每一个失败都 fail-closed 并留下账本，每一个声明的边界都点名自己覆盖与不覆盖什么——这正是它与"调低温度、截断上下文"式省 token 方案的本质区别。