@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/builtin/edit-model-catalog.js

@@ -8,15 +8,70 @@
  * Edit, by design). See docs/.../2026-06-15-unified-model-catalog-design.md §7.
  */
 import { randomBytes } from "node:crypto";
-import { userCatalogPath } from "../../model-catalog/index.js";
+import { BUILTIN_CATALOG, getMergedCatalog, loadUserCatalog, userCatalogPath, } from "../../model-catalog/index.js";
 import { saveCatalogEntry } from "../../model-catalog/save-entry.js";
-import { catalogEntrySchema } from "../../model-catalog/types.js";
+import { catalogEntrySchema, modelPresetSchema, } from "../../model-catalog/types.js";
+import { upsertModelPreset } from "../../model-catalog/upsert.js";
+import { PROVIDER_KINDS } from "../../llm/provider-kinds.js";
+const CATALOG_ADAPTER_KINDS = [...Object.keys(PROVIDER_KINDS), "fal"].join("|");
+/**
+ * Recognise first-party provider hosts so the catalog tool can reject the
+ * dangerous-but-schema-valid combination that caused an OpenRouter model to be
+ * sent to api.openai.com. Unknown/custom hosts remain allowed.
+ */
+function inferProviderKindFromBaseUrl(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).host.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    for (const [kind, meta] of Object.entries(PROVIDER_KINDS)) {
+        if (!meta.defaultBaseUrl)
+            continue;
+        try {
+            if (new URL(meta.defaultBaseUrl).host.toLowerCase() === host)
+                return kind;
+        }
+        catch {
+            // A future custom kind may intentionally have no parseable default URL.
+        }
+    }
+    return undefined;
+}
+function providerIdentityError(entry) {
+    if (entry.tag !== "text")
+        return undefined;
+    const inferred = inferProviderKindFromBaseUrl(entry.defaultBaseUrl);
+    if (!inferred || inferred === "custom" || entry.adapterKind === inferred)
+        return undefined;
+    const protocolHint = inferred === "anthropic" ? "anthropic-style" : "openai-compat";
+    return (`provider mismatch: defaultBaseUrl points to ${inferred}, but adapterKind is ` +
+        `"${entry.adapterKind}". Use adapterKind="${inferred}" and ` +
+        `protocol="${protocolHint}". adapterKind identifies the provider/gateway account; ` +
+        `protocol only identifies the HTTP wire format.`);
+}
+let modelCatalogChangedSink = null;
+export function setModelCatalogChangedSink(sink) {
+    modelCatalogChangedSink = sink;
+}
+function fireModelCatalogChanged() {
+    try {
+        modelCatalogChangedSink?.();
+    }
+    catch {
+        // Host notification is best-effort; the catalog write itself succeeded.
+    }
+}
 export const editModelCatalogToolDef = {
     name: "EditModelCatalog",
-    description: "Add or update a provider/model template in the user model catalog so it " +
-        "appears in the connection page (text/image/video). Keyed by `id`: a new id " +
-        "adds a provider, an existing id replaces that user-catalog entry. Backs up " +
-        "the file before writing and " +
+    description: "Add a model to an existing provider, or add/replace a complete provider template, " +
+        "in the user model catalog so it appears in the connection page " +
+        "(text/image/video/audio). Prefer operation='upsertModel' whenever the provider " +
+        "already exists: it preserves all existing/built-in models and reuses that provider's " +
+        "credentials. Use operation='upsertProvider' only for a genuinely new provider/endpoint " +
+        "or an intentional full provider override. Backs up the file before writing and " +
         "validates the entry. Use after researching a model's real facts (id, context " +
         "window, supported params, modalities) — do NOT guess; verify against the " +
         "provider's official docs first (see the model-fact-finder skill). Does NOT set " +
@@ -24,23 +79,58 @@ export const editModelCatalogToolDef = {
     inputSchema: {
         type: "object",
         properties: {
+            operation: {
+                type: "string",
+                enum: ["upsertModel", "upsertProvider"],
+                description: "upsertModel appends/updates one model inside an existing provider; " +
+                    "upsertProvider saves a complete provider template. Defaults from the supplied fields.",
+            },
+            providerId: {
+                type: "string",
+                description: "Existing provider id for upsertModel, e.g. 'openrouter'. Do not create a " +
+                    "provider-per-model id such as 'openrouter-kimi'.",
+            },
+            modelPreset: {
+                type: "object",
+                description: "One complete ModelPreset for upsertModel: {value, label?, maxContextTokens?, " +
+                    "maxOutputTokens?, supportsVision?, params?[]}. Existing model value updates in " +
+                    "place; a new value appends without hiding the provider's other models.",
+            },
+            setAsDefault: {
+                type: "boolean",
+                description: "For upsertModel, also make this model the provider template default.",
+            },
             entry: {
                 type: "object",
-                description: "A full CatalogEntry. Required: id, tag (text|image|video), adapterKind " +
-                    "(an already-wired adapter: openai|anthropic|google|fal), displayName, " +
+                description: "For upsertProvider only: a full CatalogEntry. Required: id, tag " +
+                    "(text|image|video|audio), adapterKind " +
+                    `(the actual provider/gateway identity: ${CATALOG_ADAPTER_KINDS}), displayName, ` +
                     "description, defaultBaseUrl. Optional: protocol (openai-compat|anthropic-style), " +
                     "defaultModel, needsKey, signupUrl, test, modelPresets[] (each {value, label?, " +
                     "maxContextTokens?, maxOutputTokens?, supportsVision?, params?[]}). Each param: " +
                     "{name, label?, control (enum|number|toggle|text), options?[], min?, max?, default?, " +
                     "doc?, wire?{field}}. Fill maxContextTokens with the model's REAL window; declare " +
-                    "params per-model (only what that model supports). To keep a custom provider " +
-                    "beside a built-in one, use a distinct id.",
+                    "params per-model (only what that model supports). IMPORTANT: adapterKind is NOT " +
+                    "the wire protocol. OpenRouter must use adapterKind='openrouter' with " +
+                    "protocol='openai-compat'; never use adapterKind='openai' merely because an endpoint " +
+                    "is OpenAI-compatible. Adding a model to OpenRouter is operation='upsertModel' with " +
+                    "providerId='openrouter', not a new provider entry. For genuinely distinct custom " +
+                    "providers, retain the real provider's adapterKind so credentials and capability " +
+                    "rules stay in the correct provider family.",
             },
         },
-        required: ["entry"],
     },
 };
 export async function editModelCatalogTool(args) {
+    const operation = args.operation ??
+        (args.providerId !== undefined || args.modelPreset !== undefined
+            ? "upsertModel"
+            : "upsertProvider");
+    if (operation === "upsertModel")
+        return upsertExistingProviderModel(args);
+    if (operation !== "upsertProvider") {
+        return "Error: `operation` must be `upsertModel` or `upsertProvider`.";
+    }
     const entry = args.entry;
     if (!entry || typeof entry !== "object") {
         return "Error: `entry` (a CatalogEntry object) is required.";
@@ -49,6 +139,9 @@ export async function editModelCatalogTool(args) {
     if (!parsed.success) {
         return `Error: invalid catalog entry: ${parsed.error.issues.map((i) => i.message).join("; ")}`;
     }
+    const identityError = providerIdentityError(parsed.data);
+    if (identityError)
+        return `Error: ${identityError}`;
     const stamp = `${Date.now()}-${randomBytes(3).toString("hex")}`;
     const r = saveCatalogEntry(parsed.data, {
         path: userCatalogPath(),
@@ -56,8 +149,75 @@ export async function editModelCatalogTool(args) {
     });
     if (!r.ok)
         return `Error: ${r.error}`;
+    fireModelCatalogChanged();
     return summarizeWrite(parsed.data, r.action ?? "added", r.backup);
 }
+async function upsertExistingProviderModel(args) {
+    const providerId = typeof args.providerId === "string" ? args.providerId.trim() : "";
+    if (!providerId)
+        return "Error: `providerId` is required for `upsertModel`.";
+    const parsedPreset = modelPresetSchema.safeParse(args.modelPreset);
+    if (!parsedPreset.success) {
+        return `Error: invalid model preset: ${parsedPreset.error.issues.map((issue) => issue.message).join("; ")}`;
+    }
+    const builtin = BUILTIN_CATALOG.find((entry) => entry.id === providerId);
+    const userEntry = loadUserCatalog().find((entry) => entry.id === providerId);
+    const provider = userEntry ?? builtin;
+    if (!provider) {
+        return (`Error: provider "${providerId}" does not exist. ` +
+            "Create it first with operation=`upsertProvider`.");
+    }
+    const effective = getMergedCatalog().find((entry) => entry.id === providerId) ?? provider;
+    const existed = effective.modelPresets?.some((preset) => preset.value === parsedPreset.data.value);
+    // For built-ins, the user file stores only model-level additions/overrides.
+    // getMergedCatalog layers these over the current shipped presets, so app
+    // upgrades can add models without being frozen by a full user override.
+    const storedPresets = builtin ? (userEntry?.modelPresets ?? []) : (provider.modelPresets ?? []);
+    const nextEntry = {
+        ...(builtin ?? provider),
+        ...(userEntry ?? {}),
+        ...(builtin ? { modelPresetsMode: "merge" } : {}),
+        ...(args.setAsDefault === true ? { defaultModel: parsedPreset.data.value } : {}),
+        modelPresets: upsertModelPreset(storedPresets, parsedPreset.data),
+    };
+    const identityError = providerIdentityError(nextEntry);
+    if (identityError)
+        return `Error: ${identityError}`;
+    const stamp = `${Date.now()}-${randomBytes(3).toString("hex")}`;
+    const result = saveCatalogEntry(nextEntry, { path: userCatalogPath(), stamp });
+    if (!result.ok)
+        return `Error: ${result.error}`;
+    fireModelCatalogChanged();
+    return summarizeModelWrite(nextEntry, parsedPreset.data, existed ? "updated" : "added", result.backup);
+}
+function summarizeModelWrite(entry, preset, action, backup) {
+    const lines = [
+        `✅ ${action === "updated" ? "Updated" : "Added"} model "${preset.value}" in provider "${entry.id}".`,
+        `adapter: ${entry.adapterKind} | baseUrl: ${entry.defaultBaseUrl}`,
+        `merge: existing provider models preserved${entry.defaultModel === preset.value ? " | provider default: yes" : ""}`,
+    ];
+    const limits = [
+        preset.maxContextTokens ? `ctx ${preset.maxContextTokens}` : "",
+        preset.maxOutputTokens ? `out ${preset.maxOutputTokens}` : "",
+    ]
+        .filter(Boolean)
+        .join(", ");
+    if (limits)
+        lines.push(`limits: ${limits}`);
+    for (const param of preset.params ?? []) {
+        const details = param.control === "enum"
+            ? ` options=[${param.options?.join(", ") ?? ""}]`
+            : param.control === "number"
+                ? ` range=${param.min ?? "?"}..${param.max ?? "?"}`
+                : "";
+        const defaultValue = param.default !== undefined ? ` default=${JSON.stringify(param.default)}` : "";
+        lines.push(`- ${param.name} (${param.control})${details}${defaultValue}`);
+    }
+    lines.push(`Written to ${userCatalogPath()}.` + (backup ? ` Backup: ${backup}.` : ""));
+    lines.push("Hot-reloads — the connection page refreshes after this write.");
+    lines.push("⚠️ Relay this summary to the user and ask them to verify the model facts against official docs.");
+    return lines.join("\n");
+}
 /**
  * Build a structured completion summary so the user can SEE exactly what was
  * written and catch a wrong value at a glance — every param's options/default
@@ -96,7 +256,7 @@ function summarizeWrite(entry, action, backup) {
         }
     }
     lines.push(`\nWritten to ${userCatalogPath()}.` + (backup ? ` Backup: ${backup}.` : ""));
-    lines.push("Hot-reloads — the connection page refreshes once this turn completes.");
+    lines.push("Hot-reloads — the connection page refreshes after this write.");
     lines.push("⚠️ Relay this summary to the user and ask them to verify each param's options/default " +
         "match the provider's OFFICIAL docs — especially enum levels (a gateway's input aliases " +
         "are NOT the model's native values). To fix: edit this file directly, or ask me to.");

package/dist/tool-system/builtin/edit.d.ts

@@ -3,5 +3,6 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+import type { ToolFailure } from "./index.js";
 export declare const editToolDef: ToolDefinition;
-export declare function editTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function editTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | ToolFailure>;

package/dist/tool-system/builtin/edit.js

@@ -1,11 +1,12 @@
 /**
  * Built-in Edit file tool — exact string replacement.
  */
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { detectEol, toLf, applyEol } from "./eol.js";
+import { getFinalWritePathSnapshot, revalidateFinalWritePath, writeFileNoFollow, } from "../path-policy.js";
 export const editToolDef = {
     name: "Edit",
     description: "Perform exact string replacements in a file. " +
@@ -50,7 +51,11 @@ export async function editTool(args, ctx) {
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
-        const raw = await readFile(filePath, "utf-8");
+        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
+        const beforeRead = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        if ("error" in beforeRead)
+            return { ok: false, error: beforeRead.error };
+        const raw = await readFile(beforeRead.resolvedPath, "utf-8");
         // CRLF handling: detect the file's line ending, then match/replace in LF
         // space (the model emits LF, so a CRLF file would never match otherwise),
         // and write back in the ORIGINAL EOL so a CRLF file stays CRLF (no whole-
@@ -69,14 +74,13 @@ export async function editTool(args, ctx) {
                 return "Error: old_string is not unique in the file. Provide more context or use replace_all.";
             }
         }
-        const updatedLf = replaceAll
-            ? content.split(oldLf).join(newLf)
-            : content.replace(oldLf, newLf);
-        await writeFile(filePath, applyEol(updatedLf, eol), "utf-8");
+        const updatedLf = replaceAll ? content.split(oldLf).join(newLf) : content.replace(oldLf, newLf);
+        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        if ("error" in beforeWrite)
+            return { ok: false, error: beforeWrite.error };
+        await writeFileNoFollow(beforeWrite.resolvedPath, applyEol(updatedLf, eol));
         fileCache.invalidate(filePath);
-        const count = replaceAll
-            ? (content.split(oldLf).length - 1)
-            : 1;
+        const count = replaceAll ? content.split(oldLf).length - 1 : 1;
         // Generate a compact diff summary
         const oldLines = oldLf.split("\n");
         const newLines = newLf.split("\n");
@@ -84,7 +88,7 @@ export async function editTool(args, ctx) {
         return `Successfully edited ${filePath} (${count} replacement${count > 1 ? "s" : ""})\n${diffSummary}`;
     }
     catch (err) {
-        return `Error editing file: ${err.message}`;
+        return { ok: false, error: `Error editing file: ${err.message}` };
     }
 }
 function generateCompactDiff(oldLines, newLines, filePath) {

package/dist/tool-system/builtin/file-cache.d.ts

@@ -14,4 +14,6 @@ declare class FileStateCache {
     get size(): number;
 }
 export declare const fileCache: FileStateCache;
+/** Public capability seam: invalidate core's Read/Edit cache after an external file tool writes. */
+export declare function invalidateFileCache(filePath: string): void;
 export {};

package/dist/tool-system/builtin/file-cache.js

@@ -45,3 +45,7 @@ class FileStateCache {
     }
 }
 export const fileCache = new FileStateCache();
+/** Public capability seam: invalidate core's Read/Edit cache after an external file tool writes. */
+export function invalidateFileCache(filePath) {
+    fileCache.invalidate(filePath);
+}

package/dist/tool-system/builtin/generate-image.js

@@ -48,7 +48,10 @@ export function effectiveApiKey(inst, list) {
  */
 function resolveFromGenList(list, prefer, def) {
     const usable = (p) => !!p.apiKey && getImageProvider(p.kind) !== null;
-    const credsOf = (p) => ({ baseUrl: p.baseUrl, apiKey: p.apiKey });
+    const credsOf = (p) => ({
+        baseUrl: p.baseUrl,
+        apiKey: p.apiKey,
+    });
     if (prefer) {
         const chosen = list.find((p) => p.id === prefer);
         if (chosen && usable(chosen))
@@ -57,7 +60,9 @@ function resolveFromGenList(list, prefer, def) {
     }
     const preferred = def ? list.find((p) => p.id === def) : undefined;
     const chosen = (preferred && usable(preferred) ? preferred : undefined) ?? list.find(usable);
-    return chosen ? { kind: chosen.kind, creds: credsOf(chosen), defaultModel: chosen.defaultModel } : null;
+    return chosen
+        ? { kind: chosen.kind, creds: credsOf(chosen), defaultModel: chosen.defaultModel }
+        : null;
 }
 const DEFAULT_SIZE = "1024x1024";
 const DEFAULT_QUALITY = "auto";
@@ -91,12 +96,12 @@ export const generateImageToolDef = {
             provider: {
                 type: "string",
                 description: "Image provider to use. With imageGen configured, this is the instance `id` " +
-                    "(e.g. \"gemini\"); otherwise it's a provider kind (e.g. \"openai\"). " +
+                    '(e.g. "gemini"); otherwise it\'s a provider kind (e.g. "openai"). ' +
                     "Defaults to the configured default / first available. Only specify to override.",
             },
             model: {
                 type: "string",
-                description: "Image model id (e.g. \"gpt-image-2\"). Defaults to the provider's default model. " +
+                description: 'Image model id (e.g. "gpt-image-2"). Defaults to the provider\'s default model. ' +
                     "Only specify to override.",
             },
             referenceImages: {
@@ -146,7 +151,10 @@ function resolveImageProvider(cwd, prefer) {
     if (imageGen && Array.isArray(imageGen.providers) && imageGen.providers.length > 0) {
         const list = imageGen.providers;
         const usable = (p) => !!effectiveApiKey(p, list) && getImageProvider(p.kind) !== null;
-        const credsOf = (p) => ({ baseUrl: p.baseUrl, apiKey: effectiveApiKey(p, list) });
+        const credsOf = (p) => ({
+            baseUrl: p.baseUrl,
+            apiKey: effectiveApiKey(p, list),
+        });
         if (prefer) {
             // Explicit request — respect the user's intent. If that exact instance
             // isn't usable (no key / no adapter), DON'T silently use another one.
@@ -171,7 +179,8 @@ function resolveImageProvider(cwd, prefer) {
     // 2. Back-compat: resolve from legacy LLM providers[] by kind. The field was
     // dropped from the schema; un-migrated settings.json still carry it via the
     // schema's .passthrough(), so read it through an inline cast.
-    const legacyProviders = settings.providers ?? [];
+    const legacyProviders = settings
+        .providers ?? [];
     const kinds = prefer ? [prefer] : [...IMAGE_PROVIDER_KINDS];
     for (const kind of kinds) {
         if (!prefer && !IMAGE_PROVIDER_KINDS.includes(kind))
@@ -331,7 +340,7 @@ export async function generateImageTool(args, ctx) {
     if (!resolved) {
         return preferKind
             ? `Error: no image provider "${preferKind}" is available (unknown id/kind, or it has no API key). Configure it in your code-shell settings, or omit \`provider\` to use the default.`
-            : 'Error: no image provider available. Configure an image provider (including an apiKey) ' +
+            : "Error: no image provider available. Configure an image provider (including an apiKey) " +
                 "in your code-shell settings to use GenerateImage.";
     }
     const adapter = getImageProvider(resolved.kind);
@@ -363,9 +372,7 @@ export async function generateImageTool(args, ctx) {
         await writeFile(path, Buffer.from(result.b64, "base64"));
         // Name the provider/model actually used, so the user/agent knows which
         // image backend produced this (esp. when a default fell back to another).
-        const mode = inputImages?.length
-            ? ` from ${inputImages.length} reference image(s)`
-            : "";
+        const mode = inputImages?.length ? ` from ${inputImages.length} reference image(s)` : "";
         return `Generated image with ${resolved.kind} (${model})${mode}, saved to ${path}`;
     }
     catch (err) {

package/dist/tool-system/builtin/generate-video.d.ts

@@ -32,6 +32,10 @@ export declare function __normalizeImagesForTests(images: string[] | undefined,
     ok: false;
     error: string;
 }>;
+export declare function __setVideoPollingLimitsForTests(limits: {
+    maxPollMs: number;
+    requestTimeoutMs: number;
+} | null): void;
 export declare const generateVideoToolDef: ToolDefinition;
 export declare function __setVideoProviderForTests(p: VideoProvider | null): void;
 export declare function isGenerateVideoAvailable(cwd?: string, nowMs?: number): boolean;