#可观测性

Agent 做的每件事本来就是一条带类型的 AgentEvent 流——文本增量、工具调用、结果、权限判定、后台任务完成。可观测性就是接住这条流：实时喂给你的 UI，和/或用 jsonlEventSink / recordEventStream 持久化成一份哈希链式 JSONL 审计日志。不需要额外的 tracing SDK。

#记录事件流

用 recordEventStream 包住任意事件流，把每个事件旁路写入 EventSink，同时原样向下游传递：

import { query, jsonlEventSink, recordEventStream } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";

const sink = jsonlEventSink({ file: "./audit/events.jsonl" });

const stream = recordEventStream(
  query({
    prompt: "Summarize package.json",
    model: anthropic(),
    modelName: "claude-sonnet-4-6",
    cwd: process.cwd(),
  }),
  sink,
  "session-1",
);

for await (const ev of stream) {
  if (ev.type === "text_delta") process.stdout.write(ev.text); // live UI output
}
await sink.close();

同一个循环也是驱动 UI 的方式：每个 AgentEvent 都有类型（text_delta、tool_use、permission_decision、background_completed 等），渲染层按 ev.type 分支即可。

#jsonlEventSink

jsonlEventSink(opts) 返回一个 EventSink，每行追加一条 JSON 记录：

export interface EventRecord {
  v: 1;
  ts: string;              // ISO timestamp
  sessionId: string;
  seq: number;             // per-file sequence
  prevHash: string | null; // hash of the previous record
  hash: string;            // sha256, or HMAC-sha256 with integrityKey
  event: AgentEvent;       // redacted before hashing
}

记录构成哈希链——每条记录都承诺了它的前驱，被篡改或重排的日志可以被检出。写入是串行化的，默认持久（每条记录 append + fsync）。

相关类型：EventSink（write(sessionId, event) / close()）、EventRecord、JsonlEventSinkOptions。

#权限审计事件

打开 permissionAudit: true 后，闸门会为每个决定向会话事件日志追加一条脱敏的 permission_decision 事件——包括决策者（policy / user / auto）。由于审计轨迹就在同一条事件流里，recordEventStream 会把它和其他事件一起捕获；配合 permissionMode: "dry-run" 可以记录候选策略将会拒绝什么而不实际拦截。见权限。

#另请参阅

• 权限 — permissionAudit、dry-run 与脱敏。
• 检查点 — 会话事件日志本身。
• 后台任务 — background_completed 事件。
• Core 策略 — AgentEvent 类型的来源。