@qilin-agent/client-ui-settings-models 0.0.0-stage → 3.1.3

package/lib/types/client/locales.d.ts

@@ -0,0 +1,113 @@
+/** Copy dictionaries for the Models settings section. */
+/** English strings (the key-set source of truth for this pair). */
+export declare const en: {
+    nav: string;
+    title: string;
+    intro: string;
+    edit: string;
+    editProvider: string;
+    remove: string;
+    removeProvider: string;
+    deleteTitle: string;
+    deleteDescription: string;
+    deleteDescriptionWithCredential: string;
+    deleteConfirm: string;
+    deleting: string;
+    add: string;
+    provider: string;
+    close: string;
+    cancel: string;
+    apply: string;
+    applying: string;
+    savedProvider: string;
+    credentialConfigured: string;
+    credentialMissing: string;
+    readOnly: string;
+    loadFailed: string;
+    conflict: string;
+    retry: string;
+    keyInput: string;
+    keyPlaceholder: string;
+    keyPlaceholderNative: string;
+    keyStored: string;
+    keyEnvLocked: string;
+    customized: string;
+    baseUrl: string;
+    baseUrlDefault: string;
+    deepSeekBaseUrl: string;
+    deepSeekEndpointHint: string;
+    models: string;
+    modelsInherited: string;
+    modelsCustomized: string;
+    resetModels: string;
+    model: string;
+    modelId: string;
+    modelName: string;
+    modelNamePlaceholder: string;
+    contextWindow: string;
+    contextWindowPlaceholder: string;
+    maxTokens: string;
+    maxTokensPlaceholder: string;
+    modelAdvanced: string;
+    modelInputTypes: string;
+    modelInputText: string;
+    modelInputImage: string;
+    addModel: string;
+    removeModel: string;
+    modelsEmpty: string;
+    keyBlank: string;
+    keyBlankNew: string;
+    keyIllegalCharacters: string;
+    modelIdRequired: string;
+    modelIdDuplicate: string;
+    modelNameInvalid: string;
+    modelContextInvalid: string;
+    modelMaxTokensInvalid: string;
+    advancedHint: string;
+    modelCapacityInvalid: string;
+    modelDuplicate: string;
+    fetchModels: string;
+    fetching: string;
+    fetchNeedsBaseUrl: string;
+    fetchEmpty: string;
+    fetchTitle: string;
+    fetchDescription: string;
+    fetchSearch: string;
+    fetchNoMatches: string;
+    fetchSelectAll: string;
+    fetchDeselectAll: string;
+    fetchAdopt: string;
+    customAdd: string;
+    customTitle: string;
+    customTag: string;
+    customRoute: string;
+    customRouteHint: string;
+    customRouteInvalid: string;
+    customRouteTaken: string;
+    customDisplayName: string;
+    customApi: string;
+    customApiUnset: string;
+    protocolOpenAiCompletions: string;
+    protocolOpenAiResponses: string;
+    protocolAnthropicMessages: string;
+    customNeedsBaseUrl: string;
+    customBaseUrlInvalid: string;
+    customNeedsModels: string;
+    customBaseUrlPlaceholder: string;
+    settingsPathUnresolvable: string;
+    create: string;
+    creating: string;
+    onboardingTitle: string;
+    onboardingDescription: string;
+    onboardingLater: string;
+    onboardingSave: string;
+    onboardingSaving: string;
+    keyRequired: string;
+};
+/** The settings.models namespace key union. */
+export type ModelsKey = keyof typeof en;
+/** Chinese strings (same keys as {@link en}). */
+export declare const zh: {
+    [Key in keyof typeof en]: string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/operations.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The Host reads and writes the Models cards perform, as callbacks built in the
+ * plugin body. Cards receive these instead of a context: the outcomes name what
+ * a card renders — a stored view, a stale revision, a refusal message — so the
+ * failure codes and Remote namespaces stay in the apply world.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { CredentialInfo, LlmDiscoveredModel, LlmModelDiscoveryRequest, SettingsNamespaceView, SettingsPathOpView } from '@qilin-agent/api-remotes/client';
+/** What one namespace write answered. */
+export type SettingsWriteOutcome = 
+/** Committed; the view carries the stored user subtree and the new revision. */
+{
+    readonly kind: 'written';
+    readonly view: SettingsNamespaceView;
+}
+/**
+ * The stored revision moved after the card read it, so the draft is stale.
+ * The message stays for callers that report the Host diagnostic as it is.
+ */
+ | {
+    readonly kind: 'conflict';
+    readonly message: string;
+}
+/** Any other refusal, with the Host's own diagnostic. */
+ | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+/** What one endpoint interrogation answered. */
+export type ModelDiscoveryOutcome = 
+/** The candidates the provider disclosed, in its own order. */
+{
+    readonly kind: 'found';
+    readonly models: readonly LlmDiscoveredModel[];
+}
+/** The interrogation was refused, with the Host's own diagnostic. */
+ | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+/** The Host operations the Models page and its cards invoke. */
+export interface ModelsOperations {
+    /**
+     * Read one credential reference's state.
+     * @param ref - credential reference name.
+     * @returns the state, or undefined when the reference is unknown or the read was refused.
+     */
+    describeCredential(ref: string): Promise<CredentialInfo | undefined>;
+    /**
+     * Store one credential literal under its reference.
+     * @param ref - credential reference name.
+     * @param value - the literal to store.
+     * @returns the refusal message, or undefined once stored.
+     */
+    storeCredential(ref: string, value: string): Promise<string | undefined>;
+    /**
+     * Remove one credential reference (idempotent).
+     * @param ref - credential reference name.
+     * @returns the refusal message, or undefined once removed.
+     */
+    removeCredential(ref: string): Promise<string | undefined>;
+    /**
+     * Apply path operations to one settings namespace.
+     * @param ns - settings namespace identity.
+     * @param ops - ordered path operations against the stored section, as the
+     * wire takes them (the Remote signature owns the array).
+     * @param expectedRevision - revision the draft was opened at, or undefined to write unfenced.
+     * @returns the write outcome the card renders from.
+     */
+    writeSettings(ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined): Promise<SettingsWriteOutcome>;
+    /**
+     * Ask a provider endpoint what models it serves.
+     * @param settingsNs - namespace whose adapter family answers.
+     * @param request - endpoint facts as the form currently shows them.
+     * @returns the candidates, or the refusal.
+     */
+    discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest): Promise<ModelDiscoveryOutcome>;
+}
+/**
+ * Bind the page's Host operations to the plugin's own Remote namespaces.
+ * @param ctx - the page plugin's context, which declares `remote.credentials`,
+ * `remote.llm`, and `remote.settings` in its own `inject`.
+ * @returns the callbacks the section and its cards are injected with.
+ */
+export declare function createModelsOperations(ctx: ClientContext): ModelsOperations;
+//# sourceMappingURL=operations.d.ts.map

package/lib/types/client/protocol-label.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Product names for the wire protocols a pi-ai route may speak. The pickers
+ * show these instead of the schema identifiers (`openai-completions`), which
+ * are what `settings.yaml` carries and what the option values stay.
+ */
+import type { ModelsKey } from './locales.ts';
+/**
+ * The picker text for one protocol identifier.
+ * @param t - section copy.
+ * @param protocol - the schema identifier of the protocol.
+ * @returns the product name this page knows the protocol by; a protocol the
+ * adapter adds before this page names it shows its identifier, the spelling
+ * `settings.yaml` needs anyway.
+ */
+export declare function protocolLabel(t: (key: ModelsKey) => string, protocol: string): string;
+//# sourceMappingURL=protocol-label.d.ts.map

package/lib/types/client/schema-operations.d.ts

@@ -0,0 +1,10 @@
+import type { SettingsSchemaService } from '@qilin-agent/client-ui-settings/client';
+/** Plain schema callbacks exposed to Models stores and presentation components. */
+export type SettingsSchemaOperations = Pick<SettingsSchemaService, 'rehydrate' | 'validate' | 'nodeAtPath' | 'getPath' | 'hasPath' | 'setPath' | 'deletePath'>;
+/**
+ * Hide the Cordis service identity behind bound schema callbacks.
+ * @param service - settings-owned schema service available in the apply context.
+ * @returns callbacks that cannot expose the service context to React components.
+ */
+export declare function createSettingsSchemaOperations(service: SettingsSchemaService): SettingsSchemaOperations;
+//# sourceMappingURL=schema-operations.d.ts.map

package/lib/types/client/slot-contract.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Models-page extension slots — the two seats through which a plugin
+ * distributed outside this repository adds UI to the Models settings section
+ * without editing it.
+ *
+ * `settings.models.provider-card` is keyed by the row's owning settings
+ * namespace (`ProviderDirectoryEntry.settingsNs`): an adapter family's
+ * companion plugin registers one entry under the family's namespace and
+ * receives every card of that family — shipped, added, and hand-declared rows
+ * alike — while the section never learns what the namespace means. Keying on
+ * the namespace follows `settings.plugin.item`, and the key domain stays the
+ * open string space because hand-declared route ids are user-chosen at
+ * runtime.
+ *
+ * TYPE HOME RATIONALE: the Models section declares these slots at runtime,
+ * and a plugin registering an extension already depends on this package for
+ * the declaration. The types therefore live with their declarer.
+ */
+import type { ProviderDirectoryEntry } from './store.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotMap {
+        /**
+         * One provider card's adapter extension area, dispatched with
+         * `entryKey = settingsNs` on every card that renders a directory row: a
+         * saved row's card (its first-run setup posture included) and the
+         * add-provider draft card. The hand-declared draft card has no directory
+         * row yet, so it dispatches nothing until saved. Without a registrant the
+         * area renders nothing.
+         */
+        'settings.models.provider-card': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: ProviderCardExtrasOwnerProps;
+        };
+        /**
+         * Ordered extension area after the provider rows and the add controls.
+         * Without a registrant the area renders nothing.
+         */
+        'settings.models.footer': {
+            kind: 'list';
+            scope: 'root';
+            owner: ModelsFooterOwnerProps;
+        };
+    }
+}
+/** Owner share of one provider-card extension occurrence. */
+export interface ProviderCardExtrasOwnerProps {
+    /** The card's directory row (route id, display name, settings address, live state). */
+    provider: ProviderDirectoryEntry;
+    /** Whether any layer configures this provider (its profile resolves); `false` while the add-provider draft edits a dormant row. */
+    configured: boolean;
+    /** Whether the row's referenced api-key credential is confirmed configured (the page's credential join). */
+    keyConfigured: boolean;
+}
+/** Owner share of the footer area (the section supplies nothing). */
+export interface ModelsFooterOwnerProps {
+    /** Marker field: footer owner props are intentionally empty. */
+    children?: never;
+}
+//# sourceMappingURL=slot-contract.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Models settings page store: one snapshot joining the configurable-provider
+ * directory (`llm/listProviders` joined with `llm/listConfigurableProviders`),
+ * the settings namespaces (shared settings mirror),
+ * and the referenced credentials (`credentials/describe`). The host stays the
+ * single fact source — every mutation writes through the wire and the page
+ * re-renders from the next describe, pushed or refetched.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { CredentialInfo, LlmConfigurableProvider, LlmProviderInfo, SettingsNamespaceView } from '@qilin-agent/api-remotes/client';
+import type { SnapshotStore } from '@qilin-agent/client-store';
+import type { SettingsDescribeFace } from '@qilin-agent/client-ui-settings/client';
+import type { SettingsSchemaOperations } from './schema-operations.ts';
+/** One provider row after joining the configurable directory with live routes. */
+export interface ProviderDirectoryEntry {
+    readonly provider: string;
+    readonly displayName: string;
+    readonly settingsNs: string;
+    readonly settingsPath: readonly string[];
+    readonly active: boolean;
+    readonly declared?: boolean;
+    readonly error?: string;
+}
+/**
+ * Join declared configurable providers with the currently registered routes.
+ * @param registered - live provider routes in registration order.
+ * @param directory - declared configurable providers in declaration order.
+ * @returns declared rows followed by live routes with no declaration.
+ */
+export declare function joinProviderDirectory(registered: readonly LlmProviderInfo[], directory: readonly LlmConfigurableProvider[]): ProviderDirectoryEntry[];
+/** One provider row the page renders. */
+export interface ProviderRow {
+    /** The directory entry (route id, display name, settings address, live state). */
+    entry: ProviderDirectoryEntry;
+    /** Whether any layer configures this provider (its profile resolves). */
+    configured: boolean;
+    /** Whether the user layer alone carries the profile (removal restores the base). */
+    removable: boolean;
+    /** The credential reference the resolved profile names, when one does. */
+    apiKeyEnv: string | undefined;
+    /** Credential state for {@link apiKeyEnv}, once described. */
+    credential: CredentialInfo | undefined;
+    /**
+     * Credential state for the page's derived `<ROUTE>_API_KEY`, described only
+     * while the profile names no reference — the provider-card seat's
+     * `keyConfigured` fact for dormant and keyless rows, matching the editor's
+     * own derivation rule.
+     */
+    derivedCredential?: CredentialInfo;
+}
+/** Page snapshot. */
+export interface ModelsSettingsState {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    /** Whole-load failure text; row-level write failures stay in the editor. */
+    error: string | null;
+    /** Credential enrichment failure; provider/settings rows remain usable. */
+    credentialError: string | null;
+    /** Whether the settings provider accepts writes. */
+    writable: boolean;
+    /** Every configurable provider joined with its configured/credential state. */
+    rows: readonly ProviderRow[];
+    /** Namespace views by ns, for the editor's schema/layers/secrets. */
+    namespaces: ReadonlyMap<string, SettingsNamespaceView>;
+}
+/**
+ * Derive the conventional credential reference for a provider route: the v1
+ * page never asks for an environment-variable name, so a typed key stores
+ * under this derived reference and the profile records it as `apiKeyEnv`.
+ * @param provider - provider route id (e.g. `anthropic`, `minimax-cn`).
+ * @returns the derived reference name (e.g. `MINIMAX_CN_API_KEY`).
+ */
+export declare function deriveKeyRef(provider: string): string;
+/**
+ * The wire protocols a hand-declared route may name, read out of the owning
+ * namespace's own schema. This stays a schema read rather than a wire field so
+ * the choices the page offers cannot drift from the ones the adapter accepts:
+ * both come from the same `Config`.
+ * @param namespace - the namespace view whose schema declares the profile shape.
+ * @param schema - settings schema operations.
+ * @returns the protocol identifiers, or an empty list when the schema has none.
+ */
+export declare function protocolChoices(namespace: SettingsNamespaceView | undefined, schema: SettingsSchemaOperations): string[];
+/** The models settings page controller (one per settings surface). */
+export declare class ModelsSettingsStore {
+    private readonly ctx;
+    private readonly schema;
+    private readonly describeFace;
+    /** The snapshot the section renders from (uSES-safe store). */
+    readonly store: SnapshotStore<ModelsSettingsState>;
+    /** Latest load wins; an older response never overwrites a newer one. */
+    private generation;
+    /**
+     * @param ctx - the page plugin's context, whose `remote.llm` and
+     * `remote.credentials` namespaces carry the directory and credential reads.
+     * @param schema - settings-owned schema and immutable path operations.
+     * @param describeFace - the shared mirror's describe face (namespace views and writability).
+     */
+    constructor(ctx: ClientContext, schema: SettingsSchemaOperations, describeFace: SettingsDescribeFace);
+    /**
+     * Refresh the whole page snapshot: the provider directory and the mirror's
+     * settings answer in parallel, then one batched credential describe over
+     * every referenced ref. Provider failure or absence of an initial settings
+     * answer keeps the last good rows and surfaces an error; a failed settings
+     * refresh reuses the mirror's held view.
+     * @returns nothing; the snapshot carries the outcome.
+     */
+    load(): Promise<void>;
+    /** Publish one load's failure text, unless a newer load already took over. */
+    private failLoad;
+}
+/**
+ * Whether a joined row can serve model requests as it stands: the route is
+ * registered with the adapter registry, and whatever credential its resolved
+ * profile names is stored. A profile naming no reference authenticates through
+ * the provider's own path (the Bedrock chain, Vertex ADC, a gateway that needs
+ * nothing), as does a live route with no settings address at all, so neither
+ * owes this page a key.
+ * @param row - one joined provider row.
+ * @returns whether the user already has this provider to talk to.
+ */
+export declare function providerUsable(row: ProviderRow): boolean;
+/** First-run onboarding readiness derived only from the shared Models join. */
+export type OnboardingReadiness = {
+    kind: 'loading';
+} | {
+    kind: 'adapter-absent';
+} | {
+    kind: 'provider-ready';
+} | {
+    kind: 'credential-missing';
+} | {
+    kind: 'unavailable';
+    reason: 'load-failed' | 'provider-inactive' | 'credentials-unavailable' | 'settings-read-only' | 'credential-read-only';
+};
+/**
+ * Project first-run readiness from the provider/settings/credential join used
+ * by the Models page. The step exists to leave the user with a model to talk
+ * to, so ANY usable provider ends it; only when none exists does the official
+ * DeepSeek route — the one route the prompt can offer a key field for — decide
+ * whether prompting can help. A missing official configurable-provider
+ * declaration means the adapter is not repairable by navigating to Models.
+ * @param state - current shared Models join snapshot.
+ * @returns the onboarding state without reading a parallel fact source.
+ */
+export declare function onboardingReadiness(state: ModelsSettingsState): OnboardingReadiness;
+//# sourceMappingURL=store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the models settings plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@qilin-agent/client-ui-settings-models",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Models settings and shared product-onboarding dialogs over existing settings and credential joins",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-settings-models"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-ui-settings",
+        "@qilin-agent/client-locale",
+        "@qilin-agent/api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/remote-mock": "3.1.3",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3",
+    "@qilin-agent/client-test-runtime": "3.1.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/client-ui-settings": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/util-values": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }