narraeon 0.1.0

package/dist/node/runtime/model/ModelConnectionStore.js

@@ -0,0 +1,378 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename, stat, unlink, } from "node:fs/promises";
+import { join } from "node:path";
+import { modelProviderPresets, } from "../../protocol/modelConnections.js";
+const libraryFileName = "model-connections-v1.json";
+const maxModelListBytes = 1024 * 1024;
+export class ModelConnectionUnavailableError extends Error {
+    constructor() {
+        super("No V1 model connection is enabled");
+        this.name = "ModelConnectionUnavailableError";
+    }
+}
+export class ModelConnectionStore {
+    #configRoot;
+    #path;
+    #fetch;
+    #mutationTail = Promise.resolve();
+    constructor(configRoot, fetchImplementation = fetch) {
+        this.#configRoot = configRoot;
+        this.#path = join(configRoot, libraryFileName);
+        this.#fetch = fetchImplementation;
+    }
+    async view() {
+        await this.#mutationTail;
+        const document = await this.#readDocument();
+        return this.#viewDocument(document);
+    }
+    save(input) {
+        return this.#mutate(async () => {
+            const document = await this.#readDocument();
+            const index = input.connectionId === undefined
+                ? -1
+                : document.connections.findIndex(({ id }) => id === input.connectionId);
+            if (input.connectionId !== undefined && index < 0)
+                throw new Error("The model configuration to edit was not found");
+            const existing = index < 0 ? undefined : document.connections[index];
+            const saved = {
+                id: existing?.id ?? randomUUID(),
+                ...normalizeSaveInput(input, existing),
+            };
+            if (index < 0)
+                document.connections.push(saved);
+            else
+                document.connections[index] = saved;
+            document.activeConnectionId = saved.id;
+            await this.#writeDocument(document);
+            return this.#viewDocument(document);
+        });
+    }
+    select(connectionId) {
+        return this.#mutate(async () => {
+            const document = await this.#readDocument();
+            if (!document.connections.some(({ id }) => id === connectionId))
+                throw new Error("The model configuration to enable was not found");
+            document.activeConnectionId = connectionId;
+            await this.#writeDocument(document);
+            return this.#viewDocument(document);
+        });
+    }
+    delete(connectionId) {
+        return this.#mutate(async () => {
+            const document = await this.#readDocument();
+            const index = document.connections.findIndex(({ id }) => id === connectionId);
+            if (index < 0)
+                throw new Error("The model configuration to delete was not found");
+            if (document.activeConnectionId === connectionId &&
+                document.connections.length > 1)
+                throw new Error("Switch to another model configuration before deleting the current one");
+            document.connections.splice(index, 1);
+            if (document.activeConnectionId === connectionId)
+                document.activeConnectionId = null;
+            await this.#writeDocument(document);
+            return this.#viewDocument(document);
+        });
+    }
+    async bind() {
+        await this.#mutationTail;
+        const document = await this.#readDocument();
+        const connection = document.connections.find(({ id }) => id === document.activeConnectionId);
+        if (connection === undefined)
+            throw new ModelConnectionUnavailableError();
+        return toBinding(connection);
+    }
+    async listModels(input) {
+        await this.#mutationTail;
+        const provider = validateProvider(input.provider);
+        const baseUrl = normalizeBaseUrl(requiredTrimmed(input.baseUrl, "Base URL", 4096));
+        let apiKey = normalizeOptionalApiKey(input.apiKey);
+        if (apiKey === undefined && input.connectionId !== undefined) {
+            const stored = (await this.#readDocument()).connections.find(({ id }) => id === input.connectionId);
+            if (stored === undefined)
+                throw new Error("Model configuration not found");
+            if (stored.provider !== provider || stored.baseUrl !== baseUrl)
+                throw new Error("The endpoint or protocol changed; enter the API key again before fetching models");
+            apiKey = stored.apiKey;
+        }
+        if (apiKey === undefined)
+            throw new Error("Fetching the model list requires an API key");
+        const url = providerUrl(baseUrl, "models");
+        if (provider === "anthropic_messages")
+            url.searchParams.set("limit", "1000");
+        const response = await this.#fetch(url, {
+            method: "GET",
+            headers: provider === "anthropic_messages"
+                ? {
+                    "anthropic-version": "2023-06-01",
+                    "x-api-key": apiKey,
+                }
+                : { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            throw await providerListError(response);
+        const declaredLength = Number(response.headers.get("content-length"));
+        if (Number.isFinite(declaredLength) && declaredLength > maxModelListBytes)
+            throw new Error("Provider model-list response exceeds the 1 MiB limit");
+        const source = await response.text();
+        if (Buffer.byteLength(source, "utf8") > maxModelListBytes)
+            throw new Error("Provider model-list response exceeds the 1 MiB limit");
+        let payload;
+        try {
+            payload = JSON.parse(source);
+        }
+        catch {
+            throw new Error("Provider model-list response is not valid JSON");
+        }
+        if (!isRecord(payload) || !Array.isArray(payload.data))
+            throw new Error("Provider model-list response is missing the data array");
+        const models = [
+            ...new Set(payload.data.flatMap((item) => {
+                if (!isRecord(item) || typeof item.id !== "string")
+                    return [];
+                const id = item.id.trim();
+                return id.length > 0 && id.length <= 512 ? [id] : [];
+            })),
+        ]
+            .sort((left, right) => left.localeCompare(right))
+            .slice(0, 2_000);
+        if (models.length === 0)
+            throw new Error("Provider model list has no usable model IDs");
+        return { models };
+    }
+    #viewDocument(document) {
+        return {
+            configured: document.activeConnectionId !== null,
+            activeConnectionId: document.activeConnectionId,
+            connections: document.connections.map(toView),
+            presets: structuredClone(modelProviderPresets),
+        };
+    }
+    async #mutate(operation) {
+        const previous = this.#mutationTail;
+        let release = () => undefined;
+        this.#mutationTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async #readDocument() {
+        try {
+            const info = await stat(this.#path);
+            if (!info.isFile())
+                throw new Error("Model-connection configuration path is not a regular file");
+            verifyPrivateMode(info.mode);
+            return validateDocument(JSON.parse(await readFile(this.#path, "utf8")));
+        }
+        catch (error) {
+            if (!isMissingFile(error))
+                throw error;
+        }
+        return { schemaVersion: 1, activeConnectionId: null, connections: [] };
+    }
+    async #writeDocument(document) {
+        await mkdir(this.#configRoot, { recursive: true, mode: 0o700 });
+        const temporary = join(this.#configRoot, `.${libraryFileName}.${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporary, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify(document, null, 2)}\n`, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await chmod(temporary, 0o600);
+            await rename(temporary, this.#path);
+            await chmod(this.#path, 0o600);
+            verifyPrivateMode((await stat(this.#path)).mode);
+        }
+        catch (error) {
+            await handle?.close().catch(() => undefined);
+            await unlink(temporary).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+function normalizeSaveInput(input, existing) {
+    const name = requiredTrimmed(input.name, "Configuration name", 160);
+    const presetId = validatePresetId(input.presetId);
+    const provider = validateProvider(input.provider);
+    const baseUrl = normalizeBaseUrl(requiredTrimmed(input.baseUrl, "Base URL", 4096));
+    const modelId = requiredTrimmed(input.modelId, "Model ID", 512);
+    const explicitApiKey = normalizeOptionalApiKey(input.apiKey);
+    const apiKey = explicitApiKey ??
+        (existing?.provider === provider && existing.baseUrl === baseUrl
+            ? existing.apiKey
+            : undefined);
+    if (apiKey === undefined)
+        throw new Error(existing === undefined
+            ? "A new model configuration requires an API key"
+            : "The endpoint or protocol changed; enter the API key again because old credentials are never forwarded to a new endpoint");
+    validateTokenLimits(input.contextWindowTokens, input.maxOutputTokens);
+    validatePresetBinding(presetId, provider, baseUrl);
+    return {
+        name,
+        presetId,
+        provider,
+        baseUrl,
+        apiKey,
+        modelId,
+        contextWindowTokens: input.contextWindowTokens,
+        maxOutputTokens: input.maxOutputTokens,
+    };
+}
+function validateDocument(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        (value.activeConnectionId !== null &&
+            typeof value.activeConnectionId !== "string") ||
+        !Array.isArray(value.connections) ||
+        value.connections.length > 64)
+        throw new Error("Model-connection configuration file does not match its fixed schema");
+    const connections = value.connections.map(validateStoredConnection);
+    if (new Set(connections.map(({ id }) => id)).size !== connections.length)
+        throw new Error("Model-connection configuration contains duplicate IDs");
+    if (value.activeConnectionId !== null &&
+        !connections.some(({ id }) => id === value.activeConnectionId))
+        throw new Error("The enabled model connection does not exist");
+    return {
+        schemaVersion: 1,
+        activeConnectionId: value.activeConnectionId,
+        connections,
+    };
+}
+function validateStoredConnection(value) {
+    if (!isRecord(value))
+        throw new Error("Model connection must be an object");
+    const id = requiredTrimmed(value.id, "Model connection ID", 160);
+    const name = requiredTrimmed(value.name, "Configuration name", 160);
+    const presetId = validatePresetId(value.presetId);
+    const provider = validateProvider(value.provider);
+    const baseUrl = normalizeBaseUrl(requiredTrimmed(value.baseUrl, "Base URL"));
+    const apiKey = requiredTrimmed(value.apiKey, "API Key", 16_384);
+    const modelId = requiredTrimmed(value.modelId, "Model ID", 512);
+    validateTokenLimits(value.contextWindowTokens, value.maxOutputTokens);
+    validatePresetBinding(presetId, provider, baseUrl);
+    return {
+        id,
+        name,
+        presetId,
+        provider,
+        baseUrl,
+        apiKey,
+        modelId,
+        contextWindowTokens: value.contextWindowTokens,
+        maxOutputTokens: value.maxOutputTokens,
+    };
+}
+function toView(connection) {
+    return structuredClone({
+        id: connection.id,
+        name: connection.name,
+        presetId: connection.presetId,
+        provider: connection.provider,
+        baseUrl: connection.baseUrl,
+        modelId: connection.modelId,
+        contextWindowTokens: connection.contextWindowTokens,
+        maxOutputTokens: connection.maxOutputTokens,
+        hasApiKey: true,
+    });
+}
+function toBinding(connection) {
+    return structuredClone({
+        provider: connection.provider,
+        baseUrl: connection.baseUrl,
+        apiKey: connection.apiKey,
+        modelId: connection.modelId,
+        contextWindowTokens: connection.contextWindowTokens,
+        maxOutputTokens: connection.maxOutputTokens,
+    });
+}
+function validateProvider(value) {
+    if (value !== "chat_completions" &&
+        value !== "openai_responses" &&
+        value !== "anthropic_messages")
+        throw new Error("Model-connection protocol is invalid");
+    return value;
+}
+function validatePresetId(value) {
+    if (typeof value !== "string" ||
+        !modelProviderPresets.some(({ id }) => id === value))
+        throw new Error("Model-provider preset is invalid");
+    return value;
+}
+function validatePresetBinding(presetId, provider, baseUrl) {
+    const preset = modelProviderPresets.find(({ id }) => id === presetId);
+    if (preset.id !== "custom" &&
+        (preset.provider !== provider ||
+            normalizeBaseUrl(preset.baseUrl) !== baseUrl))
+        throw new Error("The endpoint or protocol does not match the built-in provider; select Custom endpoint for a custom configuration");
+}
+function normalizeBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("Base URL must be absolute");
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.username.length > 0 ||
+        url.password.length > 0 ||
+        url.search.length > 0 ||
+        url.hash.length > 0)
+        throw new Error("Base URL must be an HTTP(S) address without credentials, query, or fragment");
+    url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString().replace(/\/$/u, "");
+}
+function normalizeOptionalApiKey(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    return requiredTrimmed(value, "API Key", 16_384);
+}
+function requiredTrimmed(value, label, max = 4096) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    const normalized = value.trim();
+    if (normalized.length === 0 ||
+        normalized.length > max ||
+        normalized.includes("\r") ||
+        normalized.includes("\n"))
+        throw new Error(`${label} is invalid`);
+    return normalized;
+}
+function validateTokenLimits(context, output) {
+    if (!Number.isSafeInteger(context) ||
+        context < 4_096 ||
+        context > 16_777_216 ||
+        !Number.isSafeInteger(output) ||
+        output < 256 ||
+        output >= context)
+        throw new Error("Actual model context window or maximum output is invalid");
+}
+function providerUrl(baseUrl, resource) {
+    const url = new URL(baseUrl);
+    const suffix = `/${resource}`;
+    const path = url.pathname.replace(/\/+$/u, "");
+    url.pathname = path.endsWith(suffix) ? path : `${path}${suffix}`;
+    return url;
+}
+async function providerListError(response) {
+    const text = (await response.text()).slice(0, 4096);
+    return new Error(`Failed to fetch model list: ${response.status} ${text}`);
+}
+function verifyPrivateMode(mode) {
+    if ((mode & 0o077) !== 0)
+        throw new Error("Model-connection configuration permissions are too broad; only the current user may read it");
+}
+function isMissingFile(error) {
+    return error.code === "ENOENT";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/runtime/model/ModelHost.js

@@ -0,0 +1,89 @@
+export function equalModelHostBinding(left, right) {
+    return (left.provider === right.provider &&
+        left.endpointFingerprint === right.endpointFingerprint &&
+        left.modelId === right.modelId &&
+        left.contextWindowTokens === right.contextWindowTokens &&
+        left.maxOutputTokens === right.maxOutputTokens &&
+        left.protocolConfigFingerprint === right.protocolConfigFingerprint);
+}
+/** The persisted operation binding is unavailable in the current Runtime. */
+export class ModelHostBindingMismatchError extends Error {
+    kind = "binding_mismatch";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ModelHostBindingMismatchError";
+    }
+}
+/** A deterministic provider failure: the operation may be failed safely. */
+export class ModelHostFailureError extends Error {
+    kind = "failed";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ModelHostFailureError";
+    }
+}
+/** The provider outcome cannot be replayed without risking a duplicate response. */
+export class ModelHostOutcomeUnknownError extends Error {
+    kind = "unknown";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ModelHostOutcomeUnknownError";
+    }
+}
+/** Deterministic adapter for exercising the true external ModelHost port. */
+export class ScriptedModelHost {
+    requests = [];
+    #binding;
+    #steps;
+    #responseIndex = 0;
+    constructor(input) {
+        this.#binding = structuredClone(input.binding);
+        this.#steps = structuredClone(input.steps);
+    }
+    binding() {
+        return structuredClone(this.#binding);
+    }
+    exchange(request, observer) {
+        this.requests.push(structuredClone(request));
+        const step = this.#steps.shift();
+        if (step === undefined)
+            return Promise.reject(new Error("scripted ModelHost steps exhausted"));
+        if (step.outcome === "failure")
+            return Promise.reject(new ModelHostFailureError(step.message));
+        if (step.outcome === "unknown")
+            return Promise.reject(new ModelHostOutcomeUnknownError(step.message));
+        const { outcome: _outcome, continuation, deltas, ...response } = step;
+        void _outcome;
+        for (const delta of deltas ?? [])
+            observer?.onDelta?.(structuredClone(delta));
+        const providerState = response.providerState ??
+            (continuation === "available"
+                ? scriptedProviderState(this.#binding.provider, this.#responseIndex)
+                : undefined);
+        this.#responseIndex += 1;
+        return Promise.resolve({
+            ...structuredClone(response),
+            ...(providerState === undefined
+                ? {}
+                : { providerState: structuredClone(providerState) }),
+        });
+    }
+}
+function scriptedProviderState(provider, responseIndex) {
+    if (provider === "openai_responses")
+        return {
+            protocol: "openai_responses",
+            output: [],
+            responseId: `scripted-${responseIndex}`,
+        };
+    if (provider === "anthropic_messages")
+        return {
+            protocol: "anthropic_messages",
+            content: [],
+            responseId: `scripted-${responseIndex}`,
+        };
+    return {
+        protocol: "chat_completions",
+        assistantMessage: { role: "assistant", content: null },
+    };
+}