@chatcode/cco-llm-chatcode-config 0.1.0

package/vendor/dsh-llm-pi-ai/src/index.ts

@@ -0,0 +1,336 @@
+/**
+ * Generic pi-ai-backed LLM adapter plugin. One plugin instance owns a dict of
+ * provider routes; a route naming an installed pi-ai provider inherits that
+ * provider's endpoint, protocol, and model catalog as defaults, and a route
+ * pi-ai does not ship is declared outright. Profile facts resolve per request
+ * over the optional `llm-pi-ai` user-settings section and the optional
+ * credential seam, so a changed key, endpoint, model, or knob reaches the next
+ * request without a restart; a changed *route set* (or a route's
+ * registration-captured retry policy) re-registers the same adapter instance
+ * in place.
+ *
+ * ```yaml
+ * - id: llm
+ *   name: '@deepseek-ai/dsh-llm-pi-ai'
+ *   config:
+ *     providers:
+ *       # Catalog route: everything but the credential comes from pi-ai.
+ *       openai:
+ *         apiKeyEnv: OPENAI_API_KEY
+ *         retryPolicy:
+ *           mode: normal
+ *           maxRetries: 2
+ *       # Catalog route with the catalog narrowed and one capacity corrected.
+ *       anthropic:
+ *         apiKeyEnv: ANTHROPIC_API_KEY
+ *         models:
+ *           - id: claude-sonnet-4-5
+ *             contextWindow: 200000
+ *       # Hand-declared route: pi-ai ships nothing under this key.
+ *       acme-gateway:
+ *         displayName: Acme Gateway
+ *         apiKeyEnv: ACME_GATEWAY_API_KEY
+ *         api: openai-completions
+ *         baseURL: https://gateway.acme.example/v1
+ *         # Reasoning dialect for a URL pi-ai cannot recognize.
+ *         compat:
+ *           thinkingFormat: deepseek
+ *         models:
+ *           - id: acme-large
+ *             name: Acme Large
+ *             contextWindow: 65536
+ *             maxTokens: 4096
+ *           - id: acme-think
+ *             name: Acme Think
+ *             contextWindow: 262144
+ *             maxTokens: 32768
+ *             # key = selectable level, value = wire spelling; only off may
+ *             # leave the value empty (supported, send nothing).
+ *             reasoningEfforts:
+ *               off:
+ *               high: high
+ *               max: ultra
+ * ```
+ *
+ * @module @deepseek-ai/dsh-llm-pi-ai
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import { assertUsableApiKey, LlmError, resolveImageAttachmentAccess } from '@deepseek-ai/dsh-llm'
+import type { AdapterRegistrationHandle, DirectoryRegistrationHandle, LlmConfigurableProvider } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-settings'
+import { deepEqualJson } from '@deepseek-ai/dsh-util-values'
+import { PiAiAdapter } from './adapter.ts'
+import type { PiAiRequestAuth } from './adapter.ts'
+import { authContextFrom, credentialStoreFrom } from './auth.ts'
+import { catalogProviderIds } from './catalog.ts'
+import { assertServiceable, Config, resolveProfiles } from './config.ts'
+import type { ResolvedPiAiProviderProfile } from './config.ts'
+import { discoverModels } from './discovery.ts'
+import { registerPiAiFlows } from './login.ts'
+
+export { PiAiAdapter } from './adapter.ts'
+export type { PiAiAdapterOptions, PiAiRequestAuth } from './adapter.ts'
+export { Config, resolveProfiles } from './config.ts'
+export type {
+  PiAiCompatProfile,
+  PiAiModality,
+  PiAiModelOverride,
+  PiAiModelProfile,
+  PiAiProviderProfile,
+  PiAiReasoningEfforts,
+  PiAiThinkingFormat,
+  ResolvedPiAiProviderProfile,
+} from './config.ts'
+export { isolatedPiAiAuth, recordKeyFor } from './auth.ts'
+export { supportedProtocols } from './provider.ts'
+
+export const name = 'llm-pi-ai'
+export const inject = ['llm']
+
+const NS = 'llm-pi-ai'
+
+/**
+ * The registry captures these per route; a change here must re-register.
+ * Sorted by provider so a settings document that merely reorders its keys is
+ * not mistaken for a route change.
+ */
+function registrationFacts(profiles: ReadonlyMap<string, ResolvedPiAiProviderProfile>): unknown {
+  return [...profiles.entries()]
+    // `displayName` rides along because the registry hands it to every selector
+    // through `providerInfo()`: a rename that did not re-register would leave
+    // the old label showing until some unrelated fact happened to change.
+    .map(([provider, profile]) => ({
+      provider,
+      displayName: profile.displayName,
+      retryPolicy: profile.retryPolicy,
+    }))
+    .sort((left, right) => left.provider.localeCompare(right.provider))
+}
+
+/**
+ * The configurable-provider directory: every installed catalog route, plus
+ * every route the current profiles declare. A hand-declared route has no
+ * catalog entry, so without this union it would have no settings address and
+ * configuration surfaces could neither show nor edit it.
+ * @param profiles - the currently resolved provider profiles.
+ * @returns the directory entries in catalog order, declared routes last.
+ */
+function directoryEntries(
+  profiles: ReadonlyMap<string, ResolvedPiAiProviderProfile>,
+): LlmConfigurableProvider[] {
+  const catalog = new Set(catalogProviderIds())
+  const entries = new Map<string, LlmConfigurableProvider>()
+  const declare = (provider: string, displayName: string): void => {
+    entries.set(provider, {
+      provider,
+      displayName,
+      settingsNs: NS,
+      settingsPath: ['providers', provider],
+      // Membership of the installed catalog, not of the settings document:
+      // narrowing a shipped provider's models stores a profile too, and that
+      // route is still one pi-ai knows.
+      declared: !catalog.has(provider),
+    })
+  }
+  for (const provider of catalog) declare(provider, provider)
+  for (const [provider, profile] of profiles) declare(provider, profile.displayName)
+  return [...entries.values()]
+}
+
+/** Register one generic pi-ai adapter for all configured provider routes. */
+export function apply(ctx: Context, config: Config): void {
+  let current: () => Config = () => config
+  let lastRaw: Config | undefined
+  let memoized: ReadonlyMap<string, ResolvedPiAiProviderProfile> | undefined
+  /**
+   * The resolved profiles for the current configuration, memoized by the raw
+   * snapshot's identity — which is also what makes the adapter's own snapshot
+   * stable across operations that observe no change.
+   *
+   * No fallback for an unserviceable snapshot lives here: the section schema
+   * resolves the whole profile set, so a write that could not be served is
+   * refused where it is written, and the settings seam keeps a namespace's
+   * last good value for a stored section that fails. Anything reaching this
+   * point has already resolved once.
+   */
+  const profiles = (): ReadonlyMap<string, ResolvedPiAiProviderProfile> => {
+    const raw = current()
+    if (raw === lastRaw && memoized !== undefined) return memoized
+    const next = resolveProfiles(raw.providers)
+    lastRaw = raw
+    memoized = next
+    return next
+  }
+  profiles()
+
+  const resolveApiKey = async (
+    provider: string,
+    profile: ResolvedPiAiProviderProfile,
+  ): Promise<string | undefined> => {
+    const ref = profile.apiKeyEnv
+    // Only a profile that names no credential at all defers to pi-ai's
+    // provider-native discovery. Once one is named, a miss must fail loud:
+    // handing pi-ai `undefined` would let it pick up an unrelated ambient key
+    // (OPENAI_API_KEY and friends), billing another tenant for a request the
+    // deployment meant to authenticate differently.
+    if (ref === undefined) return undefined
+    const credentials = ctx.get('credentials')
+    const hit = credentials !== undefined
+      ? (await credentials.resolve(ref))?.value
+      // Without the seam the environment is the whole credential plane.
+      : launchEnvironmentOf(ctx).get(ref)?.value
+    if (hit !== undefined && hit.length > 0) return assertUsableApiKey(hit, 'llm-pi-ai', ref)
+    throw new LlmError(
+      `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
+      + ` set — store ${ref} through the credentials service (the web Models page writes it) or export it,`
+      + ' and remove apiKeyEnv only if this provider should authenticate from pi-ai\'s own environment discovery',
+      'MISSING_CREDENTIAL',
+    )
+  }
+
+  // One store and one ambient context for the whole plugin instance: both read
+  // through `ctx` per call, so they stay correct across the collection rebuilds
+  // a configuration change causes, and a sign-in survives one.
+  const auth = { credentials: credentialStoreFrom(ctx), authContext: authContextFrom(ctx) }
+  const adapter = new PiAiAdapter({
+    profiles,
+    resolveAuth: async (provider, profile): Promise<PiAiRequestAuth> => {
+      const apiKey = await resolveApiKey(provider, profile)
+      return apiKey === undefined ? {} : { apiKey }
+    },
+    auth,
+    resolveAttachments: () => ctx.get('attachments'),
+    resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(
+      attachments,
+      hostPath => ctx.get('fs')?.processPathFromHostPath(hostPath),
+      ref,
+    ),
+    onReplayDegrade: ({ provider, model, reason }) => {
+      ctx.logger.warn(
+        `llm-pi-ai: unusable replay state on assistant history for route "${provider}/${model}";`
+        + ` sending that message as provider-neutral content (${reason})`,
+      )
+    },
+  })
+  // Independent of the route set: signing in is what makes a route worth
+  // adding, so the flows are offered before any profile names their provider.
+  // Scoped to the authorization seam rather than injected outright, because a
+  // composition without it (headless, ACP) simply has no surface to sign in
+  // from, while everything else this plugin does still works.
+  ctx.inject(['authorization'], (authorized) => { registerPiAiFlows(authorized, auth) })
+  // The full installed catalog is configurable from the moment the plugin
+  // mounts — dormant or not — so configuration surfaces can offer every
+  // pi-ai provider before any route exists. Hand-declared routes join it as
+  // profiles appear, and leave with them.
+  let directory: DirectoryRegistrationHandle | undefined
+  let directoryFacts: unknown
+  const ensureDirectory = (): void => {
+    const entries = directoryEntries(profiles())
+    if (deepEqualJson(entries, directoryFacts)) return
+    // Atomic replace, never dispose-then-register: a route another adapter
+    // family already declares (a profile keyed `deepseek-official`) would
+    // otherwise leave this plugin's whole directory withdrawn and the Models
+    // page empty. The candidate set is validated first, so a collision keeps
+    // the previous entries serving and only costs a diagnostic.
+    if (directory === undefined) {
+      directory = ctx.llm.registerConfigurableProviders(entries)
+    } else {
+      directory.replace(entries)
+    }
+    directoryFacts = entries
+  }
+  ensureDirectory()
+  /**
+   * The credential a named route already resolves, for an interrogation whose
+   * draft carries none. A route being declared for the first time names no
+   * profile yet, and a profile that names no credential defers to pi-ai's own
+   * discovery, so both answer `undefined` and the endpoint is asked
+   * unauthenticated — the same posture a request to that route would take.
+   */
+  const storedApiKey = async (provider: string | undefined): Promise<string | undefined> => {
+    if (provider === undefined) return undefined
+    const profile = profiles().get(provider)
+    if (profile === undefined) return undefined
+    return resolveApiKey(provider, profile)
+  }
+  // Interrogating an endpoint is a configuration-time action over a draft, so
+  // it is offered for the whole namespace rather than per route: the provider
+  // a surface is adding does not exist yet. The draft is the whole request
+  // except the credential: a configuration surface edits a redacted descriptor
+  // and never holds a stored secret, so an already-configured route supplies
+  // its own here rather than being interrogated unauthenticated.
+  ctx.llm.registerModelDiscovery(NS, (request, signal) => discoverModels(
+    { ...request, ...signal === undefined ? {} : { signal } },
+    () => storedApiKey(request.provider),
+  ))
+  // Route effects bind to this apply fiber via the stable `ctx` reference,
+  // even when a swap runs inside the scoped settings callback below. A bare
+  // mount (zero routes) is the dormant posture: nothing registers until a
+  // settings section supplies profiles, and routes drop when it empties.
+  let registration: AdapterRegistrationHandle | undefined
+  let registeredFacts: unknown
+  const ensureRegistrationFacts = (): void => {
+    const facts = registrationFacts(profiles())
+    if (deepEqualJson(facts, registeredFacts)) return
+    // The registry captures the route set and each route's retry policy at
+    // registration, so a change to either must re-register. The swap is
+    // atomic (same adapter instance, validated before anything moves): a
+    // conflicting route leaves the previous routes serving requests, and
+    // `registeredFacts` only advances once the registry actually holds the
+    // new set — so returning to a working configuration always re-applies.
+    const routes = [...profiles().keys()]
+    if (registration === undefined) {
+      // Dormant bare mount: nothing is registered until a section supplies
+      // profiles, and an empty section keeps it that way.
+      if (routes.length === 0) {
+        registeredFacts = facts
+        return
+      }
+      registration = ctx.llm.registerAdapter(routes, adapter)
+    } else {
+      registration.replace(routes)
+    }
+    registeredFacts = facts
+  }
+  ensureRegistrationFacts()
+
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, NS, Config, config, {
+      // Refuse an unserviceable section where it is written: without this a
+      // schema-valid profile the adapter cannot serve would be stored and then
+      // silently disable every route in this namespace.
+      validate: assertServiceable,
+      setSource: (source) => {
+        current = source
+      },
+      onChange: () => {
+        // Named here rather than left to the settings watcher: `assertServiceable`
+        // cannot see the llm registry, so a profile claiming a route another
+        // adapter family owns is stored successfully and only fails at this swap.
+        // Without its own diagnostic that refusal reaches the operator as a
+        // generic "settings: watcher failed", naming neither the route nor why it
+        // is not serving. The previous routes keep serving either way.
+        try {
+          ensureRegistrationFacts()
+        } catch (error) {
+          ctx.logger.error('llm-pi-ai: keeping the previously registered routes after a refused update')
+          ctx.logger.error(error)
+        }
+        // The directory follows the profiles the registry accepted, so a route
+        // that failed to register is not advertised as configurable. A refused
+        // directory swap is contained here for the same reason the registry's
+        // is: the previous entries keep serving, and `directoryFacts` stays put
+        // so returning to a working configuration re-applies.
+        try {
+          ensureDirectory()
+        } catch (error) {
+          ctx.logger.error('llm-pi-ai: keeping the previous configurable-provider directory after a refused update')
+          ctx.logger.error(error)
+        }
+      },
+    })
+  })
+}

package/vendor/dsh-llm-pi-ai/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-pi-ai`.
+ * @module @deepseek-ai/dsh-llm-pi-ai/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-pi-ai'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-pi-ai-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

package/vendor/dsh-llm-pi-ai/src/login.ts

@@ -0,0 +1,161 @@
+/**
+ * Authorization flows for the pi-ai providers that ship a login. This is the
+ * whole of the translation between the harness's neutral notice/prompt
+ * vocabulary and pi-ai's `AuthInteraction`; nothing above it knows which
+ * library ran the conversation.
+ *
+ * @module dsh-llm-pi-ai/login
+ */
+
+import { createModels } from '@earendil-works/pi-ai'
+import type { AuthEvent, AuthPrompt, AuthType, Provider } from '@earendil-works/pi-ai'
+import type { Context } from '@deepseek-ai/cordis'
+import type { AuthorizationMethod, AuthorizationPrompt, AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { isCredentialKeySegment } from '@deepseek-ai/dsh-credentials'
+import { catalogProvider, catalogProviderIds } from './catalog.ts'
+import { recordKeyFor } from './auth.ts'
+import type { PiAiAuthInjection } from './adapter.ts'
+
+/**
+ * The login methods one catalog provider offers.
+ *
+ * A method appears only when pi-ai can actually run it: `oauth` always carries
+ * a `login`, while an api-key method has one only when the provider collects
+ * its key interactively — which every installed one currently does, so a key is
+ * typed into pi-ai's own prompt rather than into the settings form.
+ * @param provider - the installed catalog provider, if pi-ai ships one.
+ * @returns its methods, most preferred first; empty when it offers no login.
+ */
+function loginMethods(provider: Provider | undefined): AuthorizationMethod[] {
+  const methods: AuthorizationMethod[] = []
+  const oauth = provider?.auth.oauth
+  if (oauth !== undefined) methods.push({ id: 'oauth', label: oauth.loginLabel ?? oauth.name })
+  const apiKey = provider?.auth.apiKey
+  if (apiKey?.login !== undefined) methods.push({ id: 'api-key', label: apiKey.name })
+  return methods
+}
+
+/**
+ * Restate one pi-ai login event in the seam's vocabulary.
+ *
+ * A device-code grant is the one event carrying two things the human needs at
+ * once — where to go and what to type there — which is why the neutral notice
+ * has a `code` beside its `url` rather than folding the code into the message.
+ * @param event - what pi-ai reported.
+ * @param session - the attempt to report it to.
+ */
+function relay(event: AuthEvent, session: AuthorizationSession): void {
+  switch (event.type) {
+    case 'info': {
+      const link = event.links?.[0]
+      session.notify({ message: event.message, ...link === undefined ? {} : { url: link.url } })
+      return
+    }
+    case 'auth_url':
+      session.notify({
+        message: event.instructions ?? 'Open this page to continue signing in.',
+        url: event.url,
+      })
+      return
+    case 'device_code':
+      session.notify({
+        message: 'Enter this code on the verification page to finish signing in.',
+        url: event.verificationUri,
+        code: event.userCode,
+      })
+      return
+    case 'progress':
+      session.notify({ message: event.message })
+      return
+    default:
+      // pi-ai's event union is open to new members: a build that meets one it
+      // does not know still shows the human that something is happening rather
+      // than going silent mid-login.
+      session.notify({ message: 'Signing in…' })
+  }
+}
+
+/**
+ * Restate one pi-ai prompt in the seam's vocabulary.
+ *
+ * `manual_code` becomes a plain text question because the difference pi-ai
+ * draws — a code the human copies from a browser rather than a value they know
+ * — changes nothing a surface renders. Its own `signal` is carried through, and
+ * that is the part which matters: it is how a flow racing a typed code against
+ * a browser callback withdraws the losing question.
+ * @param prompt - what pi-ai asked.
+ * @returns the neutral prompt to put to the human.
+ */
+function restate(prompt: AuthPrompt): AuthorizationPrompt {
+  const signal = prompt.signal === undefined ? {} : { signal: prompt.signal }
+  switch (prompt.type) {
+    case 'select':
+      return { ...signal, kind: 'select', message: prompt.message, options: prompt.options }
+    case 'secret':
+      return {
+        ...signal,
+        kind: 'secret',
+        message: prompt.message,
+        ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+      }
+    default:
+      return {
+        ...signal,
+        kind: 'text',
+        message: prompt.message,
+        ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+      }
+  }
+}
+
+/**
+ * Register one authorization flow per installed provider that ships a login.
+ *
+ * Registration is unconditional on configuration: a provider has to be signed
+ * into before a route for it is worth adding, so the flow exists from the
+ * moment the plugin mounts rather than appearing once a profile does.
+ * @param ctx - the plugin context carrying `ctx.authorization`.
+ * @param auth - the injectables every collection here is built with.
+ */
+export function registerPiAiFlows(ctx: Context, auth: PiAiAuthInjection): void {
+  for (const providerId of catalogProviderIds()) {
+    const provider = catalogProvider(providerId)
+    const [first, ...rest] = loginMethods(provider)
+    /* v8 ignore next 3 -- every id here names an installed provider and every
+       installed provider ships a login, so no entry is skipped; the guard
+       is what keeps that from becoming a crash if either stops being true. */
+    if (provider === undefined || first === undefined) continue
+    /* v8 ignore next 7 -- every installed catalog id is a lowercase
+       hyphenated identifier; the guard keeps a future upstream id outside the
+       record grammar (dotted or uppercase, as vendor ids elsewhere already
+       are) from throwing in `recordKeyFor` and failing the whole mount. */
+    if (!isCredentialKeySegment(providerId)) {
+      ctx.logger.warn(
+        'llm-pi-ai: catalog provider "%s" cannot address a credential record; its sign-in is not offered',
+        providerId)
+      continue
+    }
+    ctx.authorization.registerFlow({
+      key: recordKeyFor(providerId),
+      label: provider.name,
+      methods: [first, ...rest],
+      async run(session) {
+        // A collection of its own, holding only the provider being signed
+        // into: login is not serving requests, and the credential it produces
+        // lands in the shared store either way.
+        const models = createModels(auth)
+        models.setProvider(provider)
+        // Total over the two ids declared above, and the seam only ever hands
+        // back one a flow declared.
+        const type: AuthType = session.method === 'oauth' ? 'oauth' : 'api_key'
+        // pi-ai persists what the login returns through that same store, which
+        // is what makes it the single writer of this record.
+        await models.login(providerId, type, {
+          signal: session.signal,
+          notify: (event) => { relay(event, session) },
+          prompt: prompt => session.prompt(restate(prompt)),
+        })
+      },
+    })
+  }
+}