@wxip/dsh-sub2api 0.2.2

package/src/index.ts

@@ -0,0 +1,339 @@
+/**
+ * Sub2API gateway integration for the harness LLM seam.
+ *
+ * One OpenAI-compatible base URL, many provider routes. In the sub2api
+ * gateway each API key is bound to a group, and the group decides the
+ * platform (openai / anthropic / grok) and the model list the key
+ * can serve.
+ *
+ * The LLM routes this plugin used to own (`sub2api-openai` / `sub2api-claude`
+ * / `sub2api-grok`) are served by the harness's own pi-ai
+ * adapter (`dsh-llm-pi-ai`, mounted dormant by dsh-base): protocol
+ * serialization, streaming, usage mapping, replay, and retry handling all live
+ * in pi-ai, which speaks each platform's native wire protocol upstream (OpenAI
+ * → Responses API, Claude → Messages API, the rest → chat/completions).
+ * This plugin contributes the sub2api-specific surface on top: the
+ * `llm-sub2api:` settings section and its web page (baseURL + per-key model
+ * catalogs + keys), gateway model discovery and usage probes, the global
+ * image-generation tools, and a bridge
+ * that materializes the configured groups as `llm-pi-ai:` provider profiles
+ * the moment the section lands (see `./pi-ai.ts`).
+ *
+ * Keys are stored through the harness credential seam; the base URL and
+ * per-key model catalogs live in the `llm-sub2api:` settings section
+ * (the active profile `cordis.patch.yml`, written by the web settings page).
+ *
+ * @module dsh-sub2api
+ */
+
+import type { Context, Volatile } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-llm'
+import {
+  LlmError,
+  assertUsableApiKey,
+} from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import type {} from '@deepseek-ai/dsh-settings'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
+import { registerRoutes } from './routes.ts'
+import { registerImageTools } from './image-tools.ts'
+import { syncPiAiProfiles } from './pi-ai.ts'
+import { applyPiAiMultiTurnPatch } from './pi-ai-patch.ts'
+
+export {
+  PI_AI_NS,
+  ROUTE_PREFIX,
+  syncPiAiProfiles,
+  translateToPiAi,
+  type PiAiModelProfile,
+  type PiAiProviderProfile,
+  type PiAiSettingsSection,
+} from './pi-ai.ts'
+export { applyPiAiMultiTurnPatch, type PiAiPatchResult } from './pi-ai-patch.ts'
+
+export const name = 'llm-sub2api'
+export const inject: string[] = ['llm', 'settings', 'credentials']
+
+const NS = 'llm-sub2api'
+
+/** Context capacity assumed for a model neither configuration nor discovery sizes. */
+export const DEFAULT_CONTEXT_WINDOW = 128000
+/** Output capability assumed for a model neither configuration nor discovery sizes. */
+export const DEFAULT_MAX_TOKENS = 8192
+
+/**
+ * Reasoning effort levels exposed for reasoning-capable models. The gateway
+ * speaks the OpenAI chat-completions protocol, so the ids are the OpenAI
+ * `reasoning_effort` vocabulary and are sent through verbatim. Per-model
+ * configuration (filled from models.dev `reasoning_options`) may expose
+ * additional vocabulary such as `none`, `xhigh`, or `max`.
+ */
+export const REASONING_EFFORTS: readonly { id: string; name: string }[] = [
+  { id: 'low', name: 'Low' },
+  { id: 'medium', name: 'Medium' },
+  { id: 'high', name: 'High' },
+]
+
+export type ProviderKey = 'openai' | 'claude' | 'grok'
+
+export interface ProviderDef {
+  key: ProviderKey
+  route: string
+  label: string
+  icon: string
+}
+
+/** The provider routes this plugin owns, keyed by sub2api platform name. */
+export const PROVIDERS: readonly ProviderDef[] = [
+  { key: 'openai', route: 'sub2api-openai', label: 'OpenAI', icon: 'openai' },
+  { key: 'claude', route: 'sub2api-claude', label: 'Claude', icon: 'claude' },
+  { key: 'grok', route: 'sub2api-grok', label: 'Grok', icon: 'grok' },
+]
+
+export interface CatalogModel {
+  /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
+  id: string
+  /** Display name for selectors; defaults to the id. */
+  name?: string
+  /** Maximum combined request and response context in tokens. */
+  contextWindow?: number
+  /** Maximum output tokens. */
+  maxTokens?: number
+  /**
+   * Accepted request modalities. Absent or empty: the adapter guesses from
+   * the model id (multimodal families such as gpt/claude/gemini/grok/glm
+   * declare `[text, image]`, everything else stays `[text]`). Non-empty:
+   * exactly those modalities, e.g. `[text]` to pin a multimodal-looking
+   * model to text only.
+   */
+  input?: Array<'text' | 'image'>
+  /**
+   * Reasoning effort levels selectable for this model. Absent: every non-image
+   * model on any route exposes low/medium/high (the gateway is OpenAI-compatible
+   * on all routes). Empty array: reasoning effort is explicitly off for this
+   * model. Non-empty: exposes exactly those levels verbatim (e.g. models.dev
+   * vocabularies such as `xhigh`/`max`/`none`).
+   */
+  reasoningEfforts?: string[]
+}
+
+export interface ProviderProfile {
+  /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
+  apiKeyEnv?: string
+  /**
+   * Wire protocol spoken to the gateway for this platform group. Absent
+   * selects the group's native protocol (openai → responses, claude →
+   * messages, grok → chat/completions). Explicitly name a protocol to
+   * force a different endpoint, e.g. a gateway that serves a group through
+   * chat/completions after all.
+   */
+  api?: ApiProtocol
+  /** Advisory model catalog for this route. */
+  models?: CatalogModel[]
+}
+
+/** One dedicated model used by a global image tool, independent of the chat route. */
+export interface ImageToolModelRef {
+  /** Sub2API platform that owns the key and catalog (`openai` / `claude` / `grok`). */
+  provider: string
+  /** Model id sent to the gateway. */
+  model: string
+}
+
+export interface ImageToolsConfig {
+  /** Image-generation model used by the global `generate_image` tool. */
+  generate?: ImageToolModelRef
+}
+
+export interface Config {
+  /** OpenAI-compatible gateway base URL, e.g. http://localhost:8080/v1. */
+  baseURL: string
+  /** Per-platform provider profiles keyed by sub2api platform name. */
+  providers: Record<ProviderKey, ProviderProfile>
+  /** Dedicated models for the global image-generation tools. */
+  tools?: ImageToolsConfig
+}
+
+/** Live configuration references owned by the DSH Loader. */
+export interface LiveConfig {
+  baseURL: Volatile<string>
+  providers: Volatile<Record<ProviderKey, ProviderProfile>>
+  tools: Volatile<ImageToolsConfig>
+}
+
+/** Capture one configuration snapshot for a gateway operation. */
+export function readConfig(config: LiveConfig): Config {
+  return {
+    baseURL: config.baseURL.get(),
+    providers: structuredClone(config.providers.get()) as Config['providers'],
+    tools: structuredClone(config.tools.get()),
+  }
+}
+
+const catalogModel = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  contextWindow: z.number().step(1).min(1),
+  maxTokens: z.number().step(1).min(1),
+  // Default to an empty list so the settings normalization never fills a
+  // fabricated value: an empty/absent `input` means "auto" (the adapter
+  // guesses modalities from the model id).
+  input: z.array(z.union([z.const('text'), z.const('image')])).default([]),
+  // The settings layer normalizes every section through this schema, and an
+  // absent optional array would otherwise be filled with an empty array —
+  // silently turning reasoning off for every unconfigured model. Default the
+  // field to the full OpenAI effort vocabulary so a model without explicit
+  // configuration exposes low/medium/high (image models are excluded at
+  // resolve time); an explicit empty array still opts the model out.
+  reasoningEfforts: z.array(z.string()).default(REASONING_EFFORTS.map((effort) => effort.id)),
+})
+
+const apiProtocol = z.union([
+  z.const('openai-completions'),
+  z.const('openai-responses'),
+  z.const('anthropic-messages'),
+])
+
+const providerProfile = z.object({
+  apiKeyEnv: z.string().role('credential-ref'),
+  api: apiProtocol,
+  models: z.array(catalogModel),
+})
+
+// Keep these fields optional strings. The settings layer fills absent
+// objects, and a required union here would reject a still-empty tools
+// section (or silently coerce it) before the user picks a model.
+const imageToolModelRef = z.object({
+  provider: z.string(),
+  model: z.string(),
+})
+
+export const Config: z<Partial<Config>, LiveConfig> = z.object({
+  baseURL: z.string().default('').volatile(),
+  providers: z.object({
+    openai: providerProfile,
+    claude: providerProfile,
+    grok: providerProfile,
+  }).default({}).volatile(),
+  tools: z.object({
+    generate: imageToolModelRef,
+  }).default({}).volatile(),
+})
+
+/**
+ * Wire protocol the adapter speaks to the gateway for one route. Each value
+ * names a real endpoint: `openai-completions` → `/chat/completions`,
+ * `openai-responses` → `/responses`, `anthropic-messages` → `/messages`.
+ */
+export type ApiProtocol = 'openai-completions' | 'openai-responses' | 'anthropic-messages'
+
+export const API_PROTOCOLS: readonly ApiProtocol[] = ['openai-completions', 'openai-responses', 'anthropic-messages']
+
+/**
+ * The wire protocol each sub2api platform group speaks natively at the
+ * gateway. Openai groups are served upstream through the Responses API and
+ * Claude groups through the Messages API; grok groups are
+ * chat-completions. Speaking the native protocol avoids the gateway's
+ * chat/completions ↔ native conversion, which drops/misaligns tool-call
+ * names and ids for parallel calls. A provider profile may override.
+ */
+const DEFAULT_PROTOCOL: Record<ProviderKey, ApiProtocol> = {
+  openai: 'openai-responses',
+  claude: 'anthropic-messages',
+  grok: 'openai-completions',
+}
+
+/** Resolve the wire protocol for one provider key; shared by chat routes and the global image tools. */
+export function apiProtocolForKey(key: ProviderKey, profile: ProviderProfile): ApiProtocol {
+  return profile.api ?? DEFAULT_PROTOCOL[key]
+}
+
+/**
+ * The OpenAI-style API root for a gateway base URL. The Sub2API settings page
+ * stores the bare host (e.g. `https://gateway.example:6443`); OpenAI-compatible
+ * endpoints (`/responses`, `/chat/completions`, `/models`, `/usage`) live under
+ * the `/v1` root, so it is appended here when missing. A URL already carrying
+ * `/v1` passes through unchanged.
+ */
+export function gatewayApiRoot(baseURL: string): string {
+  const cleaned = (baseURL ?? '').trim().replace(/\/+$/, '')
+  if (cleaned.length === 0) return ''
+  return /\/v1$/i.test(cleaned) ? cleaned : `${cleaned}/v1`
+}
+
+/**
+ * The bare-host form the Anthropic SDK expects: `@anthropic-ai/sdk` treats the
+ * configured URL as the host and always appends `/v1/messages` itself, so a
+ * `/v1`-rooted URL would hit `/v1/v1/messages` (404). Strips a trailing `/v1`
+ * when present.
+ */
+export function gatewayAnthropicRoot(baseURL: string): string {
+  return gatewayApiRoot(baseURL).replace(/\/v1$/i, '')
+}
+
+function resolveAdapterOptions(config: Config) {
+  const baseURL = (config.baseURL ?? '').trim().replace(/\/+$/, '')
+  // An empty baseURL means "not configured yet": boot dormant and let the
+  // settings scope (or setConfig) supply the URL later. Only validate the
+  // scheme once a URL is actually present.
+  if (baseURL.length > 0 && !/^https?:\/\//.test(baseURL)) {
+    throw new Error('llm-sub2api: baseURL must start with http(s)://')
+  }
+  return { baseURL }
+}
+
+export function apply(ctx: Context, config: LiveConfig): void {
+  const current = () => readConfig(config)
+  const namespace = ctx.fiber.entry?.options.id ?? NS
+  resolveAdapterOptions(current())
+  ctx.effect(() => ctx.settings.configure({ auto: false }))
+
+  const resolveApiKey = async (route: string, profile: ProviderProfile) => {
+    if (profile.apiKeyEnv === undefined) {
+      throw new LlmError(`sub2api: no API key configured for route "${route}"`, 'MISSING_CREDENTIAL')
+    }
+    const ref = credentialRef(profile.apiKeyEnv)
+    const credentials = ctx.get('credentials')
+    const hit = credentials !== undefined ? await credentials.resolve(ref) : undefined
+    if (hit !== undefined && hit.value.length > 0) {
+      return assertUsableApiKey(hit.value, 'llm-sub2api', ref)
+    }
+    throw new LlmError(
+      `sub2api: no credential for provider route "${route}"; its profile resolves ${profile.apiKeyEnv}, which is not set — store it through the credentials service (the web Models page writes it) or export it`,
+      'MISSING_CREDENTIAL',
+    )
+  }
+
+  const syncPiAi = () => {
+    syncPiAiProfiles(ctx, current()).catch((error) => {
+      ctx.logger.error('llm-sub2api: refused to update llm-pi-ai profiles; keeping the previously registered routes')
+      ctx.logger.error(error)
+    })
+  }
+
+  // Settings-page HTTP bridge: read/write config, discover models, query usage.
+  // `listRegisteredRoutes` reports the routes the pi-ai adapter actually
+  // registered for this plugin's groups.
+  registerRoutes(ctx, {
+    config: () => current(),
+    setConfig: async (next) => {
+      resolveAdapterOptions(next)
+      await ctx.settings.replace(namespace, next)
+      await syncPiAiProfiles(ctx, current())
+    },
+    listRegisteredRoutes: () => ctx.llm.listProviders()
+      .map((info) => info.id)
+      .filter((route) => route.startsWith('sub2api-')),
+    resolveApiKey,
+  })
+
+  registerImageTools(ctx, {
+    config: () => current(),
+    resolveApiKey,
+  })
+
+  syncPiAi()
+  ctx.on('loader/volatile-update', syncPiAi)
+}

package/src/invariant.ts

@@ -0,0 +1,17 @@
+/**
+ * Load-time invariant checks for dsh-sub2api.
+ *
+ * The host half declares `inject: ['llm', 'settings', 'credentials']`; the
+ * loader surfaces a missing provider as a waiting row, so a dedicated
+ * invariant would only duplicate that signal. This module exists to keep the
+ * package's export surface stable (lib/invariant.js) and to host any future
+ * structural checks.
+ *
+ * @module dsh-sub2api/invariant
+ */
+
+export function invariant(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(`dsh-sub2api: ${message}`)
+}
+
+export default invariant

package/src/pi-ai-patch.ts

@@ -0,0 +1,94 @@
+/**
+ * Best-effort defense guard for pi-ai's prefix-token estimation.
+ *
+ * Background: pi-ai's `AssistantMessage.usage` is required in its types and
+ * `estimateContextTokens` dereferences `usage.totalTokens` on that contract.
+ * The harness path is already safe — `dsh-llm-pi-ai` attaches a zero `Usage`
+ * (`emptyPiUsage()`) to every reconstructed assistant message. The guard here
+ * only defends against *other* callers that build pi-ai contexts without
+ * `usage` (hand-rolled clients, future adapters), which would otherwise die
+ * with a bare `Cannot read properties of undefined (reading 'totalTokens')`
+ * deep inside estimation.
+ *
+ * This plugin cannot control the pi-ai version through npm — Node resolves
+ * pi-ai from the dsh install, not from this package. So the guard is applied
+ * as a precise idempotent edit to the bundled `estimate.js`:
+ *
+ * ```js
+ *   assistant.stopReason !== "error" &&
+ *   assistant.usage !== undefined &&
+ *   calculateContextTokens(assistant.usage) > 0
+ * ```
+ *
+ * It runs at plugin apply time — before any pi-ai request (pi-ai's API modules
+ * are lazy-loaded, so `estimate.js` is only imported on the first stream). A
+ * refusal to write (read-only install) only logs a warning; the harness path
+ * works without the guard, and an upstream pi-ai guard makes this a no-op.
+ *
+ * @module dsh-sub2api/pi-ai-patch
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Guard marker; its presence means the patch is already applied. */
+const MARKER = 'assistant.usage !== undefined'
+/** The exact upstream expression this patch guards. */
+const TARGET = 'calculateContextTokens(assistant.usage) > 0'
+
+/** Outcome of one patch attempt. */
+export type PiAiPatchResult =
+  | { kind: 'patched'; file: string }
+  | { kind: 'already'; file: string }
+  | { kind: 'skipped'; reason: string }
+
+/** Candidate locations of the pi-ai estimate module inside a dsh install. */
+function candidateEstimatePaths(): string[] {
+  const roots = new Set<string>()
+  const global = spawnSync('npm', ['root', '-g'], { encoding: 'utf8', windowsHide: true })
+  if (global.status === 0 && global.stdout.trim().length > 0) roots.add(global.stdout.trim())
+  if (process.env.npm_config_prefix !== undefined) {
+    roots.add(join(process.env.npm_config_prefix, 'lib', 'node_modules'))
+  }
+  roots.add(join(homedir(), '.npm-global', 'lib', 'node_modules'))
+  const dshHome = process.env.DSH_HOME !== undefined ? process.env.DSH_HOME : join(homedir(), '.dsh')
+  const paths: string[] = []
+  for (const root of roots) {
+    paths.push(join(root, '@deepseek-ai', 'dsh', 'node_modules', '@earendil-works', 'pi-ai', 'dist', 'utils', 'estimate.js'))
+    paths.push(join(root, '@deepseek-ai', 'dsh', 'node_modules', '@deepseek-ai', 'dsh-llm-pi-ai', 'node_modules', '@earendil-works', 'pi-ai', 'dist', 'utils', 'estimate.js'))
+  }
+  // Profile-local installs (dsh web profile) may carry their own copy.
+  paths.push(join(dshHome, 'profiles', 'web', 'node_modules', '@deepseek-ai', 'dsh-llm-pi-ai', 'node_modules', '@earendil-works', 'pi-ai', 'dist', 'utils', 'estimate.js'))
+  return paths
+}
+
+/**
+ * Apply the multi-turn guard to the dsh-bundled pi-ai `estimate.js` when it is
+ * missing. Idempotent; only a byte-exact edit is ever made.
+ */
+export function applyPiAiMultiTurnPatch(): PiAiPatchResult {
+  const file = candidateEstimatePaths().find((candidate) => existsSync(candidate))
+  if (file === undefined) return { kind: 'skipped', reason: 'pi-ai estimate.js not found under the dsh install' }
+  let source: string
+  try {
+    source = readFileSync(file, 'utf8')
+  } catch (error) {
+    return { kind: 'skipped', reason: `cannot read ${file}: ${String(error)}` }
+  }
+  if (source.includes(MARKER)) return { kind: 'already', file }
+  const index = source.indexOf(TARGET)
+  if (index === -1) return { kind: 'skipped', reason: `target pattern not found in ${file} (pi-ai layout changed?)` }
+  // Preserve the indentation of the line the target sits on.
+  const lineStart = source.lastIndexOf('\n', index) + 1
+  const indent = source.slice(lineStart, index).match(/^[ \t]*/)?.[0] ?? ''
+  const replacement = `${MARKER} &&\n${indent}${TARGET}`
+  const next = source.slice(0, index) + replacement + source.slice(index + TARGET.length)
+  try {
+    writeFileSync(file, next)
+  } catch (error) {
+    return { kind: 'skipped', reason: `cannot write ${file}: ${String(error)}` }
+  }
+  return { kind: 'patched', file }
+}

package/src/pi-ai.ts

@@ -0,0 +1,185 @@
+/**
+ * dsh-sub2api → dsh-llm-pi-ai profile bridge.
+ *
+ * The LLM routes this plugin used to own (`sub2api-openai` / `sub2api-claude`
+ * / `sub2api-grok`) are now served by the harness's pi-ai
+ * adapter (`dsh-llm-pi-ai`, mounted dormant by dsh-base): protocol
+ * serialization, streaming, usage mapping, replay, and retry handling all live
+ * in pi-ai. This module is the translation layer — it turns this plugin's
+ * `llm-sub2api:` settings section (gateway baseURL + per-group model catalogs
+ * + keys) into `llm-pi-ai:` provider profiles and writes them through the
+ * settings service, so routes register the moment the section lands and drop
+ * again when a key is cleared.
+ *
+ * Every sub2api group is translated as a *hand-declared* route — pi-ai ships
+ * no provider under these keys — with `api` naming the group's native wire
+ * protocol (openai→responses, claude→messages, grok→chat-completions),
+ * `baseURL` set to the shared gateway, and `models` carrying the configured
+ * catalog with each model's capacity, modalities, and reasoning levels mapped
+ * onto pi-ai's vocabulary (`none` becomes `off` with wire spelling `none`).
+ *
+ * @module dsh-sub2api/pi-ai
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-settings'
+import type { PiAiModelProfile, PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
+import type { CatalogModel, Config, ProviderKey, ProviderProfile } from './index.ts'
+import {
+  DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_MAX_TOKENS,
+  PROVIDERS,
+  apiProtocolForKey,
+  gatewayAnthropicRoot,
+  gatewayApiRoot,
+} from './index.ts'
+
+/** The settings namespace owned by dsh-llm-pi-ai. */
+export const PI_AI_NS = 'llm-pi-ai'
+
+/** Route prefix this plugin's groups own in the llm-pi-ai profile dict. */
+export const ROUTE_PREFIX: string = 'sub2api-'
+
+/** pi-ai thinking levels a profile may declare (catalog `THINKING_LEVELS`). */
+const THINKING_LEVELS: readonly string[] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+
+// Use the adapter's public contract so schema changes cannot silently drift.
+export type { PiAiModelProfile, PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
+
+/** The llm-pi-ai settings section value this plugin writes. */
+export interface PiAiSettingsSection {
+  providers?: Record<string, PiAiProviderProfile>
+}
+
+/**
+ * Request modalities a catalog model declares to the harness. An explicit
+ * `input` wins; absent/empty falls back to a family guess — frontier
+ * multimodal families accept images, everything else stays text-only (the
+ * official harness posture: a hand-entered model is text-only until it says
+ * otherwise).
+ */
+function catalogInputModalities(model: { id: string; input?: Array<'text' | 'image'> }): Array<'text' | 'image'> {
+  if (model.input !== undefined && model.input.length > 0) return [...model.input]
+  return /^(gpt|o[1-9]|claude|gemini|grok|glm|qwen|kimi|moonshot|minimax|mistral|llama|phi|command|jamba|codex|sora|veo|imagen|dall-e)/i.test(model.id)
+    ? ['text', 'image']
+    : ['text']
+}
+
+/**
+ * Map this plugin's reasoning-effort ids (OpenAI vocabulary — `none`,
+ * `xhigh`, `max`, …) onto pi-ai's level keys. `none` is not a pi-ai level; it
+ * becomes `off` with wire spelling `none`, which pi-ai dispatches as
+ * `reasoning_effort: "none"` (chat/completions) or `reasoning:{effort:"none"}`
+ * (responses) — exactly what this plugin used to send. An empty list declares
+ * a non-reasoning model, as does a list containing only off/none; unmappable
+ * ids are dropped.
+ */
+function translateReasoningEfforts(model: CatalogModel): false | Partial<Record<string, string | null>> | undefined {
+  const ids = model.reasoningEfforts
+  if (ids === undefined) {
+    // The plugin's old default: every non-image model exposes low/medium/high.
+    if (/image/i.test(model.id)) return false
+    return { low: 'low', medium: 'medium', high: 'high' }
+  }
+  if (ids.length === 0) return false
+  const efforts: Record<string, string | null> = {}
+  for (const id of ids) {
+    if (id === 'none') efforts.off = 'none'
+    else if (THINKING_LEVELS.includes(id)) efforts[id] = id
+  }
+  if (Object.keys(efforts).length === 0) return undefined
+  return Object.keys(efforts).some(level => level !== 'off') ? efforts : false
+}
+
+/** One configured catalog model, translated onto pi-ai's per-model fields. */
+function translateModel(model: CatalogModel): PiAiModelProfile {
+  const reasoningEfforts = translateReasoningEfforts(model)
+  return {
+    id: model.id,
+    ...(model.name !== undefined && model.name.length > 0 ? { name: model.name } : {}),
+    ...(model.contextWindow !== undefined ? { contextWindow: model.contextWindow } : {}),
+    ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+    input: catalogInputModalities(model),
+    ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
+  }
+}
+
+/**
+ * Translate one sub2api group into a hand-declared llm-pi-ai provider profile.
+ * `apiKeyEnv` passes through verbatim (the harness resolves it per request
+ * through `ctx.credentials`); routes without a key are skipped by the caller.
+ *
+ * The settings store the bare gateway host; the protocols join it differently.
+ * OpenAI-compatible SDKs append their endpoint to the `/v1` API root, while
+ * `@anthropic-ai/sdk` treats the given URL as the bare host and appends
+ * `/v1/messages` itself — so OpenAI-style routes get the `/v1`-rooted URL and
+ * the anthropic route gets the bare host.
+ */
+function translateProfile(key: ProviderKey, profile: ProviderProfile, baseURL: string, label: string): PiAiProviderProfile {
+  const api = apiProtocolForKey(key, profile)
+  return {
+    ...(profile.apiKeyEnv !== undefined ? { apiKeyEnv: profile.apiKeyEnv } : {}),
+    displayName: `Sub2API ${label}`,
+    api,
+    baseURL: api === 'anthropic-messages' ? gatewayAnthropicRoot(baseURL) : gatewayApiRoot(baseURL),
+    models: (profile.models ?? []).map(translateModel),
+    // Route-level fallbacks mirror the plugin's old adapter defaults, so a
+    // catalog entry that omits a size keeps sizing like before.
+    defaultContextWindow: DEFAULT_CONTEXT_WINDOW,
+    defaultMaxTokens: DEFAULT_MAX_TOKENS,
+    defaultInput: ['text'],
+    // Sub2api acts as a proxy to upstream providers that may enforce their own
+    // rate limits (HTTP 429). The default normal policy (2 retries, max 10s)
+    // is too short for upstream throttling windows; raise to 5 retries / 120s
+    // so transient rate limits resolve before the agent gives up.
+    retryPolicy: {
+      mode: 'normal',
+      maxRetries: 5,
+      retryableCodes: ['RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE'],
+      backoff: { initialDelayMs: 1000, maxDelayMs: 120000, jitterRatio: 0.2 },
+    },
+  }
+}
+
+/**
+ * Build the `llm-pi-ai` provider profile dict for every configured sub2api
+ * group. A group is emitted only when it has both a key and at least one
+ * model — a hand-declared pi-ai route needs a non-empty `models` list, and a
+ * keyless group would otherwise surface as an unauthenticated route.
+ */
+export function translateToPiAi(config: Config): Record<string, PiAiProviderProfile> {
+  const baseURL = (config.baseURL ?? '').trim().replace(/\/+$/, '')
+  if (baseURL.length === 0) return {}
+  const profiles: Record<string, PiAiProviderProfile> = {}
+  for (const def of PROVIDERS) {
+    const profile = config.providers[def.key]
+    if (profile.apiKeyEnv === undefined) continue
+    const models = (profile.models ?? []).filter((model) => model.id.length > 0)
+    if (models.length === 0) continue
+    profiles[def.route] = translateProfile(def.key, { ...profile, models }, baseURL, def.label)
+  }
+  return profiles
+}
+
+/**
+ * Write the translated profiles into the `llm-pi-ai` settings section. Routes
+ * under this plugin's `sub2api-` prefix are replaced wholesale; any other
+ * route the user configured (e.g. through the built-in Models page) is
+ * preserved. The write goes through the settings service, so dsh-llm-pi-ai's
+ * own validation (schema + `assertServiceable`) refuses an unserviceable
+ * profile at the write site and the section keeps its last good value.
+ */
+export async function syncPiAiProfiles(ctx: Context, config: Config): Promise<void> {
+  const settings = ctx.get('settings')
+  if (settings === undefined) return
+  const current = settings.describe().find(section => section.ns === PI_AI_NS)?.value as PiAiSettingsSection | undefined
+  const providers: Record<string, PiAiProviderProfile> = { ...(current?.providers ?? {}) }
+  for (const route of Object.keys(providers)) {
+    if (route.startsWith(ROUTE_PREFIX)) delete providers[route]
+  }
+  Object.assign(providers, translateToPiAi(config))
+  const next: PiAiSettingsSection = { providers }
+  const before = JSON.stringify(current?.providers ?? {})
+  if (JSON.stringify(providers) === before) return
+  await settings.replace(PI_AI_NS, next)
+}