@cjhyy/code-shell-core 0.7.1 → 0.8.1

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.js

@@ -74,17 +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);
+        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");

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.js

@@ -21,7 +21,7 @@ import { notificationQueue } from "./agent-notifications.js";
 import { backgroundJobRegistry } from "./background-jobs.js";
 import { logger } from "../../logging/logger.js";
 import { getVideoProvider, DEFAULT_VIDEO_MODEL, } from "./video-providers.js";
-import { getImageUploader, isHttpUrl } from "./image-uploader.js";
+import { getImageUploader, isHttpUrl, } from "./image-uploader.js";
 import { effectiveApiKey } from "./generate-image.js";
 import { getMergedCatalog, findCatalogEntry } from "../../model-catalog/index.js";
 import { genInstancesFromConnections } from "../../model-catalog/gen-connections.js";
@@ -78,7 +78,10 @@ export const generateVideoToolDef = {
                 description: "Video provider kind to use. Defaults to the first configured video provider.",
             },
             model: { type: "string", description: "Video model id. Defaults to the provider's default." },
-            image: { type: "string", description: "Image URL (http/https) for image-to-video. When set, an image-to-video model is used." },
+            image: {
+                type: "string",
+                description: "Image URL (http/https) for image-to-video. When set, an image-to-video model is used.",
+            },
             images: {
                 type: "array",
                 items: { type: "string" },
@@ -87,7 +90,7 @@ export const generateVideoToolDef = {
             videos: {
                 type: "array",
                 items: { type: "string" },
-                description: "Reference/continuation video URLs (http/https only — NOT local paths) for video extension. Forces reference-to-video (Seedance model required). Up to 3. Refer to them in prompt as @Video1, @Video2 (e.g. \"continue from @Video1\").",
+                description: 'Reference/continuation video URLs (http/https only — NOT local paths) for video extension. Forces reference-to-video (Seedance model required). Up to 3. Refer to them in prompt as @Video1, @Video2 (e.g. "continue from @Video1").',
             },
         },
         required: ["prompt"],
@@ -184,7 +187,10 @@ function resolveVideoProvider(cwd, preferKind) {
         const list = genInstancesFromConnections(conns, (Array.isArray(creds) ? creds : []), getMergedCatalog(), "video");
         const def = settings.defaults?.video;
         const usable = (p) => !!p.apiKey && getVideoProvider(p.kind) !== null;
-        const credsOf = (p) => ({ baseUrl: p.baseUrl, apiKey: p.apiKey });
+        const credsOf = (p) => ({
+            baseUrl: p.baseUrl,
+            apiKey: p.apiKey,
+        });
         if (preferKind) {
             const chosen = list.find((p) => (p.id === preferKind || p.kind === preferKind) && usable(p));
             if (chosen)
@@ -202,7 +208,10 @@ function resolveVideoProvider(cwd, preferKind) {
     if (videoGen?.providers?.length) {
         const list = videoGen.providers;
         const usable = (p) => !!effectiveApiKey(p, list) && getVideoProvider(p.kind) !== null;
-        const credsOf = (p) => ({ baseUrl: p.baseUrl, apiKey: effectiveApiKey(p, list) });
+        const credsOf = (p) => ({
+            baseUrl: p.baseUrl,
+            apiKey: effectiveApiKey(p, list),
+        });
         if (preferKind) {
             const chosen = list.find((p) => (p.id === preferKind || p.kind === preferKind) && usable(p));
             if (chosen)
@@ -220,7 +229,8 @@ function resolveVideoProvider(cwd, preferKind) {
     // Back-compat: scan legacy LLM providers[] for a video-capable kind. The
     // field was dropped from the schema; un-migrated settings.json still carry it
     // via .passthrough(), so read it through an inline cast.
-    const legacyProviders = settings.providers ?? [];
+    const legacyProviders = settings
+        .providers ?? [];
     const kinds = preferKind ? [preferKind] : VIDEO_PROVIDER_KINDS;
     for (const kind of kinds) {
         const provider = legacyProviders.find((p) => p.kind === kind);
@@ -290,7 +300,15 @@ export async function generateVideoTool(args, ctx) {
     const norm = await __normalizeImagesForTests(imagesArg, image, uploader, { baseUrl: creds.baseUrl, apiKey: creds.apiKey }, ctx?.signal);
     if (!norm.ok)
         return `Error: ${norm.error}`;
-    const submit = await adapter.submit({ prompt, model, image: undefined, images: norm.urls, videos: videosArg, creds, signal: ctx?.signal });
+    const submit = await adapter.submit({
+        prompt,
+        model,
+        image: undefined,
+        images: norm.urls,
+        videos: videosArg,
+        creds,
+        signal: ctx?.signal,
+    });
     if (!submit.ok) {
         return `Error submitting video job: ${submit.error}`;
     }
@@ -333,6 +351,7 @@ export async function generateVideoTool(args, ctx) {
         clearTimeout(totalTimer);
         ctx?.signal?.removeEventListener("abort", onTurnAbort);
     });
+    ctx?.runYield?.request("background_notification");
     return [
         `Video generation started in the background.`,
         `job_id: ${jobId} (internal — do not show to user)`,

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

@@ -135,7 +135,7 @@ export async function grepTool(args, ctx) {
             if (isCommandNotFound(rgErr) || isCommandNotFound(grepErr)) {
                 return await runNodeGrep(pattern, searchPath, fileGlob, context, maxResults, outputMode, caseInsensitive, ctx?.signal);
             }
-            throw new Error(`Error in search: ${grepErr.message}`);
+            throw new Error(`Error in search: ${grepErr.message}`, { cause: grepErr });
         }
     }
 }
@@ -227,7 +227,7 @@ async function runNodeGrep(pattern, path, fileGlob, context, maxResults, outputM
         regex = new RegExp(pattern, caseInsensitive ? "i" : "");
     }
     catch (err) {
-        throw new Error(`Error in search: ${err.message}`);
+        throw new Error(`Error in search: ${err.message}`, { cause: err });
     }
     const matches = [];
     await walkTextFiles(path, fileGlob, async (file) => {

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

@@ -10,7 +10,13 @@ export function isHttpUrl(s) {
 }
 function mimeFromName(name) {
     const ext = name.toLowerCase().split(".").pop() ?? "";
-    const map = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
+    const map = {
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        webp: "image/webp",
+        gif: "image/gif",
+    };
     return map[ext] ?? "application/octet-stream";
 }
 export class FalStorageUploader {

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

@@ -1,7 +1,7 @@
 /**
  * Built-in tool registration.
  */
-import type { RegisteredTool } from "../../types.js";
+import type { PermissionRule, RegisteredTool } from "../../types.js";
 import type { ToolVisibilityContext } from "../context.js";
 /**
  * Tool executor signature.
@@ -51,14 +51,39 @@ export type BuiltinToolGuard = (ctx: ToolVisibilityContext) => boolean;
 export interface BuiltinTool {
     definition: RegisteredTool;
     execute: BuiltinToolFn;
+    exposure: BuiltinToolExposure;
+}
+export interface BuiltinToolExposure {
+    /** Empty means explicit enableBuiltinTools-only. */
+    presetTags: readonly string[];
+    /** Execution policy is explicit and never inferred from permissionDefault. */
+    defaultPermissionRules?: readonly PermissionRule[];
+    /** Prompt sections enabled whenever at least one contributing tool is active. */
+    promptSections?: readonly string[];
+    /** Complete capability companions that must share every preset tag. */
+    requires?: readonly string[];
+    /** Shared by model visibility and the executor's second safety gate. */
+    availability?: BuiltinToolGuard;
+    /**
+     * Per-turn dynamic rewrite of the tool definition the model sees (e.g. a
+     * closed enum derived from run-scoped state). Pure; must not mutate `def`.
+     */
+    rewriteDefinition?: (def: import("../../types.js").ToolDefinition, ctx: ToolVisibilityContext) => import("../../types.js").ToolDefinition;
 }
 export declare const BUILTIN_TOOLS: BuiltinTool[];
-/**
- * Per-tool availability predicates. A tool listed here is filtered OUT of the
- * exposed toolDefs when its predicate returns false for the active cwd (see
- * engine.ts toolDefs assembly). Tools NOT listed here are always visible.
- * Keyed by the tool's `name` (must match the toolDef name).
- */
+export declare function validateBuiltinToolExposures(tools?: readonly BuiltinTool[]): void;
+/** Derive a preset's tool list and safe defaults from any composed tool catalog. */
+export declare function derivePresetExposure(tag: string, tools?: readonly BuiltinTool[]): {
+    builtinTools: string[];
+    defaultPermissionRules: PermissionRule[];
+};
+/** Backwards-compatible name for callers deriving only from the core catalog. */
+export declare function deriveBuiltinPresetExposure(tag: string): {
+    builtinTools: string[];
+    defaultPermissionRules: PermissionRule[];
+};
+export declare function deriveToolGatedPromptSections(tools?: readonly BuiltinTool[]): Record<string, string[]>;
+/** Compatibility view consumed by engine + executor; metadata is authoritative. */
 export declare const BUILTIN_TOOL_GUARDS: Map<string, BuiltinToolGuard>;
 /** UseCredential is available when the cwd's credential metadata has ≥1 entry. */
 export declare function isUseCredentialAvailable(cwd: string, settingsScope?: import("../../settings/manager.js").SettingsScope): boolean;