@konduiteu/openclaw 0.1.0 → 0.2.0

package/README.md

@@ -18,10 +18,17 @@ openclaw plugins install npm:@konduiteu/openclaw
 ```
 
 Set `KONDUIT_API_KEY` to a key minted in the [konduit console](https://console.konduit.eu),
-or run `openclaw onboard --konduit-api-key kdt-…`. The key needs the
-`usage:read` scope for the card to show a balance; a key created without any
-scopes is unrestricted and works as it is. A key narrowed to `chat:write` still
-completes, and the card says why it shows nothing.
+or run `openclaw onboard --konduit-api-key kdt-…`. A key created without any
+scopes is unrestricted and works as it is. A key that carries scopes needs:
+
+| Scope | What stops working without it |
+| --- | --- |
+| `chat:write` | inference — `POST /v1/chat/completions` |
+| `models:read` | the model list. The plugin reads konduit's catalog at startup and again when it resolves a model it does not list, so a key without this scope leaves you with no konduit models to choose from |
+| `usage:read` | the balance and the limits on the provider card, nothing else |
+
+konduit's scopes are a flat allowlist, so `chat:write` does not imply
+`models:read`; a scoped key is refused on every route it does not name.
 
 If you had configured konduit by hand under `models.providers.konduit`, keep
 it: OpenClaw merges your entries with the plugin's by model id, and your
@@ -52,14 +59,21 @@ context window, output cap and price, generated from `GET /v1/models`:
 KONDUIT_API_KEY=kdt-… npm run catalog
 ```
 
+The catalog is authenticated because it carries prices, so this needs a key
+with `models:read` — and nothing else. That is the scope the repository's
+`KONDUIT_API_KEY` secret carries, and all `catalog:check` in CI asks for.
+
 That includes deployments konduit marks `deprecated`: the status discourages
 them, it does not switch them off, and a model you already have in your config
 should not vanish from the list because of a label. Only `retired` deployments
 are left out. The default model is never a deprecated one.
 
-CI checks the committed list against the live catalog. Live discovery is on
-as well, so a deployment konduit adds appears before the next release — at
-cost zero until the generator has written its price.
+CI checks the committed list against the live catalog. Live discovery is on as
+well, and it reads konduit's catalog with the same projection the generator
+uses: a deployment konduit adds appears before the next release with its real
+context window, output cap, capabilities and price, and can be selected right
+away. Deployments that do not serve chat — the embedding ones — stay out of the
+model list rather than being offered as something to talk to.
 
 **One caveat.** OpenClaw prices models in US dollars per million tokens and
 has no currency field. konduit prices in euros; the euro figures are stored

package/dist/catalog-mapping.js

@@ -0,0 +1,69 @@
+// konduit's own deployment id grammar: a provider slug, a slash, the model
+// name, and an optional `:variant`. The model segment stays free-form because
+// konduit does not control what characters an upstream model name contains —
+// apart from `@`, which is the whole reason this is checked here.
+//
+// The separator used to be `@` and moved to `:` on 2026-09-11, because enough
+// of the ecosystem reads `@` as an instance selector to corrupt an id in
+// transit. These ids are written into a manifest that lands in every user's
+// OpenClaw config, so shipping the old spelling would plant it where it is
+// hardest to take back. The same pattern guards konduit's live canary.
+const DEPLOYMENT_ID = /^[a-z0-9-]+\/[^:@]+(:[a-z0-9.-]+)?$/;
+const PRICING_UNIT = "micro_eur_per_million_tokens";
+const MICRO_PER_UNIT = 1_000_000;
+// konduit reports max_output_tokens as null for a deployment whose operator
+// publishes no cap. OpenClaw needs a number; this is a conservative one.
+const FALLBACK_MAX_TOKENS = 4096;
+// konduit serves a deployment while its status is active or deprecated —
+// deprecated is discouraged, not switched off, and a user whose config names
+// one would find it missing from the catalog if we dropped it. `retired`, and
+// any status this generator has not seen, is left out rather than advertised.
+const SERVABLE_STATUS = new Set(["active", "deprecated"]);
+function isServableChat(model) {
+    return model.modality === "chat" && SERVABLE_STATUS.has(model.deployment.status);
+}
+/** Servable chat deployments, sorted by id so two runs produce one diff. */
+export function mapCatalog(models) {
+    return models
+        .filter(isServableChat)
+        .map(mapModel)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * The id the manifest should name as its default: the one it already names
+ * while konduit still serves it — deprecated included, since it still answers —
+ * otherwise the first active deployment in id order, so a fresh manifest never
+ * defaults to a model whose operator is winding it down. Empty when konduit
+ * serves no chat deployment, which the generator refuses to write anyway.
+ */
+export function pickDefaultModel(models, current) {
+    const servable = models.filter(isServableChat).sort((a, b) => a.id.localeCompare(b.id));
+    if (servable.some((model) => model.id === current))
+        return current;
+    const active = servable.find((model) => model.deployment.status === "active");
+    return (active ?? servable[0])?.id ?? "";
+}
+export function mapModel(model) {
+    if (!DEPLOYMENT_ID.test(model.id)) {
+        throw new Error(`deployment id ${model.id} is not provider/model[:variant]; konduit does not accept '@' anywhere and this catalog will not publish it`);
+    }
+    if (model.pricing.unit !== PRICING_UNIT) {
+        throw new Error(`unexpected pricing unit ${model.pricing.unit} on ${model.id}; this generator understands ${PRICING_UNIT}`);
+    }
+    const input = model.pricing.input / MICRO_PER_UNIT;
+    const output = (model.pricing.output ?? model.pricing.input) / MICRO_PER_UNIT;
+    return {
+        id: model.id,
+        name: model.display_name,
+        reasoning: model.reasoning,
+        input: ["text"],
+        contextWindow: model.context_window,
+        maxTokens: model.max_output_tokens ?? FALLBACK_MAX_TOKENS,
+        cost: { input, output, cacheRead: 0, cacheWrite: 0 },
+        compat: {
+            supportsUsageInStreaming: model.capabilities.streaming,
+            supportsTools: model.capabilities.tools,
+            maxTokensField: "max_tokens",
+        },
+    };
+}

package/dist/catalog.js

@@ -5,6 +5,7 @@
 // vitest; ../openclaw.plugin.json is the package root from both.
 import { createRequire } from "node:module";
 import { buildManifestModelProviderConfig } from "openclaw/plugin-sdk/provider-catalog-shared";
+import { mapCatalog } from "./catalog-mapping.js";
 export const PROVIDER_ID = "konduit";
 export const manifest = createRequire(import.meta.url)("../openclaw.plugin.json");
 const catalog = manifest.modelCatalog.providers.konduit;
@@ -18,3 +19,93 @@ export function buildKonduitProvider() {
         models: structuredClone(buildManifestModelProviderConfig({ providerId: PROVIDER_ID, catalog: catalog }).models),
     };
 }
+/** The manifest's models by id, lowercased, the way OpenClaw compares model ids. */
+const modelsById = new Map(buildKonduitProvider().models.map((model) => [model.id.trim().toLowerCase(), model]));
+/**
+ * One manifest model as a model OpenClaw can route to, or nothing for an id
+ * konduit does not serve.
+ *
+ * OpenClaw reads a plugin's manifest catalog at resolution time only for
+ * plugins it ships itself; a plugin installed from ClawHub lives outside that
+ * set, so its models are listed but cannot be selected. This hook is the
+ * documented way out: the provider answers the lookup itself.
+ */
+export function resolveKonduitRuntimeModel(params) {
+    const model = modelsById.get(params.modelId.trim().toLowerCase());
+    return model && toKonduitRuntimeModel(model, params.baseUrl);
+}
+/**
+ * One catalog row as a model OpenClaw can route to. A user who pointed
+ * models.providers.konduit at another gateway keeps that baseUrl.
+ */
+export function toKonduitRuntimeModel(model, baseUrl) {
+    return {
+        ...structuredClone(model),
+        provider: PROVIDER_ID,
+        api: "openai-completions",
+        baseUrl: baseUrl?.trim() || KONDUIT_BASE_URL,
+        // The catalog type leaves name, cost, input and the caps optional; every
+        // row this plugin projects carries them, static or live.
+    };
+}
+/**
+ * konduit's own GET /v1/models rows as catalog entries — the same projection
+ * the manifest generator writes, run at discovery time.
+ *
+ * OpenClaw's generic mapper reads an OpenAI `/models` body, which carries an id
+ * and little else; konduit's carries the context window, the output cap, the
+ * capabilities and the price. Handing it the generic reader would list a
+ * deployment konduit added with guessed numbers, and would offer konduit's
+ * embedding deployment as something to chat with.
+ *
+ * A row this release cannot read keeps the entry the manifest already has for
+ * it, and a body with nothing readable in it leaves the manifest's list alone,
+ * because an empty catalog is how a provider disappears from the picker.
+ */
+export function projectKonduitLiveModels(rows, fallbackModels) {
+    const knownById = new Map(fallbackModels.map((model) => [model.id, model]));
+    const projected = new Map();
+    for (const row of rows) {
+        try {
+            // mapCatalog applies the servable-chat predicate, so a retired, embedding
+            // or image deployment drops out here rather than in a second copy of it.
+            for (const model of mapCatalog([row]))
+                projected.set(model.id, model);
+        }
+        catch {
+            const id = typeof row?.id === "string" ? row.id : undefined;
+            const known = id === undefined ? undefined : knownById.get(id);
+            if (known)
+                projected.set(known.id, known);
+        }
+    }
+    if (projected.size === 0)
+        return [...fallbackModels];
+    return [...projected.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+ * What the entry hands OpenClaw's live discovery. Declared here, beside the
+ * projection it runs, so it is exercised by the same tests.
+ */
+export const konduitLiveModelDiscovery = {
+    projectRows: (rows, fallback) => projectKonduitLiveModels(rows, fallback.models),
+};
+/**
+ * The deployment ids this release lists, for a message that has to name them.
+ * A copy: the caller must not be able to edit the manifest through it.
+ */
+export function listKonduitModelIds() {
+    return [...modelsById.values()].map((model) => model.id);
+}
+/**
+ * The id konduit serves that a user most likely meant. Only one case is worth
+ * guessing: a deployment written without its `:variant`, which is the id konduit
+ * publishes for a model served in one precision and the spelling a user copies
+ * from somewhere else. Anything further from the truth gets the list instead.
+ */
+export function suggestKonduitModelId(modelId) {
+    const wanted = modelId.trim().toLowerCase();
+    if (!wanted || wanted.includes(":"))
+        return;
+    return listKonduitModelIds().find((id) => id.toLowerCase().split(":")[0] === wanted);
+}

package/dist/discovery.js

@@ -0,0 +1,48 @@
+// konduit's catalog at resolution time. The manifest answers the models a
+// release knows; this module answers the ones konduit started serving since —
+// so a deployment that shows up in the model list can also be selected, rather
+// than listing and then failing with "Unknown model".
+import { getCachedLiveCatalogValue } from "openclaw/plugin-sdk/provider-catalog-shared";
+import { readProviderJsonResponse } from "openclaw/plugin-sdk/provider-http";
+import { fetchJson } from "openclaw/plugin-sdk/provider-usage";
+import { PROVIDER_ID, projectKonduitLiveModels, toKonduitRuntimeModel } from "./catalog.js";
+const LABEL = "konduit model catalog";
+// A minute, the same window OpenClaw's own live discovery keeps: long enough
+// that a busy session reads the catalog once, short enough that a deployment
+// konduit adds is usable while the user is still looking for it.
+const TTL_MS = 60_000;
+const TIMEOUT_MS = 5_000;
+/**
+ * The deployment konduit serves under this id, or nothing.
+ *
+ * Nothing is also the answer when konduit refuses the catalog or cannot be
+ * reached: a model lookup is not the place to surface that, and the request the
+ * user actually made reports it with its own status.
+ */
+export async function resolveKonduitLiveModel(lookup) {
+    const baseUrl = lookup.baseUrl.trim().replace(/\/+$/, "");
+    if (!baseUrl || !lookup.apiKey)
+        return;
+    const wanted = lookup.modelId.trim().toLowerCase();
+    try {
+        const models = await getCachedLiveCatalogValue({
+            keyParts: [PROVIDER_ID, "live-models", baseUrl, lookup.apiKey],
+            ttlMs: TTL_MS,
+            load: async () => await readServableModels(baseUrl, lookup),
+            shouldCache: (models) => models.length > 0,
+        });
+        const model = models.find((candidate) => candidate.id.trim().toLowerCase() === wanted);
+        return model && toKonduitRuntimeModel(model, baseUrl);
+    }
+    catch {
+        return;
+    }
+}
+/** GET {baseUrl}/models, projected the way the manifest generator projects it. */
+async function readServableModels(baseUrl, lookup) {
+    const response = await fetchJson(`${baseUrl}/models`, { headers: { Authorization: `Bearer ${lookup.apiKey}`, Accept: "application/json" } }, lookup.timeoutMs ?? TIMEOUT_MS, lookup.fetchFn ?? fetch);
+    if (!response.ok)
+        throw new Error(`${LABEL}: HTTP ${response.status}`);
+    const body = await readProviderJsonResponse(response, LABEL);
+    return projectKonduitLiveModels(Array.isArray(body.data) ? body.data : [], []);
+}

package/dist/index.js

@@ -2,7 +2,8 @@
 // API, plus the two hooks that put the organisation's balance and limits on the
 // provider card. Shape follows OpenClaw's bundled extensions/deepseek.
 import { defineSingleProviderPluginEntry, } from "openclaw/plugin-sdk/provider-entry";
-import { buildKonduitProvider, manifest, PROVIDER_ID } from "./catalog.js";
+import { buildKonduitProvider, konduitLiveModelDiscovery, KONDUIT_BASE_URL, listKonduitModelIds, manifest, PROVIDER_ID, resolveKonduitRuntimeModel, suggestKonduitModelId, } from "./catalog.js";
+import { resolveKonduitLiveModel } from "./discovery.js";
 import { fetchKonduitUsage, resolveBaseUrl } from "./usage.js";
 export default defineSingleProviderPluginEntry({
     id: PROVIDER_ID,
@@ -20,10 +21,50 @@ export default defineSingleProviderPluginEntry({
             // A user who configured models.providers.konduit.baseUrl keeps it.
             allowExplicitBaseUrl: true,
             // GET {baseUrl}/models: a deployment konduit adds appears without a plugin
-            // release, at cost zero until the generator writes its price.
-            liveModelDiscovery: true,
+            // release. konduit's catalog carries the context window, the output cap,
+            // the capabilities and the price, so the rows are read here rather than
+            // by OpenClaw's generic reader, which would only find an id.
+            liveModelDiscovery: konduitLiveModelDiscovery,
             discoveryMode: "strict",
         },
+        // OpenClaw reads a manifest catalog at model-resolution time only for the
+        // plugins it ships itself. Without this hook a ClawHub install lists its
+        // models and then fails to select one: "Unknown model: konduit/…".
+        resolveDynamicModel: ({ modelId, providerConfig }) => resolveKonduitRuntimeModel({ modelId, ...(providerConfig?.baseUrl ? { baseUrl: providerConfig.baseUrl } : {}) }),
+        // The async half of the same answer: a deployment konduit started serving
+        // after this release is in konduit's catalog and not in the manifest, and
+        // listing it without being able to select it is the bug one level up.
+        prepareDynamicModel: async ({ modelId, providerConfig, config, agentDir, workspaceDir, authProfileId }) => {
+            const baseUrl = providerConfig?.baseUrl;
+            const listed = resolveKonduitRuntimeModel({ modelId, ...(baseUrl ? { baseUrl } : {}) });
+            if (listed)
+                return listed;
+            // The key lives in OpenClaw's auth store; this is the SDK's way in.
+            const { resolveApiKeyForProvider } = await import("openclaw/plugin-sdk/provider-auth-runtime");
+            const apiKey = (await resolveApiKeyForProvider({
+                provider: PROVIDER_ID,
+                cfg: config,
+                ...(agentDir ? { agentDir } : {}),
+                ...(workspaceDir ? { workspaceDir } : {}),
+                ...(authProfileId ? { profileId: authProfileId, lockedProfile: true } : {}),
+            }))?.apiKey;
+            if (!apiKey)
+                return;
+            return await resolveKonduitLiveModel({
+                modelId,
+                baseUrl: baseUrl?.trim() || KONDUIT_BASE_URL,
+                apiKey,
+            });
+        },
+        // OpenClaw's generic advice for an unknown model is to register it under
+        // models.providers, which is not how this plugin is used: konduit publishes
+        // its own catalog, so the answer is what konduit serves.
+        buildUnknownModelHint: ({ modelId }) => {
+            const suggestion = suggestKonduitModelId(modelId);
+            const named = suggestion ? `konduit serves that model as "${suggestion}".` : `konduit serves no deployment called "${modelId}".`;
+            return `${named} Deployment ids are provider/model[:variant]; \`openclaw models list --provider konduit\` lists the ${listKonduitModelIds().length} this release knows, and konduit's own catalog is read at runtime for the rest.`;
+        },
+        buildMissingAuthMessage: () => 'Mint a konduit API key at https://console.konduit.eu, then run `openclaw models auth paste-api-key --provider konduit` — or set KONDUIT_API_KEY. A key with no scopes works; the provider card also needs `usage:read`.',
         // Both hooks are required for OpenClaw to poll this provider's usage at
         // all; a plugin with only fetchUsageSnapshot is not auto-discovered.
         resolveUsageAuth: async (ctx) => {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "konduit",
   "name": "konduit",
   "description": "European AI inference through konduit, with live balance and rate limits.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "categories": [
     "models"
   ],
@@ -28,7 +28,7 @@
           {
             "id": "hetzner/qwen3.6-35b-a3b:fp8",
             "name": "Qwen3.6 35B A3B",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -49,7 +49,7 @@
           {
             "id": "hetzner/qwen3.8-27b",
             "name": "Qwen3.8 27B",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -70,7 +70,7 @@
           {
             "id": "scaleway/deepseek-v4-flash-0731",
             "name": "DeepSeek V4 Flash 0731",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -91,7 +91,7 @@
           {
             "id": "scaleway/gemma-4-26b-a4b-it",
             "name": "Gemma 4 26B A4B IT",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -112,7 +112,7 @@
           {
             "id": "scaleway/glm-5.2",
             "name": "GLM-5.2",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -133,7 +133,7 @@
           {
             "id": "scaleway/gpt-oss-120b",
             "name": "GPT-OSS 120B",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -280,7 +280,7 @@
           {
             "id": "scaleway/qwen3.5-397b-a17b",
             "name": "Qwen3.5 397B A17B",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],
@@ -301,7 +301,7 @@
           {
             "id": "scaleway/qwen3.6-35b-a3b",
             "name": "Qwen3.6 35B A3B",
-            "reasoning": false,
+            "reasoning": true,
             "input": [
               "text"
             ],

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@konduiteu/openclaw",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenClaw provider plugin for konduit: European inference, with live balance and rate limits on the provider card.",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/schnaq/openclaw-konduit"
+    "url": "git+https://github.com/schnaq/openclaw-konduit.git"
   },
   "homepage": "https://konduit.eu",
   "engines": {