@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/local-runtime/request-cancellation-route.js

@@ -0,0 +1,34 @@
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { getString, sendJson } from "./http.js";
+export async function cancelWebRequest(input) {
+    if (!acceptConfigMutationRequest(input.request, input.response))
+        return;
+    const requestId = getString(input.body?.requestId).trim();
+    const sessionId = getString(input.body?.sessionId).trim();
+    if (!requestId || !sessionId) {
+        sendJson(input.response, 400, {
+            ok: false,
+            error: "request_identity_required",
+        });
+        return;
+    }
+    const cancel = input.environment.requests.cancel;
+    if (!cancel) {
+        sendJson(input.response, 409, {
+            ok: false,
+            error: "cancellation_unavailable",
+        });
+        return;
+    }
+    const body = input.body;
+    const wait = typeof body?.waitId === "string"
+        ? {
+            waitId: body.waitId,
+            generation: getString(body.generation),
+            revision: Number(body.revision),
+            commandId: getString(body.commandId),
+        }
+        : undefined;
+    const result = await cancel(requestId, sessionId, wait);
+    sendJson(input.response, 200, { ok: true, ...result });
+}

package/dist/src/web-ui/local-runtime/request-execution.d.ts

@@ -3,20 +3,23 @@ import type { SchedulerRun } from "../../runtime/scheduler/contracts.js";
 import type { RuntimeRequestOptions } from "../../runtime/composition.js";
 import type { JsonObject, RuntimeEnvironment } from "./contracts.js";
 import { RealtimeClientHub } from "./realtime-hub.js";
+import { PendingToolApprovals } from "./pending-tool-approvals.js";
+import type { LocalPendingToolApproval } from "../../runtime/local-host/request-approval-contracts.js";
 export declare class LocalRequestExecution {
     private readonly realtime;
     private readonly activeRequests;
-    private readonly pendingToolApprovals;
+    readonly toolApprovals: PendingToolApprovals;
     constructor(realtime: RealtimeClientHub);
     scheduledRequestOptions(run: SchedulerRun): RuntimeRequestOptions;
     publishScheduled(payload: JsonObject): void;
     start(res: ServerResponse, body: JsonObject, environmentId: string, environment: RuntimeEnvironment): Promise<void>;
     activeReplay(requestId: string, afterSeq: number): JsonObject | undefined;
+    activeReplayForSession(requestId: string, sessionId: string, environmentId: string): readonly JsonObject[] | undefined;
     healthDetails(): JsonObject[];
     handleSteer(message: JsonObject, resolveEnvironment: (id: string) => RuntimeEnvironment): Promise<JsonObject>;
     resolveToolApproval(message: JsonObject): void;
+    attachToolApproval(environmentId: string, environment: RuntimeEnvironment, pending: LocalPendingToolApproval, events: readonly JsonObject[]): Promise<void>;
     private run;
-    private createToolApprovalController;
     private publishRaw;
     private publish;
 }

package/dist/src/web-ui/local-runtime/request-execution.js

@@ -1,5 +1,8 @@
 import { createRequestSteeringInbox, } from "../../runtime/request/request-steering.js";
 import { getNumber, getString, sendJson } from "./http.js";
+import { PendingToolApprovals } from "./pending-tool-approvals.js";
+import { createWorkspaceChangeNotifier } from "./workspace-notifications.js";
+import { attachApprovalRequest } from "./approval-request-attachment.js";
 function createRequestId() {
     const random = Math.random().toString(36).slice(2, 8);
     return `web-${Date.now()}-${random}`;
@@ -7,9 +10,16 @@ function createRequestId() {
 export class LocalRequestExecution {
     realtime;
     activeRequests = new Map();
-    pendingToolApprovals = new Map();
+    toolApprovals;
     constructor(realtime) {
         this.realtime = realtime;
+        const notify = createWorkspaceChangeNotifier(realtime);
+        this.toolApprovals = new PendingToolApprovals((requestId) => this.activeRequests.get(requestId), (requestId) => {
+            const active = this.activeRequests.get(requestId);
+            if (!active)
+                return;
+            notify(active.environmentId, ["approvals"]);
+        });
     }
     scheduledRequestOptions(run) {
         const requestSteering = createRequestSteeringInbox({
@@ -27,13 +37,13 @@ export class LocalRequestExecution {
             requestSteering,
         });
         return {
-            toolApprovalController: this.createToolApprovalController(),
+            toolApprovalController: this.toolApprovals,
             requestSteering,
         };
     }
     publishScheduled(payload) {
         const isTerminal = payload.type === "completed" || payload.type === "failed";
-        const outbound = isTerminal
+        const outbound = isTerminal && payload.requestOrigin !== "approval"
             ? { ...payload, requestOrigin: "schedule" }
             : payload;
         if (payload.sessionDeleted !== true)
@@ -99,6 +109,14 @@ export class LocalRequestExecution {
             finalState: active.finalState,
         };
     }
+    activeReplayForSession(requestId, sessionId, environmentId) {
+        const active = this.activeRequests.get(requestId);
+        if (!active || active.sessionId !== sessionId)
+            return undefined;
+        if (active.environmentId !== environmentId)
+            return undefined;
+        return active.events;
+    }
     healthDetails() {
         return [...this.activeRequests.values()].map((request) => ({
             requestId: request.requestId,
@@ -139,15 +157,17 @@ export class LocalRequestExecution {
             };
     }
     resolveToolApproval(message) {
-        const approvalId = getString(message.approvalId);
-        if (!approvalId)
-            return;
-        const pending = this.pendingToolApprovals.get(approvalId);
-        if (!pending)
-            return;
-        pending.resolve({
-            approved: message.approved === true,
-            reason: getString(message.reason).trim() || undefined,
+        this.toolApprovals.resolveRealtime(message);
+    }
+    attachToolApproval(environmentId, environment, pending, events) {
+        return attachApprovalRequest({
+            environmentId,
+            environment,
+            pending,
+            events,
+            activeRequests: this.activeRequests,
+            toolApprovals: this.toolApprovals,
+            publish: (data) => this.publishRaw(data, { environmentId, sessionId: pending.sessionId }),
         });
     }
     async run(environment, request, environmentId, sessionId, requestSteering) {
@@ -155,39 +175,11 @@ export class LocalRequestExecution {
             send: (data) => this.publishRaw(data, { environmentId, sessionId }),
         };
         await environment.requests.handle(localWs, request, {
-            toolApprovalController: this.createToolApprovalController(),
+            toolApprovalController: this.toolApprovals,
             requestSteering,
+            durableApprovals: true,
         });
     }
-    createToolApprovalController() {
-        return {
-            requestToolApproval: (request, options) => new Promise((resolve) => {
-                if (options?.abortSignal?.aborted) {
-                    resolve({
-                        approved: false,
-                        reason: "Tool approval was cancelled.",
-                    });
-                    return;
-                }
-                const complete = (decision) => {
-                    this.pendingToolApprovals.delete(request.approvalId);
-                    options?.abortSignal?.removeEventListener("abort", onAbort);
-                    resolve(decision);
-                };
-                const onAbort = () => complete({
-                    approved: false,
-                    reason: "Tool approval was cancelled.",
-                });
-                options?.abortSignal?.addEventListener("abort", onAbort, {
-                    once: true,
-                });
-                this.pendingToolApprovals.set(request.approvalId, {
-                    requestId: request.requestId,
-                    resolve: complete,
-                });
-            }),
-        };
-    }
     publishRaw(data, context) {
         try {
             const parsed = JSON.parse(data);
@@ -231,5 +223,12 @@ export class LocalRequestExecution {
             }
         }
         this.realtime.broadcast(payload);
+        if (payload.name === "request.lifecycle.changed") {
+            this.realtime.broadcast({
+                type: "workspace_changed",
+                environment: payload.environment,
+                resources: ["approvals", "sessions"],
+            });
+        }
     }
 }

package/dist/src/web-ui/local-runtime/runtime-availability.js

@@ -1,17 +1,38 @@
+import { validateEffectiveRuntimeModelConfig } from "../../runtime/config/effective-model-config-validation.js";
 import { buildRuntimeModelConfiguration } from "../../runtime/config/builders.js";
 import { isRecord } from "../../runtime/config/utils.js";
 import { validateRuntimeConfigFile } from "../../runtime/config/validation.js";
-function setupRequired(message) {
+import { readConfiguredSetupRunner } from "./runtime-setup-provider.js";
+function hasExistingSetupProfiles(source) {
+    const models = isRecord(source.config.models) ? source.config.models : {};
+    const profiles = isRecord(models.profiles) ? models.profiles : {};
+    return Object.keys(profiles).length > 0;
+}
+function setupRequired(source, message) {
+    const hasExistingProfiles = hasExistingSetupProfiles(source);
     return {
         status: "setup_required",
         code: "runtime_configuration_required",
-        message,
+        message: hasExistingProfiles
+            ? "Existing model profiles need attention. Open Models to repair their provider, model and request-runner settings."
+            : message,
+        ...(hasExistingProfiles ? { recovery: "configuration" } : {}),
     };
 }
 export function inspectRuntimeSetupRequirement(source) {
     if (!source.exists) {
-        return setupRequired("No runtime configuration was found. Choose a provider and model to finish setup.");
+        return setupRequired(source, "No runtime configuration was found. Choose a provider and model to finish setup.");
+    }
+    try {
+        return inspectExistingRuntimeSetup(source);
+    }
+    catch (error) {
+        if (!hasExistingSetupProfiles(source))
+            throw error;
+        return setupRequired(source, "Review the existing configuration.");
     }
+}
+function inspectExistingRuntimeSetup(source) {
     validateRuntimeConfigFile(source.config, source.path, {
         allowIncompleteSetup: true,
     });
@@ -21,10 +42,10 @@ export function inspectRuntimeSetupRequirement(source) {
     const providers = modelPolicy?.providers ?? {};
     const profiles = Object.values(modelPolicy?.profiles ?? {});
     if (Object.keys(providers).length === 0) {
-        return setupRequired("No usable model provider is configured. Choose a provider and model to finish setup.");
+        return setupRequired(source, "No usable model provider is configured. Choose a provider and model to finish setup.");
     }
     if (profiles.length === 0) {
-        return setupRequired("No model profile has a concrete model ID. Add a model connected to a declared provider.");
+        return setupRequired(source, "No model profile has a concrete model ID. Add a model connected to a declared provider.");
     }
     const usableProfile = profiles.find((profile) => {
         const modelId = profile.model?.trim();
@@ -32,14 +53,22 @@ export function inspectRuntimeSetupRequirement(source) {
         return !!modelId && !!providerId && Object.hasOwn(providers, providerId);
     });
     if (!usableProfile) {
-        return setupRequired("No model profile resolves to a declared provider. Connect a model profile to one of the configured providers.");
+        return setupRequired(source, "No model profile resolves to a declared provider. Connect a model profile to one of the configured providers.");
     }
     const requestRunner = isRecord(source.config.requestRunner)
         ? source.config.requestRunner
         : undefined;
     if (typeof requestRunner?.configRef !== "string" ||
         requestRunner.configRef.trim().length === 0) {
-        return setupRequired("A model is configured, but the request-runner configuration is missing. Run the initializer to finish setup.");
+        return setupRequired(source, "A model is configured, but the request-runner configuration is missing. Run the initializer to finish setup.");
+    }
+    const runnerConfig = readConfiguredSetupRunner(source);
+    if (runnerConfig) {
+        validateEffectiveRuntimeModelConfig({
+            configPath: source.path,
+            modelPolicy,
+            runnerConfig,
+        });
     }
     return null;
 }

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

@@ -0,0 +1,13 @@
+import type { RuntimeSetupActivation } from "./runtime-setup-input.js";
+import type { RuntimeSetupRoutes } from "./runtime-setup-routes.js";
+/** Close only the draft that was present when applying started. */
+export declare function applyAndCompleteRuntimeSetup(setup: RuntimeSetupRoutes, apply: () => Promise<RuntimeSetupActivation>): Promise<RuntimeSetupActivation>;
+export declare function pendingRuntimeSetupCatalog(setup: RuntimeSetupRoutes): Promise<{
+    profiles: never[];
+    modes: never[];
+    availability: {
+        status: string;
+        code: string;
+        message: string;
+    };
+} | null>;

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

@@ -0,0 +1,28 @@
+/** Close only the draft that was present when applying started. */
+export async function applyAndCompleteRuntimeSetup(setup, apply) {
+    const snapshot = await setup.status();
+    const revision = snapshot.editableConnection?.revision;
+    const activation = await apply();
+    if (activation.status !== "ready" || !revision)
+        return activation;
+    if (await setup.finalize(revision))
+        return activation;
+    return {
+        status: "restart_required",
+        message: "Your connection changed while setup was being applied. Review the current settings and apply again.",
+    };
+}
+export async function pendingRuntimeSetupCatalog(setup) {
+    const snapshot = await setup.status();
+    if (!snapshot.editableConnection)
+        return null;
+    return {
+        profiles: [],
+        modes: [],
+        availability: {
+            status: "setup_required",
+            code: "runtime_configuration_required",
+            message: "Continue setup to review and apply your saved connection.",
+        },
+    };
+}

package/dist/src/web-ui/local-runtime/runtime-setup-connection-edit.d.ts

@@ -0,0 +1,13 @@
+import { type RuntimeSetupInput } from "./runtime-setup-input.js";
+import { type RuntimeSetupDraft } from "./runtime-setup-draft.js";
+/** Applies only fields owned by the unfinished wizard, retaining optional-step edits. */
+export declare function editRuntimeSetupConnection(params: {
+    rootDir: string;
+    configPath: string;
+    draft: RuntimeSetupDraft;
+    input: RuntimeSetupInput;
+    credentialChanged: boolean;
+}): Promise<{
+    draft: RuntimeSetupDraft;
+    embeddingInvalidated: boolean;
+}>;

package/dist/src/web-ui/local-runtime/runtime-setup-connection-edit.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { buildModelConfig, buildProviderConfig, readJsonObject, resolveRuntimePackageRoot, } from "../../../scripts/runtime-setup-files.js";
+import { withConfigFileTransaction } from "../../runtime/adapters/config-file-transaction.js";
+import { inspectRuntimeConfigFileWithMeta } from "../../runtime/config/loader.js";
+import { RuntimeSetupError, } from "./runtime-setup-input.js";
+import { isCurrentRuntimeSetupDraft, setupConfigurationChanged, setupConfigMap, writeRuntimeSetupDraft, } from "./runtime-setup-draft.js";
+import { validateRuntimeSetupPlan } from "./runtime-setup-validation.js";
+import { retainSetupConnectionProviders } from "./runtime-setup-provider-retention.js";
+import { shouldInvalidateSetupEmbedding } from "./runtime-setup-embedding-invalidation.js";
+function preserveExistingProvider(existing, requested, owned) {
+    if (existing === undefined)
+        return;
+    if (owned)
+        return;
+    if (isDeepStrictEqual(existing, requested))
+        return;
+    throw new RuntimeSetupError("setup_provider_conflict", "That provider already has settings. Its existing connection was preserved.", 409);
+}
+/** Applies only fields owned by the unfinished wizard, retaining optional-step edits. */
+export async function editRuntimeSetupConnection(params) {
+    return withConfigFileTransaction(params.configPath, async (configTransaction) => {
+        const source = inspectRuntimeConfigFileWithMeta(params.rootDir, params.configPath);
+        if (!(await isCurrentRuntimeSetupDraft(source, params.draft)))
+            throw setupConfigurationChanged();
+        return withConfigFileTransaction(params.draft.modelPath, async (modelTransaction) => {
+            if (!isDeepStrictEqual(modelTransaction.snapshot.config, params.draft.modelConfig))
+                throw setupConfigurationChanged();
+            const models = setupConfigMap(source.config.models);
+            const providers = setupConfigMap(models.providers);
+            const providerId = params.input.provider;
+            const provider = buildProviderConfig(providerId, params.input.baseUrl);
+            const existing = providers[providerId];
+            const owned = Object.hasOwn(params.draft.ownedProviders, providerId);
+            preserveExistingProvider(existing, provider, owned);
+            const embeddingInvalidated = shouldInvalidateSetupEmbedding({
+                config: source.config,
+                providerId,
+                provider,
+                providerChanged: !isDeepStrictEqual(existing, provider),
+                credentialChanged: params.credentialChanged,
+            });
+            const modelTemplate = await readJsonObject(join(resolveRuntimePackageRoot(import.meta.dirname), "examples/models/default.config.json"));
+            const contextWindowTokens = params.input.contextWindowTokens ??
+                params.draft.modelConfig.contextWindowTokens;
+            const modelConfig = buildModelConfig(modelTemplate, providerId, params.input.model, typeof contextWindowTokens === "number"
+                ? contextWindowTokens
+                : undefined);
+            const memory = setupConfigMap(source.config.longTermMemory);
+            const retained = retainSetupConnectionProviders({
+                providers,
+                ownedProviders: params.draft.ownedProviders,
+                embeddingProfiles: models.embeddingProfiles,
+                providerId,
+                provider,
+            });
+            const config = {
+                ...source.config,
+                models: {
+                    ...models,
+                    providers: retained.providers,
+                },
+                ...(embeddingInvalidated
+                    ? { longTermMemory: { ...memory, enabled: false } }
+                    : {}),
+            };
+            const runner = setupConfigMap(config.requestRunner);
+            if (typeof runner.configRef !== "string")
+                throw setupConfigurationChanged();
+            await validateRuntimeSetupPlan({
+                rootDir: params.rootDir,
+                config,
+                modelConfig,
+                runnerPath: resolve(dirname(params.configPath), runner.configRef),
+            });
+            const nextDraft = {
+                ...params.draft,
+                revision: randomUUID(),
+                modelConfig,
+                ownedProviders: retained.ownedProviders,
+            };
+            let modelWritten = false;
+            let configWritten = false;
+            try {
+                await modelTransaction.write(modelConfig, {
+                    expectedConfig: params.draft.modelConfig,
+                });
+                modelWritten = true;
+                await configTransaction.write(config, {
+                    expectedConfig: source.config,
+                });
+                configWritten = true;
+                await writeRuntimeSetupDraft(nextDraft);
+            }
+            catch (error) {
+                if (configWritten)
+                    await configTransaction.write(source.config, {
+                        expectedConfig: config,
+                    });
+                if (modelWritten)
+                    await modelTransaction.write(params.draft.modelConfig, {
+                        expectedConfig: modelConfig,
+                    });
+                throw error;
+            }
+            return { draft: nextDraft, embeddingInvalidated };
+        });
+    });
+}

package/dist/src/web-ui/local-runtime/runtime-setup-credential-completion.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeSetupInput } from "./runtime-setup-input.js";
+import type { configuredSetupModel } from "./runtime-setup-provider.js";
+/** A revisionless retry can fill a missing credential, never edit its connection. */
+export declare function canCompleteMissingRuntimeSetupCredential(existing: ReturnType<typeof configuredSetupModel>, input: RuntimeSetupInput, rootDir: string): boolean;

package/dist/src/web-ui/local-runtime/runtime-setup-credential-completion.js

@@ -0,0 +1,21 @@
+import { readRuntimeSetupCredential } from "./runtime-setup-credentials.js";
+/** A revisionless retry can fill a missing credential, never edit its connection. */
+export function canCompleteMissingRuntimeSetupCredential(existing, input, rootDir) {
+    if (!existing)
+        return false;
+    if (input.connectionRevision !== undefined)
+        return false;
+    if (existing.provider !== "openai")
+        return false;
+    if (input.provider !== existing.provider)
+        return false;
+    if (existing.model.trim() !== input.model.trim())
+        return false;
+    const requestedContext = input.contextWindowTokens ?? existing.contextWindowTokens;
+    if (requestedContext !== existing.contextWindowTokens)
+        return false;
+    // Both projections already normalize addresses to origins.
+    if ((existing.baseUrl ?? "") !== (input.baseUrl ?? ""))
+        return false;
+    return !readRuntimeSetupCredential(rootDir, existing.apiKeyEnv);
+}

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

@@ -0,0 +1,14 @@
+type RuntimeSetupCredentialWrite = {
+    rootDir: string;
+    configPath: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    preserveExistingCredential?: boolean;
+};
+export declare function readRuntimeSetupCredential(rootDir: string, apiKeyEnv?: string): string;
+export declare function assertRuntimeSetupCredentialFile(rootDir: string): Promise<void>;
+export declare function hasRuntimeSetupCredential(rootDir: string, apiKeyEnv?: string): Promise<boolean>;
+export declare function persistRuntimeSetupCredentials(params: RuntimeSetupCredentialWrite): Promise<void>;
+/** Keep the credential private and locked until the related setup commit settles. */
+export declare function commitRuntimeSetupCredentials<T>(params: RuntimeSetupCredentialWrite, commit: () => Promise<T>): Promise<T>;
+export {};

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

@@ -0,0 +1,148 @@
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+import { parse } from "dotenv";
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { chmod, lstat, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { replaceRuntimeSetupEnvironmentAssignment } from "./runtime-setup-environment-assignment.js";
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function readCredentialFileSnapshot(rootDir) {
+    const path = join(rootDir, ".env");
+    try {
+        const info = await lstat(path);
+        const isRegularCredentialFile = info.isFile() && !info.isSymbolicLink();
+        if (!isRegularCredentialFile)
+            throw new RuntimeSetupError("unsafe_credential_file", "The local credential file must be a regular file.", 409);
+        return { raw: await readFile(path, "utf8"), mode: info.mode & 0o777 };
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return { mode: 0o600 };
+        throw error;
+    }
+}
+async function readCredentialFile(rootDir) {
+    return (await readCredentialFileSnapshot(rootDir)).raw ?? "";
+}
+async function requireUnchangedCredentialFile(rootDir, expected) {
+    const current = await readCredentialFileSnapshot(rootDir);
+    if (current.raw === expected)
+        return;
+    throw new RuntimeSetupError("setup_credentials_changed", "Credentials changed while setup was being saved. Try again.", 409);
+}
+async function replaceCredentialFile(rootDir, previous, next, mode = 0o600) {
+    const path = join(rootDir, ".env");
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, next, { encoding: "utf8", mode, flag: "wx" });
+        await chmod(temporary, mode);
+        await requireUnchangedCredentialFile(rootDir, previous);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await removeFailedCredentialTemporary(error, temporary);
+    }
+}
+async function removeFailedCredentialTemporary(error, temporary) {
+    try {
+        await rm(temporary, { force: true });
+    }
+    catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "Credential saving failed and its temporary file could not be removed.");
+    }
+    throw error;
+}
+async function restoreCredentialFile(rootDir, previous, written) {
+    if (previous.raw !== undefined) {
+        await replaceCredentialFile(rootDir, written, previous.raw, previous.mode);
+        return;
+    }
+    await requireUnchangedCredentialFile(rootDir, written);
+    await rm(join(rootDir, ".env"), { force: true });
+}
+async function restoreCredentialsAfterFailure(error, rootDir, previous, written) {
+    try {
+        await restoreCredentialFile(rootDir, previous, written);
+    }
+    catch (rollbackError) {
+        throw new AggregateError([error, rollbackError], "Setup failed and its credential file could not be restored.");
+    }
+    throw error;
+}
+async function commitOrRestoreCredentials(rootDir, previous, written, commit) {
+    try {
+        return await commit();
+    }
+    catch (error) {
+        return restoreCredentialsAfterFailure(error, rootDir, previous, written);
+    }
+}
+function readSavedApiKey(raw, apiKeyEnv) {
+    return parse(raw)[apiKeyEnv]?.trim() ?? "";
+}
+export function readRuntimeSetupCredential(rootDir, apiKeyEnv = "OPENAI_API_KEY") {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(apiKeyEnv))
+        return "";
+    const inherited = process.env[apiKeyEnv]?.trim();
+    if (inherited)
+        return inherited;
+    const path = join(rootDir, ".env");
+    try {
+        if (!lstatSync(path).isFile())
+            return "";
+        return readSavedApiKey(readFileSync(path, "utf8"), apiKeyEnv);
+    }
+    catch {
+        return "";
+    }
+}
+export async function assertRuntimeSetupCredentialFile(rootDir) {
+    await readCredentialFile(rootDir);
+}
+export async function hasRuntimeSetupCredential(rootDir, apiKeyEnv = "OPENAI_API_KEY") {
+    return Boolean(readRuntimeSetupCredential(rootDir, apiKeyEnv));
+}
+export async function persistRuntimeSetupCredentials(params) {
+    await commitRuntimeSetupCredentials(params, async () => undefined);
+}
+/** Keep the credential private and locked until the related setup commit settles. */
+export async function commitRuntimeSetupCredentials(params, commit) {
+    const rootDir = await realpath(params.rootDir);
+    return withFileLock(join(rootDir, ".env.credentials.lock"), () => saveCredentialAssignments({ ...params, rootDir }, commit));
+}
+function wouldReplaceConfiguredCredential(preserveExistingCredential, incomingKey, configuredKeys) {
+    if (!preserveExistingCredential)
+        return false;
+    if (!incomingKey)
+        return false;
+    return configuredKeys.some((configuredKey) => {
+        if (!configuredKey)
+            return false;
+        return configuredKey !== incomingKey;
+    });
+}
+async function saveCredentialAssignments(params, commit) {
+    const apiKeyEnv = params.apiKeyEnv ?? "OPENAI_API_KEY";
+    const previousFile = await readCredentialFileSnapshot(params.rootDir);
+    const previous = previousFile.raw ?? "";
+    const configuredKeys = [
+        readSavedApiKey(previous, apiKeyEnv),
+        process.env[apiKeyEnv]?.trim() ?? "",
+    ];
+    if (wouldReplaceConfiguredCredential(params.preserveExistingCredential, params.apiKey, configuredKeys))
+        throw new RuntimeSetupError("credential_already_configured", "That provider now has a saved API key. Its credential was preserved.", 409);
+    let next = replaceRuntimeSetupEnvironmentAssignment(previous, "LLM_RUNTIME_CONFIG_FILE", params.configPath);
+    if (params.apiKey)
+        next = replaceRuntimeSetupEnvironmentAssignment(next, apiKeyEnv, params.apiKey);
+    await replaceCredentialFile(params.rootDir, previousFile.raw, next);
+    const result = await commitOrRestoreCredentials(params.rootDir, previousFile, next, commit);
+    const key = params.apiKey ||
+        process.env[apiKeyEnv] ||
+        readSavedApiKey(previous, apiKeyEnv);
+    if (key)
+        process.env[apiKeyEnv] = key;
+    return result;
+}

package/dist/src/web-ui/local-runtime/runtime-setup-draft-recovery.d.ts

@@ -0,0 +1,7 @@
+import type { InspectedRuntimeConfigFile } from "../../runtime/config/loader.js";
+import { type RuntimeSetupDraft } from "./runtime-setup-draft.js";
+export declare function inspectRuntimeSetupDraftForSave(source: InspectedRuntimeConfigFile): Promise<{
+    draft?: RuntimeSetupDraft;
+    recoveryDraft?: RuntimeSetupDraft;
+    recoveringDraft: boolean;
+}>;

package/dist/src/web-ui/local-runtime/runtime-setup-draft-recovery.js

@@ -0,0 +1,18 @@
+import { isCurrentRuntimeSetupDraft, readRuntimeSetupDraft, } from "./runtime-setup-draft.js";
+import { MalformedRuntimeSetupReceiptError } from "./runtime-setup-receipt-file.js";
+export async function inspectRuntimeSetupDraftForSave(source) {
+    let draft;
+    try {
+        draft = await readRuntimeSetupDraft(source.path);
+    }
+    catch (error) {
+        if (!(error instanceof MalformedRuntimeSetupReceiptError))
+            throw error;
+        return { recoveringDraft: true };
+    }
+    if (!draft)
+        return { recoveringDraft: false };
+    if (await isCurrentRuntimeSetupDraft(source, draft))
+        return { draft, recoveringDraft: false };
+    return { recoveryDraft: draft, recoveringDraft: true };
+}