dsh-cline-pass 0.1.0

package/lib/index.js

@@ -0,0 +1,409 @@
+/**
+ * dsh-cline-pass — a self-contained Cline Pass provider for the DeepSeek
+ * Harness. It registers on the host plane:
+ *
+ * 1. One LLM provider route (default `cline-pass`), served by
+ *    {@link ClinePassAdapter}.
+ * 2. A configurable-provider directory entry for that route.
+ * 3. The `cline_pass_*` tools, and the setup panel's host half.
+ *
+ * Configuration lives in the `cline-pass` settings section, so it survives
+ * restarts and reloads live. API keys never go there: accounts name a
+ * credential reference resolved per request through the credential seam.
+ *
+ * Routing behavior reimplements the MIT-licensed cline-pass-switcher findings.
+ *
+ * @module dsh-cline-pass
+ */
+import z from '@deepseek-ai/schemastery'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { assertUsableApiKey, errorChain, LlmError } from '@deepseek-ai/dsh-llm'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import {
+  ClinePassAdapter,
+  DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_REQUEST_IMAGE_POLICY,
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+} from './adapter.js'
+import { catalogEntry, MODEL_CATALOG, REASONING_EFFORTS } from './catalog.js'
+import { createEngine } from './engine.js'
+import { createPanel, PANEL_PATH, registerPanel } from './panel.js'
+import { createStore } from './store.js'
+import { registerTools } from './tools.js'
+
+export { ClinePassAdapter, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_REQUEST_IMAGE_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS }
+export { collectImageRefs, prepareRequestImages } from './adapter.js'
+export { MODEL_CATALOG, REASONING_EFFORTS } from './catalog.js'
+export { createEngine } from './engine.js'
+export { createPanel, PANEL_PATH, registerPanel } from './panel.js'
+export { createStore } from './store.js'
+export { buildAttempts, injectPrefs, parseRouting } from './protocol.js'
+
+/** Stable Loader identity. */
+export const name = 'cline-pass'
+
+/** The LLM seam and the host tool registry. */
+export const inject = ['llm', 'tools']
+
+/** The settings namespace this plugin owns. */
+export const DEFAULT_SETTINGS_NS = 'cline-pass'
+
+/** The provider route registered when configuration names none. */
+export const DEFAULT_PROVIDER = 'cline-pass'
+
+/** The credential name used when no account declares one. */
+export const DEFAULT_API_KEY_ENV = 'CLINE_PASS_API_KEY'
+
+/** Cline Pass subscription models current at release time; refreshed on demand. */
+export const DEFAULT_MODELS = [
+  'cline-pass/glm-5.3-flash',
+  'cline-pass/kimi-k3',
+  'cline-pass/deepseek-v4-flash',
+  'cline-pass/deepseek-v4.1-flash',
+  'cline-pass/qwen3.8-max',
+  'cline-pass/minimax-m3',
+  'cline-pass/glm-5.3',
+  'cline-pass/glm-5.2',
+  'cline-pass/deepseek-v4-pro',
+  'cline-pass/mimo-v2.5-pro',
+  'cline-pass/mimo-v2.5',
+  'cline-pass/kimi-k2.6',
+  'cline-pass/qwen3.7-plus',
+  'cline-pass/kimi-k2.7-code',
+  'cline-pass/qwen3.7-max',
+]
+
+/** One Cline Pass account: a credential reference plus routing participation. */
+export const AccountProfile = z.object({
+  displayName: z.string().default(''),
+  apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+  enabled: z.boolean().default(true),
+  baseURL: z.string().default(''),
+})
+
+/** One model's catalog override, merged over the published metadata. */
+export const ModelProfile = z.object({
+  name: z.string().default(''),
+  contextWindow: z.number().default(0),
+  maxTokens: z.number().default(0),
+  reasoning: z.union([z.boolean(), z.const(undefined)]).default(undefined),
+  input: z.array(z.string()).default([]),
+})
+
+/** One model's upstream pin. */
+export const PinProfile = z.object({
+  upstreams: z.array(z.string()).default([]),
+  exclude: z.array(z.string()).default([]),
+  pinMode: z.string().default('strict'),
+  sort: z.string().default(''),
+})
+
+/** Validated plugin configuration (this plugin's settings section). */
+export const Config = z.object({
+  provider: z.string().default(DEFAULT_PROVIDER),
+  displayName: z.string().default('Cline Pass'),
+  baseURL: z.string().default('https://api.cline.bot/api/v1'),
+  apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+  accounts: z.dict(AccountProfile).default({}),
+  accountMode: z.string().default('single'),
+  activeAccount: z.string().default(''),
+  knownModels: z.array(z.string()).default(DEFAULT_MODELS),
+  models: z.dict(ModelProfile).default({}),
+  perModel: z.dict(PinProfile).default({}),
+  reasoningModels: z.boolean().default(true),
+  defaultContextWindow: z.number().default(DEFAULT_CONTEXT_WINDOW),
+  defaultMaxTokens: z.number().default(DEFAULT_MAX_TOKENS),
+  streamIdleTimeoutMs: z.number().default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  exposeCatalog: z.boolean().default(false),
+  historyLimit: z.number().default(100),
+})
+
+/** Redact a secret, keeping just enough to recognize it. */
+function maskKey(value) {
+  const key = String(value ?? '')
+  if (key.length === 0) return ''
+  if (key.length <= 10) return `${key.slice(0, 2)}…${key.slice(-2)}`
+  return `${key.slice(0, 6)}…${key.slice(-4)}`
+}
+
+/**
+ * Register the Cline Pass provider on the harness LLM seam, expose its
+ * management tools, and publish its setup panel.
+ *
+ * @param ctx - host plugin context.
+ * @param config - validated plugin configuration.
+ */
+export function apply(ctx, config) {
+  const store = createStore({ historyLimit: config.historyLimit })
+  let liveConfig = config
+  let current = () => liveConfig
+  const live = () => current()
+
+  // ── account pool ──────────────────────────────────────────────────────────
+
+  let roundRobin = 0
+
+  /**
+   * Resolve the configured accounts.
+   *
+   * An empty `accounts` dictionary means one implicit account on the top-level
+   * fields, so a fresh install works as soon as `CLINE_PASS_API_KEY` exists.
+   */
+  const accountProfiles = () => {
+    const cfg = live()
+    const declared = Object.entries(cfg.accounts ?? {})
+    if (declared.length === 0) {
+      return [['default', {
+        displayName: cfg.displayName,
+        apiKeyEnv: credentialRef(cfg.apiKeyEnv),
+        enabled: true,
+        baseURL: cfg.baseURL,
+      }]]
+    }
+    return declared.map(([key, profile]) => [key, {
+      displayName: String(profile?.displayName ?? '') || key,
+      apiKeyEnv: credentialRef(profile?.apiKeyEnv || cfg.apiKeyEnv),
+      enabled: profile?.enabled !== false,
+      baseURL: String(profile?.baseURL ?? '') || cfg.baseURL,
+    }])
+  }
+
+  /**
+   * Resolve one credential reference through the credential seam, falling back
+   * to the launching environment when no credentials service is composed.
+   * @returns the key value, or undefined when nothing is stored.
+   */
+  const resolveKey = async (ref) => {
+    const credentials = ctx.get('credentials')
+    if (credentials !== undefined) {
+      const hit = await credentials.resolve(ref)
+      const value = hit?.value
+      return value !== undefined && String(value).length > 0 ? String(value) : undefined
+    }
+    const ambient = launchEnvironmentOf(ctx).get(ref)
+    return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined
+  }
+
+  /** Pick the account for the next request and resolve its key. */
+  const resolveAccount = async () => {
+    const cfg = live()
+    const enabled = accountProfiles().filter(([, profile]) => profile.enabled)
+    if (enabled.length === 0) {
+      throw new LlmError('cline-pass: every configured account is disabled; enable one or add another', 'MISSING_CREDENTIAL')
+    }
+    let picked
+    if (cfg.accountMode === 'roundrobin' && enabled.length > 1) {
+      picked = enabled[roundRobin % enabled.length]
+      roundRobin = (roundRobin + 1) % 1000000000
+    } else {
+      picked = enabled.find(([key]) => key === cfg.activeAccount) ?? enabled[0]
+    }
+    const [key, profile] = picked
+    const value = await resolveKey(profile.apiKeyEnv)
+    if (value === undefined) {
+      throw new LlmError(
+        `cline-pass: no API key for account "${key}"; store it at ${profile.apiKeyEnv} (cline_pass_accounts action="add" name=${key} key=… writes it, or use the dsh Models page), or export ${profile.apiKeyEnv} in the launching environment`,
+        'MISSING_CREDENTIAL',
+      )
+    }
+    return { name: key, key: assertUsableApiKey(value, 'cline-pass', profile.apiKeyEnv), baseURL: profile.baseURL }
+  }
+
+  // ── connection facts ──────────────────────────────────────────────────────
+
+  /** The model ids the route advertises: configured, plus the catalog when asked. */
+  const modelIds = () => {
+    const cfg = live()
+    const ids = (cfg.knownModels ?? []).map(String)
+    if (cfg.exposeCatalog === true) {
+      for (const id of store.catalog().ids ?? []) if (!ids.includes(id)) ids.push(String(id))
+    }
+    return ids
+  }
+
+  const connection = () => {
+    const cfg = live()
+    return {
+      baseURL: cfg.baseURL,
+      displayName: cfg.displayName,
+      models: modelIds().map((id) => {
+        const entry = catalogEntry(id) ?? {}
+        const override = cfg.models?.[id] ?? {}
+        return {
+          id,
+          name: override.name || entry.name || id.replace(/^cline-pass\//, ''),
+          contextWindow: override.contextWindow || entry.contextWindow,
+          maxTokens: override.maxTokens || entry.maxTokens,
+          reasoning: override.reasoning ?? entry.reasoning,
+          input: override.input?.length ? override.input : entry.input,
+        }
+      }),
+      defaultContextWindow: cfg.defaultContextWindow,
+      maxTokens: cfg.defaultMaxTokens,
+      reasoningModels: cfg.reasoningModels,
+      streamIdleTimeoutMs: cfg.streamIdleTimeoutMs,
+    }
+  }
+
+  /**
+   * Best context-window guess for one model: the largest window OpenRouter
+   * reports for its endpoints, when a probe has seen them.
+   */
+  const discoveredContext = (model) => {
+    const detail = store.metaOf(model)?.upstreamDetail ?? {}
+    let max = 0
+    for (const entry of Object.values(detail)) max = Math.max(max, Number(entry?.context ?? 0))
+    return max > 0 ? max : undefined
+  }
+
+  // ── engine + adapter ──────────────────────────────────────────────────────
+
+  const engine = createEngine({
+    resolveAccount,
+    store,
+    logger: ctx.logger,
+    attemptTimeoutMs: 180000,
+    probeTimeoutMs: 60000,
+  })
+  engine.setPinReader((model) => live().perModel?.[model] ?? {})
+
+  const adapter = new ClinePassAdapter({
+    connection,
+    modelMeta: (model) => store.metaOf(model),
+    pin: (model) => live().perModel?.[model] ?? {},
+    resolveAccount,
+    discoveredContext,
+    // Images reach an adapter as durable attachment references, never as bytes,
+    // so the adapter resolves them through the attachment service per request.
+    // Resolved lazily: a text-only call must not require that service.
+    resolveAttachments: () => ctx.get('attachments'),
+    record: (model, info) => store.record({ model, ...info }),
+    learnUpstream: (model, upstream, status, note, ms) => store.learnUpstream(model, upstream, status, note, ms),
+  })
+
+  const provider = String(config.provider ?? '').trim() || DEFAULT_PROVIDER
+  if (config.provider !== provider) {
+    throw new LlmError('cline-pass: `provider` must be a non-empty route name', 'INVALID_ADAPTER')
+  }
+  ctx.llm.registerAdapter([provider], adapter)
+
+  // The directory entry is what makes the web Models page treat this settings
+  // namespace as the configuration of this route; a conflict here is cosmetic
+  // and must not take the route down with it.
+  try {
+    ctx.llm.registerConfigurableProviders([{
+      provider,
+      displayName: config.displayName,
+      settingsNs: DEFAULT_SETTINGS_NS,
+      settingsPath: [],
+    }])
+  } catch (error) {
+    ctx.logger?.warn('[cline-pass] configurable-provider directory entry refused: %s', errorChain(error))
+  }
+
+  // ── configuration surface ─────────────────────────────────────────────────
+
+  /**
+   * Persist one shallow patch into this plugin's settings section.
+   *
+   * Nested dictionaries (`accounts`, `perModel`) are always written whole by
+   * the caller, so the section's merge semantics never half-apply a change.
+   * Without a settings service the patch is applied in memory, which keeps the
+   * session working but does not survive a restart.
+   */
+  const updateConfig = async (patch) => {
+    const settings = ctx.get('settings')
+    if (settings === undefined) {
+      liveConfig = { ...liveConfig, ...patch }
+      return
+    }
+    await settings.update(DEFAULT_SETTINGS_NS, patch)
+  }
+
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, DEFAULT_SETTINGS_NS, Config, config, {
+      setSource: (source) => {
+        current = source
+      },
+      // Every consumer reads the live config through a thunk, so a settings
+      // change reaches the next request with nothing to re-register.
+      onChange: () => {},
+    })
+  })
+
+  // ── catalog ───────────────────────────────────────────────────────────────
+
+  /** Rescan the official subscription list and adopt models that are new. */
+  const refreshCatalog = async () => {
+    const scan = await engine.officialModels({})
+    const cfg = live()
+    const currentModels = (cfg.knownModels ?? []).map(String)
+    const added = scan.models.filter((id) => !currentModels.includes(id))
+    if (added.length > 0) await updateConfig({ knownModels: [...currentModels, ...added] })
+    store.setCatalog({
+      ids: [...new Set([...scan.models, ...(cfg.exposeCatalog === true ? await engine.gatewayCatalog({}).catch(() => []) : [])])],
+      sources: scan.sources,
+    })
+    return { added, models: scan.models, sources: scan.sources }
+  }
+
+  // ── tools ─────────────────────────────────────────────────────────────────
+
+  // One control surface serves both faces of the configuration: the
+  // `cline_pass_*` tools an agent calls, and the browser setup panel. Sharing
+  // it is what keeps the two from ever disagreeing about what is configured.
+  const control = {
+    providerName: provider,
+    displayName: config.displayName,
+    settingsAvailable: () => ctx.get('settings') !== undefined,
+    routeRegistered: () => true,
+    readConfig: () => live(),
+    updateConfig,
+    accounts: () => accountProfiles().map(([key, profile]) => ({
+      key,
+      displayName: profile.displayName,
+      apiKeyEnv: String(profile.apiKeyEnv),
+      enabled: profile.enabled,
+      baseURL: profile.baseURL,
+    })),
+    accountsWithKeys: async () => await Promise.all(accountProfiles().map(async ([key, profile]) => {
+      const value = await resolveKey(profile.apiKeyEnv).catch(() => undefined)
+      return {
+        key,
+        displayName: profile.displayName,
+        apiKeyEnv: String(profile.apiKeyEnv),
+        enabled: profile.enabled,
+        keyConfigured: value !== undefined,
+        keyHint: maskKey(value),
+      }
+    })),
+    readCredential: async (ref) => (await resolveKey(credentialRef(ref))) ?? '',
+    setCredential: async (ref, value) => {
+      const credentials = ctx.get('credentials')
+      if (credentials === undefined) {
+        throw new Error('the dsh credentials service is unavailable, so the key cannot be stored; set the environment variable instead')
+      }
+      await credentials.set(credentialRef(ref), String(value))
+    },
+    refreshCatalog,
+  }
+
+  registerTools(ctx, { store, engine, control })
+
+  // The same surface as an ordinary browser page, for users who would rather
+  // click than compose a tool call. Absent in a headless composition.
+  try {
+    registerPanel(ctx, { control, engine, store, logger: ctx.logger })
+  } catch (error) {
+    ctx.logger?.warn('[cline-pass] setup panel unavailable (the tools still work): %s', errorChain(error))
+  }
+
+  // Keep the provider directory honest without adopting anything: an explicit
+  // `cline_pass_models refresh` is what changes the model list.
+  void refreshCatalog().catch((error) => {
+    ctx.logger?.warn('[cline-pass] initial catalog scan failed (models stay on the configured list): %s', errorChain(error))
+  })
+
+  ctx.logger?.info('[cline-pass] provider route "%s" registered with %d model(s)', provider, modelIds().length)
+}