@lihuu/dsh-ollama-cloud 0.1.2 → 0.2.0

package/README.md

@@ -5,6 +5,9 @@ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin tha
 ## What it does
 
 - Registers the `ollama-cloud-direct` provider route on the LLM seam
+- Declares the route in the configurable-provider directory as a **dormant entry**: until configured, it is offered by the Models page's **添加提供方** select (like a pi-ai route), and configuring it turns it into a removable **Ollama Cloud** row
+- Installs the `llm-ollama-cloud` user-settings section, so base URL, model catalog, and defaults are editable on the page and take effect without a restart
+- Answers the Models page's **fetch available models** action from the resolved catalog, or interrogates a drafted endpoint at `GET {baseURL}/models`
 - Ships with a default model catalog: DeepSeek-V4-Flash (cloud), DeepSeek-V4-Pro (cloud), GLM-5.2 (cloud)
 - Reads the API key through the harness credential seam, per request — a changed key takes effect without a restart
 - Model ids without a `:cloud` suffix are sent as `id:cloud` (e.g. `deepseek-v4-flash` → `deepseek-v4-flash:cloud`)
@@ -28,13 +31,35 @@ dsh plugin --profile web add @lihuu/dsh-ollama-cloud
 
 Restart the web service once after installing (bundle layers are composed at boot).
 
+### Upgrading from 0.1.x
+
+0.2.0 moves the configuration from section-level fields to a per-route profile (`providers.ollama-cloud-direct`), which is what makes the route appear in the Models page's **添加提供方** select. If you pinned config in `~/.dsh/cordis.patch.yml`, move it under the profile:
+
+```yaml
+# 0.1.x                          # 0.2.0
+- id: llm-ollama-cloud            - id: llm-ollama-cloud
+  config:                           config:
+    apiKeyEnv: ...                    providers:
+    baseURL: ...                        ollama-cloud-direct:
+    models: ...                           apiKeyEnv: ...
+                                          baseURL: ...
+                                          models: ...
+```
+
+Easiest path: drop the `config:` block entirely (keep the bare row) and configure on the Models page after restarting.
+
 ## Configuration
 
 ### 1. Set the API key
 
-The plugin reads the key through the harness credential seam, per request — a changed key takes effect without a restart.
+After a restart, open **Settings → Models**, click **添加提供方**, and pick **Ollama Cloud** from the select:
+
+- Type the key and **保存** — it is stored write-only under the `OLLAMA_CLOUD_DIRECT_API_KEY` credential reference, and the profile is created. The row appears with a green key dot.
+- Or save **without typing a key** — the profile resolves the conventional `OLLAMA_CLOUD_API_KEY` reference instead, so a key already set in the environment or the credentials file keeps working.
+
+The key can also be set outside the page:
 
-**Recommended — credentials file.** Add one line to `~/.dsh/.credentials.yaml`:
+**Credentials file.** Add one line to `~/.dsh/.credentials.yaml`:
 
 ```yaml
 version: 1
@@ -42,29 +67,52 @@ refs:
   OLLAMA_CLOUD_API_KEY: ollama-xxxxxxxxxxxxxxxx
 ```
 
-**Alternative — environment variable.** Set `OLLAMA_CLOUD_API_KEY` in the environment the harness process runs under (your shell profile, a launchd unit, a process manager, etc.):
+**Environment variable.** Set `OLLAMA_CLOUD_API_KEY` in the environment the harness process runs under (your shell profile, a launchd unit, a process manager, etc.):
 
 ```sh
 export OLLAMA_CLOUD_API_KEY="ollama-xxxxxxxxxxxxxxxx"
 ```
 
+While the route is dormant (no profile stored), the adapter already serves the default catalog through that reference — page-stored credentials win over the environment once a profile names one; both are read per request, so changing either never needs a restart.
+
 ### 2. Select the provider
 
 Choose the `ollama-cloud-direct` provider for the model (for example in the model settings or the agent's provider configuration).
 
+### Settings section
+
+The section shape is one profile per route:
+
+```yaml
+llm-ollama-cloud:
+  providers:
+    ollama-cloud-direct:
+      apiKeyEnv: OLLAMA_CLOUD_API_KEY
+      baseURL: https://ollama.com/v1
+      models:
+        - id: deepseek-v4-flash
+          contextWindow: 800000
+```
+
+The plugin's `cordis.yml` mount entry is the section's base layer: pinning the profile there presents the route as an already-configured row; leaving it out keeps it dormant in the add-provider select. Everything the profile allows (`apiKeyEnv`, `baseURL`, `thinking`, `reasoningEffort`, `maxTokens`, `defaultContextWindow`, `models`, `streamIdleTimeoutMs`, `retryPolicy`) is editable on the page or in `settings.yaml` — the user layer wins, and a change takes effect on the next request without a restart. Fields the curated editor does not show (retry policy, timeouts, thinking defaults) stay owned by the mount config and `settings.yaml`.
+
 ## Custom model catalog
 
-The bundle mounts the plugin with its default model catalog. To override it, add a config row in `~/.dsh/cordis.patch.yml`:
+The plugin resolves a default catalog when the profile names no `models` array. To pin one for the deployment, add it to the profile in `~/.dsh/cordis.patch.yml`:
 
 ```yaml
 - id: llm-ollama-cloud
   config:
-    models:
-      - id: deepseek-v4-flash
-        name: DeepSeek-V4-Flash
-        contextWindow: 800000
+    providers:
+      ollama-cloud-direct:
+        models:
+          - id: deepseek-v4-flash
+            name: DeepSeek-V4-Flash
+            contextWindow: 800000
 ```
 
+(Note: pinning the profile this way also presents the route as configured.) The Models page can override the catalog per deployment (自定义设置 → models); **reset** there hands the catalog back to the layer beneath.
+
 ## License
 
 MIT

package/dist/index.js

@@ -1,6 +1,8 @@
 // src/index.ts
+import z from "@deepseek-ai/schemastery";
+import { assertUsableApiKey, LlmError as LlmError6, resolveRetryPolicy, RetryPolicySchema } from "@deepseek-ai/dsh-llm";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
-import { assertUsableApiKey, LlmError as LlmError5, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { deepEqualJson, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 
 // src/adapter.ts
 import {
@@ -574,7 +576,7 @@ var OllamaAdapter = class extends LlmAdapter {
   }
   config;
   providerInfo(provider) {
-    return { id: provider, name: "Ollama" };
+    return { id: provider, name: "Ollama Cloud" };
   }
   providerRetryPolicy(_provider) {
     return this.config.options().retryPolicy;
@@ -713,9 +715,152 @@ var OllamaAdapter = class extends LlmAdapter {
   }
 };
 
+// src/discovery.ts
+import { INVALID_CREDENTIAL_CODE, LlmError as LlmError5, normalizeApiKey } from "@deepseek-ai/dsh-llm";
+import { attributionHeaders as attributionHeaders2 } from "@deepseek-ai/dsh-llm";
+var MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+function capacity(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isInteger(candidate) && candidate > 0) return candidate;
+  }
+  return void 0;
+}
+function label(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.length > 0) return candidate;
+  }
+  return void 0;
+}
+function listingUrl(baseURL) {
+  return `${baseURL.replace(/\/+$/, "")}/models`;
+}
+function usableProbeKey(raw) {
+  const checked = normalizeApiKey(raw);
+  if (checked.ok) return checked.value;
+  throw new LlmError5(
+    checked.reason === "empty" ? "this provider's API key is blank; enter it on the Models page, or clear it to probe unauthenticated" : "this provider's API key contains characters no HTTP header can carry; paste the raw key only",
+    INVALID_CREDENTIAL_CODE
+  );
+}
+async function readBounded(response, url) {
+  const oversized = () => new LlmError5(`${url} answered with more than ${MAX_RESPONSE_BYTES} bytes`, "DISCOVERY_FAILED");
+  const declared = Number(response.headers.get("content-length") ?? Number.NaN);
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel();
+    throw oversized();
+  }
+  if (response.body === null) return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_RESPONSE_BYTES) throw oversized();
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(body);
+}
+function readListing(body) {
+  const data = body?.data;
+  if (!Array.isArray(data)) {
+    throw new LlmError5(
+      `the endpoint's model listing has no "data" array; enter this provider's models by hand`,
+      "DISCOVERY_FAILED"
+    );
+  }
+  const models = [];
+  for (const raw of data) {
+    const entry = raw;
+    const id = label(entry?.id);
+    if (id === void 0) continue;
+    const name2 = label(entry?.name, entry?.display_name);
+    const contextWindow = capacity(entry?.context_window, entry?.context_length);
+    const maxTokens = capacity(entry?.max_output_tokens, entry?.max_tokens);
+    models.push({
+      id,
+      ...name2 === void 0 ? {} : { name: name2 },
+      ...contextWindow === void 0 ? {} : { contextWindow },
+      ...maxTokens === void 0 ? {} : { maxTokens }
+    });
+  }
+  return models;
+}
+async function discoverModels(request, installed, storedApiKey) {
+  if (request.provider !== void 0 && installed.length > 0) {
+    return installed.map((model) => ({
+      id: model.id,
+      name: model.name ?? model.id,
+      ...model.contextWindow === void 0 ? {} : { contextWindow: model.contextWindow },
+      ...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens }
+    }));
+  }
+  if (request.baseURL === void 0 || request.baseURL.length === 0) {
+    throw new LlmError5(
+      "model discovery needs a baseURL to interrogate; set one, or enter this provider's models by hand",
+      "DISCOVERY_FAILED"
+    );
+  }
+  const url = listingUrl(request.baseURL);
+  const supplied = request.apiKey ?? await storedApiKey?.();
+  const apiKey = supplied === void 0 ? void 0 : usableProbeKey(supplied);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        ...apiKey === void 0 ? {} : { authorization: `Bearer ${apiKey}` },
+        ...attributionHeaders2()
+      },
+      ...request.signal === void 0 ? {} : { signal: request.signal }
+    });
+  } catch (error) {
+    if (request.signal?.aborted) {
+      throw new LlmError5("model discovery aborted by caller", "ABORTED", { cause: error });
+    }
+    throw new LlmError5(`could not reach ${url}`, "DISCOVERY_FAILED", { cause: error });
+  }
+  if (!response.ok) {
+    throw new LlmError5(
+      `${url} answered ${response.status}${response.status === 401 || response.status === 403 ? "; check the API key" : ""}`,
+      "DISCOVERY_FAILED"
+    );
+  }
+  let text;
+  try {
+    text = await readBounded(response, url);
+  } catch (error) {
+    if (request.signal?.aborted) {
+      throw new LlmError5("model discovery aborted by caller", "ABORTED", { cause: error });
+    }
+    throw error;
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch (error) {
+    throw new LlmError5(`${url} did not answer with JSON`, "DISCOVERY_FAILED", { cause: error });
+  }
+  return readListing(body);
+}
+
 // src/index.ts
 var name = "llm-ollama-cloud";
 var inject = ["llm"];
+var NS = settingsNamespace("llm-ollama-cloud");
 var DEFAULT_API_KEY_ENV = "OLLAMA_CLOUD_API_KEY";
 var PROVIDER = "ollama-cloud-direct";
 var DEFAULT_MODELS = [
@@ -724,6 +869,28 @@ var DEFAULT_MODELS = [
   { id: "glm-5.2:cloud", name: "GLM-5.2 (cloud)", contextWindow: DEFAULT_CONTEXT_WINDOW }
 ];
 var MODEL_MODALITIES = ["text", "image"];
+var catalogModel = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  description: z.string(),
+  contextWindow: z.number().step(1).min(1),
+  maxTokens: z.number().step(1).min(1),
+  inputModalities: z.array(z.union(MODEL_MODALITIES)).min(1).default(["text"])
+});
+var profileSchema = z.object({
+  apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+  baseURL: z.string(),
+  thinking: z.union(["enabled", "disabled"]),
+  reasoningEffort: z.union(["off", "low", "high", "max"]),
+  maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_TOKENS),
+  defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+  models: z.array(catalogModel).default(DEFAULT_MODELS),
+  streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema
+});
+var Config = z.object({
+  providers: z.dict(profileSchema).default({})
+});
 var PUBLIC_BASE_URL = "https://ollama.com/v1";
 function resolveModels(models) {
   const seen = /* @__PURE__ */ new Set();
@@ -768,73 +935,123 @@ function resolveModels(models) {
   });
 }
 function resolveAdapterOptions(config) {
-  if (config.thinking === "disabled" && config.reasoningEffort !== void 0 && config.reasoningEffort !== "off") {
+  return resolveProfileOptions(config.providers?.[PROVIDER]);
+}
+function resolveProfileOptions(profile) {
+  if (profile?.thinking === "disabled" && profile.reasoningEffort !== void 0 && profile.reasoningEffort !== "off") {
     throw new Error('llm-ollama-cloud: only reasoningEffort "off" can be configured when thinking is disabled');
   }
-  if (config.defaultContextWindow !== void 0 && (!Number.isInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) {
+  if (profile?.defaultContextWindow !== void 0 && (!Number.isInteger(profile.defaultContextWindow) || profile.defaultContextWindow <= 0)) {
     throw new Error("llm-ollama-cloud: defaultContextWindow must be a positive integer");
   }
-  if (config.maxTokens !== void 0 && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) {
+  if (profile?.maxTokens !== void 0 && (!Number.isSafeInteger(profile.maxTokens) || profile.maxTokens <= 0)) {
     throw new Error("llm-ollama-cloud: maxTokens must be a positive safe integer");
   }
-  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  const streamIdleTimeoutMs = profile?.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
   if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
     throw new Error(
       `llm-ollama-cloud: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`
     );
   }
   return {
-    apiKeyEnv: config.apiKeyEnv ?? DEFAULT_API_KEY_ENV,
-    baseURL: config.baseURL ?? PUBLIC_BASE_URL,
+    apiKeyEnv: credentialRef(profile?.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+    baseURL: profile?.baseURL ?? PUBLIC_BASE_URL,
     defaults: {
-      thinking: config.thinking,
-      reasoningEffort: config.reasoningEffort
+      thinking: profile?.thinking,
+      reasoningEffort: profile?.reasoningEffort
     },
-    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
-    defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
-    models: resolveModels(config.models),
+    maxTokens: profile?.maxTokens ?? DEFAULT_MAX_TOKENS,
+    defaultContextWindow: profile?.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    models: resolveModels(profile?.models),
     streamIdleTimeoutMs,
-    retryPolicy: resolveRetryPolicy(config.retryPolicy, "llm-ollama-cloud: retryPolicy")
+    retryPolicy: resolveRetryPolicy(profile?.retryPolicy, "llm-ollama-cloud: retryPolicy")
   };
 }
 function apply(ctx, config = {}) {
-  const options = () => resolveAdapterOptions(config);
-  const connection = options();
-  credentialRef(connection.apiKeyEnv);
-  const credentials = ctx.get("credentials");
-  const adapter = new OllamaAdapter({
-    options,
-    resolveApiKey: async (connection2) => {
-      const ref = connection2.apiKeyEnv;
-      if (credentials !== void 0) {
-        const hit = await credentials.resolve(ref);
-        if (hit !== void 0 && hit.value.length > 0) {
-          return assertUsableApiKey(hit.value, "llm-ollama-cloud", ref);
-        }
-      }
-      const value = process.env[ref];
-      if (value !== void 0 && value.length > 0) {
-        return assertUsableApiKey(value, "llm-ollama-cloud", ref);
+  let current = () => config;
+  let lastRaw;
+  let lastGood;
+  const options = () => {
+    const raw = current();
+    if (raw === lastRaw && lastGood !== void 0) return lastGood;
+    try {
+      const next = resolveAdapterOptions(raw);
+      lastRaw = raw;
+      lastGood = next;
+      return next;
+    } catch (error) {
+      if (lastGood === void 0) throw error;
+      lastRaw = raw;
+      ctx.logger.error("llm-ollama-cloud: keeping the last good configuration after an invalid settings section");
+      ctx.logger.error(error);
+      return lastGood;
+    }
+  };
+  options();
+  const resolveApiKey = async (connection) => {
+    const ref = connection.apiKeyEnv;
+    const credentials = ctx.get("credentials");
+    if (credentials !== void 0) {
+      const hit = await credentials.resolve(ref);
+      if (hit !== void 0 && hit.value.length > 0) {
+        return assertUsableApiKey(hit.value, "llm-ollama-cloud", ref);
       }
-      throw new LlmError5(
-        `llm-ollama-cloud: no API key for provider route "${PROVIDER}"; store ${ref} in the credentials file or export it in the launching environment`,
-        "MISSING_CREDENTIAL"
-      );
     }
+    const ambient = process.env[ref];
+    if (ambient !== void 0 && ambient.length > 0) {
+      return assertUsableApiKey(ambient, "llm-ollama-cloud", ref);
+    }
+    throw new LlmError6(
+      `llm-ollama-cloud: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials service (the web Models page writes it), or export ${ref} in the launching environment`,
+      "MISSING_CREDENTIAL"
+    );
+  };
+  const storedApiKey = async () => {
+    const ref = options().apiKeyEnv;
+    const credentials = ctx.get("credentials");
+    const hit = credentials !== void 0 ? (await credentials.resolve(ref))?.value : void 0;
+    const value = hit !== void 0 && hit.length > 0 ? hit : process.env[ref];
+    return value !== void 0 && value.length > 0 ? value : void 0;
+  };
+  const adapter = new OllamaAdapter({ options, resolveApiKey });
+  ctx.llm.registerConfigurableProviders([
+    { provider: PROVIDER, displayName: "Ollama Cloud", settingsNs: NS, settingsPath: ["providers", PROVIDER] }
+  ]);
+  const registration = ctx.llm.registerAdapter([PROVIDER], adapter);
+  let registeredPolicy = options().retryPolicy;
+  const ensureRegistrationFacts = () => {
+    const policy = options().retryPolicy;
+    if (deepEqualJson(policy, registeredPolicy)) return;
+    registration.replace([PROVIDER]);
+    registeredPolicy = policy;
+  };
+  ctx.llm.registerModelDiscovery(NS, (request, signal) => discoverModels(
+    { ...request, ...signal === void 0 ? {} : { signal } },
+    options().models,
+    storedApiKey
+  ));
+  installSettingsSection(ctx, NS, Config, config, {
+    setSource: (source) => {
+      current = source;
+    },
+    onChange: ensureRegistrationFacts
   });
-  ctx.llm.registerAdapter([PROVIDER], adapter);
 }
 export {
+  Config,
   DEFAULT_CONTEXT_WINDOW,
   DEFAULT_MAX_TOKENS,
   DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   MAX_TIMER_DELAY_MS,
   OllamaAdapter,
+  PROVIDER,
   PUBLIC_BASE_URL,
   apply,
+  discoverModels,
   inject,
   name,
   normalizeCloud,
-  resolveAdapterOptions
+  resolveAdapterOptions,
+  resolveProfileOptions
 };
 //# sourceMappingURL=index.js.map