dsh-plugin-effort-declare 0.1.0

package/src/core/catalog.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical thinking levels and openai-completions thinkingFormat names.
+ *
+ * Levels match `@deepseek-ai/dsh-llm-pi-ai` catalog.ts `THINKING_LEVELS`.
+ * Formats match `SUPPORTED_THINKING_FORMATS` in the same file (rc.8).
+ * Runtime UI prefers the live settings schema union; these lists are the
+ * fallback plus a test pin so a silent drift is a failing test, not a
+ * second hand-maintained copy nobody notices.
+ */
+
+/** Selectable reasoning levels, in pi-ai escalation order. */
+export const THINKING_LEVELS = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+] as const
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number]
+
+/** Thinking levels other than Off; Off has its own tri-state control. */
+export const THINKING_LEVELS_WITHOUT_OFF = THINKING_LEVELS.filter(
+  (level): level is Exclude<ThinkingLevel, 'off'> => level !== 'off',
+)
+
+/**
+ * openai-completions thinkingFormat values from llm-pi-ai catalog.ts rc.8.
+ * Tests pin this list; the settings page prefers schema union choices.
+ */
+export const FALLBACK_THINKING_FORMATS = [
+  'openai',
+  'deepseek',
+  'openrouter',
+  'together',
+  'zai',
+  'qwen',
+  'chat-template',
+  'qwen-chat-template',
+  'string-thinking',
+  'ant-ling',
+] as const
+
+export type ThinkingFormat = (typeof FALLBACK_THINKING_FORMATS)[number]
+
+/** Wire protocol this plugin's v1 editor supports. */
+export const OPENAI_COMPLETIONS = 'openai-completions'
+
+/** Settings namespace this plugin writes. */
+export const LLM_PI_AI_NS = 'llm-pi-ai'
+
+/** Official DeepSeek adapter namespace — skip. */
+export const LLM_DEEPSEEK_NS = 'llm-deepseek'
+
+/** Official DeepSeek provider route — skip. */
+export const DEEPSEEK_OFFICIAL = 'deepseek-official'
+
+/** Any route key walks a dict schema to the same profile node. */
+export const SCHEMA_PROBE_ROUTE = '\u0000probe'

package/src/core/drafts.ts

@@ -0,0 +1,137 @@
+/**
+ * Route-card draft merge: user-layer slices, namespace revision, dirty preserve.
+ * No React — settings UI and tests share these helpers.
+ */
+import { profileAt } from './filter.ts'
+import { buildSaveOps } from './path-ops.ts'
+import { cloneModels, cloneObject, isPlainObject } from './paths.ts'
+
+/** Editable llm-pi-ai route as the settings section holds it. */
+export interface RouteDraft {
+  provider: string
+  displayName: string
+  /** Path inside the llm-pi-ai section (`llm.providers[].settingsPath`). */
+  settingsPath: readonly string[]
+  /** Namespace revision (one value for the whole llm-pi-ai document). */
+  revision: number
+  models: Record<string, unknown>[]
+  originalModels: Record<string, unknown>[]
+  compat: Record<string, unknown>
+  originalCompat: Record<string, unknown>
+  /** Whether `compat` is present on the user profile (not the effective view). */
+  compatPresent: boolean
+}
+
+/** Build a draft from the stored user subtree (never from effective `value`). */
+export function routeDraftFromUserProfile(args: {
+  provider: string
+  displayName: string
+  settingsPath: readonly string[]
+  revision: number
+  userProfile: unknown
+}): RouteDraft {
+  const { provider, displayName, settingsPath, revision, userProfile } = args
+  const models = cloneModels(isPlainObject(userProfile) ? userProfile.models : [])
+  const compatPresent = isPlainObject(userProfile) && 'compat' in userProfile && isPlainObject(userProfile.compat)
+  const compat = cloneObject(isPlainObject(userProfile) ? userProfile.compat : {})
+  return {
+    provider,
+    displayName,
+    settingsPath: [...settingsPath],
+    revision,
+    models,
+    originalModels: cloneModels(models),
+    compat,
+    originalCompat: cloneObject(compat),
+    compatPresent,
+  }
+}
+
+/** Dirty iff pathOps would emit something (same comparison as save). */
+export function draftDirty(draft: RouteDraft): boolean {
+  return buildSaveOps({
+    settingsPath: draft.settingsPath,
+    beforeModels: draft.originalModels,
+    afterModels: draft.models,
+    beforeCompat: draft.compatPresent ? draft.originalCompat : undefined,
+    afterCompat: draft.compat,
+  }).length > 0
+}
+
+/** Treat the current models/compat as the committed originals (no-op save). */
+export function alignDraft(draft: RouteDraft): RouteDraft {
+  return {
+    ...draft,
+    originalModels: cloneModels(draft.models),
+    originalCompat: cloneObject(draft.compat),
+    compatPresent: Object.keys(draft.compat).length > 0 ? true : draft.compatPresent,
+  }
+}
+
+/** Fold a successful mutate view: saved card realigns; every card gets the new revision. */
+export function applySaveSuccess(
+  drafts: readonly RouteDraft[],
+  savedProvider: string,
+  slice: { user: unknown; revision: number },
+): RouteDraft[] {
+  return drafts.map((draft) => {
+    if (draft.provider !== savedProvider) {
+      return { ...draft, revision: slice.revision }
+    }
+    const userProfile = profileAt(slice.user, draft.settingsPath, draft.provider)
+    return routeDraftFromUserProfile({
+      provider: draft.provider,
+      displayName: draft.displayName,
+      settingsPath: draft.settingsPath,
+      revision: slice.revision,
+      userProfile,
+    })
+  })
+}
+
+/**
+ * Apply a freshly loaded table. Dirty cards keep models/compat; originals and
+ * revision follow the incoming snapshot so a later save is against the new user layer.
+ */
+export function mergeLoadedDrafts(
+  current: readonly RouteDraft[],
+  incoming: readonly RouteDraft[],
+  options: { preserveDirty: boolean },
+): { drafts: RouteDraft[]; conflicted: string[] } {
+  const currentByProvider = new Map(current.map(draft => [draft.provider, draft]))
+  const conflicted: string[] = []
+  const drafts = incoming.map((next) => {
+    const prev = currentByProvider.get(next.provider)
+    if (prev === undefined || !options.preserveDirty || !draftDirty(prev)) return next
+    conflicted.push(next.provider)
+    return {
+      ...prev,
+      displayName: next.displayName,
+      settingsPath: next.settingsPath,
+      revision: next.revision,
+      originalModels: cloneModels(next.originalModels),
+      originalCompat: cloneObject(next.originalCompat),
+      compatPresent: next.compatPresent,
+    }
+  })
+  return { drafts, conflicted }
+}
+
+/** Increment a generation counter; callers discard stale async settlements. */
+export function nextGeneration(holder: { current: number }): number {
+  holder.current += 1
+  return holder.current
+}
+
+/** Whether `generation` is still the latest issued token. */
+export function generationIsCurrent(holder: { current: number }, generation: number): boolean {
+  return holder.current === generation
+}
+
+/** Keep a stored thinkingFormat visible even if the schema union omitted it. */
+export function thinkingFormatChoices(formats: readonly string[], current: unknown): string[] {
+  if (typeof current === 'string' && current.length > 0 && !formats.includes(current)) {
+    return [current, ...formats]
+  }
+  return [...formats]
+}

package/src/core/efforts.ts

@@ -0,0 +1,119 @@
+import { THINKING_LEVELS, type ThinkingLevel } from './catalog.ts'
+
+/** Per-model reasoningEfforts dict as stored in llm-pi-ai settings. */
+export type ReasoningEfforts = Partial<Record<ThinkingLevel, string | null>>
+
+/** Off tri-state. Must not be collapsed into a single checkbox. */
+export type OffMode = 'absent' | 'empty' | 'value'
+
+export type ReasoningEffortsField = ReasoningEfforts | false | undefined
+
+/** Read Off's three states from a stored dict. */
+export function readOff(efforts: ReasoningEfforts | undefined): { mode: OffMode; value: string } {
+  if (efforts === undefined || !('off' in efforts) || efforts.off === undefined) {
+    return { mode: 'absent', value: 'none' }
+  }
+  if (efforts.off === null) return { mode: 'empty', value: 'none' }
+  return { mode: 'value', value: efforts.off }
+}
+
+/** Write Off's three states onto a dict (does not mutate the input). */
+export function writeOff(
+  efforts: ReasoningEfforts,
+  mode: OffMode,
+  value: string,
+): ReasoningEfforts {
+  const next: ReasoningEfforts = { ...efforts }
+  delete next.off
+  if (mode === 'empty') next.off = null
+  else if (mode === 'value') next.off = value.trim().length > 0 ? value : 'none'
+  return next
+}
+
+/** Whether a thinking level (other than Off) is currently declared. */
+export function hasLevel(efforts: ReasoningEfforts | undefined, level: Exclude<ThinkingLevel, 'off'>): boolean {
+  return efforts !== undefined && efforts[level] !== undefined && efforts[level] !== null
+}
+
+/** Toggle a non-off level. New levels default the wire spelling to the key. */
+export function toggleLevel(
+  efforts: ReasoningEfforts,
+  level: Exclude<ThinkingLevel, 'off'>,
+  enabled: boolean,
+  wire?: string,
+): ReasoningEfforts {
+  const next: ReasoningEfforts = { ...efforts }
+  if (enabled) next[level] = wire !== undefined && wire.length > 0 ? wire : level
+  else delete next[level]
+  return next
+}
+
+/** Set the wire spelling for a declared non-off level. */
+export function setWireSpelling(
+  efforts: ReasoningEfforts,
+  level: Exclude<ThinkingLevel, 'off'>,
+  wire: string,
+): ReasoningEfforts {
+  if (!hasLevel(efforts, level)) return efforts
+  return { ...efforts, [level]: wire }
+}
+
+/**
+ * Validate a reasoningEfforts field. Returns an error code; never throws.
+ * Absence / `false` are valid (default-off / catalog strip). Empty dict and
+ * off-only are rejected by the official resolver.
+ */
+export function validateReasoningEfforts(efforts: unknown): 'empty' | 'off-only' | 'bad-wire' | undefined {
+  if (efforts === undefined || efforts === false) return undefined
+  if (efforts === null || (typeof efforts === 'object' && !Array.isArray(efforts) && Object.keys(efforts).length === 0)) {
+    return 'empty'
+  }
+  if (typeof efforts !== 'object' || Array.isArray(efforts)) return 'empty'
+  const record = efforts as Record<string, unknown>
+  const known = new Set<string>(THINKING_LEVELS)
+  for (const key of Object.keys(record)) {
+    if (!known.has(key)) return 'bad-wire'
+  }
+  const declared = THINKING_LEVELS.flatMap((level) => {
+    if (!(level in record) || record[level] === undefined) return []
+    return [[level, record[level]] as const]
+  })
+  for (const [level, wire] of declared) {
+    if (wire === null) {
+      if (level !== 'off') return 'bad-wire'
+    } else if (typeof wire !== 'string' || wire.length === 0) {
+      return 'bad-wire'
+    }
+  }
+  if (!declared.some(([level]) => level !== 'off')) return 'off-only'
+  return undefined
+}
+
+/** Drop reasoningEfforts from a model row; keep every other field. */
+export function clearReasoningEfforts(row: Record<string, unknown>): Record<string, unknown> {
+  const next = { ...row }
+  delete next.reasoningEfforts
+  return next
+}
+
+/** Read reasoningEfforts from a model row. `false` is treated as absent for the editor. */
+export function readEfforts(row: Record<string, unknown>): ReasoningEfforts | undefined {
+  const value = row.reasoningEfforts
+  if (value === undefined || value === false || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) return undefined
+  return value as ReasoningEfforts
+}
+
+/** Put a dict (or omit the field) onto a spread row. */
+export function writeEfforts(
+  row: Record<string, unknown>,
+  efforts: ReasoningEfforts | undefined,
+): Record<string, unknown> {
+  const next = { ...row }
+  if (efforts === undefined || Object.keys(efforts).length === 0) {
+    delete next.reasoningEfforts
+    return next
+  }
+  next.reasoningEfforts = efforts
+  return next
+}

package/src/core/filter.ts

@@ -0,0 +1,82 @@
+import {
+  DEEPSEEK_OFFICIAL,
+  LLM_DEEPSEEK_NS,
+  LLM_PI_AI_NS,
+  OPENAI_COMPLETIONS,
+} from './catalog.ts'
+import { getPath, isPlainObject } from './paths.ts'
+
+/** Directory row from `llm.providers()` (the fields v1 filtering reads). */
+export interface ProviderDirectoryEntry {
+  provider: string
+  displayName?: string
+  settingsNs?: string
+  settingsPath?: readonly string[]
+  declared?: boolean
+  active?: boolean
+}
+
+/**
+ * Resolve the wire protocol for a route.
+ * User/effective `api` wins; then schema default; then openai-completions.
+ */
+export function resolveRouteApi(
+  profile: unknown,
+  schemaDefault: string | undefined,
+): string {
+  if (isPlainObject(profile) && typeof profile.api === 'string' && profile.api.length > 0) {
+    return profile.api
+  }
+  if (schemaDefault !== undefined && schemaDefault.length > 0) return schemaDefault
+  return OPENAI_COMPLETIONS
+}
+
+export interface EditableDecision {
+  editable: boolean
+  reason?: 'not-pi-ai' | 'official-deepseek' | 'catalog' | 'not-completions'
+}
+
+/**
+ * v1 editable routes: hand-declared llm-pi-ai openai-completions.
+ * Catalog routes are excluded (writing `models` replaces the whole catalog).
+ */
+export function classifyRoute(
+  entry: ProviderDirectoryEntry,
+  profile: unknown,
+  schemaDefaultApi?: string,
+): EditableDecision {
+  if (entry.provider === DEEPSEEK_OFFICIAL || entry.settingsNs === LLM_DEEPSEEK_NS) {
+    return { editable: false, reason: 'official-deepseek' }
+  }
+  if (entry.settingsNs !== LLM_PI_AI_NS) {
+    return { editable: false, reason: 'not-pi-ai' }
+  }
+  if (entry.declared !== true) {
+    return { editable: false, reason: 'catalog' }
+  }
+  const api = resolveRouteApi(profile, schemaDefaultApi)
+  if (api !== OPENAI_COMPLETIONS) {
+    return { editable: false, reason: 'not-completions' }
+  }
+  return { editable: true }
+}
+
+/** Profile object at `providers.<route>` from an llm-pi-ai section value. */
+export function profileAt(
+  section: unknown,
+  settingsPath: readonly string[] | undefined,
+  provider: string,
+): unknown {
+  const path = settingsPath !== undefined && settingsPath.length > 0
+    ? settingsPath
+    : ['providers', provider]
+  return getPath(section, path)
+}
+
+/** String choices from a schemastery union node (`type: 'union'`). */
+export function unionStringChoices(node: unknown): string[] {
+  if (!isPlainObject(node) || node.type !== 'union' || !Array.isArray(node.list)) return []
+  return node.list
+    .map((entry) => (isPlainObject(entry) ? entry.value : undefined))
+    .filter((value): value is string => typeof value === 'string')
+}

package/src/core/path-ops.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal path ops, same one-level-key algorithm as the official
+ * ProviderEditor.pathOps: only keys that differ produce a set/unset.
+ */
+
+export type PathOp =
+  | { op: 'set'; path: string[]; value: unknown }
+  | { op: 'unset'; path: string[] }
+
+/**
+ * The minimal path ops carrying `after` over `before`.
+ * @param base - path of the edited subtree.
+ * @param before - subtree as loaded, or undefined when new.
+ * @param after - subtree as edited.
+ */
+export function pathOps(
+  base: readonly string[],
+  before: unknown,
+  after: Record<string, unknown>,
+): PathOp[] {
+  const previous = typeof before === 'object' && before !== null && !Array.isArray(before)
+    ? before as Record<string, unknown>
+    : {}
+  const ops: PathOp[] = []
+  for (const [key, value] of Object.entries(after)) {
+    if (JSON.stringify(previous[key]) === JSON.stringify(value)) continue
+    ops.push({ op: 'set', path: [...base, key], value })
+  }
+  for (const key of Object.keys(previous)) {
+    if (!(key in after)) ops.push({ op: 'unset', path: [...base, key] })
+  }
+  return ops
+}
+
+export interface SaveSlices {
+  /** Profile path from `llm.providers[].settingsPath` (not a hardcoded route id). */
+  settingsPath: readonly string[]
+  /** Models array before the edit (user layer). */
+  beforeModels: unknown
+  /** Models array after the edit — every existing row, spread intact. */
+  afterModels: unknown[]
+  /** Route-level compat before the edit (`undefined` = field absent on user). */
+  beforeCompat: unknown
+  /**
+   * Route-level compat after the edit. `undefined` means leave the field
+   * untouched (no compat ops at all).
+   */
+  afterCompat: Record<string, unknown> | undefined
+}
+
+/**
+ * Ops for one route: whole-array `models` replace when the table changed,
+ * plus one-level compat path ops. Never replace the `llm-pi-ai` section.
+ */
+export function buildSaveOps(slices: SaveSlices): PathOp[] {
+  const base = [...slices.settingsPath]
+  const ops: PathOp[] = []
+  if (JSON.stringify(slices.beforeModels) !== JSON.stringify(slices.afterModels)) {
+    ops.push({ op: 'set', path: [...base, 'models'], value: slices.afterModels })
+  }
+  if (slices.afterCompat !== undefined) {
+    ops.push(...pathOps([...base, 'compat'], slices.beforeCompat, slices.afterCompat))
+  }
+  return ops
+}

package/src/core/paths.ts

@@ -0,0 +1,45 @@
+/**
+ * Nested get/has over plain JSON, matching ui-settings SettingsSchemaService
+ * for the paths this plugin needs. Kept in-repo so tests do not import a
+ * Cordis service.
+ */
+
+/** Read a nested value by string keys / array indexes. */
+export function getPath(value: unknown, path: readonly string[]): unknown {
+  let current: unknown = value
+  for (const key of path) {
+    if (Array.isArray(current)) {
+      current = current[Number(key)]
+      continue
+    }
+    if (typeof current !== 'object' || current === null) return undefined
+    current = (current as Record<string, unknown>)[key]
+  }
+  return current
+}
+
+/** Whether the final path key exists, independently of its value. */
+export function hasPath(value: unknown, path: readonly string[]): boolean {
+  if (path.length === 0) return value !== undefined
+  const parent = getPath(value, path.slice(0, -1))
+  const key = path[path.length - 1] as string
+  if (Array.isArray(parent)) return Number(key) < parent.length
+  if (typeof parent !== 'object' || parent === null) return false
+  return key in parent
+}
+
+/** Plain object (not array, not null). */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Structured clone of a JSON object, or `{}` when the source is not one. */
+export function cloneObject(value: unknown): Record<string, unknown> {
+  return isPlainObject(value) ? structuredClone(value) : {}
+}
+
+/** Structured clone of a models array; non-arrays and non-object rows are skipped. */
+export function cloneModels(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((row) => (isPlainObject(row) ? [structuredClone(row)] : []))
+}

package/src/core/presets.ts

@@ -0,0 +1,104 @@
+import type { ReasoningEfforts } from './efforts.ts'
+
+export type PresetId = 'deepseek' | 'openai' | 'toggle'
+
+export interface PresetCompatPatch {
+  /**
+   * Every preset states all three UI dialect keys. `set` writes the key;
+   * `unset` removes it. Unknown extra compat keys are left in place.
+   */
+  thinkingFormat: 'set' | 'unset'
+  thinkingFormatValue?: string
+  supportsDeveloperRole: 'set-false' | 'unset'
+  supportsReasoningEffort: 'set-false' | 'unset'
+}
+
+export interface EffortPreset {
+  id: PresetId
+  efforts: ReasoningEfforts
+  compat: PresetCompatPatch
+  /** True when selector levels do not change the on-wire request (except Off). */
+  warnSameWire: boolean
+}
+
+/** DeepSeek-compatible gateway: explicit thinking.disabled on Off. */
+export const DEEPSEEK_PRESET: EffortPreset = {
+  id: 'deepseek',
+  efforts: {
+    off: null,
+    low: 'low',
+    high: 'high',
+    max: 'max',
+  },
+  compat: {
+    thinkingFormat: 'set',
+    thinkingFormatValue: 'deepseek',
+    supportsDeveloperRole: 'set-false',
+    supportsReasoningEffort: 'unset',
+  },
+  warnSameWire: false,
+}
+
+/** OpenAI-compatible gateway: default thinkingFormat (omit the key). */
+export const OPENAI_PRESET: EffortPreset = {
+  id: 'openai',
+  efforts: {
+    minimal: 'minimal',
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+  },
+  compat: {
+    thinkingFormat: 'unset',
+    supportsDeveloperRole: 'unset',
+    supportsReasoningEffort: 'unset',
+  },
+  warnSameWire: false,
+}
+
+/** On/off only: selector may list levels that are identical on the wire. */
+export const TOGGLE_PRESET: EffortPreset = {
+  id: 'toggle',
+  efforts: {
+    off: null,
+    high: 'high',
+  },
+  compat: {
+    thinkingFormat: 'unset',
+    supportsDeveloperRole: 'unset',
+    supportsReasoningEffort: 'set-false',
+  },
+  warnSameWire: true,
+}
+
+export const PRESETS: Record<PresetId, EffortPreset> = {
+  deepseek: DEEPSEEK_PRESET,
+  openai: OPENAI_PRESET,
+  toggle: TOGGLE_PRESET,
+}
+
+/** Apply a preset's efforts onto every model row (spread, keep other fields). */
+export function applyPresetEfforts(
+  models: readonly Record<string, unknown>[],
+  preset: EffortPreset,
+): Record<string, unknown>[] {
+  return models.map(row => ({ ...row, reasoningEfforts: { ...preset.efforts } }))
+}
+
+/** Merge a preset's compat patch onto the current route-level compat object. */
+export function applyPresetCompat(
+  compat: Record<string, unknown>,
+  preset: EffortPreset,
+): Record<string, unknown> {
+  const next = { ...compat }
+  const { compat: patch } = preset
+  if (patch.thinkingFormat === 'unset') delete next.thinkingFormat
+  else if (patch.thinkingFormat === 'set' && patch.thinkingFormatValue !== undefined) {
+    next.thinkingFormat = patch.thinkingFormatValue
+  }
+  if (patch.supportsDeveloperRole === 'unset') delete next.supportsDeveloperRole
+  else if (patch.supportsDeveloperRole === 'set-false') next.supportsDeveloperRole = false
+  if (patch.supportsReasoningEffort === 'unset') delete next.supportsReasoningEffort
+  else if (patch.supportsReasoningEffort === 'set-false') next.supportsReasoningEffort = false
+  return next
+}

package/src/core/validate.ts

@@ -0,0 +1,7 @@
+import { validateReasoningEfforts } from './efforts.ts'
+
+/** Per-model client-side check used to show errors without throwing. */
+export function modelEffortError(row: Record<string, unknown>): 'empty' | 'off-only' | 'bad-wire' | undefined {
+  if (!('reasoningEfforts' in row) || row.reasoningEfforts === undefined) return undefined
+  return validateReasoningEfforts(row.reasoningEfforts)
+}

package/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export const cssText: string
+  export const cssTagId: string
+  export default classes
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * dsh-plugin-effort-declare — host half.
+ * v1 contributes no host services, adapters, or events. The cordis row still
+ * has to exist so a later `dsh plugin add` can load the bundle.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'dsh-plugin-effort-declare'
+
+/** Host apply is intentionally empty in v1. */
+export function apply(_ctx: Context): void {}