SDK 运行、事件与用量

一次 send 返回一个 Run，同一 Agent 的后续 send 继承会话。下面 API 名以 TypeScript 为主，Python 使用对应 snake_case，并有独立的终止与流消费规则。

读取结果

await run.wait() 返回 RunResult，最终文本在 result.result，不是 text、message 或 content。可检查 status、error、model、durationMs、usage 和云端 git。结构化会话使用 run.conversation()。

TypeScript RunStatus 为 running、finished、error、cancelled；Python 还明确暴露 expired。SDK 流中的云端 status 事件使用大写服务端状态，不应与句柄的规范化状态直接混作一个枚举。

消费事件

SDKMessage 按 type 区分 system、user、assistant、thinking、tool_call、status、task、request、usage，并带 agent_id 与 run_id。assistant 文本位于 message.content 的 text block，tool_call 通过 call_id 关联开始和完成。

工具 args/result 的具体结构可能变化，按 unknown 防御式解析；truncated 表示较大字段被截断。最终结果保留在 Run 上，不靠猜测最后一个 assistant 事件。

TypeScript send 的 onDelta/onStep 和 Python SendOptions 的 on_delta/on_step 提供更细粒度更新。TypeScript 回调参数含 update/step，Python 回调直接接收对应对象；回调完成或 await 后才处理下一事件，可用于背压。

取消与 steering

TypeScript run.cancel() 对已完成轮为无操作；Python 对已终止轮抛 UnsupportedRunOperationError，应检查 run.status。Python supports/unsupported_reason 只表示接口能力，不验证当前状态。

TypeScript run.steer(text) 可把指令送入正在执行的本地轮：complete_delivered 表示已接收，不能重复发送；revert_to_followup 表示等待当前轮完成后另 send。云端和 detached local handle 会回退。steer 是可选方法，不属于 RunOperation，检查方法本身而不是 supports。

本地后台 subagent 的结果会作为同一 Run 的后续轮继续处理，stream 会继续，wait 最终返回最后一轮文本，不能在父轮首次结束时提前视为全 Run 完成。

Token 与实际计费

usage 事件给出一轮的统计，run.usage/result.usage 是本次 Run 累计。未报告时为 undefined（Python 为 None），不能当作零用量。totalTokens 是输入、输出、缓存读取和缓存写入之和；reasoningTokens 是 outputTokens 的子集，不重复累加。

agent.getUsage() / agent.get_usage() 返回账单记录：cloud 按 Run，local 按 turn。cost 结算前可缺失；rawCostCents 为未折扣模型成本，chargedCents 含折扣与 Cursor Token Fee，按套餐包含、BYOK 或赠送 credit 的用量可为 0。

本地账单查询正在逐步开放，未开放时返回 403 feature_unavailable；TypeScript 映射为 UnknownAgentError。实时 token 与账单是两种视图，不能自行用 token 量替代已结算费用。

关联诊断

TypeScript Run/RunResult 的 requestId 可将脚本任务与后端日志对应；服务端返回时也会出现在云端轮。记录它及错误中的 requestId；Python 错误字段为 request_id。不要只记录 Agent ID 而丢失具体失败轮。