@lqc123qwe/car-runtime 1.0.0 → 1.1.0

package/src/runtime-core/redaction.ts

@@ -0,0 +1,94 @@
+/**
+ * M8 · 脱敏钩子（redact ——《系统设计》§3.2.M8.2 脱敏行 / SQ-07 输出敏感扫描 / O-14）
+ *
+ * 口径：
+ *  - 检测器单一权威：本层只做 M8 面（RedactionResult 形态 + 流式 hold-back），
+ *    模式库/三层检测/遮蔽口径全部委托 F12 scanSecrets（security/secrets.ts）——
+ *    双实现必然漂移，S15 已确立「回填前强制 redact」先例；
+ *  - 遮蔽口径（§3.2.M8.3 字段表）：API Key 形如 sk-****（保留首尾 ≤4 字符）= F12 maskToken；
+ *  - 流式扫描（StreamRedactor）：delta 直发会造成跨 chunk 命中逃逸——hold-back 窗口
+ *    「从最早疑似锚点起驻留」，命中补齐即遮蔽放行，finishReason 收口时 flush 全量扫描；
+ *    结构标记类模式（GCP service_account 等）的匹配起点先于锚点，流式模式不保证完整遮蔽
+ *    （登记为流式已知边界；非流式 redact() 为权威口径）。
+ */
+import { scanSecrets, type ScanHit } from '../security/secrets.ts'
+
+export interface RedactionResult {
+  /** 脱敏后文本（§3.2.M8.3 字段表口径：RedactionResult.redacted） */
+  redacted: string
+  /** 命中遮蔽次数 */
+  redactedCount: number
+  /** 命中明细（审计留痕用；不含原文） */
+  hits: Array<Pick<ScanHit, 'category' | 'name' | 'start' | 'end' | 'masked' | 'score'>>
+}
+
+/** 非流式脱敏钩子（§3.2.M8.2：redact(text): RedactionResult，天然幂等） */
+export function redact(text: string): RedactionResult {
+  const { hits } = scanSecrets(text)
+  let out = ''
+  let cursor = 0
+  for (const h of hits) {
+    out += text.slice(cursor, h.start) + h.masked
+    cursor = h.end
+  }
+  out += text.slice(cursor)
+  return { redacted: out, redactedCount: hits.length, hits }
+}
+
+/**
+ * 疑似锚点：所有模式匹配串的起始字面量（大小写不敏感）。
+ * 命中检测必然先经过锚点——锚点之后的字节才需要驻留等待命中补齐。
+ */
+const ANCHOR_RE = /(sk[-_]|gh[pousr]_|xox|akia|rk_|npm_|-----begin|postgres|mysql|mongodb|redis|jdbc:|aws|service_account|accountkey|eyJ|authorization|bearer|api[_-]?key|client[_-]?secret|access[_-]?token|password)/i
+
+/** 无锚点时的尾部驻留长度（≥ 最长锚点 15，防锚点跨 chunk 拼合逃逸） */
+const TRAILING_HOLD = 16
+
+/**
+ * 流式脱敏器：push() 返回「当前可安全放行」的文本（已遮蔽），flush() 收口全量扫描。
+ * 语义：不泄漏（任何已放行字节不可能成为命中的一部分）、不误遮（锚点未补齐成命中时
+ * 原文放行）、粒度换正确性（疑似锚点驻留直到命中补齐或 flush——长行含假锚点时
+ * 流式粒度退化到收口时点，登记为已接受折衷）。
+ */
+export class StreamRedactor {
+  #pending = ''
+
+  /** 追加 delta，返回可安全放行的文本（可能为空串） */
+  push(text: string): string {
+    this.#pending += text
+    let out = ''
+    // 1) 命中补齐：从前往后逐个遮蔽（遮蔽后重扫——遮蔽串不会再命中）
+    for (;;) {
+      const { hits } = scanSecrets(this.#pending)
+      const h = hits[0]
+      if (!h) break
+      out += this.#pending.slice(0, h.start) + h.masked
+      this.#pending = this.#pending.slice(h.end)
+    }
+    // 2) 无完整命中：从最早疑似锚点起驻留
+    const m = ANCHOR_RE.exec(this.#pending)
+    if (m && m.index !== undefined) {
+      out += this.#pending.slice(0, m.index)
+      this.#pending = this.#pending.slice(m.index)
+      return out
+    }
+    // 3) 无锚点：放行除尾部驻留窗外的全部（尾窗防锚点跨 chunk 拼合）
+    if (this.#pending.length > TRAILING_HOLD) {
+      out += this.#pending.slice(0, this.#pending.length - TRAILING_HOLD)
+      this.#pending = this.#pending.slice(-TRAILING_HOLD)
+    }
+    return out
+  }
+
+  /** 收口（finishReason 时点）：全量扫描遮蔽剩余驻留 */
+  flush(): string {
+    const r = redact(this.#pending)
+    this.#pending = ''
+    return r.redacted
+  }
+
+  /** 已遮蔽计数口径（测试/审计观察面）：flush 前的累计放行不含命中原文 */
+  get pendingLength(): number {
+    return this.#pending.length
+  }
+}

package/src/runtime-core/telemetry.ts

@@ -0,0 +1,243 @@
+/**
+ * M8 · 遥测门面（getTracer/getMeter ——《系统设计》§3.2.M8.2 遥测行 / §3.2.M8.5 隐私三原则）
+ *
+ * 口径（§3.2.M8.5 关键约束，逐条落地）：
+ *  - 默认关：无端点配置时不初始化任何 exporter——无配置 = noop 句柄 + 零出站（可机器断言）；
+ *  - 显式开：用户配置端点即视为开启（CAR_OTEL_ENDPOINT 或显式 config 传入）；
+ *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（fetch），导出超时 5s、0 重试、
+ *    端点不可达静默丢弃（BD-05——不抛错、不重试、不落审计）；
+ *  - 严格解耦：本文件零 import 自 session/*（遥测与审计日志禁止混流）——测试做静态断言；
+ *  - S17 零内容计数器（telemetry/metrics.ts）是登记表兜底通道，与本门面并存互补：
+ *    本面是 OTel 形态的出站通道，不承接 S17 的零内容红线语义（内容治理属调用方）；
+ *  - 零依赖：OTel「标准句柄形态」自研（startSpan/attributes/end、createCounter/add），
+ *    不引入 @opentelemetry/* 依赖（项目零依赖红线，README engines 纪律）。
+ */
+import { randomBytes } from 'node:crypto'
+
+export interface TelemetryConfig {
+  /** 用户自配 OTLP/HTTP 端点（如 https://otel.example.internal）——无值 = 默认关 */
+  endpoint?: string
+  serviceName?: string
+  headers?: Record<string, string>
+  /** 导出超时（§3.5.4 基线 5s） */
+  exportTimeoutMs?: number
+  /** 自动导出间隔 ms；0（缺省）= 仅手动 flush（测试/收口时点调用） */
+  intervalMs?: number
+}
+
+export interface TelemetrySpan {
+  setAttribute(key: string, value: string | number | boolean): this
+  addEvent(name: string, attrs?: Record<string, string | number | boolean>): this
+  recordException(err: unknown): this
+  end(): void
+  readonly traceId: string
+}
+
+export interface TelemetryTracer {
+  startSpan(name: string, opts?: { attributes?: Record<string, string | number | boolean> }): TelemetrySpan
+}
+
+export interface TelemetryCounter {
+  add(value: number, labels?: Record<string, string>): void
+}
+
+export interface TelemetryMeter {
+  createCounter(name: string): TelemetryCounter
+}
+
+export interface TelemetryStats {
+  spansEnded: number
+  tracesExported: number
+  metricsExported: number
+  droppedExports: number
+}
+
+export interface TelemetryFacade {
+  /** 默认关 = false（无端点配置时） */
+  readonly enabled: boolean
+  /** 幂等句柄（§3.2.M8.2：天然幂等） */
+  getTracer(): TelemetryTracer
+  getMeter(): TelemetryMeter
+  /** 手动导出（BD-05：端点不可达静默丢弃——resolve 不 reject） */
+  flush(): Promise<void>
+  shutdown(): Promise<void>
+  /** 观察面（测试/收口；不含内容字段） */
+  stats(): TelemetryStats
+}
+
+// ==================== noop 句柄（默认关路径：零出站、零积累） ====================
+
+const noopSpan = (): TelemetrySpan => ({
+  setAttribute() { return noopSpan() },
+  addEvent() { return noopSpan() },
+  recordException() { return noopSpan() },
+  end() {},
+  traceId: '',
+})
+const NOOP_TRACER: TelemetryTracer = { startSpan: () => noopSpan() }
+const NOOP_METER: TelemetryMeter = { createCounter: () => ({ add() {} }) }
+
+// ==================== 活动门面（显式开路径） ====================
+
+interface SpanRecord {
+  traceId: string
+  spanId: string
+  parentSpanId: string | null
+  name: string
+  startMs: number
+  endMs: number
+  attributes: Record<string, string | number | boolean>
+}
+
+const attrValue = (v: string | number | boolean) =>
+  typeof v === 'string' ? { stringValue: v } : typeof v === 'boolean' ? { boolValue: v } : { doubleValue: v }
+
+export function createTelemetryFacade(
+  config: TelemetryConfig | null | undefined,
+  opts: { fetchImpl?: typeof fetch; now?: () => number } = {},
+): TelemetryFacade {
+  const endpoint = config?.endpoint?.replace(/\/+$/, '')
+  if (!endpoint) {
+    return {
+      enabled: false,
+      getTracer: () => NOOP_TRACER,
+      getMeter: () => NOOP_METER,
+      flush: async () => {},
+      shutdown: async () => {},
+      stats: () => ({ spansEnded: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0 }),
+    }
+  }
+
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const now = opts.now ?? Date.now
+  const timeoutMs = config?.exportTimeoutMs ?? 5_000
+  const baseHeaders = { 'content-type': 'application/json', ...(config?.headers ?? {}) }
+  const serviceName = config?.serviceName ?? 'car-runtime'
+
+  const spans: SpanRecord[] = []
+  const counters = new Map<string, { labels: Record<string, string>; value: number }>()
+  const stats: TelemetryStats = { spansEnded: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0 }
+  let tracer: TelemetryTracer | null = null
+  let meter: TelemetryMeter | null = null
+  let timer: ReturnType<typeof setInterval> | null = null
+  let flushing = false
+
+  const exportOtlp = async (path: string, body: unknown): Promise<boolean> => {
+    try {
+      // 单次尝试 + 有界超时（§3.5.4：OTel 导出 5s / 0 重试）；失败静默丢弃（BD-05）
+      await fetchImpl(endpoint + path, {
+        method: 'POST',
+        headers: baseHeaders,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const flush = async (): Promise<void> => {
+    if (flushing) return
+    flushing = true
+    try {
+      const spanBatch = spans.splice(0, spans.length)
+      if (spanBatch.length) {
+        const body = {
+          resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+          scopeSpans: [{
+            scope: { name: 'car-runtime' },
+            spans: spanBatch.map(s => ({
+              traceId: s.traceId,
+              spanId: s.spanId,
+              ...(s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
+              name: s.name,
+              kind: 'SPAN_KIND_INTERNAL',
+              startTimeUnixNano: String(s.startMs * 1e6),
+              endTimeUnixNano: String(s.endMs * 1e6),
+              attributes: Object.entries(s.attributes).map(([key, v]) => ({ key, value: attrValue(v) })),
+              status: { code: 'STATUS_CODE_UNSET' },
+            })),
+          }],
+        }
+        if (await exportOtlp('/v1/traces', body)) stats.tracesExported++
+        else stats.droppedExports++
+      }
+      if (counters.size) {
+        const batch = [...counters.entries()]
+        counters.clear()
+        const body = {
+          resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+          scopeMetrics: [{
+            scope: { name: 'car-runtime' },
+            metrics: batch.map(([name, c]) => ({
+              name,
+              sum: {
+                aggregationTemporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE',
+                dataPoints: Object.entries(c.labels).length
+                  ? Object.entries(c.labels).map(([k, v]) => ({ asInt: c.value, attributes: [{ key: k, value: { stringValue: v } }] }))
+                  : [{ asInt: c.value }],
+              },
+            })),
+          }],
+        }
+        if (await exportOtlp('/v1/metrics', body)) stats.metricsExported++
+        else stats.droppedExports++
+      }
+    } finally {
+      flushing = false
+    }
+  }
+
+  if ((config?.intervalMs ?? 0) > 0) timer = setInterval(() => { void flush() }, config!.intervalMs!)
+
+  const activeTracer: TelemetryTracer = {
+    startSpan(name, startOpts) {
+      const record: SpanRecord = {
+        traceId: randomBytes(16).toString('hex'),
+        spanId: randomBytes(8).toString('hex'),
+        parentSpanId: null,
+        name,
+        startMs: now(),
+        endMs: 0,
+        attributes: { ...startOpts?.attributes },
+      }
+      return {
+        get traceId() { return record.traceId },
+        setAttribute(key, value) { record.attributes[key] = value; return this },
+        addEvent(evtName, attrs) { record.attributes[`event.${evtName}`] = attrs ? JSON.stringify(attrs) : evtName; return this },
+        recordException(err) { record.attributes['exception.message'] = String((err as Error)?.message ?? err); return this },
+        end() {
+          record.endMs = now()
+          spans.push(record)
+          stats.spansEnded++
+        },
+      }
+    },
+  }
+
+  const activeMeter: TelemetryMeter = {
+    createCounter(name) {
+      return {
+        add(value, labels = {}) {
+          const key = name + JSON.stringify(labels)
+          const cur = counters.get(key) ?? { labels, value: 0 }
+          cur.value += value
+          counters.set(key, cur)
+        },
+      }
+    },
+  }
+
+  return {
+    enabled: true,
+    getTracer() { tracer ??= activeTracer; return tracer },
+    getMeter() { meter ??= activeMeter; return meter },
+    flush,
+    async shutdown() {
+      if (timer) { clearInterval(timer); timer = null }
+      await flush()
+    },
+    stats: () => ({ ...stats }),
+  }
+}

package/src/runtime-core/types.ts

@@ -0,0 +1,79 @@
+/**
+ * M8 · 运行时底座共享 DTO（《系统设计》§3.2.M8.3 / §3.3.1 O-10/O-11/O-13/O-14）
+ *
+ * 口径：
+ *  - LlmChunk.finishReason 为不可变透传（readonly 语义，ADR-001；vLLM #53269 教训 SR-17）——
+ *    唯一信号源，禁止中间层改写/吞没；llm.ts 的流包装层对此做防御性断言；
+ *  - LlmRequest.tools 含 declaredSideEffect（权限门依据；readonly 是 ADR-001 补错重试白名单前置）；
+ *  - ToolDefinition 为 M8 共享 DTO（O-10）：M3 授权门/M5 MCP 网关/M8 模型请求三方复用；
+ *    与 loop/stop.ts 的 ToolDef 分工——ToolDefinition 是声明面（进模型 schema），ToolDef 是执行面；
+ *  - CredentialRef 不落明文（O-13）：ref 只含来源定位，值经 credentials.reveal 按需取用；
+ *  - 规格外扩展字段（adapterId / error）以加法演进登记——与 hostRaw 同纪律，不改动规格最小集语义。
+ */
+
+/** 模型请求（Provider 无关） */
+export interface LlmRequest {
+  model: string
+  messages: Array<{ role: 'system' | 'user' | 'assistant' | 'toolResult'; content: unknown }>
+  /** 工具 schema（缓存失效因素：工具集合/模型切换/compaction，D3 §14.6） */
+  tools: ToolDefinition[]
+  maxTokens?: number
+  metadata?: { sessionId: string; turnId: string; traceId: string }
+  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  /** 多适配器在册时显式路由；缺省用默认适配器 */
+  adapterId?: string
+}
+
+/** 工具调用流式增量（跨 chunk 聚合出完整 ToolCall） */
+export interface ToolCallDelta {
+  index?: number
+  id?: string
+  name?: string
+  /** JSON 增量片段，聚合后整体 JSON.parse（半截 JSON 不解析——ADR-001 同纪律） */
+  argumentsDelta?: string
+}
+
+/** 流式块（finishReason 一经产生不可被任何中间层改写） */
+export interface LlmChunk {
+  delta?: string
+  toolCallDelta?: ToolCallDelta
+  finishReason?: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted'
+  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  /** finishReason='error' 时的结构化原因（消费方落 turnEnd meta，不进模型消息流） */
+  error?: { code: string; message: string }
+}
+
+/** Provider 适配器（ACL，C-02）：统一签名，消解 Provider 差异 */
+export interface LlmAdapter {
+  /** 如 openai-compat / anthropic */
+  id: string
+  chat(req: LlmRequest): AsyncIterable<LlmChunk>
+}
+
+/** 可逆注册句柄（dispose = Effect 回卷） */
+export interface Disposable {
+  dispose(): void
+}
+
+/** 共享工具声明 DTO（O-10；注册时构造，进模型请求 schema） */
+export interface ToolDefinition {
+  name: string
+  description?: string
+  /** JSON Schema 形态参数声明 */
+  parameters?: unknown
+  /** 副作用声明（必填——M5 网关 T-22 强制点同一口径：缺声明即 write） */
+  declaredSideEffect: 'readonly' | 'write'
+}
+
+/** 凭据来源（§3.2.M8.3 字段表：env 需用户显式开启 fallback） */
+export type CredentialSource = 'keychain' | 'env'
+
+/** 凭据引用（O-13）：只含来源定位与掩码提示，值永不入此结构 */
+export interface CredentialRef {
+  provider: string
+  source: CredentialSource
+  /** 来源标识：keychain 服务名 / env 变量名 */
+  origin: string
+  /** keychain 通道不可用等降级留痕（降级必须显式，禁静默） */
+  degraded?: string
+}

package/test/s18.spec.ts

@@ -50,6 +50,15 @@ test('S18: 采集窗口——会话结束 stderr 输出零内容快照（登记
   assert.ok('car_registry_decision|source=registry' in snap)
 })
 
+test('S18+: 1.1-S4 边界——未指定 --plugin 时装载计数不出现（装载接线不改变缺省协议面与快照键集）', async () => {
+  const { stderr } = await talk('claude-code', [
+    JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 's' } } }),
+  ])
+  const snap = JSON.parse(/snapshot=(\{.*?\}) zeroContent/.exec(stderr)![1])
+  assert.ok(!('car_load_total|result=ok' in snap), '无 --plugin = 无装载计数（1.1 装载接线为显式 opt-in）')
+  assert.ok(!('car_unsigned_confirmed|confirmed=no' in snap))
+})
+
 test('S18: codex 宿主接入（同一入口不同 hostId）', async () => {
   const { outs } = await talk('codex', [
     JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 'cx-e2e' } } }),