@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/model-catalog/types.d.ts

@@ -0,0 +1,561 @@
+/**
+ * Model接入 Catalog — declarative provider templates (design doc:
+ * docs/superpowers/specs/2026-06-11-model-catalog-design.md).
+ *
+ * A {@link CatalogEntry} is a *template* the user can pick in the 连接 page to
+ * create a configured instance (stored in settings.imageGen/videoGen.providers[]).
+ * Catalog = "能配哪些"; providers[] = "配了哪些". The two are decoupled.
+ *
+ * `adapterKind` reuses the existing adapter selectors ("openai"/"google"/"fal")
+ * — the runtime getImageProvider/getVideoProvider switches and adapter classes
+ * are unchanged; the catalog only declares which template points at which
+ * already-wired adapter. `shape` is documentation/future only.
+ */
+import { z } from "zod";
+/**
+ * How the param maps onto the outgoing request body. `field` is the request
+ * field this param lands on — same param name can land differently per
+ * adapter (reasoning → `reasoning_effort` on OpenAI vs
+ * `thinking.budget_tokens` on Anthropic), so the divergence lives in data, not
+ * in `if (kind === ...)` branches in the engine. Minimal v1: field only.
+ */
+export declare const wireSpecSchema: z.ZodObject<{
+    field: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+}, {
+    field: string;
+}>;
+/**
+ * One **generic** declarative param — no special-casing per param. reasoning
+ * is not its own variant: it's `control: "enum"` (OpenAI effort levels) or
+ * `control: "number"` (Anthropic token budget), decided by the entry's data.
+ * The connection page renders by `switch(control)`; `doc` is woven into the
+ * tool description so the agent knows what a configured model accepts.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §3.2.
+ */
+export declare const paramSpecSchema: z.ZodObject<{
+    /** Logical name, e.g. "reasoning" / "size" / "quality" / "temperature". */
+    name: z.ZodString;
+    /** UI control label (falls back to `name`). */
+    label: z.ZodOptional<z.ZodString>;
+    control: z.ZodEnum<["enum", "number", "toggle", "text"]>;
+    /** control=enum allowed values, e.g. ["low","medium","high","xhigh"]. */
+    options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** control=number bounds. */
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    /** Natural-language usage note → injected into the tool description. */
+    doc: z.ZodOptional<z.ZodString>;
+    /** How this param lands on the request body. */
+    wire: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+    }, {
+        field: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    control: "number" | "text" | "enum" | "toggle";
+    options?: string[] | undefined;
+    default?: string | number | boolean | undefined;
+    label?: string | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    doc?: string | undefined;
+    wire?: {
+        field: string;
+    } | undefined;
+}, {
+    name: string;
+    control: "number" | "text" | "enum" | "toggle";
+    options?: string[] | undefined;
+    default?: string | number | boolean | undefined;
+    label?: string | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    doc?: string | undefined;
+    wire?: {
+        field: string;
+    } | undefined;
+}>;
+export type ParamSpec = z.infer<typeof paramSpecSchema>;
+/**
+ * A known model under an entry, carrying its own param schema
+ * (per-entry-per-model — the same modelId via OpenRouter vs the official API
+ * can expose different params, since gateways normalize differently).
+ */
+export declare const modelPresetSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    maxContextTokens: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    supportsVision: z.ZodOptional<z.ZodBoolean>;
+    /** Params this model supports; absent → no adjustable knobs. */
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Logical name, e.g. "reasoning" / "size" / "quality" / "temperature". */
+        name: z.ZodString;
+        /** UI control label (falls back to `name`). */
+        label: z.ZodOptional<z.ZodString>;
+        control: z.ZodEnum<["enum", "number", "toggle", "text"]>;
+        /** control=enum allowed values, e.g. ["low","medium","high","xhigh"]. */
+        options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** control=number bounds. */
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        /** Natural-language usage note → injected into the tool description. */
+        doc: z.ZodOptional<z.ZodString>;
+        /** How this param lands on the request body. */
+        wire: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+        }, {
+            field: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        control: "number" | "text" | "enum" | "toggle";
+        options?: string[] | undefined;
+        default?: string | number | boolean | undefined;
+        label?: string | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        doc?: string | undefined;
+        wire?: {
+            field: string;
+        } | undefined;
+    }, {
+        name: string;
+        control: "number" | "text" | "enum" | "toggle";
+        options?: string[] | undefined;
+        default?: string | number | boolean | undefined;
+        label?: string | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        doc?: string | undefined;
+        wire?: {
+            field: string;
+        } | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    params?: {
+        name: string;
+        control: "number" | "text" | "enum" | "toggle";
+        options?: string[] | undefined;
+        default?: string | number | boolean | undefined;
+        label?: string | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        doc?: string | undefined;
+        wire?: {
+            field: string;
+        } | undefined;
+    }[] | undefined;
+    supportsVision?: boolean | undefined;
+    maxOutputTokens?: number | undefined;
+    label?: string | undefined;
+    maxContextTokens?: number | undefined;
+}, {
+    value: string;
+    params?: {
+        name: string;
+        control: "number" | "text" | "enum" | "toggle";
+        options?: string[] | undefined;
+        default?: string | number | boolean | undefined;
+        label?: string | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        doc?: string | undefined;
+        wire?: {
+            field: string;
+        } | undefined;
+    }[] | undefined;
+    supportsVision?: boolean | undefined;
+    maxOutputTokens?: number | undefined;
+    label?: string | undefined;
+    maxContextTokens?: number | undefined;
+}>;
+export type ModelPreset = z.infer<typeof modelPresetSchema>;
+export declare const catalogEntrySchema: z.ZodObject<{
+    /** Template id, e.g. "openai" / "openai-images" / "fal-video". */
+    id: z.ZodString;
+    /** Which 连接 page group this lands in. (audio = speech-to-text / voice input.) */
+    tag: z.ZodEnum<["text", "image", "video", "audio"]>;
+    /** Runtime adapter selector — reuses existing "openai" | "anthropic" | "google" | "fal". */
+    adapterKind: z.ZodString;
+    /** LLM client protocol (text entries). */
+    protocol: z.ZodOptional<z.ZodEnum<["openai-compat", "anthropic-style"]>>;
+    /** HTTP shape — documentation/future only; runtime dispatches on adapterKind. */
+    shape: z.ZodOptional<z.ZodEnum<["generic-sync", "fal-queue"]>>;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    defaultBaseUrl: z.ZodString;
+    defaultModel: z.ZodOptional<z.ZodString>;
+    /** Whether this provider needs an API key (ollama/local = false). */
+    needsKey: z.ZodOptional<z.ZodBoolean>;
+    modelPresets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        maxContextTokens: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        supportsVision: z.ZodOptional<z.ZodBoolean>;
+        /** Params this model supports; absent → no adjustable knobs. */
+        params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            /** Logical name, e.g. "reasoning" / "size" / "quality" / "temperature". */
+            name: z.ZodString;
+            /** UI control label (falls back to `name`). */
+            label: z.ZodOptional<z.ZodString>;
+            control: z.ZodEnum<["enum", "number", "toggle", "text"]>;
+            /** control=enum allowed values, e.g. ["low","medium","high","xhigh"]. */
+            options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            /** control=number bounds. */
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            /** Natural-language usage note → injected into the tool description. */
+            doc: z.ZodOptional<z.ZodString>;
+            /** How this param lands on the request body. */
+            wire: z.ZodOptional<z.ZodObject<{
+                field: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                field: string;
+            }, {
+                field: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }, {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }, {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }>, "many">>;
+    signupUrl: z.ZodOptional<z.ZodString>;
+    /** Whether the 连接 card offers a "测试" button (image=true, video=false). */
+    test: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Natural-language note on the params/usage this entry supports — surfaced to
+     * the agent via the dynamic GenerateImage/GenerateVideo tool description so it
+     * knows what a configured model accepts (different models differ).
+     */
+    paramsDoc: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    tag: "text" | "image" | "video" | "audio";
+    adapterKind: string;
+    displayName: string;
+    description: string;
+    defaultBaseUrl: string;
+    shape?: "generic-sync" | "fal-queue" | undefined;
+    test?: boolean | undefined;
+    defaultModel?: string | undefined;
+    protocol?: "openai-compat" | "anthropic-style" | undefined;
+    needsKey?: boolean | undefined;
+    modelPresets?: {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }[] | undefined;
+    signupUrl?: string | undefined;
+    paramsDoc?: string | undefined;
+}, {
+    id: string;
+    tag: "text" | "image" | "video" | "audio";
+    adapterKind: string;
+    displayName: string;
+    description: string;
+    defaultBaseUrl: string;
+    shape?: "generic-sync" | "fal-queue" | undefined;
+    test?: boolean | undefined;
+    defaultModel?: string | undefined;
+    protocol?: "openai-compat" | "anthropic-style" | undefined;
+    needsKey?: boolean | undefined;
+    modelPresets?: {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }[] | undefined;
+    signupUrl?: string | undefined;
+    paramsDoc?: string | undefined;
+}>;
+export type CatalogEntry = z.infer<typeof catalogEntrySchema>;
+/** A user-catalog file is just an array of entries (zod-validated on load). */
+export declare const userCatalogFileSchema: z.ZodArray<z.ZodObject<{
+    /** Template id, e.g. "openai" / "openai-images" / "fal-video". */
+    id: z.ZodString;
+    /** Which 连接 page group this lands in. (audio = speech-to-text / voice input.) */
+    tag: z.ZodEnum<["text", "image", "video", "audio"]>;
+    /** Runtime adapter selector — reuses existing "openai" | "anthropic" | "google" | "fal". */
+    adapterKind: z.ZodString;
+    /** LLM client protocol (text entries). */
+    protocol: z.ZodOptional<z.ZodEnum<["openai-compat", "anthropic-style"]>>;
+    /** HTTP shape — documentation/future only; runtime dispatches on adapterKind. */
+    shape: z.ZodOptional<z.ZodEnum<["generic-sync", "fal-queue"]>>;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    defaultBaseUrl: z.ZodString;
+    defaultModel: z.ZodOptional<z.ZodString>;
+    /** Whether this provider needs an API key (ollama/local = false). */
+    needsKey: z.ZodOptional<z.ZodBoolean>;
+    modelPresets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        maxContextTokens: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        supportsVision: z.ZodOptional<z.ZodBoolean>;
+        /** Params this model supports; absent → no adjustable knobs. */
+        params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            /** Logical name, e.g. "reasoning" / "size" / "quality" / "temperature". */
+            name: z.ZodString;
+            /** UI control label (falls back to `name`). */
+            label: z.ZodOptional<z.ZodString>;
+            control: z.ZodEnum<["enum", "number", "toggle", "text"]>;
+            /** control=enum allowed values, e.g. ["low","medium","high","xhigh"]. */
+            options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            /** control=number bounds. */
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            /** Natural-language usage note → injected into the tool description. */
+            doc: z.ZodOptional<z.ZodString>;
+            /** How this param lands on the request body. */
+            wire: z.ZodOptional<z.ZodObject<{
+                field: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                field: string;
+            }, {
+                field: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }, {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }, {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }>, "many">>;
+    signupUrl: z.ZodOptional<z.ZodString>;
+    /** Whether the 连接 card offers a "测试" button (image=true, video=false). */
+    test: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Natural-language note on the params/usage this entry supports — surfaced to
+     * the agent via the dynamic GenerateImage/GenerateVideo tool description so it
+     * knows what a configured model accepts (different models differ).
+     */
+    paramsDoc: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    tag: "text" | "image" | "video" | "audio";
+    adapterKind: string;
+    displayName: string;
+    description: string;
+    defaultBaseUrl: string;
+    shape?: "generic-sync" | "fal-queue" | undefined;
+    test?: boolean | undefined;
+    defaultModel?: string | undefined;
+    protocol?: "openai-compat" | "anthropic-style" | undefined;
+    needsKey?: boolean | undefined;
+    modelPresets?: {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }[] | undefined;
+    signupUrl?: string | undefined;
+    paramsDoc?: string | undefined;
+}, {
+    id: string;
+    tag: "text" | "image" | "video" | "audio";
+    adapterKind: string;
+    displayName: string;
+    description: string;
+    defaultBaseUrl: string;
+    shape?: "generic-sync" | "fal-queue" | undefined;
+    test?: boolean | undefined;
+    defaultModel?: string | undefined;
+    protocol?: "openai-compat" | "anthropic-style" | undefined;
+    needsKey?: boolean | undefined;
+    modelPresets?: {
+        value: string;
+        params?: {
+            name: string;
+            control: "number" | "text" | "enum" | "toggle";
+            options?: string[] | undefined;
+            default?: string | number | boolean | undefined;
+            label?: string | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            doc?: string | undefined;
+            wire?: {
+                field: string;
+            } | undefined;
+        }[] | undefined;
+        supportsVision?: boolean | undefined;
+        maxOutputTokens?: number | undefined;
+        label?: string | undefined;
+        maxContextTokens?: number | undefined;
+    }[] | undefined;
+    signupUrl?: string | undefined;
+    paramsDoc?: string | undefined;
+}>, "many">;

package/dist/model-catalog/types.js

@@ -0,0 +1,93 @@
+/**
+ * Model接入 Catalog — declarative provider templates (design doc:
+ * docs/superpowers/specs/2026-06-11-model-catalog-design.md).
+ *
+ * A {@link CatalogEntry} is a *template* the user can pick in the 连接 page to
+ * create a configured instance (stored in settings.imageGen/videoGen.providers[]).
+ * Catalog = "能配哪些"; providers[] = "配了哪些". The two are decoupled.
+ *
+ * `adapterKind` reuses the existing adapter selectors ("openai"/"google"/"fal")
+ * — the runtime getImageProvider/getVideoProvider switches and adapter classes
+ * are unchanged; the catalog only declares which template points at which
+ * already-wired adapter. `shape` is documentation/future only.
+ */
+import { z } from "zod";
+/**
+ * How the param maps onto the outgoing request body. `field` is the request
+ * field this param lands on — same param name can land differently per
+ * adapter (reasoning → `reasoning_effort` on OpenAI vs
+ * `thinking.budget_tokens` on Anthropic), so the divergence lives in data, not
+ * in `if (kind === ...)` branches in the engine. Minimal v1: field only.
+ */
+export const wireSpecSchema = z.object({
+    field: z.string(),
+});
+/**
+ * One **generic** declarative param — no special-casing per param. reasoning
+ * is not its own variant: it's `control: "enum"` (OpenAI effort levels) or
+ * `control: "number"` (Anthropic token budget), decided by the entry's data.
+ * The connection page renders by `switch(control)`; `doc` is woven into the
+ * tool description so the agent knows what a configured model accepts.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §3.2.
+ */
+export const paramSpecSchema = z.object({
+    /** Logical name, e.g. "reasoning" / "size" / "quality" / "temperature". */
+    name: z.string(),
+    /** UI control label (falls back to `name`). */
+    label: z.string().optional(),
+    control: z.enum(["enum", "number", "toggle", "text"]),
+    /** control=enum allowed values, e.g. ["low","medium","high","xhigh"]. */
+    options: z.array(z.string()).optional(),
+    /** control=number bounds. */
+    min: z.number().optional(),
+    max: z.number().optional(),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    /** Natural-language usage note → injected into the tool description. */
+    doc: z.string().optional(),
+    /** How this param lands on the request body. */
+    wire: wireSpecSchema.optional(),
+});
+/**
+ * A known model under an entry, carrying its own param schema
+ * (per-entry-per-model — the same modelId via OpenRouter vs the official API
+ * can expose different params, since gateways normalize differently).
+ */
+export const modelPresetSchema = z.object({
+    value: z.string(),
+    label: z.string().optional(),
+    maxContextTokens: z.number().optional(),
+    maxOutputTokens: z.number().optional(),
+    supportsVision: z.boolean().optional(),
+    /** Params this model supports; absent → no adjustable knobs. */
+    params: z.array(paramSpecSchema).optional(),
+});
+export const catalogEntrySchema = z.object({
+    /** Template id, e.g. "openai" / "openai-images" / "fal-video". */
+    id: z.string(),
+    /** Which 连接 page group this lands in. (audio = speech-to-text / voice input.) */
+    tag: z.enum(["text", "image", "video", "audio"]),
+    /** Runtime adapter selector — reuses existing "openai" | "anthropic" | "google" | "fal". */
+    adapterKind: z.string(),
+    /** LLM client protocol (text entries). */
+    protocol: z.enum(["openai-compat", "anthropic-style"]).optional(),
+    /** HTTP shape — documentation/future only; runtime dispatches on adapterKind. */
+    shape: z.enum(["generic-sync", "fal-queue"]).optional(),
+    displayName: z.string(),
+    description: z.string(),
+    defaultBaseUrl: z.string(),
+    defaultModel: z.string().optional(),
+    /** Whether this provider needs an API key (ollama/local = false). */
+    needsKey: z.boolean().optional(),
+    modelPresets: z.array(modelPresetSchema).optional(),
+    signupUrl: z.string().optional(),
+    /** Whether the 连接 card offers a "测试" button (image=true, video=false). */
+    test: z.boolean().optional(),
+    /**
+     * Natural-language note on the params/usage this entry supports — surfaced to
+     * the agent via the dynamic GenerateImage/GenerateVideo tool description so it
+     * knows what a configured model accepts (different models differ).
+     */
+    paramsDoc: z.string().optional(),
+});
+/** A user-catalog file is just an array of entries (zod-validated on load). */
+export const userCatalogFileSchema = z.array(catalogEntrySchema);

package/dist/model-catalog/upsert.d.ts

@@ -0,0 +1,9 @@
+/**
+ * upsertCatalogEntry — add-or-update a CatalogEntry in the user catalog array,
+ * keyed by `id`. Pure: returns a new array, input untouched. Existing id →
+ * replaced in place (order preserved); new id → appended. The catalog edit tool
+ * wraps this with backup + zod validate + atomic write.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §7.
+ */
+import type { CatalogEntry } from "./types.js";
+export declare function upsertCatalogEntry(existing: CatalogEntry[], entry: CatalogEntry): CatalogEntry[];

package/dist/model-catalog/upsert.js

@@ -0,0 +1,8 @@
+export function upsertCatalogEntry(existing, entry) {
+    const idx = existing.findIndex((e) => e.id === entry.id);
+    if (idx === -1)
+        return [...existing, entry];
+    const next = existing.slice();
+    next[idx] = entry;
+    return next;
+}