@lqc123qwe/car-runtime 1.9.0 → 1.11.0

package/src/loop/stop.ts

@@ -10,6 +10,9 @@
  *    turn 内任一 step 撞限 → turn/end 保留 max-tokens，不被后续成功 step 冲销
  *  - 工具收口：concludesTurn=OR（任一 true 即收口）；terminate=AND（整批 finalized 全 true 才中断）
  *  - 取消：未派发调用补记成对事件（toolCall + 合成错误 toolResult），日志无缺口
+ *  - 1.11-S2（D-33 / 计量设计 §3.3）：turnEnd meta.usage = 本 turn usage 事件四分量求和
+ *    （聚合在内核消费侧单点 closeTurn——适配器无状态 ACL；无 usage 事件 → meta 不带 usage 键，
+ *    缺省=未采集向后兼容；撞限/异常 turn 照常聚合，截断前已完成请求的 usage 事实不吞）
  */
 import type { SessionLog } from '../session/log.ts'
 import { CarM8Error } from '../runtime-core/errors.ts'
@@ -58,6 +61,29 @@ export class TurnAborted extends Error {
   constructor() { super('CAR-ABORTED: turn cancelled by user') }
 }
 
+/**
+ * 1.11-S2（D-33 / 计量设计 §3.3）：turn 级 usage 聚合——扫描本 turn 的 'usage' 事件（事实本体
+ * 在 JSONL，聚合由事实行求和而非运行时状态；字段非数值容错跳过不吞计数）。无 usage 事件
+ * 返回 undefined → turnEnd meta 不带 usage 键（缺省=未采集，旧格式向后兼容）。
+ */
+function turnUsageFrom(log: SessionLog, turnId: string): { input: number; output: number; cacheRead: number; cacheCreation: number; requests: number } | undefined {
+  let input = 0
+  let output = 0
+  let cacheRead = 0
+  let cacheCreation = 0
+  let requests = 0
+  for (const e of log.events) {
+    if (e.kind !== 'usage' || e.turnId !== turnId) continue
+    const p = (e.payload ?? {}) as Record<string, unknown>
+    if (typeof p.input === 'number') input += p.input
+    if (typeof p.output === 'number') output += p.output
+    if (typeof p.cacheRead === 'number') cacheRead += p.cacheRead
+    if (typeof p.cacheCreation === 'number') cacheCreation += p.cacheCreation
+    requests++
+  }
+  return requests ? { input, output, cacheRead, cacheCreation, requests } : undefined
+}
+
 export async function runTurn(opts: {
   log: SessionLog
   turnId: string
@@ -72,6 +98,13 @@ export async function runTurn(opts: {
   let sawMaxTokens = false
   let steps = 0
 
+  // 1.11-S2（D-33）：turnEnd 落链单点包装——聚合本 turn usage 事件（无 usage 不带键，
+  // 缺省=未采集向后兼容）；reason 保持 meta 首键，usage 恒为加法尾键
+  const closeTurn = (meta: Record<string, unknown>) => {
+    const usage = turnUsageFrom(log, turnId)
+    return log.append('runtime', 'turnEnd', turnId, null, { ...meta, ...(usage ? { usage } : {}) })
+  }
+
   const executeBatch = async (calls: ToolCall[]): Promise<{ concludesTurn: boolean; concludesAll: boolean; terminateVotes: number; terminateAll: boolean; finalized: number; denies: number }> => {
     let concludesTurn = false
     let concludesVotes = 0
@@ -122,7 +155,7 @@ export async function runTurn(opts: {
   try {
     while (steps < maxSteps) {
       if (signal?.aborted) {
-        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+        const seq = closeTurn({ reason: 'aborted' }).seq
         trail.push({ seq, reason: 'aborted' })
         return { reason: 'aborted', steps, endReasonTrail: trail }
       }
@@ -131,7 +164,7 @@ export async function runTurn(opts: {
       const step = await model()
 
       if (step.stopReason === 'error') {
-        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error' }).seq
+        const seq = closeTurn({ reason: 'error' }).seq
         trail.push({ seq, reason: 'error' })
         return { reason: 'error', steps, endReasonTrail: trail }
       }
@@ -151,7 +184,7 @@ export async function runTurn(opts: {
           continue
         }
         // 默认收口：截断响应不解析、不执行任何工具调用
-        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'max-tokens' }).seq
+        const seq = closeTurn({ reason: 'max-tokens' }).seq
         trail.push({ seq, reason: 'max-tokens' })
         return { reason: 'max-tokens', steps, endReasonTrail: trail }
       }
@@ -160,21 +193,21 @@ export async function runTurn(opts: {
         const batch = await executeBatch(step.toolCalls)
         // F13：授权拒绝即收口（blockOnDeny 产出点——blocked 仅新增产出点，枚举不增）
         if (preset.blockOnDeny && batch.denies > 0) {
-          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'blocked', denies: batch.denies }).seq
+          const seq = closeTurn({ reason: 'blocked', denies: batch.denies }).seq
           trail.push({ seq, reason: 'blocked' })
           return { reason: 'blocked', steps, endReasonTrail: trail }
         }
         const agg = preset.aggregate ?? {}
         const abortedNow = (agg.terminate ?? 'all') === 'any' ? batch.terminateVotes > 0 : batch.terminateAll
         if (abortedNow) { // terminate 收口：默认 AND（整批），可配置 any
-          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+          const seq = closeTurn({ reason: 'aborted' }).seq
           trail.push({ seq, reason: 'aborted' })
           return { reason: 'aborted', steps, endReasonTrail: trail }
         }
         const concludedNow = (agg.concludesTurn ?? 'any') === 'any' ? batch.concludesTurn : batch.concludesAll && batch.finalized > 0
         if (concludedNow) { // concludesTurn 收口：默认 OR，可配置 all
           const reason: TurnEndReason = sawMaxTokens ? 'max-tokens' : 'completed'
-          const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq
+          const seq = closeTurn({ reason }).seq
           trail.push({ seq, reason })
           return { reason, steps, endReasonTrail: trail }
         }
@@ -184,16 +217,16 @@ export async function runTurn(opts: {
 
       // stopReason === 'stop'：模型自然完成
       const reason: TurnEndReason = sawMaxTokens ? 'max-tokens' : 'completed'
-      const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq
+      const seq = closeTurn({ reason }).seq
       trail.push({ seq, reason })
       return { reason, steps, endReasonTrail: trail }
     }
-    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: 'max-steps' }).seq
+    const seq = closeTurn({ reason: 'error', detail: 'max-steps' }).seq
     trail.push({ seq, reason: 'error' })
     return { reason: 'error', steps, endReasonTrail: trail }
   } catch (e) {
     if (e instanceof TurnAborted) {
-      const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq
+      const seq = closeTurn({ reason: 'aborted' }).seq
       trail.push({ seq, reason: 'aborted' })
       return { reason: 'aborted', steps, endReasonTrail: trail }
     }
@@ -201,7 +234,7 @@ export async function runTurn(opts: {
     // car doctor」可达用户；非 CarM8Error 维持 String(e) 口径不变）
     const m8 = e instanceof CarM8Error
     const detail = m8 ? `${e.slug}: ${e.message}` : String(e)
-    const seq = log.append('runtime', 'turnEnd', turnId, null, {
+    const seq = closeTurn({
       reason: 'error', detail,
       ...(m8 ? { code: e.code, userHint: e.userHint, retryable: e.retryable } : {}),
     }).seq

package/src/runtime-core/chatStep.ts

@@ -12,12 +12,15 @@
  *     （半截 JSON 不解析——ADR-001 同纪律，length 时只交 truncatedTools）；
  *  5. assistant 文本事件落 M7（脱敏后 + secretsRedacted 计数留痕 meta）；
  *  6. finishReason 不可变透传为 ModelStep.stopReason（error/aborted → 'error'，BD-04 收口
- *     由 runTurn 落 turnEnd）；工具调用事件由 runTurn executeBatch 落（本层不重复）。
+ *     由 runTurn 落 turnEnd）；工具调用事件由 runTurn executeBatch 落（本层不重复）；
+ *  7. 1.11-S2（D-33 / 计量设计 §3.3）：流尾 usage chunk → 'runtime'/'usage' 请求级事实落链
+ *     （缺失 = provider 未回/流中断/畸形，禁补造；actor='runtime'、model_visible=0 不进模型
+ *     消息流）——turn 级聚合在 stop.ts 收口单点，本层不做跨请求状态。
  */
 import type { SessionLog } from '../session/log.ts'
 import { TurnAborted, type ModelStep, type ToolCall } from '../loop/stop.ts'
 import type { RuntimeCore } from './llm.ts'
-import type { ToolDefinition } from './types.ts'
+import type { LlmUsage, ToolDefinition } from './types.ts'
 import { StreamRedactor } from './redaction.ts'
 import { scanSecrets } from '../security/secrets.ts'
 import { providerUnreachable } from './errors.ts'
@@ -67,6 +70,7 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
   const calls = new Map<number, { id?: string; name?: string; argsBuf: string }>()
   let stopReason: ModelStep['stopReason'] | undefined
   let errorDetail: string | undefined
+  let usage: LlmUsage | undefined
 
   const stream = core.chat({
     model,
@@ -90,6 +94,7 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
       calls.set(idx, cur)
     }
     if (chunk.error) errorDetail = chunk.error.message
+    if (chunk.usage) usage = chunk.usage // D-33：附着于最后一个 chunk——后到覆盖
     if (chunk.finishReason !== undefined) stopReason = chunk.finishReason === 'aborted' ? 'error' : chunk.finishReason
   }
   // 1.4-S4（D-19）：finish 检查前先查取消（适配器取消路径静默收口无 finishReason——
@@ -101,6 +106,21 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
   }
   text += redactor.flush()
 
+  // 1.11-S2（D-33 / 计量设计 §3.3）：请求级 usage 事实落链（拿到 usage 的最后一个 chunk 即请求
+  // 收尾；撞限/异常 turn 照常落——截断前已完成请求的 usage 事实不吞）。缺失 = provider 未回，
+  // 禁补造；actor='runtime'、不进模型消息流（deriveMessages 不投影 usage，§2.5 红线）
+  if (usage) {
+    log.append('runtime', 'usage', turnId, {
+      model: usage.model,
+      adapterId: usage.adapterId,
+      input: usage.inputTokens,
+      output: usage.outputTokens,
+      cacheRead: usage.cacheReadTokens,
+      cacheCreation: usage.cacheCreationTokens,
+      providerRaw: usage.providerRaw,
+    })
+  }
+
   // 5. assistant 文本落 M7（脱敏后 + 计数留痕；空文本不产事件）
   //    flush 后兜底复扫只计数不复写：流式遮蔽已生效，>0 即流式边界逃逸的审计信号
   let secretsRedacted = 0

package/src/runtime-core/llm.ts

@@ -20,10 +20,15 @@
  *    0xC0000409）——car run 真路径 ≥3 次模型请求 + PTC worker/MCP 子进程并存即确定性复现
  *    （1.4 彼时仅修遥测出站，LLM 出站同为 undici 默认——潜伏至 1.8 E2E 三请求形态暴露）；
  *    流式契约 body = AsyncIterable<Uint8Array> 不变；测试注入缝 fetchImpl 保留。
+ *  - 1.11-S1（D-33 / 计量设计 §3.2）：usage 采集——openai 请求体加 stream_options.include_usage
+ *    （默认开启，第三方网关不兼容时回退 = baseUrl 白名单，登记可回退项；缺失走缺失口径禁估算），
+ *    解析「先摘 evt.usage 再判 choice」（空 choices 尾包不再被吞）；anthropic message_start（input 侧）
+ *    + message_delta（output 侧）两包合并（message_delta 缺席 = output 不完整，整条不落）；
+ *    归一口径 §1.1（openai 减法 / anthropic 透传 + cache_creation），畸形/缺失整条不落（禁补造）。
  */
 import { CarM8Error, providerUnreachable } from './errors.ts'
 import { CredentialService } from './credentials.ts'
-import type { Disposable, LlmAdapter, LlmChunk, LlmRequest, ToolCallDelta } from './types.ts'
+import type { Disposable, LlmAdapter, LlmChunk, LlmRequest, LlmUsage, ToolCallDelta } from './types.ts'
 import type { PluginContext } from '../kernel/context.ts'
 import { request as httpRequest } from 'node:http'
 import { request as httpsRequest } from 'node:https'
@@ -279,8 +284,30 @@ const FINISH_MAP: Record<string, LlmChunk['finishReason']> = {
 
 class Retryable extends Error {}
 
-/** 明文 SSE → LlmChunk 流解析（增量容错：半行驻留到下一 chunk） */
-async function* parseSseStream(body: AsyncIterable<Uint8Array>): AsyncIterable<LlmChunk> {
+/**
+ * 1.11-S1（D-33 / 计量设计 §1.1）：openai usage 归一——prompt_tokens 含 cached，inputTokens
+ * 必须做减法（prompt − prompt_tokens_details.cached_tokens）；cache_creation 恒 0（无对应字段，
+ * 登记不估算）。usage 对象缺席/畸形（两侧主字段任一非数值）= 整条不落（缺失口径，禁补造）。
+ */
+function normalizeOpenAIUsage(u: unknown, model: string, adapterId: string): LlmUsage | undefined {
+  if (!u || typeof u !== 'object') return undefined
+  const r = u as Record<string, unknown>
+  if (typeof r.prompt_tokens !== 'number' || typeof r.completion_tokens !== 'number') return undefined
+  const details = (r.prompt_tokens_details ?? null) as Record<string, unknown> | null
+  const cached = details && typeof details.cached_tokens === 'number' ? details.cached_tokens : 0
+  return {
+    inputTokens: r.prompt_tokens - cached,
+    outputTokens: r.completion_tokens,
+    cacheReadTokens: cached,
+    cacheCreationTokens: 0,
+    model,
+    adapterId,
+    providerRaw: u,
+  }
+}
+
+/** 明文 SSE → LlmChunk 流解析（增量容错：半行驻留到下一 chunk；1.11-S1：model/adapterId 供 usage 归一） */
+async function* parseSseStream(body: AsyncIterable<Uint8Array>, model: string, adapterId: string): AsyncIterable<LlmChunk> {
   const decoder = new TextDecoder()
   let buf = ''
   for await (const bytes of body) {
@@ -295,8 +322,15 @@ async function* parseSseStream(body: AsyncIterable<Uint8Array>): AsyncIterable<L
       if (!data) continue
       let evt: any
       try { evt = JSON.parse(data) } catch { continue } // 心跳/注释行容错（显式跳过非 JSON data）
+      // 1.11-S1（D-33 / 计量设计 §3.2 必核行）：先摘 usage 再判 choice——stream_options.include_usage
+      // 的尾包 choices 为空，下方 `if (!choice) continue` 原样会把它吞掉
+      const usage = evt.usage !== undefined ? normalizeOpenAIUsage(evt.usage, model, adapterId) : undefined
       const choice = evt.choices?.[0]
-      if (!choice) continue
+      if (!choice) {
+        // 独立 usage 尾包（官方形态：finish_reason chunk 之后、[DONE] 之前）——请求最后一个 chunk
+        if (usage) yield { usage }
+        continue
+      }
       const delta = choice.delta ?? {}
       const raw = choice.finish_reason
       const finish: LlmChunk['finishReason'] | undefined = raw == null ? undefined : (() => {
@@ -315,26 +349,34 @@ async function* parseSseStream(body: AsyncIterable<Uint8Array>): AsyncIterable<L
         : []
       const text = typeof delta.content === 'string' && delta.content.length ? delta.content : undefined
       // LlmChunk 单 toolCallDelta 口径：同事件多条 tool_calls 顺序展开为多 chunk
-      if (!text && !toolCallDeltas.length && finish === undefined) continue
+      if (!text && !toolCallDeltas.length && finish === undefined) {
+        // 空事件但携 usage（部分 compat 网关形态）：usage 不随空事件丢失
+        if (usage) yield { usage }
+        continue
+      }
+      const chunks: LlmChunk[] = []
       if (toolCallDeltas.length === 0) {
-        yield {
+        chunks.push({
           ...(text !== undefined ? { delta: text } : {}),
           ...(finish !== undefined
             ? { finishReason: finish, ...(finish === 'error' ? { error: { code: 'B080001', message: `未映射的 finish_reason "${raw}"` } } : {}) }
             : {}),
-        }
+        })
       } else {
         for (let i = 0; i < toolCallDeltas.length; i++) {
           const last = i === toolCallDeltas.length - 1
-          yield {
+          chunks.push({
             ...(i === 0 && text !== undefined ? { delta: text } : {}),
             toolCallDelta: toolCallDeltas[i],
             ...(last && finish !== undefined
               ? { finishReason: finish, ...(finish === 'error' ? { error: { code: 'B080001', message: `未映射的 finish_reason "${raw}"` } } : {}) }
               : {}),
-          }
+          })
         }
       }
+      // 1.11-S1（D-33）：usage 与事件内容同 chunk 到达（网关共存形态）→ 附着于本事件最后一个 chunk
+      if (usage) chunks[chunks.length - 1]!.usage = usage
+      for (const c of chunks) yield c
     }
   }
 }
@@ -364,6 +406,9 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
     body: JSON.stringify({
       model: req.model,
       stream: true,
+      // 1.11-S1（D-33 / 计量设计 §9-2 推荐A）：usage 采集默认开启；第三方网关不兼容时的
+      // 回退方案（baseUrl 白名单）登记可回退项——不支持网关走缺失口径（禁估算补造）
+      stream_options: { include_usage: true },
       ...(req.maxTokens != null ? { max_tokens: req.maxTokens } : {}),
       messages: req.messages.map(m => {
         if (m.role === 'toolResult') {
@@ -402,7 +447,7 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
         fetchImpl,
         signal: req.signal,
         timeoutMs, firstByteMs, retries, backoffMs, sleep,
-      }, parseSseStream)
+      }, (body) => parseSseStream(body, req.model, id))
     },
   }
 }
@@ -436,6 +481,31 @@ const ANTHROPIC_STOP_REASON_MAP: Record<string, LlmChunk['finishReason']> = {
   refusal: 'aborted',
 }
 
+/**
+ * 1.11-S1（D-33 / 计量设计 §3.2）：anthropic usage 两包合并——message_start（input 侧：
+ * input_tokens 天然不含 cache + cache_read/cache_creation）+ message_delta（output 侧：
+ * output_tokens）。任一包缺席或主字段非数值 = 侧不完整，整条不落（缺失口径，禁补造半条事实）；
+ * providerRaw 保留两原始片段供审计对拍。
+ */
+function mergeAnthropicUsage(
+  start: Record<string, unknown> | null,
+  delta: Record<string, unknown> | null,
+  model: string,
+  adapterId: string,
+): LlmUsage | undefined {
+  if (!start || !delta) return undefined
+  if (typeof start.input_tokens !== 'number' || typeof delta.output_tokens !== 'number') return undefined
+  return {
+    inputTokens: start.input_tokens,
+    outputTokens: delta.output_tokens,
+    cacheReadTokens: typeof start.cache_read_input_tokens === 'number' ? start.cache_read_input_tokens : 0,
+    cacheCreationTokens: typeof start.cache_creation_input_tokens === 'number' ? start.cache_creation_input_tokens : 0,
+    model,
+    adapterId,
+    providerRaw: { messageStart: start, messageDelta: delta },
+  }
+}
+
 /**
  * Anthropic Messages API 请求体（D-20）：system 消息提升为顶层 `system`（多条 \n\n 连接）；
  * toolResult 收敛进 user 消息 content（连续多条合并为单 user 多 tool_result 块——Anthropic
@@ -499,10 +569,13 @@ function toAnthropic(req: LlmRequest, apiKey: string) {
  * Anthropic SSE → LlmChunk 流解析（data-only：data JSON 自带 `type` 字段，`event:` 行不依赖）。
  * content_block_start(tool_use) → toolCallDelta{id,name}；input_json_delta → toolCallDelta{argumentsDelta}；
  * message_delta.stop_reason → finishReason（终态信号，单次）；ping/message_stop/未知事件容错跳过。
+ * 1.11-S1（D-33）：message_start.usage 采集 input 侧（原解析整体跳过该事件）+ message_delta.usage
+ * 合并 output 侧附着于终态 chunk；流中断 delta 未到 = output 侧不完整，整条不落（R-2）。
  */
-async function* parseAnthropicSseStream(body: AsyncIterable<Uint8Array>): AsyncIterable<LlmChunk> {
+async function* parseAnthropicSseStream(body: AsyncIterable<Uint8Array>, model: string, adapterId: string): AsyncIterable<LlmChunk> {
   const decoder = new TextDecoder()
   let buf = ''
+  let startUsage: Record<string, unknown> | null = null
   for await (const bytes of body) {
     buf += decoder.decode(bytes, { stream: true })
     let nl: number
@@ -528,13 +601,23 @@ async function* parseAnthropicSseStream(body: AsyncIterable<Uint8Array>): AsyncI
           yield { toolCallDelta: { index: evt.index, argumentsDelta: d.partial_json } }
         }
         // thinking_delta / citations_delta 等非 CAR 消费面：容错跳过
+      } else if (type === 'message_start') {
+        // 1.11-S1（D-33）：input 侧采集（usage 嵌套在 message 下）
+        const u = (evt.message as Record<string, unknown> | undefined)?.usage
+        if (u && typeof u === 'object') startUsage = u as Record<string, unknown>
       } else if (type === 'message_delta') {
         const raw = evt.delta?.stop_reason
+        // 1.11-S1（D-33）：output 侧（delta.usage.output_tokens）与 input 侧合并——两包齐才落
+        const usage = mergeAnthropicUsage(startUsage, (evt.usage ?? null) as Record<string, unknown> | null, model, adapterId)
         if (raw != null) {
           const finish = ANTHROPIC_STOP_REASON_MAP[String(raw)]
-          yield finish
+          const chunk: LlmChunk = finish
             ? { finishReason: finish }
             : { finishReason: 'error', error: { code: 'B080001', message: `未映射的 stop_reason "${raw}"` } }
+          yield usage ? { ...chunk, usage } : chunk
+        } else if (usage) {
+          // delta 未携 stop_reason 但携 usage（网关形态）：usage 不随缺失终态信号丢失
+          yield { usage }
         }
       } else if (type === 'error') {
         // 流内 error 事件（overloaded_error 等）→ error chunk 收口（后续 message_delta 由守卫拦冲突）
@@ -575,7 +658,7 @@ export function createAnthropicAdapter(opts: AnthropicAdapterOptions): LlmAdapte
         fetchImpl,
         signal: req.signal,
         timeoutMs, firstByteMs, retries, backoffMs, sleep,
-      }, parseAnthropicSseStream)
+      }, (body) => parseAnthropicSseStream(body, req.model, id))
     },
   }
 }

package/src/runtime-core/types.ts

@@ -36,14 +36,35 @@ export interface ToolCallDelta {
   argumentsDelta?: string
 }
 
+/**
+ * 1.11-S1（D-33 / 计量设计 §3.1）：token 四分量归一化用量——跨 provider 可加总的库内口径
+ * （§1.1：openai prompt_tokens 含 cached 必须减法归一；anthropic input_tokens 天然不含 cache）。
+ * provider 原始 usage 整体存 providerRaw 供审计对拍（对拍恒以 provider_raw 为准）。
+ */
+export interface LlmUsage {
+  /** 非缓存输入 token（归一化后） */
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  /** openai 系无对应字段，恒 0（登记不估算） */
+  cacheCreationTokens: number
+  /** 实际请求模型（req.model） */
+  model: string
+  adapterId: string
+  /** provider 原始 usage 对象（anthropic 为 messageStart/messageDelta 两原始片段） */
+  providerRaw: unknown
+}
+
 /** 流式块（finishReason 一经产生不可被任何中间层改写） */
 export interface LlmChunk {
   delta?: string
   toolCallDelta?: ToolCallDelta
   finishReason?: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted'
-  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  // —— 规格外加法扩展（登记：M8 收口文档 §4 / 计量设计 §3.1，1.11.0）——
   /** finishReason='error' 时的结构化原因（消费方落 turnEnd meta，不进模型消息流） */
   error?: { code: string; message: string }
+  /** 1.11-S1（D-33）：每次请求最后一个 chunk 附带归一化用量；缺失 = provider 未回，禁补造 */
+  usage?: LlmUsage
 }
 
 /** Provider 适配器（ACL，C-02）：统一签名，消解 Provider 差异 */

package/src/seam.ts

@@ -0,0 +1,24 @@
+/**
+ * KernelSeam 公开导出面（1.10.0 加法——D16 T-6 冻结面口径：本文件即内核库形态的 semver 承诺面）
+ *
+ * 消费方：CAR 平台层（KernelSeam 适配器）；约定：
+ *  - 仅暴露进程内挂接所需的最窄面（装配/会话/turn/遥测），禁止透出内核内部模块路径语义；
+ *  - 破坏性变更须内核 major；加法演进走 minor 并在本文件头登记；
+ *  - 语义不变：runTurn/chatStep/SessionLog 即 CLI 与测试承载的同一实现（非转发壳）。
+ *
+ * 加法登记：1.11.0 —— AuthzService/checkCapability 出面（平台确认桥幂等决策 + 会话策略直判承载；F4 US-3 语义同源）。
+ */
+export { SessionLog, type SessionEvent, type EventKind, type Actor } from './session/log.ts'
+export { SessionFileStore } from './session/store.ts'
+export { runTurn, type TurnEndReason, type TurnPreset, type TurnResult } from './loop/stop.ts'
+export { chatStep } from './runtime-core/chatStep.ts'
+export { RuntimeCore, createOpenAICompatAdapter, createAnthropicAdapter } from './runtime-core/llm.ts'
+export { CredentialService } from './runtime-core/credentials.ts'
+export type { LlmAdapter, LlmRequest, LlmChunk } from './runtime-core/types.ts'
+export { mountPlugin } from './load/loader.ts'
+export { Context } from './kernel/context.ts'
+export { loadCarConfig, mergeLlmConfig, mergeSignatureGate, warmCarConfig, type CarConfig, type LlmConfig } from './load/config.ts'
+export { probeCapabilities, SandboxExecutor } from './sandbox/sandbox.ts'
+export { AuthzService, checkCapability, type Decision, type AuthzRequest, type AuthzDecision, type DeclaredCapabilities } from './authz/authz.ts'
+export { createTelemetryFacade, telemetryConfigFromEnv } from './runtime-core/telemetry.ts'
+export { TurnTracer, type TurnSpanHandle } from './runtime-core/trace.ts'

package/src/session/log.ts

@@ -11,7 +11,7 @@ import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { decodeLogBuffer, splitJsonlLines } from './format.ts'
 
-export type EventKind = 'user' | 'assistant' | 'toolCall' | 'toolResult' | 'turnEnd' | 'goalUpdate' | 'hostRaw' | 'fork' | 'system' // M3-S11 加法扩展：多宿主归一化降级通道（pattern 未命中留痕，零静默）；M5-DEC4 加法扩展：跨宿主 fork 标记事件；1.4-S2 加法扩展：system prompt 落链（§3.5.5：新模型可见输入 = 新事件类型）；六值 TurnEndReason 不变
+export type EventKind = 'user' | 'assistant' | 'toolCall' | 'toolResult' | 'turnEnd' | 'goalUpdate' | 'hostRaw' | 'fork' | 'system' | 'usage' // M3-S11 加法扩展：多宿主归一化降级通道（pattern 未命中留痕，零静默）；M5-DEC4 加法扩展：跨宿主 fork 标记事件；1.4-S2 加法扩展：system prompt 落链（§3.5.5：新模型可见输入 = 新事件类型）；1.11-S2 加法扩展：usage 计量事实（D-33，actor='runtime'、model_visible=0 不进模型消息流，deriveMessages 不投影）；六值 TurnEndReason 不变
 export type Actor = 'user' | 'model' | 'plugin' | 'runtime'
 export interface SessionEvent {
   seq: number

package/.gitattributes

@@ -1,11 +0,0 @@
-# 行尾纪律：Windows runner checkout 默认 autocrlf=true 会把文本文件打成 CRLF，
-# WSL 内 bash 脚本遇 \r 即炸（run 35314482866：set: pipefail\r invalid option）。
-* text=auto
-*.sh text eol=lf
-*.c text eol=lf
-*.h text eol=lf
-Makefile text eol=lf
-*.md text eol=lf
-*.yml text eol=lf
-*.json text eol=lf
-*.ts text eol=lf