@thebtf/dsh-cliproxyapi-provider 0.0.0-stage → 0.4.3

package/locale/ru.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "CLIProxyAPI",
+    "description": "Подключение шлюза CLIProxyAPI и управление моделями в DeepSeek Harness.",
+    "detail": "details/ru.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "CLIProxyAPI",
+    "description": "在 DeepSeek Harness 中连接 CLIProxyAPI 网关并管理模型。",
+    "detail": "details/zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,85 @@
-{
-  "name": "@thebtf/dsh-cliproxyapi-provider",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@thebtf/dsh-cliproxyapi-provider",
+  "version": "0.4.3",
+  "description": "GUI-configurable CLIProxyAPI provider for DeepSeek Harness with a selectable wire protocol",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./client.js",
+    "./catalog": "./src/catalog.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "client.js",
+    "locale",
+    "details",
+    "cordis.patch.yml",
+    "README.md",
+    "README_EN.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js && node --check src/catalog.js && node --check client.js && node --test",
+    "pack:github": "npm pack"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thebtf/dsh-cliproxyapi-provider.git"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-credentials": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.2-rc.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-llm-pi-ai": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-util-values": "^0.2.2-rc.2",
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-api-remotes": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.2-rc.2",
+    "react": "^18.2.0"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "^0.2.2-rc.2"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cliproxyapi",
+    "llm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/adapter.js

@@ -0,0 +1,68 @@
+import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { LlmError, resolveImageAttachmentAccess, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import { createProvider, InMemoryCredentialStore, defaultProviderAuthContext } from '@earendil-works/pi-ai'
+import { createTransport } from './transport.js'
+import { resolveIdentity } from './connection.js'
+import { protocolOf } from './policy.js'
+
+const PROVIDER = 'CLIProxyAPI'
+const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+
+export function createGatewayAdapter(ctx, snapshot, diagnostics, onMissing = () => { }) {
+  let profiles = new Map()
+  const update = (next) => {
+    const captured = structuredClone(next)
+    const protocol = protocolOf(captured.policy)
+    const models = captured.models.filter((model) => captured.modelSelection?.[model.id] !== false).map((model) => {
+      const efforts = model.reasoningEfforts
+      const thinkingLevelMap = efforts && Object.fromEntries(LEVELS.flatMap((level) => efforts[level] === undefined ? [[level, null]] : efforts[level] === null ? [] : [[level, efforts[level]]]))
+      return {
+        id: model.id, name: model.name ?? model.id, provider: PROVIDER, api: protocol,
+        baseUrl: captured.baseURL, reasoning: !!efforts, ...(thinkingLevelMap ? { thinkingLevelMap } : {}),
+        input: model.inputModalities ?? model.input ?? ['text'], contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        compat: { ...captured.policy?.compat, ...model.compat, supportsStrictMode: true },
+      }
+    })
+    const piProvider = createProvider({
+      id: PROVIDER, name: PROVIDER, baseUrl: captured.baseURL, models,
+      auth: { apiKey: { name: 'DSH key resolver', resolve: async ({ credential }) => ({ auth: { apiKey: credential?.key ?? 'cpa-keyless' }, source: 'DSH' }) } },
+      api: createTransport(protocol, captured.baseURL, diagnostics, globalThis.fetch, captured.authIdentity?.type === 'none'),
+    })
+    const profile = {
+      provider: PROVIDER, displayName: PROVIDER, baseURL: captured.baseURL, piProvider, api: protocol,
+      authIdentity: captured.authIdentity, headers: captured.policy?.headers,
+      reasoning: captured.policy?.reasoning, thinkingBudgets: captured.policy?.thinkingBudgets,
+      cacheRetention: captured.policy?.cacheRetention, transport: captured.policy?.transport,
+      timeoutMs: captured.policy?.timeoutMs, websocketConnectTimeoutMs: captured.policy?.websocketConnectTimeoutMs,
+      streamIdleTimeoutMs: captured.policy?.streamIdleTimeoutMs ?? 30000,
+      maxRequestImageBytes: captured.policy?.maxRequestImageBytes ?? 20 * 1024 * 1024,
+      maxRequestImages: captured.policy?.maxRequestImages ?? 50,
+      imageOffloadCountQuantum: captured.policy?.imageOffloadCountQuantum ?? Math.min(10, captured.policy?.maxRequestImages ?? 50),
+      requestImagePixelBudget: captured.policy?.requestImagePixelBudget ?? 2048 * 2048, requestImageMaxBytes: captured.policy?.requestImageMaxBytes ?? 1024 * 1024,
+      retryPolicy: resolveRetryPolicy(captured.policy?.retryPolicy, 'CPA'),
+      modelErrors: new Map(), configuredMaxTokens: new Map(),
+    }
+    profiles = new Map([[PROVIDER, profile]])
+  }
+  if (snapshot) update(snapshot)
+  const adapter = new PiAiAdapter({
+    profiles: () => profiles,
+    resolveApiKey: async (_provider, profile) => {
+      const value = await resolveIdentity(ctx.credentials, profile.authIdentity)
+      if (profile.authIdentity?.type !== 'none' && !value) {
+        onMissing()
+        throw new LlmError('CPA credential is missing', 'MISSING_CREDENTIAL')
+      }
+      return value
+    },
+    auth: { credentials: new InMemoryCredentialStore(), authContext: defaultProviderAuthContext },
+    resolveAttachments: () => ctx.get('attachments'),
+    resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, (path) => ctx.get('fs')?.processPathFromHostPath(path), ref),
+    onReplayDegrade: () => {
+      diagnostics.push({ at: Date.now(), stage: 'replay-degraded' })
+      if (diagnostics.length > 50) diagnostics.splice(0, diagnostics.length - 50)
+    },
+  })
+  return { adapter, update }
+}

package/src/catalog-store.js

@@ -0,0 +1,62 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, open, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { dshCachePath } from '@deepseek-ai/dsh-home-paths'
+
+const MAX_CACHE_BYTES = 8 * 1024 * 1024
+const MAX_CATALOG_BYTES = 4 * 1024 * 1024
+
+function cachePath(documentPath, generation) {
+  if (typeof documentPath !== 'string' || !documentPath || typeof generation !== 'string' || !/^[a-f0-9]{64}$/.test(generation)) throw new TypeError('A document path and valid generation are required')
+  const documentHash = createHash('sha256').update(documentPath).digest('hex')
+  return dshCachePath('llm-cliproxyapi', documentHash, `${generation}.json`)
+}
+
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, /^(?:api[_-]?key|authorization|proxy[_-]?authorization|cookie|set-cookie|password|secret|access[_-]?token|refresh[_-]?token)$/i.test(key) ? '[redacted]' : redact(item)]))
+}
+function validModels(models) {
+  return Array.isArray(models) && models.length > 0 && models.every((model) => model && typeof model === 'object' && !Array.isArray(model) && typeof model.id === 'string' && model.id.length > 0 && typeof model.name === 'string' && Number.isSafeInteger(model.contextWindow) && model.contextWindow > 0 && Number.isSafeInteger(model.maxTokens) && model.maxTokens > 0 && Array.isArray(model.inputModalities) && model.inputModalities.length > 0 && model.inputModalities.every((input) => input === 'text' || input === 'image') && (model.reasoningEfforts === undefined || (model.reasoningEfforts && typeof model.reasoningEfforts === 'object' && !Array.isArray(model.reasoningEfforts) && Object.entries(model.reasoningEfforts).every(([level, wire]) => ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(level) && (typeof wire === 'string' && wire.length > 0 || level === 'off' && wire === null))))) && new Set(models.map((model) => model.id)).size === models.length
+}
+
+export async function readCatalogCache(documentPath, generation, baseURL, authIdentity) {
+  try {
+    const handle = await open(cachePath(documentPath, generation), 'r')
+    let data
+    try {
+      const buffer = Buffer.alloc(MAX_CACHE_BYTES + 1)
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+      if (bytesRead > MAX_CACHE_BYTES) return undefined
+      data = buffer.subarray(0, bytesRead)
+    } finally {
+      await handle.close()
+    }
+    const value = JSON.parse(data.toString('utf8'))
+    if (!value || value.schemaVersion !== 1 || value.generation !== generation || value.baseURL !== baseURL || JSON.stringify(value.authIdentity) !== JSON.stringify(authIdentity) || !Number.isFinite(value.fetchedAt) || !Array.isArray(value.raw) || !validModels(value.effective)) return undefined
+    return value
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return undefined
+    throw error
+  }
+}
+
+export async function writeCatalogCache(documentPath, snapshot) {
+  const file = cachePath(documentPath, snapshot.generation)
+  const raw = redact(snapshot.raw)
+  const effective = redact(snapshot.effective)
+  if (!Array.isArray(raw) || !validModels(effective)) throw new TypeError('Catalog models are invalid')
+  if (Buffer.byteLength(JSON.stringify(raw)) > MAX_CATALOG_BYTES) throw new RangeError('Catalog exceeds 4 MiB')
+  const contents = JSON.stringify({ schemaVersion: 1, generation: snapshot.generation, baseURL: snapshot.baseURL, authIdentity: snapshot.authIdentity, fetchedAt: snapshot.fetchedAt, raw, effective })
+  if (Buffer.byteLength(contents) > MAX_CACHE_BYTES) throw new RangeError('Catalog cache exceeds 8 MiB')
+  await mkdir(dirname(file), { recursive: true })
+  const temporary = `${file}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, contents, { encoding: 'utf8', flag: 'wx', mode: 0o600 })
+    await rename(temporary, file)
+  } catch (error) {
+    await unlink(temporary).catch(() => { })
+    throw error
+  }
+}

package/src/catalog.js

@@ -0,0 +1,129 @@
+import { credentialField } from './secrets.js'
+
+const CANONICAL_REASONING_LEVELS = new Set([
+  'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max',
+])
+
+function positiveInteger(...values) {
+  for (const value of values) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) return value
+  }
+}
+
+function nonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+}
+
+function normalizeReasoningLevel(value) {
+  const wire = nonEmptyString(value)?.toLowerCase()
+  if (!wire) return undefined
+  if (wire === 'none' || wire === 'off') return { canonical: 'off', wire: 'none' }
+  if (wire === 'ultra') return { canonical: 'max', wire }
+  if (!CANONICAL_REASONING_LEVELS.has(wire)) return undefined
+  return { canonical: wire, wire }
+}
+
+export function reasoningEffortsOf(entry) {
+  if (!Array.isArray(entry?.supported_reasoning_levels)) return undefined
+  const efforts = {}
+  for (const raw of entry.supported_reasoning_levels) {
+    const normalized = normalizeReasoningLevel(typeof raw === 'string' ? raw : raw?.effort)
+    if (normalized && !(normalized.canonical in efforts)) efforts[normalized.canonical] = normalized.wire
+  }
+  // llm-pi-ai rejects a capability map that offers only "off". Omitting the
+  // field correctly describes a non-reasoning model for a hand-declared route.
+  if (Object.keys(efforts).every((level) => level === 'off')) return undefined
+  return Object.keys(efforts).length ? efforts : undefined
+}
+
+function inputModalitiesOf(entry, fallback) {
+  if (!Array.isArray(entry?.input_modalities)) return [...fallback]
+  const modalities = []
+  const seen = new Set()
+  for (const raw of entry.input_modalities) {
+    const value = nonEmptyString(raw)?.toLowerCase()
+    if ((value === 'text' || value === 'image') && !seen.has(value)) {
+      seen.add(value)
+      modalities.push(value)
+    }
+  }
+  return modalities.length ? modalities : [...fallback]
+}
+function safeMetadata(value) {
+  if (Array.isArray(value)) return value.map(safeMetadata)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    credentialField(key) ? '[redacted]' : safeMetadata(item),
+  ]))
+}
+
+
+export function modelProfileOf(entry, options = {}) {
+  const id = nonEmptyString(entry?.slug, entry?.id, entry?.model)
+  if (!id || (!options.includeHiddenModels && entry?.visibility === 'hide')) return undefined
+  const reasoningEfforts = reasoningEffortsOf(entry)
+  return {
+    id,
+    name: nonEmptyString(entry?.display_name, entry?.name, entry?.description, id),
+    contextWindow: positiveInteger(entry?.max_context_window, entry?.context_window, entry?.context_length, options.defaultContextWindow),
+    maxTokens: positiveInteger(entry?.max_output_tokens, entry?.max_completion_tokens, entry?.max_tokens, options.defaultMaxTokens),
+    input: inputModalitiesOf(entry, options.defaultInput ?? ['text']),
+    ...(reasoningEfforts ? { reasoningEfforts } : {}),
+  }
+}
+
+export function readCodexCatalogWithMetadata(body, options = {}) {
+  if (!body || !Array.isArray(body.models)) throw new TypeError('CLIProxyAPI model catalog has no "models" array')
+  const models = []
+  const discovery = []
+  const seen = new Set()
+  for (const entry of body.models) {
+    const model = modelProfileOf(entry, options)
+    if (!model || seen.has(model.id)) continue
+    seen.add(model.id)
+    const override = options.overrides?.[model.id] ?? {}
+    const overrideContext = positiveInteger(override.contextWindow)
+    const overrideMax = positiveInteger(override.maxTokens)
+    const overrideInput = Array.isArray(override.inputModalities) && override.inputModalities.length && override.inputModalities.every((value) => value === 'text' || value === 'image') ? [...new Set(override.inputModalities)] : undefined
+    const overrideEfforts = override.reasoningEfforts && typeof override.reasoningEfforts === 'object' && !Array.isArray(override.reasoningEfforts) ? Object.fromEntries(Object.entries(override.reasoningEfforts).filter(([level, wire]) => CANONICAL_REASONING_LEVELS.has(level) && (typeof wire === 'string' && wire.length > 0 || level === 'off' && wire === null))) : undefined
+    if (overrideContext) model.contextWindow = overrideContext
+    if (typeof override.name === 'string' && override.name) model.name = override.name
+    if (override.reasoningEfforts === false) delete model.reasoningEfforts
+    if (override.compat && typeof override.compat === 'object') model.compat = override.compat
+    if (overrideMax) model.maxTokens = overrideMax
+    if (overrideInput) model.input = overrideInput
+    if (overrideEfforts && Object.keys(overrideEfforts).some((level) => level !== 'off')) model.reasoningEfforts = overrideEfforts
+    const defaultEffort = normalizeReasoningLevel(override.defaultReasoningEffort ?? entry.default_reasoning_level)?.canonical
+    models.push(model)
+    discovery.push({
+      ...model,
+      inputModalities: [...model.input],
+      ...(defaultEffort && model.reasoningEfforts?.[defaultEffort] !== undefined ? { defaultReasoningEffort: defaultEffort } : {}),
+      catalogMetadata: safeMetadata(entry),
+      catalogSources: {
+        contextWindow: overrideContext ? 'override' : positiveInteger(entry.max_context_window, entry.context_window, entry.context_length) ? 'cpa' : 'default',
+        maxTokens: overrideMax ? 'override' : positiveInteger(entry.max_output_tokens, entry.max_completion_tokens, entry.max_tokens) ? 'cpa' : 'default',
+        inputModalities: overrideInput ? 'override' : Array.isArray(entry.input_modalities) && entry.input_modalities.some((value) => ['text', 'image'].includes(nonEmptyString(value)?.toLowerCase())) ? 'cpa' : 'default',
+        reasoningEfforts: overrideEfforts && Object.keys(overrideEfforts).some((level) => level !== 'off') ? 'override' : reasoningEffortsOf(entry) ? 'cpa' : 'default',
+      },
+    })
+  }
+  if (!models.length) throw new TypeError('CLIProxyAPI model catalog contains no usable models')
+  return { models, discovery }
+}
+
+export function readCodexCatalog(body, options = {}) {
+  return readCodexCatalogWithMetadata(body, options).models
+}
+
+export function catalogURL(baseURL) {
+  const base = String(baseURL ?? '').trim()
+  if (!base) throw new TypeError('CLIProxyAPI baseURL must not be empty')
+  const url = new URL(base)
+  url.pathname = url.pathname.replace(/\/+$/, '') + '/models'
+  url.searchParams.set('client_version', 'dsh-cliproxyapi-provider')
+  return url.toString()
+}

package/src/connection-store.js

@@ -0,0 +1,98 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, open, rename, unlink, writeFile } from 'node:fs/promises'
+import { basename, dirname } from 'node:path'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+import { ConnectionError, validateEndpoint } from './connection.js'
+
+// A connection snapshot that only this plugin owns. The settings row lives in
+// the profile patch file and can disappear when the host profile is rebuilt, a
+// row is denied by a core-compatibility gate, or the user reinstalls the
+// bundle. The snapshot is the reconnect source of truth for those cases.
+const MAX_SNAPSHOT_BYTES = 256 * 1024
+const IDENTITY_TYPES = new Set(['none', 'reference', 'record'])
+
+function snapshotPath(documentPath) {
+  // Keyed by the profile, not by the profile path: a rebuilt profile has a new
+  // patch file path but keeps its name, so the snapshot must survive the rebuild.
+  const profile = documentPath ? basename(dirname(documentPath)) : 'default'
+  const name = /^[\w.-]{1,64}$/.test(profile) ? profile : createHash('sha256').update(profile).digest('hex').slice(0, 16)
+  return dshHomePath('llm-cliproxyapi', name + '.json')
+}
+
+function validIdentity(identity) {
+  if (!identity || typeof identity !== 'object' || Array.isArray(identity)) return false
+  if (!IDENTITY_TYPES.has(identity.type)) return false
+  if (identity.type === 'reference') return typeof identity.ref === 'string' && identity.ref.length > 0
+  if (identity.type === 'record') return typeof identity.key === 'string' && identity.key.length > 0
+  return Object.keys(identity).length === 1
+}
+
+const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+export function snapshotOf(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('A connection is required')
+  if (typeof value.baseURL !== 'string' || !value.baseURL) throw new TypeError('A connection endpoint is required')
+  if (typeof value.generation !== 'string' || !/^[a-f0-9]{64}$/.test(value.generation)) throw new TypeError('A connection generation is required')
+  if (!validIdentity(value.authIdentity)) throw new TypeError('A connection identity is required')
+  validateEndpoint(value.baseURL)
+  if (value.policy !== undefined && !plain(value.policy)) throw new TypeError('A connection policy must be an object')
+  if (value.overrides !== undefined && !plain(value.overrides)) throw new TypeError('Connection overrides must be an object')
+  if (value.modelSelection !== undefined && (!plain(value.modelSelection) || Object.values(value.modelSelection).some((selected) => typeof selected !== 'boolean'))) throw new TypeError('A model selection must contain booleans')
+  return {
+    schemaVersion: 1,
+    baseURL: value.baseURL,
+    authIdentity: structuredClone(value.authIdentity),
+    enabled: value.enabled !== false,
+    policy: structuredClone(value.policy ?? {}),
+    modelSelection: structuredClone(value.modelSelection ?? {}),
+    overrides: structuredClone(value.overrides ?? {}),
+    generation: value.generation,
+    ...(typeof value.operationId === 'string' && value.operationId ? { operationId: value.operationId } : {}),
+  }
+}
+
+export async function writeConnectionSnapshot(documentPath, value) {
+  const snapshot = { ...snapshotOf(value), savedAt: Date.now() }
+  const contents = JSON.stringify(snapshot)
+  if (Buffer.byteLength(contents) > MAX_SNAPSHOT_BYTES) throw new RangeError('Connection snapshot exceeds 256 KiB')
+  const file = snapshotPath(documentPath)
+  await mkdir(dirname(file), { recursive: true })
+  const temporary = `${file}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, contents, { encoding: 'utf8', flag: 'wx', mode: 0o600 })
+    await rename(temporary, file)
+  } catch (error) {
+    await unlink(temporary).catch(() => { })
+    throw error
+  }
+  return snapshot
+}
+
+export async function readConnectionSnapshot(documentPath) {
+  let data
+  try {
+    const handle = await open(snapshotPath(documentPath), 'r')
+    try {
+      const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1)
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+      if (bytesRead > MAX_SNAPSHOT_BYTES) return undefined
+      data = buffer.subarray(0, bytesRead)
+    } finally {
+      await handle.close()
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw error
+  }
+  let value
+  try { value = JSON.parse(data.toString('utf8')) } catch { return undefined }
+  if (!value || value.schemaVersion !== 1 || !Number.isFinite(value.savedAt)) return undefined
+  try { return snapshotOf(value) } catch { return undefined }
+}
+
+export async function removeConnectionSnapshot(documentPath) {
+  try { await unlink(snapshotPath(documentPath)); return true } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw new ConnectionError('SNAPSHOT_UNAVAILABLE', 'Connection snapshot could not be removed')
+  }
+}

package/src/connection.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
+
+const NS = 'llm-cliproxyapi'
+
+export class ConnectionError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'ConnectionError'
+    this.code = code
+  }
+}
+
+export function validateEndpoint(input) {
+  if (typeof input !== 'string' || !input.trim() || input !== input.trim()) throw new ConnectionError('INVALID_URL', 'A valid endpoint is required')
+  let parsed
+  try { parsed = new URL(input) } catch { throw new ConnectionError('INVALID_URL', 'A valid endpoint is required') }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) {
+    throw new ConnectionError('INVALID_URL', 'Endpoint must be HTTP or HTTPS without user information or fragment')
+  }
+  for (const key of parsed.searchParams.keys()) {
+    if (/(?:key|secret|token|password|authorization|credential)/i.test(key)) throw new ConnectionError('INVALID_URL', 'Endpoint query may not contain secrets')
+  }
+  return input
+}
+
+function descriptor(settings) {
+  const result = settings.describe().find((row) => row.ns === NS)
+  if (!result || !Number.isSafeInteger(result.revision)) throw new ConnectionError('SETTINGS_UNAVAILABLE', 'Connection settings are unavailable')
+  return result
+}
+
+export async function resolveIdentity(credentials, identity) {
+  if (identity?.type === 'none') return undefined
+  if (identity?.type === 'reference') return (await credentials.resolve(credentialRef(identity.ref)))?.value
+  if (identity?.type === 'record') {
+    const record = await credentials.readRecord(identity.key)
+    return record?.kind === 'api-key' ? record.key : undefined
+  }
+  throw new ConnectionError('INVALID_AUTH', 'Unknown credential identity')
+}
+
+export async function saveConnection(settings, credentials, input) {
+  const current = descriptor(settings)
+  if (!Number.isSafeInteger(input.expectedRevision)) throw new ConnectionError('SETTINGS_CONFLICT', 'Connection settings have changed')
+  if (typeof input.operationId !== 'string' || !input.operationId || input.operationId.length > 256) throw new ConnectionError('INVALID_OPERATION', 'An operation ID is required')
+  if (current.value?.operationId === input.operationId) {
+    const same = current.value.baseURL === input.baseURL && JSON.stringify(current.value.policy ?? {}) === JSON.stringify(input.policy ?? current.value.policy ?? {}) && Object.entries(input.selectionChanges ?? {}).every(([id, selected]) => current.value.modelSelection?.[id] === selected)
+    if (!same) throw new ConnectionError('OPERATION_CONFLICT', 'Operation ID was already used for a different draft')
+    const identity = current.value.authIdentity
+    if (input.authEdit?.type === 'none' && identity?.type !== 'none' || input.authEdit?.type === 'reference' && (identity?.type !== 'reference' || identity.ref !== input.authEdit.ref) || input.authEdit?.type === 'replace' && (identity?.type !== 'record' || await resolveIdentity(credentials, identity) !== input.authEdit.key)) throw new ConnectionError('OPERATION_CONFLICT', 'Operation ID was already used for a different draft')
+    return { revision: current.revision, generation: current.value.generation, operationId: input.operationId }
+  }
+  if (input.expectedRevision !== current.revision) throw new ConnectionError('SETTINGS_CONFLICT', 'Connection settings have changed')
+  const baseURL = validateEndpoint(input.baseURL)
+  const previous = current.value ?? {}
+  if (input.selectionChanges != null && (typeof input.selectionChanges !== 'object' || Array.isArray(input.selectionChanges) || Object.values(input.selectionChanges).some((v) => typeof v !== 'boolean'))) throw new ConnectionError('INVALID_SELECTION', 'Model selection must contain booleans')
+  const edit = input.authEdit
+  if (!edit || typeof edit !== 'object') throw new ConnectionError('INVALID_AUTH', 'An explicit authentication action is required')
+  let identity
+  if (edit.type === 'keep') {
+    if (!previous.authIdentity) throw new ConnectionError('INVALID_AUTH', 'There is no existing identity to retain')
+    if (previous.baseURL && previous.baseURL !== baseURL && edit.allowEndpointReuse !== true) throw new ConnectionError('AUTH_REUSE_REQUIRED', 'Credential reuse on a new endpoint requires consent')
+    identity = previous.authIdentity
+  } else if (edit.type === 'none') {
+    identity = { type: 'none' }
+  } else if (edit.type === 'reference') {
+    try { identity = { type: 'reference', ref: credentialRef(edit.ref) } } catch { throw new ConnectionError('INVALID_AUTH', 'Invalid credential reference') }
+    if (previous.baseURL && previous.baseURL !== baseURL && previous.authIdentity?.type === 'reference' && previous.authIdentity.ref === identity.ref && edit.allowEndpointReuse !== true) throw new ConnectionError('AUTH_REUSE_REQUIRED', 'Credential reuse on a new endpoint requires consent')
+  } else if (edit.type === 'replace') {
+    if (typeof edit.key !== 'string' || !edit.key.trim()) throw new ConnectionError('INVALID_AUTH', 'A non-empty key is required')
+    const id = 'op-' + createHash('sha256').update(input.operationId).digest('hex')
+    const key = credentialKey(NS, id)
+    const existing = await credentials.readRecord(key)
+    if (existing && (existing.kind !== 'api-key' || existing.key !== edit.key)) throw new ConnectionError('OPERATION_CONFLICT', 'Operation ID already belongs to another credential')
+    if (!existing) {
+      let record
+      try {
+        record = await credentials.modifyRecord(key, async (value) => {
+          if (value) return undefined
+          return { kind: 'api-key', key: edit.key }
+        })
+      } catch {
+        try { record = await credentials.readRecord(key) } catch { }
+        if (!record) throw new ConnectionError('UNKNOWN', 'Credential staging outcome is unknown; read state before retrying')
+      }
+      if (record?.kind !== 'api-key' || record.key !== edit.key) throw new ConnectionError('OPERATION_CONFLICT', 'Operation ID already belongs to another credential')
+    }
+    identity = { type: 'record', key }
+  } else {
+    throw new ConnectionError('INVALID_AUTH', 'Unknown authentication action')
+  }
+  const generation = createHash('sha256').update(input.operationId).update('\0').update(String(current.revision)).digest('hex')
+  const values = {
+    baseURL, authIdentity: identity, enabled: previous.enabled ?? true,
+    policy: input.policy ?? previous.policy ?? {},
+    modelSelection: { ...(previous.modelSelection ?? {}), ...(input.selectionChanges ?? {}) },
+    operationId: input.operationId, generation,
+  }
+  const ops = Object.entries(values).map(([key, value]) => ({ op: 'set', path: [key], value }))
+  try {
+    await settings.mutate(NS, ops, input.expectedRevision)
+  } catch (error) {
+    if (error?.code === 'SETTINGS_CONFLICT') throw error
+    try {
+      const after = descriptor(settings)
+      if (after.value?.operationId === input.operationId && after.value?.generation === generation) return { revision: after.revision, generation, operationId: input.operationId }
+    } catch { }
+    throw new ConnectionError('UNKNOWN', 'Save outcome is unknown; read state before retrying')
+  }
+  const after = descriptor(settings)
+  if (after.value?.operationId !== input.operationId || after.value?.generation !== generation) throw new ConnectionError('UNKNOWN', 'Save outcome is unknown; read state before retrying')
+  return { revision: after.revision, generation, operationId: input.operationId }
+}