zcode-acp-server 0.1.0 → 0.3.0

package/dist/config/plugin-commands.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Plugin command discovery — reads enabled plugins from `~/.zcode/cli/config.json`
+ * and scans their `commands/*.md` frontmatter to build slash-command entries.
+ *
+ * Plugin commands (e.g. `/code-review`) are resolved by the ZCode backend's
+ * `customCommandPromptResolver` before the model sees them, so they work in
+ * app-server mode without bridge interception.
+ */
+/** A slash-command entry compatible with `sendAvailableCommands`. */
+export interface PluginCommandEntry {
+    name: string;
+    description: string;
+    input?: {
+        hint: string;
+    };
+}
+/**
+ * Read enabled plugin commands from `~/.zcode/cli/config.json` + the plugin
+ * cache directory. Returns entries suitable for `available_commands_update`.
+ *
+ * Best-effort: failures are logged and swallowed (returns []).
+ */
+export declare function loadPluginCommands(): PluginCommandEntry[];
+//# sourceMappingURL=plugin-commands.d.ts.map

package/dist/config/plugin-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-commands.d.ts","sourceRoot":"","sources":["../../src/config/plugin-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B;AA+BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,kBAAkB,EAAE,CAyDzD"}

package/dist/config/plugin-commands.js

@@ -0,0 +1,107 @@
+/**
+ * Plugin command discovery — reads enabled plugins from `~/.zcode/cli/config.json`
+ * and scans their `commands/*.md` frontmatter to build slash-command entries.
+ *
+ * Plugin commands (e.g. `/code-review`) are resolved by the ZCode backend's
+ * `customCommandPromptResolver` before the model sees them, so they work in
+ * app-server mode without bridge interception.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { compareVersions, log } from "../utils.js";
+/** Path to the ZCode CLI config (plugins, skills, mcp). */
+const CLI_CONFIG_PATH = path.join(homedir(), ".zcode", "cli", "config.json");
+/** Root of the plugin cache directory. */
+const PLUGIN_CACHE_DIR = path.join(homedir(), ".zcode", "cli", "plugins", "cache");
+/** Parse YAML-like frontmatter from a plugin command .md file. */
+function parseFrontmatter(content) {
+    const fm = {};
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return fm;
+    const lines = match[1].split(/\r?\n/);
+    for (const line of lines) {
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const key = line.slice(0, idx).trim();
+        // Strip surrounding quotes from the value (YAML scalar style).
+        let val = line.slice(idx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        if (key)
+            fm[key] = val;
+    }
+    return fm;
+}
+/**
+ * Read enabled plugin commands from `~/.zcode/cli/config.json` + the plugin
+ * cache directory. Returns entries suitable for `available_commands_update`.
+ *
+ * Best-effort: failures are logged and swallowed (returns []).
+ */
+export function loadPluginCommands() {
+    if (!existsSync(CLI_CONFIG_PATH) || !existsSync(PLUGIN_CACHE_DIR))
+        return [];
+    try {
+        const cfg = JSON.parse(readFileSync(CLI_CONFIG_PATH, "utf8"));
+        const enabled = cfg.plugins?.enabledPlugins ?? {};
+        const entries = [];
+        // enabledPlugins keys are "pluginName@marketplace"
+        for (const [pluginKey, enabledFlag] of Object.entries(enabled)) {
+            if (!enabledFlag)
+                continue;
+            const atIdx = pluginKey.indexOf("@");
+            if (atIdx <= 0)
+                continue;
+            const pluginName = pluginKey.slice(0, atIdx);
+            const marketplace = pluginKey.slice(atIdx + 1);
+            // Scan all versions of this plugin in the cache (use latest found).
+            const marketDir = path.join(PLUGIN_CACHE_DIR, marketplace);
+            if (!existsSync(marketDir))
+                continue;
+            const pluginDir = path.join(marketDir, pluginName);
+            if (!existsSync(pluginDir))
+                continue;
+            // Find the latest version directory.
+            let latestVersion = "";
+            for (const entry of readdirSync(pluginDir)) {
+                const vDir = path.join(pluginDir, entry);
+                if (statSync(vDir).isDirectory() && compareVersions(entry, latestVersion) > 0) {
+                    latestVersion = entry;
+                }
+            }
+            if (!latestVersion)
+                continue;
+            const commandsDir = path.join(pluginDir, latestVersion, "commands");
+            if (!existsSync(commandsDir))
+                continue;
+            for (const file of readdirSync(commandsDir)) {
+                if (!file.endsWith(".md"))
+                    continue;
+                const cmdPath = path.join(commandsDir, file);
+                const content = readFileSync(cmdPath, "utf8");
+                const fm = parseFrontmatter(content);
+                const name = file.replace(/\.md$/, "");
+                const description = fm["description"] ?? "";
+                if (!description)
+                    continue;
+                const entry = { name, description };
+                const hint = fm["argument-hint"];
+                if (hint)
+                    entry.input = { hint };
+                entries.push(entry);
+            }
+        }
+        log(`plugin-commands: loaded ${entries.length} plugin command(s)`);
+        return entries;
+    }
+    catch (e) {
+        log(`plugin-commands: load failed (${e instanceof Error ? e.message : String(e)})`);
+        return [];
+    }
+}
+//# sourceMappingURL=plugin-commands.js.map

package/dist/config/plugin-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-commands.js","sourceRoot":"","sources":["../../src/config/plugin-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAC/B,OAAO,EAAE,EACT,QAAQ,EACR,KAAK,EACL,aAAa,CACd,CAAC;AAEF,0CAA0C;AAC1C,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAChC,OAAO,EAAE,EACT,QAAQ,EACR,KAAK,EACL,SAAS,EACT,OAAO,CACR,CAAC;AAeF,kEAAkE;AAClE,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,EAAE,GAA2B,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC3D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,CAAC;YAAE,SAAS;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,+DAA+D;QAC/D,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IACE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC1C,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC1C,CAAC;YACD,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;QACD,IAAI,GAAG;YAAE,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAc,CAAC;QAC3E,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,cAAc,IAAI,EAAE,CAAC;QAClD,MAAM,OAAO,GAAyB,EAAE,CAAC;QAEzC,mDAAmD;QACnD,KAAK,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,WAAW;gBAAE,SAAS;YAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACrC,IAAI,KAAK,IAAI,CAAC;gBAAE,SAAS;YACzB,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC7C,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAE/C,oEAAoE;YACpE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;YAC3D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,SAAS;YACrC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YACnD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,SAAS;YAErC,qCAAqC;YACrC,IAAI,aAAa,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;gBACzC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,IAAI,eAAe,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC9E,aAAa,GAAG,KAAK,CAAC;gBACxB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,aAAa;gBAAE,SAAS;YAE7B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;YACpE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;gBAAE,SAAS;YAEvC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC5C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;gBAC7C,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC9C,MAAM,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBACvC,MAAM,WAAW,GAAG,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;gBAC5C,IAAI,CAAC,WAAW;oBAAE,SAAS;gBAC3B,MAAM,KAAK,GAAuB,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;gBACxD,MAAM,IAAI,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;gBACjC,IAAI,IAAI;oBAAE,KAAK,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAED,GAAG,CAAC,2BAA2B,OAAO,CAAC,MAAM,oBAAoB,CAAC,CAAC;QACnE,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CACD,iCAAiC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAC/E,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/config/provider-registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Build a provider-registry payload for `workspace/updateProviderRegistry`.
+ *
+ * The V4 backend doesn't auto-load providers from config.json — the host must
+ * push them via this RPC after `session/create`, otherwise third-party
+ * providers fail with `provider_not_configured` (misclassified as a network
+ * error after turn-retry exhausts). ZCode app does this from its
+ * ModelProviderService; the bridge mirrors it by reading config.json directly.
+ *
+ * Provider element schema (from the backend's `j7t` converter in zcode.cjs):
+ *   { providerId, apiKey?, apiKeyRequired?, apiFormat?, baseURL?, headers?,
+ *     kind?, label?, models?, providerOptions?, source? }
+ * `apiKey` is a discriminated union `{source:"inline", value:"<key>"}` — a
+ * bare string is rejected. `apiFormat` maps from `kind`:
+ *   anthropic → "anthropic-messages", openai-compatible → "openai-chat-completions".
+ */
+/** A model entry in config.json (`provider.<id>.models.<modelId>`). */
+export interface ModelEntry {
+    name?: string;
+    limit?: {
+        context?: number;
+        output?: number;
+    };
+    reasoning?: {
+        enabled?: boolean;
+        variants?: string[];
+        defaultVariant?: string;
+    };
+}
+/** Registry payload for `workspace/updateProviderRegistry`. */
+export interface ProviderRegistryPayload {
+    providers: ReadonlyArray<Record<string, unknown>>;
+    generatedAt: number;
+    revision: string;
+}
+/**
+ * Build a single model element from a config.json model entry.
+ *
+ * Beyond `{modelId}`, the backend's schema accepts label / contextWindow /
+ * maxOutputTokens / reasoning. `reasoning` is the important one: without it
+ * the backend falls back to the apiFormat's default thought levels (a 2-state
+ * enabled/disabled for anthropic-messages), losing the provider's real
+ * variants (e.g. max/high/low) — the session then shows a wrong thought-level
+ * dropdown. config.json's `variants`/`defaultVariant` map to the protocol's
+ * `levels`/`defaultLevel`.
+ *
+ * Exported: runtime-model.ts reuses it for the `runtimeModel` overlay — both
+ * paths must carry identical model definitions or the overlay (resume /
+ * setModel) silently downgrades the session back to the 2-state default.
+ */
+export declare function buildModelElement(modelId: string, m: ModelEntry): Record<string, unknown>;
+/**
+ * Build the registry payload from ALL providers in config.json.
+ *
+ * Unlike `loadAllModels` (dropdown, enabled-only), the registry pushes every
+ * configured provider so the backend recognises any of them when a session
+ * switches to it. The backend applies its own enable/availability rules.
+ */
+export declare function buildProviderRegistry(): ProviderRegistryPayload;
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/config/provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../../src/config/provider-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF;AAgBD,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezF;AAmCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,uBAAuB,CAe/D"}

package/dist/config/provider-registry.js

@@ -0,0 +1,128 @@
+/**
+ * Build a provider-registry payload for `workspace/updateProviderRegistry`.
+ *
+ * The V4 backend doesn't auto-load providers from config.json — the host must
+ * push them via this RPC after `session/create`, otherwise third-party
+ * providers fail with `provider_not_configured` (misclassified as a network
+ * error after turn-retry exhausts). ZCode app does this from its
+ * ModelProviderService; the bridge mirrors it by reading config.json directly.
+ *
+ * Provider element schema (from the backend's `j7t` converter in zcode.cjs):
+ *   { providerId, apiKey?, apiKeyRequired?, apiFormat?, baseURL?, headers?,
+ *     kind?, label?, models?, providerOptions?, source? }
+ * `apiKey` is a discriminated union `{source:"inline", value:"<key>"}` — a
+ * bare string is rejected. `apiFormat` maps from `kind`:
+ *   anthropic → "anthropic-messages", openai-compatible → "openai-chat-completions".
+ */
+import { readFileSync } from "node:fs";
+import { ZCODE_CREDS_PATH, log } from "../utils.js";
+/** Map config.json `kind` → backend `apiFormat`. */
+function apiFormatForKind(kind) {
+    if (!kind)
+        return undefined;
+    if (kind.includes("anthropic"))
+        return "anthropic-messages";
+    if (kind.includes("openai"))
+        return "openai-chat-completions";
+    return undefined;
+}
+/**
+ * Build a single model element from a config.json model entry.
+ *
+ * Beyond `{modelId}`, the backend's schema accepts label / contextWindow /
+ * maxOutputTokens / reasoning. `reasoning` is the important one: without it
+ * the backend falls back to the apiFormat's default thought levels (a 2-state
+ * enabled/disabled for anthropic-messages), losing the provider's real
+ * variants (e.g. max/high/low) — the session then shows a wrong thought-level
+ * dropdown. config.json's `variants`/`defaultVariant` map to the protocol's
+ * `levels`/`defaultLevel`.
+ *
+ * Exported: runtime-model.ts reuses it for the `runtimeModel` overlay — both
+ * paths must carry identical model definitions or the overlay (resume /
+ * setModel) silently downgrades the session back to the 2-state default.
+ */
+export function buildModelElement(modelId, m) {
+    const el = { modelId };
+    if (m.name)
+        el.label = m.name;
+    if (m.limit?.context)
+        el.contextWindow = m.limit.context;
+    if (m.limit?.output)
+        el.maxOutputTokens = m.limit.output;
+    const variants = m.reasoning?.variants ?? [];
+    if (m.reasoning?.enabled && variants.length > 0) {
+        const reasoning = {
+            enabled: true,
+            levels: variants.map((v) => ({ value: v, label: v })),
+        };
+        if (m.reasoning.defaultVariant)
+            reasoning.defaultLevel = m.reasoning.defaultVariant;
+        el.reasoning = reasoning;
+    }
+    return el;
+}
+/** Build a single provider element from a config.json entry. */
+function buildProviderElement(providerId, p) {
+    // models MUST be an array — the backend's strict schema rejects the object
+    // form ({modelId: {...}}) that config.json uses.
+    const models = Object.entries(p.models ?? {}).map(([modelId, m]) => buildModelElement(modelId, m ?? {}));
+    const el = {
+        providerId,
+        kind: p.kind,
+        apiFormat: apiFormatForKind(p.kind),
+        baseURL: p.options?.baseURL,
+        label: p.name ?? providerId,
+        models,
+        source: p.source ?? "custom",
+    };
+    if (p.options?.apiKeyRequired !== undefined) {
+        el.apiKeyRequired = p.options.apiKeyRequired;
+    }
+    // apiKey MUST be the inline union shape — a bare string is rejected by the
+    // backend's strict schema. When present, the backend stores it into its
+    // session secrets and resolves auth from there (no separate headers callback
+    // needed for these providers).
+    if (p.options?.apiKey) {
+        el.apiKey = { source: "inline", value: p.options.apiKey };
+    }
+    // Omit undefined values so the payload stays clean.
+    for (const k of Object.keys(el)) {
+        if (el[k] === undefined)
+            delete el[k];
+    }
+    return el;
+}
+/**
+ * Build the registry payload from ALL providers in config.json.
+ *
+ * Unlike `loadAllModels` (dropdown, enabled-only), the registry pushes every
+ * configured provider so the backend recognises any of them when a session
+ * switches to it. The backend applies its own enable/availability rules.
+ */
+export function buildProviderRegistry() {
+    const cfg = JSON.parse(readFileSync(ZCODE_CREDS_PATH, "utf8"));
+    const providers = Object.entries(cfg.provider ?? {}).map(([pid, p]) => buildProviderElement(pid, p ?? {}));
+    const generatedAt = Date.now();
+    // revision is a content hash; the backend skips unchanged revisions. A stable
+    // JSON hash over provider ids+kinds+baseURLs is enough — apiKey changes are
+    // rare and a generatedAt bump alone won't force re-apply (revision is the gate).
+    const revision = hashRevision(providers);
+    log(`provider-registry: built ${providers.length} provider(s) ` +
+        `(ids: ${providers.map((p) => p.providerId).join(", ") || "none"})`);
+    return { providers, generatedAt, revision };
+}
+/** Stable short hash over provider ids + kind + baseURL + models (revision gate). */
+function hashRevision(providers) {
+    const sig = providers
+        .map((p) => `${p.providerId}|${p.kind ?? ""}|${p.baseURL ?? ""}|${JSON.stringify(p.models ?? [])}`)
+        .sort()
+        .join("\n");
+    // FNV-1a 32-bit → hex; cheap, dependency-free, stable.
+    let h = 0x811c9dc5;
+    for (let i = 0; i < sig.length; i++) {
+        h ^= sig.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+//# sourceMappingURL=provider-registry.js.map

package/dist/config/provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.js","sourceRoot":"","sources":["../../src/config/provider-registry.ts"],"names":[],"mappings":"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"}

package/dist/config/runtime-model.d.ts

@@ -1,33 +1,69 @@
 /**
  * runtimeModel overlay plumbing.
  *
- * The backend resolves auth from its OAuth token store, so the `runtimeModel`
- * provider deliberately carries NO `apiKey` (the config.json apiKey is the
- * legacy plain key and has expired → 401). Two uses:
+ * The runtimeModel names the provider+model a session should use. For THIRD-
+ * PARTY providers it also carries `apiKey` as `{source:"inline", value:"<key>"}`;
+ * the backend resolves model-call auth from the overlay itself, so omitting it
+ * yields HTTP 401 "Missing API key". Builtin providers keep using their own
+ * OAuth/config auth and never inline a key. `apiFormat` mirrors `kind`.
  *
- *   1. Resume overlay (`buildResumeRuntimeModel`): a resumed session may carry
- *      a stale provider id in its history that the backend can no longer
- *      authenticate. Sending the *current* enabled provider's runtimeModel at
- *      resume makes the backend overlay it and use its own OAuth creds.
+ * Two uses:
+ *
+ *   1. Resume/load overlay (`buildResumeRuntimeModel`): a resumed session may
+ *      carry a stale/revoked model in its history → send fails with "历史模型
+ *      不可用". The overlay pins the session onto the default model — the FIRST
+ *      enabled provider's FIRST model, the same one a fresh `session/new` lands
+ *      on — so resume never inherits the session's last-used (possibly
+ *      third-party / unavailable) model.
  *
  *   2. Model switch (`applyModelSwitch`): UI/slash model switching goes through
- *      `session/updateRuntimeModelConfig` with `applyModelSelection:true` (a
- *      runtime-only change, sidestepping `session/setModel`'s "no loaded config
- *      file" persistence failure).
+ *      `session/setModel` with both a `model` ref and a `runtimeModel` provider
+ *      definition (runtime-only via `persistAsWorkspaceLastUsed:false`).
+ *
+ * Note: a provider registry push (`workspace/updateProviderRegistry`) is ALSO
+ * required for the backend to recognise third-party providers at all — without
+ * it the turn fails with `provider_not_configured` before auth is even tried.
+ * See provider-registry.ts.
  */
+import { formatModelValue } from "./options.js";
+import type { ModelRef } from "./options.js";
 import type { ZcodeAcpServer } from "../server.js";
-/** Build a runtimeModel overlay object for the enabled provider. */
-export declare function buildRuntimeModel(modelId?: string, revision?: string): unknown | null;
-/** Build the resume-time overlay (current enabled provider, default model). */
+/**
+ * Build a runtimeModel overlay for the given provider+model.
+ *
+ * For THIRD-PARTY providers the overlay MUST carry `apiKey` as the inline union
+ * `{source:"inline", value:"<key>"}` — the backend resolves model-call auth from
+ * the runtimeModel itself, so omitting it yields HTTP 401 "Missing API key".
+ * (This was previously believed unnecessary; live probing proved otherwise.)
+ * Builtin providers resolve auth from their own OAuth/config store, so no
+ * apiKey is sent for them. `apiFormat` mirrors `kind` per the backend's catalog.
+ */
+export declare function buildRuntimeModel(ref: ModelRef, revision?: string): unknown | null;
+/**
+ * Build the resume-time overlay pinned to the default model: the FIRST enabled
+ * provider's FIRST model (the same one a fresh `session/new` lands on). This
+ * ensures resume never inherits the session's last-used model, which may be a
+ * now-unavailable third-party model (e.g. Nvidia) and cause "历史模型不可用".
+ */
 export declare function buildResumeRuntimeModel(): unknown | null;
 /**
- * Switch a session's model via session/updateRuntimeModelConfig.
+ * Switch a session's model via `session/setModel`.
+ *
+ * `value` is the configOption value: either `"providerId\modelId"` (encoded) or
+ * a legacy plain modelId (resolved to the first enabled builtin provider).
+ *
+ * Sends BOTH a `model` ref (the target) AND a `runtimeModel` (the full provider
+ * definition). The runtimeModel lets the backend register the provider into its
+ * workspace catalog (so even third-party / non-default models are recognised),
+ * while `model` names the selection. `persistAsWorkspaceLastUsed:false` keeps
+ * this a runtime-only change. Invalidates the model cache on success.
  *
- * Uses `applyModelSelection:true` so the change applies at runtime without
- * persistence — sidestepping `session/setModel`'s "no loaded config file"
- * failure. Invalidates the model cache on success. Returns true on success.
+ * NOTE: the older `session/updateRuntimeModelConfig` path returns `changed:false`
+ * on current backends without applying — `session/setModel` is the working
+ * protocol since the backend model-management refactor.
  */
-export declare function applyModelSwitch(server: ZcodeAcpServer, zcodeSid: string, modelId: string): Promise<boolean>;
+export declare function applyModelSwitch(server: ZcodeAcpServer, zcodeSid: string, value: string): Promise<boolean>;
 /** Invalidate the session-level model cache after a switch. */
 export declare function invalidateModelCache(server: ZcodeAcpServer, zcodeSid: string): void;
+export { formatModelValue };
 //# sourceMappingURL=runtime-model.d.ts.map

package/dist/config/runtime-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-model.d.ts","sourceRoot":"","sources":["../../src/config/runtime-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAoDnD,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAW,GAAG,OAAO,GAAG,IAAI,CAcvF;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,OAAO,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEnF"}
+{"version":3,"file":"runtime-model.d.ts","sourceRoot":"","sources":["../../src/config/runtime-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAEL,gBAAgB,EAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAWnD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,SAAW,GAAG,OAAO,GAAG,IAAI,CAkCpF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,GAAG,IAAI,CAOxD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEnF;AAGD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}