@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/evidence/receipts.ts

@@ -0,0 +1,175 @@
+import type { Digest, SnapshotId, TaskId, ToolEvidence, WorkOrder, WorkOrderId } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import { EVENT_CONFLICT, FusionError } from '../errors.js'
+
+export interface InvocationHeader {
+  taskId: ToolEvidence['taskId']
+  workOrderId?: WorkOrderId
+  revision?: number
+  operationId: ToolEvidence['operationId']
+  actor: ToolEvidence['actor']
+  nativeToolCallId: string
+  argvDigest: Digest
+  cwdDigest: Digest
+  inputSnapshot: SnapshotId
+  startedAt: string
+  verifierPlanDigest?: Digest
+}
+
+export interface CheckPlan {
+  id: string
+  version: number
+  taskId: TaskId
+  workOrderId: WorkOrderId
+  revision: number
+  criterionId: string
+  kind: 'test' | 'static-check' | 'human' | 'review'
+  snapshot: SnapshotId
+  /**
+   * Version 2 may freeze the verifier before editing. `snapshot` then names the
+   * WorkOrder base; native invocation receipts must still bind both input and
+   * output to the exact current candidate. Omission retains v1 exact semantics.
+   */
+  snapshotBinding?: 'candidate'
+  cwdDigest: Digest
+  argvDigest: Digest
+  definitionDigest: Digest
+  policyDigest: Digest
+  minExecutedTests?: number
+  /**
+   * Baseline-relative test check: ids that already failed on the untouched workspace, frozen before the
+   * Worker started. Only these may fail on the candidate; every other executed test must pass.
+   */
+  allowedFailures?: readonly string[]
+}
+
+export interface PlannedReceipt {
+  id: string
+  planDigest: Digest
+  evidence: ToolEvidence
+  counts?: { executed: number; passed: number; failed: number
+    /** Failures frozen in the plan's baseline (not counted as executed). */
+    knownFailures?: readonly string[]
+    /** Failures absent from the baseline; counted in `failed`. */
+    newFailures?: readonly string[] }
+}
+
+export interface VerificationRegistry {
+  getPlan(planId: string): CheckPlan | undefined
+  getReceipt(receiptId: string): PlannedReceipt | undefined
+}
+
+export function memoryVerificationRegistry(
+  plans: readonly CheckPlan[],
+  receipts: readonly PlannedReceipt[],
+): VerificationRegistry {
+  const planById = new Map(plans.map(plan => [plan.id, freezePlan(plan)]))
+  const receiptById = new Map(receipts.map(receipt => [receipt.id, structuredClone(receipt)]))
+  return {
+    getPlan: id => planById.get(id),
+    getReceipt: id => {
+      const receipt = receiptById.get(id)
+      return receipt === undefined ? undefined : structuredClone(receipt)
+    },
+  }
+}
+
+function freezePlan(plan: CheckPlan): CheckPlan {
+  return Object.freeze(structuredClone(plan))
+}
+
+function requireThat(value: unknown, code: string): asserts value {
+  if (!value) throw new FusionError(EVENT_CONFLICT, code)
+}
+
+export function assertPlannedCheck(
+  workOrder: WorkOrder,
+  criterionId: string,
+  plan: CheckPlan,
+  receipt: PlannedReceipt,
+  actualSnapshot: SnapshotId,
+): void {
+  requireThat(plan.taskId === workOrder.taskId && plan.workOrderId === workOrder.id && plan.revision === workOrder.revision, 'PLAN_SCOPE_MISMATCH')
+  requireThat(plan.criterionId === criterionId, 'CRITERION_SCOPE_MISMATCH')
+  requireThat(receipt.planDigest === digestOf(plan), 'PLAN_DIGEST_MISMATCH')
+  if (plan.snapshotBinding === undefined) {
+    requireThat(plan.snapshot === actualSnapshot, 'PLAN_SNAPSHOT_MISMATCH')
+  } else {
+    requireThat(plan.snapshotBinding === 'candidate' && plan.version === 2, 'UNSUPPORTED_SNAPSHOT_BINDING')
+    requireThat(plan.snapshot === workOrder.baseSnapshot, 'PLAN_BASE_SNAPSHOT_MISMATCH')
+  }
+  const criterion = workOrder.acceptance.find(item => item.id === criterionId)
+  requireThat(criterion && criterion.verificationKind === plan.kind, 'VERIFIER_KIND_MISMATCH')
+  requireThat(criterion.planId === plan.id && criterion.planDigest === digestOf(plan), 'PLAN_NOT_FROZEN_IN_WORK_ORDER')
+  requireThat(plan.kind === 'test' || plan.kind === 'static-check', 'USE_TYPED_HUMAN_OR_REVIEW_RECEIPT')
+  requireThat(plan.cwdDigest && plan.argvDigest, 'EXACT_VERIFIER_CONTEXT_REQUIRED')
+  const evidence = receipt.evidence
+  requireThat(evidence.taskId === workOrder.taskId && evidence.cwdDigest === plan.cwdDigest && evidence.argvDigest === plan.argvDigest, 'INVOCATION_SCOPE_MISMATCH')
+  // A baseline-relative run exits non-zero while frozen pre-existing failures remain; its counts must then
+  // show that every failure was one of them.
+  const knownOnly = plan.kind === 'test' && plan.allowedFailures !== undefined && receipt.counts?.failed === 0
+    && (receipt.counts.knownFailures ?? []).every(id => plan.allowedFailures!.includes(id))
+  requireThat(evidence.state === 'completed' && evidence.endedAt !== null
+    && (evidence.exitCode === 0 || (knownOnly && evidence.exitCode !== null && (receipt.counts?.knownFailures?.length ?? 0) > 0)), 'CHECK_NOT_SUCCESSFUL')
+  requireThat(evidence.inputSnapshot === actualSnapshot && evidence.outputSnapshot === actualSnapshot, 'CHECK_SNAPSHOT_MISMATCH')
+  if (plan.kind === 'test') {
+    const counts = receipt.counts
+    requireThat(counts && [counts.executed, counts.passed, counts.failed].every(value => Number.isSafeInteger(value) && value >= 0), 'TEST_COUNTS_REQUIRED')
+    requireThat(counts.executed >= (plan.minExecutedTests ?? 1) && counts.failed === 0 && counts.passed === counts.executed, 'TEST_SUITE_NOT_PASSED')
+  }
+}
+
+export function invocationHeader(record: ToolEvidence, extras: Partial<InvocationHeader> = {}): InvocationHeader {
+  return {
+    taskId: record.taskId,
+    operationId: record.operationId,
+    actor: record.actor,
+    nativeToolCallId: record.nativeToolCallId,
+    argvDigest: record.argvDigest,
+    cwdDigest: record.cwdDigest,
+    inputSnapshot: record.inputSnapshot,
+    startedAt: record.startedAt,
+    ...extras,
+  }
+}
+
+export function sameInvocationHeader(left: InvocationHeader, right: InvocationHeader): boolean {
+  return digestOf(left) === digestOf(right)
+}
+
+export function artifactFingerprint(ref: ToolEvidence['stdout']): string {
+  return digestOf({
+    id: ref.id,
+    digest: ref.digest,
+    bytes: ref.bytes,
+    ownerTaskId: ref.ownerTaskId,
+    mediaType: ref.mediaType,
+  })
+}
+
+export function resolveInvocation(records: readonly ToolEvidence[]): ToolEvidence {
+  if (!records.length) throw new FusionError(EVENT_CONFLICT, 'NO_INVOCATION')
+  const header = invocationHeader(records[0]!)
+  for (const record of records) {
+    if (!sameInvocationHeader(header, invocationHeader(record))) {
+      throw new FusionError(EVENT_CONFLICT, 'IMMUTABLE_INVOCATION_CHANGED')
+    }
+  }
+  const terminals = records.filter(record => record.state !== 'started')
+  if (!terminals.length) return records[0]!
+  const first = terminals[0]!
+  for (const terminal of terminals) {
+    if (digestOf({ ...first, id: undefined }) !== digestOf({ ...terminal, id: undefined })) {
+      throw new FusionError(EVENT_CONFLICT, 'EVIDENCE_TERMINAL_CONFLICT')
+    }
+  }
+  if (first.endedAt === null) throw new FusionError(EVENT_CONFLICT, 'TERMINAL_END_REQUIRED')
+  if (first.state === 'completed' && (first.exitCode === null || !Number.isSafeInteger(first.exitCode))) {
+    throw new FusionError(EVENT_CONFLICT, 'EXIT_STATUS_REQUIRED')
+  }
+  return first
+}
+
+export function checkPlanDigest(plan: CheckPlan): Digest {
+  return digestOf(plan)
+}

package/src/execution/write-lease.ts

@@ -0,0 +1,187 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { DatabaseSync } from 'node:sqlite'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { OperationId, SessionId, TaskId, WriteLease } from '../contracts.js'
+import { FusionError, LEASE_BUSY, LEASE_GENERATION } from '../errors.js'
+
+export interface LeaseRecord extends WriteLease {
+  readonly owner: string
+  readonly pid: number
+  readonly acquiredAt: string
+  readonly liveProcessRefs: readonly number[]
+}
+
+export function canonicalWorkspace(cwd: string): string {
+  return fs.realpathSync.native(cwd)
+}
+
+const DURABLE_LEASE_ROOT = path.join(os.homedir(), '.local', 'state', 'dsh-fusion', 'leases')
+/** Where this plugin kept durable leases before it was renamed from `dsh-model-fusion`. */
+const LEGACY_LEASE_ROOT = path.join(os.homedir(), '.local', 'state', 'dsh-model-fusion', 'leases')
+
+/**
+ * Move a pre-rename lease registry to its current name.
+ *
+ * The registry outlives a single process, so a rename must carry it: a fresh
+ * empty directory beside a lock nobody reads would report the workspace as
+ * free while a previous holder believes it still owns the write lease. A move
+ * keeps that holder visible to the next process; a cross-device install copies
+ * the directory instead, and a failed copy removes only what it created.
+ *
+ * @param next - registry directory the current release uses.
+ * @param legacy - registry directory the previous name used.
+ * @returns whether a legacy registry was adopted.
+ */
+export function adoptLegacyLeaseRoot(next: string, legacy = LEGACY_LEASE_ROOT): boolean {
+  if (fs.existsSync(next) || !fs.existsSync(legacy)) return false
+  try {
+    fs.renameSync(legacy, next)
+    return true
+  } catch {
+    // Cross-device or a locked file: fall back to a copy, then drop the source.
+  }
+  try {
+    fs.cpSync(legacy, next, { recursive: true })
+  } catch {
+    fs.rmSync(next, { recursive: true, force: true })
+    return false
+  }
+  try {
+    fs.rmSync(legacy, { recursive: true, force: true })
+  } catch {
+    // The new copy is complete; a leftover legacy directory is harmless.
+  }
+  return true
+}
+
+export function leasePath(workspaceId: string, root = DURABLE_LEASE_ROOT): string {
+  const key = createHash('sha256').update(workspaceId).digest('hex').slice(0, 24)
+  return path.join(root, `${key}.lock`)
+}
+
+export class WorkspaceWriteLease {
+  constructor(private readonly root = DURABLE_LEASE_ROOT) {
+    if (!path.isAbsolute(root)) throw new TypeError('lease registry directory must be absolute')
+    adoptLegacyLeaseRoot(root)
+  }
+
+  acquire(input: {
+    cwd: string
+    holder: SessionId
+    taskId: TaskId
+    operationId: OperationId
+    liveProcessRefs?: readonly number[]
+  }): LeaseRecord {
+    const workspaceId = canonicalWorkspace(input.cwd)
+    return this.#transaction(workspaceId, db => {
+      const row = this.#row(db)
+      const prior = this.#record(row, workspaceId)
+      if (prior) throw new FusionError(LEASE_BUSY, `workspace is held by ${prior.holder}; reconcile before handoff`)
+      if (row.generation === Number.MAX_SAFE_INTEGER) throw new FusionError(LEASE_GENERATION, 'lease generation exhausted')
+      const refs = [...new Set([process.pid, ...(input.liveProcessRefs ?? [])])]
+      if (refs.some(pid => !Number.isSafeInteger(pid) || pid <= 0)) throw new FusionError(LEASE_BUSY, 'invalid process reference')
+      const record: LeaseRecord = {
+        workspaceId, holder: input.holder, taskId: input.taskId, generation: row.generation + 1,
+        activeOperationIds: [input.operationId], owner: `${process.pid}:${randomUUID()}`, pid: process.pid,
+        acquiredAt: new Date().toISOString(), liveProcessRefs: refs,
+      }
+      db.prepare('UPDATE lease SET generation=?, record=? WHERE id=1').run(record.generation, JSON.stringify(record))
+      return record
+    })
+  }
+
+  assertGeneration(lease: WriteLease, generation: number): void {
+    const current = this.current(lease.workspaceId)
+    if (lease.generation !== generation || current?.generation !== generation
+      || current.holder !== lease.holder || current.taskId !== lease.taskId) {
+      throw new FusionError(LEASE_GENERATION, `stale write generation ${generation}`)
+    }
+  }
+
+  stillHeld(lease: LeaseRecord): boolean {
+    const current = this.current(lease.workspaceId)
+    return current?.owner === lease.owner && current.generation === lease.generation
+  }
+
+  /** Caller must prove native Worker/tool quiescence before releasing. */
+  release(lease: LeaseRecord): void {
+    this.#transaction(lease.workspaceId, db => {
+      const current = this.#record(this.#row(db), lease.workspaceId)
+      if (current?.owner === lease.owner && current.generation === lease.generation) {
+        db.prepare('UPDATE lease SET record=NULL WHERE id=1 AND generation=?').run(lease.generation)
+      }
+    })
+  }
+
+  /** Trusted recovery inspection. A dead PID by itself never authorizes stealing. */
+  current(cwd: string): LeaseRecord | undefined {
+    const workspaceId = canonicalWorkspace(cwd)
+    return this.#transaction(workspaceId, db => this.#record(this.#row(db), workspaceId))
+  }
+
+  #row(db: DatabaseSync): { generation: number; record: unknown } {
+    const row = db.prepare('SELECT generation, record FROM lease WHERE id=1').get()
+    if (!row || typeof row.generation !== 'number' || !Number.isSafeInteger(row.generation) || row.generation < 0) {
+      throw new FusionError(LEASE_BUSY, 'durable lease generation is corrupt')
+    }
+    return { generation: row.generation, record: row.record }
+  }
+
+  #record(row: { generation: number; record: unknown }, workspaceId: string): LeaseRecord | undefined {
+    if (row.record === null) return undefined
+    if (typeof row.record !== 'string') throw new FusionError(LEASE_BUSY, 'invalid durable lease record')
+    const value = JSON.parse(row.record) as Partial<LeaseRecord>
+    if (value.workspaceId !== workspaceId || value.generation !== row.generation
+      || typeof value.owner !== 'string' || typeof value.holder !== 'string' || typeof value.taskId !== 'string'
+      || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 || typeof value.acquiredAt !== 'string'
+      || !Array.isArray(value.activeOperationIds) || !Array.isArray(value.liveProcessRefs)) {
+      throw new FusionError(LEASE_BUSY, 'durable lease requires reconciliation')
+    }
+    return value as LeaseRecord
+  }
+
+  /** Atomic publication/CAS; generations survive release and process restart. */
+  #transaction<T>(workspaceId: string, body: (db: DatabaseSync) => T): T {
+    const legacy = leasePath(workspaceId, this.root)
+    fs.mkdirSync(path.dirname(legacy), { recursive: true, mode: 0o700 })
+    const oldTemporary = leasePath(workspaceId, path.join(fs.existsSync('/tmp') ? '/tmp' : os.tmpdir(), 'dsh-model-fusion-leases'))
+    // A lock written under the pre-rename registry, or by the pre-rename
+    // temporary one, still names a writer: refuse rather than take the
+    // workspace out from under it.
+    const oldDurable = leasePath(workspaceId, LEGACY_LEASE_ROOT)
+    for (const lock of new Set([legacy, oldDurable, oldTemporary])) {
+      try {
+        fs.lstatSync(lock)
+        throw new FusionError(LEASE_BUSY, 'legacy writer lock requires explicit reconciliation')
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      }
+    }
+    const db = new DatabaseSync(`${legacy}.sqlite`)
+    let transaction = false
+    try {
+      db.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;')
+      transaction = true
+      const version = db.prepare('PRAGMA user_version').get()?.user_version
+      if (version !== 0 && version !== 1) throw new FusionError(LEASE_BUSY, 'unknown lease database version')
+      if (version === 0) {
+        const tables = db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").get()?.n
+        if (tables !== 0) throw new FusionError(LEASE_BUSY, 'unversioned nonempty lease database')
+        db.exec('CREATE TABLE lease (id INTEGER PRIMARY KEY CHECK(id=1), generation INTEGER NOT NULL, record TEXT); INSERT INTO lease VALUES (1, 0, NULL); PRAGMA user_version=1;')
+      }
+      const result = body(db)
+      db.exec('COMMIT'); transaction = false
+      return result
+    } catch (error) {
+      if (transaction) db.exec('ROLLBACK')
+      throw error
+    } finally { db.close() }
+  }
+}
+
+export function classifyEffect(kind: 'read-tool' | 'write-tool' | 'unknown-shell'): 'read' | 'write' {
+  if (kind === 'read-tool') return 'read'
+  return 'write'
+}

package/src/host/bindings.ts

@@ -0,0 +1,91 @@
+import type { PairProfile, TaskId } from '../contracts.js'
+import { TaskId as taskId } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import { completeProfile } from '../profile/resolve.js'
+import type { PromptBundle, ResolvedProfile } from '../profile/resolve.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+
+export interface SessionBinding {
+  readonly schemaVersion: 1
+  readonly sessionId: string
+  readonly taskId: TaskId
+  readonly selected: boolean
+  /** One native continuable Worker for this selection, across completed tasks. */
+  readonly workerId?: string
+  readonly profile: PairProfile
+  readonly prompts: PromptBundle
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid Fusion session binding')
+  return value as Record<string, unknown>
+}
+
+export function readBinding(value: unknown, sessionId: string): SessionBinding {
+  const row = object(value)
+  if (row.schemaVersion !== 1 || row.sessionId !== sessionId || typeof row.taskId !== 'string'
+    || typeof row.selected !== 'boolean') throw new Error('Fusion binding migration or reconciliation required')
+  const prompt = object(row.prompts)
+  if (row.workerId !== undefined && (typeof row.workerId !== 'string' || !row.workerId || row.workerId.includes('\0'))) {
+    throw new Error('Invalid persistent Fusion Worker identity')
+  }
+  if (typeof prompt.lead !== 'string' || typeof prompt.worker !== 'string' || typeof prompt.compact !== 'string') {
+    throw new Error('Frozen Fusion prompts are missing')
+  }
+  const prompts: PromptBundle = { lead: prompt.lead, worker: prompt.worker, compact: prompt.compact }
+  const profile = completeProfile(object(row.profile), prompts)
+  if (digestOf(profile) !== digestOf(row.profile)) throw new Error('Frozen Fusion profile or prompt digest changed')
+  return { schemaVersion: 1, sessionId, taskId: taskId(row.taskId), selected: row.selected, profile, prompts,
+    ...(row.workerId === undefined ? {} : { workerId: row.workerId as string }) }
+}
+
+/** Selection is durable and scoped by the native Lead identity, never a global default. */
+export class BindingRepository {
+  constructor(private readonly store: SqliteFusionStore) {}
+
+  read(sessionId: string): { revision: number; binding: SessionBinding } | undefined {
+    const document = this.store.readDocument(`binding:${sessionId}`)
+    return document ? { revision: document.revision, binding: readBinding(document.value, sessionId) } : undefined
+  }
+
+  select(sessionId: string, id: TaskId, resolved: ResolvedProfile): SessionBinding {
+    const prior = this.read(sessionId)
+    if (prior?.binding.selected) throw new Error('Fusion is already selected for this session')
+    const binding: SessionBinding = {
+      schemaVersion: 1, sessionId, taskId: id, selected: true,
+      profile: structuredClone(resolved.profile), prompts: structuredClone(resolved.prompts),
+    }
+    readBinding(binding, sessionId)
+    this.store.writeDocument(`binding:${sessionId}`, prior?.revision ?? 0, binding)
+    return binding
+  }
+
+  clear(sessionId: string): void {
+    const prior = this.read(sessionId)
+    if (!prior || !prior.binding.selected) return
+    this.store.writeDocument(`binding:${sessionId}`, prior.revision, { ...prior.binding, selected: false })
+  }
+
+  /** Reserve identity before native dispatch; an existing selection cannot swap workers. */
+  assignWorker(sessionId: string, expectedTask: TaskId, workerId: string): void {
+    const prior = this.read(sessionId)
+    if (!prior?.binding.selected || prior.binding.taskId !== expectedTask) throw new Error('Fusion binding changed before Worker dispatch')
+    if (prior.binding.workerId && prior.binding.workerId !== workerId) throw new Error('Persistent Worker identity cannot change within a Fusion selection')
+    const binding = { ...prior.binding, workerId }
+    readBinding(binding, sessionId)
+    this.store.writeDocument(`binding:${sessionId}`, prior.revision, binding)
+  }
+
+  /** A new native user turn starts a new task while preserving the frozen pair. */
+  rollover(sessionId: string, expectedTask: TaskId, nextTask: TaskId): SessionBinding {
+    const prior = this.read(sessionId)
+    if (!prior?.binding.selected || prior.binding.taskId !== expectedTask) throw new Error('Fusion binding changed during task rollover')
+    const binding = { ...prior.binding, taskId: nextTask }
+    this.store.writeDocument(`binding:${sessionId}`, prior.revision, binding)
+    return binding
+  }
+
+  selected(): readonly SessionBinding[] {
+    return this.store.listDocumentIds('binding:').map(id => this.read(id.slice('binding:'.length))!.binding).filter(row => row.selected)
+  }
+}

package/src/host/cache-defaults.ts

@@ -0,0 +1,103 @@
+/**
+ * Default prompt-cache behaviour for the models most people pair in Fusion, from each provider's official
+ * documentation. Matching uses the model id (stable across DSH setups), never the route name, except for the
+ * routes of this project's own OAuth plugins, whose billing we know. Everything here is a default: the user's
+ * per-model setting always wins, and the runtime can shorten an interval it observes to be too long.
+ */
+
+export const CACHE_DEFAULTS_CHECKED = '2026-09-27'
+/** Safe for every provider documented here (the shortest documented lifetime is 5 minutes). */
+export const GENERIC_INTERVAL_SECONDS = 285
+
+export type CacheMode = 'auto' | 'on' | 'off'
+
+export interface CacheFamily {
+  id: string
+  label: string
+  match: RegExp
+  /** Official lifetime text as documented (not a guarantee; caches are best-effort). */
+  lifetime: { zh: string; en: string }
+  /** Cached input price relative to uncached input, as documented. */
+  discount: string
+  keepalive: CacheMode
+  intervalSeconds: number
+  docs: string
+}
+
+export const CACHE_FAMILIES: readonly CacheFamily[] = [
+  { id: 'openai', label: 'OpenAI', match: /^(gpt-|o\d|codex|chatgpt)/i, discount: '1/10', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '空闲 5–10 分钟，最长 1 小时；部分新模型至少 30 分钟（ChatGPT 订阅通道实测：空闲 10 分钟仍命中，15 分钟已过期）', en: '5–10 min idle, up to 1 h; some newer models ≥ 30 min (ChatGPT subscription measured: still cached after 10 idle min, gone at 15)' },
+    docs: 'https://developers.openai.com/api/docs/guides/prompt-caching' },
+  { id: 'anthropic', label: 'Anthropic', match: /^claude/i, discount: '1/10', keepalive: 'auto', intervalSeconds: 270,
+    lifetime: { zh: '5 分钟，每次命中重新计时（可选 1 小时）', en: '5 min, refreshed on each hit (1 h option)' },
+    docs: 'https://platform.claude.com/docs/en/build-with-claude/prompt-caching' },
+  { id: 'google', label: 'Google', match: /^gemini/i, discount: '1/10', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '隐式缓存自动，时长未公布', en: 'implicit, lifetime not published' },
+    docs: 'https://ai.google.dev/gemini-api/docs/caching' },
+  { id: 'deepseek', label: 'DeepSeek', match: /^deepseek/i, discount: '1/10–1/50', keepalive: 'off', intervalSeconds: 285,
+    lifetime: { zh: '硬盘缓存，通常保留几小时到几天（等待期间不会过期，无需保活）', en: 'disk cache, hours to days (no keepalive needed)' },
+    docs: 'https://api-docs.deepseek.com/guides/kv_cache/' },
+  { id: 'xai', label: 'xAI', match: /^grok/i, discount: '≈1/6', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '自动，时长未公布，内存紧张时可能被清除', en: 'automatic, lifetime not published, evicted under memory pressure' },
+    docs: 'https://docs.x.ai/developers/advanced-api-usage/prompt-caching' },
+  { id: 'zhipu', label: 'Z.AI / 智谱', match: /^glm/i, discount: '≈1/5', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '自动，时长未公布', en: 'automatic, lifetime not published' },
+    docs: 'https://docs.bigmodel.cn/cn/guide/capabilities/cache' },
+  { id: 'moonshot', label: 'Moonshot / Kimi', match: /^kimi|^moonshot/i, discount: '1/10', keepalive: 'auto', intervalSeconds: 270,
+    lifetime: { zh: '默认 5 分钟，每次命中重新计时（可选 1 小时）', en: '5 min default, refreshed on each hit (1 h tier)' },
+    docs: 'https://platform.moonshot.ai/docs/pricing/chat-k3' },
+  { id: 'alibaba', label: 'Alibaba / Qwen', match: /^qwen/i, discount: '1/5', keepalive: 'auto', intervalSeconds: 270,
+    lifetime: { zh: '隐式缓存由系统管理；显式缓存 5 分钟', en: 'implicit cache system-managed; explicit cache 5 min' },
+    docs: 'https://help.aliyun.com/zh/model-studio/context-cache' },
+  { id: 'xiaomi', label: 'Xiaomi MiMo', match: /^mimo/i, discount: '≈1/120', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '自动，时长未公布', en: 'automatic, lifetime not published' },
+    docs: 'https://mimo.mi.com/docs/en-US/price/pay-as-you-go' },
+  { id: 'stepfun', label: 'StepFun', match: /^step/i, discount: '1/5', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '自动，时长未公布', en: 'automatic, lifetime not published' },
+    docs: 'https://platform.stepfun.com/docs/guide/prompt_cache' },
+  { id: 'meta', label: 'Meta Muse', match: /^muse/i, discount: '≈1/8', keepalive: 'auto', intervalSeconds: 285,
+    lifetime: { zh: '自动；可申请 24 小时保留但不保证', en: 'automatic; 24 h retention is a hint, not a guarantee' },
+    docs: 'https://dev.meta.ai/docs/pricing-rate-limits' },
+  { id: 'minimax', label: 'MiniMax', match: /^minimax/i, discount: '1/5', keepalive: 'auto', intervalSeconds: 270,
+    lifetime: { zh: '5 分钟，每次命中重新计时', en: '5 min, refreshed on each hit' },
+    docs: 'https://platform.minimax.io/docs/api-reference/text-prompt-caching' },
+]
+
+/** Routes of this project's OAuth plugins (dsh-oauth-login, dsh-antigravity-oauth): billing we know. */
+export interface RouteBilling { match: RegExp; label: string; keepalive: CacheMode; reason: { zh: string; en: string }
+  /** Interval measured on this route; overrides the model family default. */
+  intervalSeconds?: number }
+export const OWN_ROUTES: readonly RouteBilling[] = [
+  { match: /^pi-zai-coding/, label: 'GLM Coding Plan', keepalive: 'off',
+    reason: { zh: '按请求次数计额度，保活会占用次数', en: 'quota counts requests; keepalive pings would use it' } },
+  { match: /^pi-kimi-coding/, label: 'Kimi Code', keepalive: 'off',
+    reason: { zh: '订阅按请求次数计额度', en: 'subscription quota counts requests' } },
+  { match: /^pi-github-copilot/, label: 'GitHub Copilot', keepalive: 'off',
+    reason: { zh: '每次请求都算一次高级请求', en: 'every request counts as a premium request' } },
+  { match: /^agy-/, label: 'Antigravity', keepalive: 'off',
+    reason: { zh: '按请求次数限额', en: 'request-count limits' } },
+  // Probed 2026-10-01 on gpt-6-astra: a 20.7k-token prefix still hit after 4, 7 and 10 idle minutes and was gone
+  // at 15 and 22. 480 s is 0.8 x the shortest confirmed lifetime; it halves the pings of the 285 s family default.
+  { match: /^pi-openai-codex/, label: 'ChatGPT (Codex)', keepalive: 'auto', intervalSeconds: 480,
+    reason: { zh: '按用量计，缓存命中能省额度；实测缓存空闲 10 分钟仍在', en: 'usage-based; cache hits save quota; measured cache still warm after 10 idle min' } },
+  ...([[/^pi-anthropic/, 'Claude'], [/^pi-xai/, 'xAI'], [/^pi-openrouter/, 'OpenRouter']] as const)
+    .map(([match, label]): RouteBilling => ({ match, label, keepalive: 'auto',
+      reason: { zh: '按用量计，缓存命中能省额度', en: 'usage-based; cache hits save quota' } })),
+]
+
+export interface CacheDefaults {
+  keepalive: CacheMode
+  intervalSeconds: number
+  source: 'route' | 'family' | 'generic'
+  family?: CacheFamily
+  route?: RouteBilling
+}
+
+/** Defaults for one physical route; the model id selects the family, our own routes set the billing mode. */
+export function cacheDefaults(provider: string, model: string): CacheDefaults {
+  const family = CACHE_FAMILIES.find(item => item.match.test(model))
+  const route = OWN_ROUTES.find(item => item.match.test(provider))
+  if (route) return { keepalive: route.keepalive, intervalSeconds: route.intervalSeconds ?? family?.intervalSeconds ?? GENERIC_INTERVAL_SECONDS, source: 'route', family, route }
+  if (family) return { keepalive: family.keepalive, intervalSeconds: family.intervalSeconds, source: 'family', family }
+  return { keepalive: 'auto', intervalSeconds: GENERIC_INTERVAL_SECONDS, source: 'generic' }
+}