@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/local-runtime/model-setup-input.d.ts

@@ -0,0 +1,24 @@
+export type NewModelProvider = Readonly<{
+    id: string;
+    type: "openai" | "ollama";
+    baseUrl?: string;
+}>;
+export type ModelSetupInput = Readonly<{
+    profileId: string;
+    model: string;
+    contextWindowTokens?: number;
+    apiKey?: string;
+}> & (Readonly<{
+    providerId: string;
+    newProvider?: never;
+}> | Readonly<{
+    newProvider: NewModelProvider;
+    providerId?: never;
+}>);
+export declare class ModelSetupError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly credentialSaved: boolean;
+    constructor(code: string, message: string, statusCode?: number, credentialSaved?: boolean);
+}
+export declare function parseModelSetupInput(body: Record<string, unknown>): ModelSetupInput;

package/dist/src/web-ui/local-runtime/model-setup-input.js

@@ -0,0 +1,116 @@
+import { parseRuntimeModelProfileId } from "../../../scripts/runtime-model-addition.js";
+import { parseBaseUrl, parseContextWindowTokens, } from "../../../scripts/runtime-setup-files.js";
+import { isRecord } from "../../runtime/config/utils.js";
+export class ModelSetupError extends Error {
+    code;
+    statusCode;
+    credentialSaved;
+    constructor(code, message, statusCode = 400, credentialSaved = false) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.credentialSaved = credentialSaved;
+    }
+}
+function requireAllowedFields(body, allowed) {
+    if (Object.keys(body).some((key) => !allowed.includes(key))) {
+        throw new ModelSetupError("invalid_model_input", "The model update contains unsupported fields.");
+    }
+}
+function inputString(body, field, optional = false) {
+    const value = body[field];
+    if (value === undefined && optional)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        throw new ModelSetupError("invalid_model_input", `The ${field} field must be a non-empty string.`);
+    return value.trim();
+}
+function isReservedIdentifier(value) {
+    return ["__proto__", "prototype", "constructor"].includes(value);
+}
+function requireIdentifier(value, kind) {
+    const pattern = kind === "provider"
+        ? /^[A-Za-z][A-Za-z0-9._-]*$/u
+        : /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+    if (value.length > 128 ||
+        !pattern.test(value) ||
+        isReservedIdentifier(value)) {
+        throw new ModelSetupError(`invalid_${kind}_id`, `Choose a ${kind} ID of up to 128 letters, numbers, dots, underscores, or dashes, starting with ${kind === "provider" ? "a letter" : "a letter or number"}.`);
+    }
+    return kind === "profile" ? parseRuntimeModelProfileId(value) : value;
+}
+function hasWindowsDeviceBasename(value) {
+    return /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu.test(value);
+}
+function requirePortableModelProfileId(value) {
+    const profileId = requireIdentifier(value, "profile");
+    if (hasWindowsDeviceBasename(profileId))
+        throw new ModelSetupError("invalid_profile_id", "Choose a profile ID that is not a reserved Windows device name.");
+    return profileId;
+}
+function readNewProvider(value) {
+    if (!isRecord(value))
+        throw new ModelSetupError("invalid_model_provider", "Choose a configured provider or add a new provider.");
+    requireAllowedFields(value, ["id", "type", "baseUrl"]);
+    const id = requireIdentifier(inputString(value, "id"), "provider");
+    const type = inputString(value, "type");
+    if (type !== "openai" && type !== "ollama")
+        throw new ModelSetupError("invalid_model_provider", "A new provider must use OpenAI or Ollama.");
+    const address = inputString(value, "baseUrl", true);
+    if (address && type !== "ollama")
+        throw new ModelSetupError("invalid_model_address", "A custom address is available for a new Ollama provider.");
+    let baseUrl;
+    try {
+        baseUrl = address ? parseBaseUrl(address) : undefined;
+    }
+    catch {
+        throw new ModelSetupError("invalid_model_address", "Enter an HTTP or HTTPS origin without a path or credentials.");
+    }
+    return { id, type, ...(baseUrl ? { baseUrl } : {}) };
+}
+function requireModelIdentifier(model) {
+    if (model.length > 256 || /[\u0000-\u0020\u007f]/u.test(model))
+        throw new ModelSetupError("invalid_model_id", "Enter a model ID without spaces or control characters.");
+}
+function requireSafeCredential(apiKey) {
+    if (!apiKey)
+        return;
+    if (apiKey.length > 4096 || /[\u0000-\u0020\u007f'"`]/u.test(apiKey))
+        throw new ModelSetupError("invalid_model_credential", "The API key contains unsupported characters.");
+}
+export function parseModelSetupInput(body) {
+    requireAllowedFields(body, [
+        "profileId",
+        "model",
+        "contextWindowTokens",
+        "providerId",
+        "newProvider",
+        "apiKey",
+    ]);
+    const profileId = requirePortableModelProfileId(inputString(body, "profileId"));
+    let contextWindowTokens;
+    try {
+        contextWindowTokens = parseContextWindowTokens(body.contextWindowTokens);
+    }
+    catch {
+        throw new ModelSetupError("invalid_context_window", "Context window must be a positive whole number of tokens.");
+    }
+    const model = inputString(body, "model");
+    requireModelIdentifier(model);
+    const apiKey = inputString(body, "apiKey", true);
+    requireSafeCredential(apiKey);
+    const providerId = inputString(body, "providerId", true);
+    const hasOneProvider = (providerId !== undefined) !== (body.newProvider !== undefined);
+    if (!hasOneProvider)
+        throw new ModelSetupError("invalid_model_provider", "Choose exactly one configured provider or new provider.");
+    const selection = providerId
+        ? { providerId }
+        : { newProvider: readNewProvider(body.newProvider) };
+    return {
+        profileId,
+        model,
+        ...(contextWindowTokens !== undefined ? { contextWindowTokens } : {}),
+        ...(apiKey ? { apiKey } : {}),
+        ...selection,
+    };
+}

package/dist/src/web-ui/local-runtime/model-setup-profile-file.d.ts

@@ -0,0 +1,17 @@
+import { type ConfigFileTransaction } from "../../runtime/adapters/config-file-transaction.js";
+type ProfileFileOptions = {
+    rootDir: string;
+    configPath: string;
+};
+export declare function modelSetupProfilePath(options: ProfileFileOptions, profileId: string): Promise<string>;
+export declare function isDiscoveredModelSetupProfileAtTarget(options: ProfileFileOptions, profileId: string, discoveredPath: string): Promise<boolean>;
+/** The caller holds the Runtime lock; a new or exact existing profile is locked until commit. */
+export declare function withModelSetupProfile<T>(options: ProfileFileOptions, root: ConfigFileTransaction, profileId: string, profile: Record<string, unknown>, commit: (declaration: {
+    configRef: string;
+}, assertProfileUnchanged: () => Promise<void>) => Promise<T>): Promise<T>;
+/** Preserve exact retry identity for both legacy inline and linked declarations. */
+export declare function readSavedModelSetupProfile(options: ProfileFileOptions, declaration: Record<string, unknown>): Promise<{
+    profile: Record<string, unknown>;
+    assertUnchanged: () => Promise<void>;
+}>;
+export {};

package/dist/src/web-ui/local-runtime/model-setup-profile-file.js

@@ -0,0 +1,121 @@
+import { lstat, rm } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { canonicalConfigFilePath, readConfigFileSnapshot, withConfigFileTransaction, } from "../../runtime/adapters/config-file-transaction.js";
+import { ModelSetupError } from "./model-setup-input.js";
+function declaredModelSetupProfilePath(options, profileId) {
+    return resolve(dirname(options.configPath), `./models/${profileId}.config.json`);
+}
+export async function modelSetupProfilePath(options, profileId) {
+    return canonicalConfigFilePath(declaredModelSetupProfilePath(options, profileId));
+}
+export async function isDiscoveredModelSetupProfileAtTarget(options, profileId, discoveredPath) {
+    return ((await canonicalConfigFilePath(discoveredPath)) ===
+        (await modelSetupProfilePath(options, profileId)));
+}
+function matchesRequestedModelSetupProfile(snapshot, profile) {
+    if (snapshot.invalidJson)
+        return false;
+    return isDeepStrictEqual(snapshot.config, profile);
+}
+function requireProfileInsideWorkspace(rootDir, path) {
+    const target = relative(rootDir, path);
+    if (!target.startsWith("..") && !isAbsolute(target))
+        return;
+    throw new ModelSetupError("model_config_outside_workspace", "The model configuration must be inside the workspace.", 409);
+}
+function rejectExistingModelFile() {
+    throw new ModelSetupError("model_profile_exists", "A model file already uses this profile ID. Choose another ID.", 409);
+}
+async function requireAbsentModelProfileEntry(path) {
+    try {
+        // A dangling symlink is an existing user-owned entry, not a new file.
+        await lstat(path);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    rejectExistingModelFile();
+}
+async function requireUnchangedProfileTarget(declaredPath, expectedPath) {
+    if ((await canonicalConfigFilePath(declaredPath)) === expectedPath)
+        return;
+    throw new ModelSetupError("config_changed", "The model file reference changed while being checked. Reload Configuration before retrying.", 409);
+}
+async function discardUncommittedProfile(root, rootRevision, path, profileRevision) {
+    // A changed root or child may belong to an external editor; preserve it.
+    try {
+        if ((await readConfigFileSnapshot(root.path)).revision !== rootRevision)
+            return;
+        if ((await readConfigFileSnapshot(path)).revision !== profileRevision)
+            return;
+        await rm(path);
+    }
+    catch {
+        // Cleanup must never hide the original save failure or erase uncertain data.
+    }
+}
+/** The caller holds the Runtime lock; a new or exact existing profile is locked until commit. */
+export async function withModelSetupProfile(options, root, profileId, profile, commit) {
+    const configRef = `./models/${profileId}.config.json`;
+    const declaredPath = declaredModelSetupProfilePath(options, profileId);
+    const path = await modelSetupProfilePath(options, profileId);
+    requireProfileInsideWorkspace(options.rootDir, path);
+    if (path === root.path)
+        rejectExistingModelFile();
+    return withConfigFileTransaction(path, async (target) => {
+        await requireUnchangedProfileTarget(declaredPath, path);
+        const createdByThisAddition = !target.snapshot.exists;
+        if (!createdByThisAddition &&
+            !matchesRequestedModelSetupProfile(target.snapshot, profile))
+            rejectExistingModelFile();
+        const rootRevision = root.snapshot.revision;
+        if (createdByThisAddition) {
+            await requireAbsentModelProfileEntry(declaredPath);
+            await target.write(profile);
+        }
+        const profileRevision = target.snapshot.revision;
+        const assertProfileUnchanged = async () => {
+            await requireUnchangedProfileTarget(declaredPath, path);
+            if ((await readConfigFileSnapshot(path, { allowMalformedJson: true }))
+                .revision !== profileRevision)
+                throw new ModelSetupError("config_changed", "The model file changed while saving. Reload Configuration to check the saved model.", 409);
+        };
+        try {
+            await assertProfileUnchanged();
+            // The confirmed Runtime commit is the save boundary. Later external
+            // profile edits must not report the committed declaration as rejected.
+            return await commit({ configRef }, assertProfileUnchanged);
+        }
+        catch (error) {
+            if (createdByThisAddition)
+                await discardUncommittedProfile(root, rootRevision, path, profileRevision);
+            throw error;
+        }
+    }, { allowMalformedJson: true });
+}
+/** Preserve exact retry identity for both legacy inline and linked declarations. */
+export async function readSavedModelSetupProfile(options, declaration) {
+    if (!Object.hasOwn(declaration, "configRef"))
+        return { profile: declaration, assertUnchanged: async () => { } };
+    if (typeof declaration.configRef !== "string")
+        rejectExistingModelFile();
+    if (Object.keys(declaration).length !== 1)
+        rejectExistingModelFile();
+    const declaredPath = resolve(dirname(options.configPath), declaration.configRef);
+    const path = await canonicalConfigFilePath(declaredPath);
+    requireProfileInsideWorkspace(options.rootDir, path);
+    const snapshot = await readConfigFileSnapshot(path);
+    if (!snapshot.exists)
+        rejectExistingModelFile();
+    return {
+        profile: snapshot.config,
+        async assertUnchanged() {
+            await requireUnchangedProfileTarget(declaredPath, path);
+            if ((await readConfigFileSnapshot(path)).revision !== snapshot.revision)
+                throw new ModelSetupError("config_changed", "The saved model file changed while being checked. Reload Configuration before retrying.", 409);
+        },
+    };
+}

package/dist/src/web-ui/local-runtime/model-setup-provider.d.ts

@@ -0,0 +1,17 @@
+import { type ModelSetupInput, type NewModelProvider } from "./model-setup-input.js";
+import type { ModelSetupOptions } from "./model-setup-catalog.js";
+export declare function buildNewModelProvider(selection: NewModelProvider): {
+    id: string;
+    config: import("../../../scripts/runtime-setup-files.js").JsonObject;
+};
+export declare function planModelProvider(providers: Record<string, unknown>, input: ModelSetupInput): {
+    id: string;
+    config: import("../../../scripts/runtime-setup-files.js").JsonObject;
+};
+export declare function prepareModelCredential(options: ModelSetupOptions, provider: Record<string, unknown>, apiKey?: string): Promise<{
+    apiKey?: string | undefined;
+    apiKeyEnv: string;
+} | undefined>;
+export declare function saveModelCredential(options: ModelSetupOptions & {
+    configPath: string;
+}, credential: Awaited<ReturnType<typeof prepareModelCredential>>): Promise<boolean>;

package/dist/src/web-ui/local-runtime/model-setup-provider.js

@@ -0,0 +1,68 @@
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { hasProviderCredentialBinding, isolatedProviderCredentialName, } from "./provider-credential-identity.js";
+import { buildProviderConfig } from "../../../scripts/runtime-setup-files.js";
+import { isRecord } from "../../runtime/config/utils.js";
+import { readRuntimeSetupCredential, assertRuntimeSetupCredentialFile, persistRuntimeSetupCredentials, } from "./runtime-setup-credentials.js";
+import { ModelSetupError, } from "./model-setup-input.js";
+export function buildNewModelProvider(selection) {
+    const config = buildProviderConfig(selection.type, selection.baseUrl);
+    const needsIsolatedCredentialBinding = selection.type === "openai";
+    if (needsIsolatedCredentialBinding)
+        config.apiKeyEnv = isolatedProviderCredentialName(selection.id);
+    return { id: selection.id, config };
+}
+export function planModelProvider(providers, input) {
+    if (input.providerId !== undefined) {
+        const provider = Object.hasOwn(providers, input.providerId)
+            ? providers[input.providerId]
+            : undefined;
+        if (!isRecord(provider))
+            throw new ModelSetupError("model_provider_not_found", "The selected provider no longer exists. Refresh and choose a provider.", 404);
+        return { id: input.providerId, config: provider };
+    }
+    const selection = input.newProvider;
+    if (Object.hasOwn(providers, selection.id))
+        throw new ModelSetupError("model_provider_exists", "That provider ID already exists. Choose its saved connection or use another ID.", 409);
+    const provider = buildNewModelProvider(selection);
+    const apiKeyEnv = provider.config.apiKeyEnv;
+    const hasNewProviderCredentialCollision = typeof apiKeyEnv === "string" &&
+        hasProviderCredentialBinding(providers, apiKeyEnv);
+    if (hasNewProviderCredentialCollision)
+        throw new ModelSetupError("model_credential_conflict", "The new provider's credential name is already in use. Choose another provider ID.", 409);
+    return provider;
+}
+export async function prepareModelCredential(options, provider, apiKey) {
+    const requiresApiKey = provider.type === "openai";
+    if (!requiresApiKey) {
+        if (apiKey)
+            throw new ModelSetupError("invalid_model_credential", "Only an OpenAI connection accepts an API key here.");
+        return undefined;
+    }
+    const apiKeyEnv = typeof provider.apiKeyEnv === "string"
+        ? provider.apiKeyEnv
+        : "OPENAI_API_KEY";
+    await assertRuntimeSetupCredentialFile(options.rootDir);
+    const savedKey = readRuntimeSetupCredential(options.rootDir, apiKeyEnv);
+    if (savedKey && apiKey && savedKey !== apiKey)
+        throw new ModelSetupError("credential_already_configured", "That provider already has a saved API key. Its credential was preserved.", 409);
+    if (!savedKey && !apiKey)
+        throw new ModelSetupError("model_credential_required", "Enter an API key for this OpenAI connection.");
+    return { apiKeyEnv, ...(savedKey ? {} : { apiKey }) };
+}
+export async function saveModelCredential(options, credential) {
+    if (!credential)
+        return false;
+    try {
+        await persistRuntimeSetupCredentials({
+            ...options,
+            ...credential,
+            preserveExistingCredential: true,
+        });
+    }
+    catch (error) {
+        if (error instanceof RuntimeSetupError)
+            throw new ModelSetupError(error.code, error.message, error.statusCode);
+        throw error;
+    }
+    return true;
+}

package/dist/src/web-ui/local-runtime/model-setup-retry.d.ts

@@ -0,0 +1,14 @@
+import { type ModelSetupOptions } from "./model-setup-catalog.js";
+import { type ModelSetupInput } from "./model-setup-input.js";
+/** A repeated POST may acknowledge only the exact addition already committed. */
+export declare function recoverCommittedModelAddition(options: ModelSetupOptions & {
+    configPath: string;
+}, models: Record<string, unknown>, input: ModelSetupInput, expectedRevision: string): Promise<{
+    model: {
+        profileId: string;
+        providerId: string;
+        provider: string;
+        model: string;
+    };
+    restartRequired: true;
+}>;

package/dist/src/web-ui/local-runtime/model-setup-retry.js

@@ -0,0 +1,49 @@
+import { isDeepStrictEqual } from "node:util";
+import { readConfigFileSnapshot } from "../../runtime/adapters/config-file-transaction.js";
+import { isRecord } from "../../runtime/config/utils.js";
+import { modelConfigMap, } from "./model-setup-catalog.js";
+import { buildModelSetupProfile, modelSetupResult, } from "./model-setup-identity.js";
+import { ModelSetupError } from "./model-setup-input.js";
+import { readSavedModelSetupProfile } from "./model-setup-profile-file.js";
+import { buildNewModelProvider, planModelProvider, prepareModelCredential, } from "./model-setup-provider.js";
+function rejectModelProfileCollision() {
+    throw new ModelSetupError("model_profile_exists", "That model profile ID already exists with different settings. Choose another ID.", 409);
+}
+function committedRetryProvider(providers, input) {
+    if (input.providerId !== undefined)
+        return planModelProvider(providers, input);
+    return buildNewModelProvider(input.newProvider);
+}
+async function requireUnchangedRetryConfiguration(options, expectedRevision) {
+    const current = await readConfigFileSnapshot(options.configPath);
+    if (current.revision === expectedRevision)
+        return;
+    throw new ModelSetupError("config_changed", "Configuration changed while the saved model was being checked. Refresh before retrying.", 409);
+}
+/** A repeated POST may acknowledge only the exact addition already committed. */
+export async function recoverCommittedModelAddition(options, models, input, expectedRevision) {
+    const profiles = modelConfigMap(models.profiles);
+    const declaration = profiles[input.profileId];
+    if (!isRecord(declaration))
+        rejectModelProfileCollision();
+    const saved = await readSavedModelSetupProfile(options, declaration);
+    const providers = modelConfigMap(models.providers);
+    const providerId = input.providerId ?? input.newProvider.id;
+    const hasSavedProviderConnection = isRecord(providers[providerId]);
+    if (!hasSavedProviderConnection)
+        rejectModelProfileCollision();
+    const provider = committedRetryProvider(providers, input);
+    const savedProviderMatchesRequest = isDeepStrictEqual(providers[provider.id], provider.config);
+    if (!savedProviderMatchesRequest)
+        rejectModelProfileCollision();
+    const expectedProfile = await buildModelSetupProfile(provider, input);
+    const savedProfileMatchesRequest = isDeepStrictEqual(saved.profile, expectedProfile);
+    if (!savedProfileMatchesRequest)
+        rejectModelProfileCollision();
+    const credential = await prepareModelCredential(options, provider.config, input.apiKey);
+    if (credential?.apiKey)
+        throw new ModelSetupError("model_credential_required", "The saved model's credential is missing. Restore its connection in Models before retrying.", 409);
+    await requireUnchangedRetryConfiguration(options, expectedRevision);
+    await saved.assertUnchanged();
+    return modelSetupResult(provider, input);
+}

package/dist/src/web-ui/local-runtime/model-setup-routes.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { ModelSetupService } from "./model-setup-service.js";
+export declare class ModelSetupRoutes {
+    private readonly service;
+    constructor(service: ModelSetupService);
+    handle(params: {
+        method: string;
+        route: string;
+        request: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+}

package/dist/src/web-ui/local-runtime/model-setup-routes.js

@@ -0,0 +1,52 @@
+import { assertConfigMutationRequest, ConfigMutationRequestError, } from "./config-mutation-request.js";
+import { readBody, readJsonBody, sendJson } from "./http.js";
+import { ModelSetupError } from "./model-setup-input.js";
+export class ModelSetupRoutes {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async handle(params) {
+        if (!["runtime/config/models", "runtime/config/models/setup"].includes(params.route))
+            return false;
+        params.response.setHeader("cache-control", "no-store");
+        try {
+            if (params.route === "runtime/config/models/setup" &&
+                params.method === "GET") {
+                sendJson(params.response, 200, {
+                    ok: true,
+                    ...(await this.service.catalog()),
+                });
+            }
+            else if (params.route === "runtime/config/models" &&
+                ["POST", "DELETE"].includes(params.method)) {
+                assertConfigMutationRequest(params.request);
+                const body = readJsonBody(await readBody(params.request, { maxBytes: 16_384 }));
+                sendJson(params.response, 200, {
+                    ok: true,
+                    ...(params.method === "DELETE"
+                        ? await this.service.remove(body)
+                        : await this.service.add(body)),
+                });
+            }
+            else
+                sendJson(params.response, 405, {
+                    ok: false,
+                    error: "method_not_allowed",
+                });
+        }
+        catch (error) {
+            const known = error instanceof ModelSetupError ||
+                error instanceof ConfigMutationRequestError;
+            sendJson(params.response, known ? error.statusCode : 400, {
+                ok: false,
+                error: error instanceof ModelSetupError ? error.code : "model_setup_failed",
+                message: known
+                    ? error.message
+                    : "Model configuration could not be completed. Check the settings and try again.",
+                credentialSaved: error instanceof ModelSetupError && error.credentialSaved,
+            });
+        }
+        return true;
+    }
+}

package/dist/src/web-ui/local-runtime/model-setup-service.d.ts

@@ -0,0 +1,35 @@
+export declare class ModelSetupService {
+    private readonly options;
+    constructor(options: {
+        rootDir: string;
+        getConfigPath: () => string | undefined;
+    });
+    private sourceOptions;
+    catalog(): Promise<{
+        providers: {
+            id: string;
+            type: string;
+            label: string;
+            requiresApiKey: boolean;
+            credentialConfigured: boolean;
+        }[];
+        defaultContextWindowTokens: number;
+        profileIds: string[];
+    }>;
+    private canonicalOptions;
+    remove(body: Record<string, unknown>): Promise<{
+        profileId: string;
+        restartRequired: boolean;
+    }>;
+    add(body: Record<string, unknown>): Promise<{
+        model: {
+            profileId: string;
+            providerId: string;
+            provider: string;
+            model: string;
+        };
+        restartRequired: true;
+    }>;
+    private save;
+    private commit;
+}