@abot-ai/runtime 1.6.0 → 1.8.0

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

@@ -108,10 +108,36 @@ export async function hasRuntimeSetupCredential(rootDir, apiKeyEnv = "OPENAI_API
 export async function persistRuntimeSetupCredentials(params) {
     await commitRuntimeSetupCredentials(params, async () => undefined);
 }
+/** Publish process credentials only after the caller's complete transaction commits. */
+export async function withPlannedRuntimeSetupCredentials(params, operation) {
+    const rootDir = await realpath(params.rootDir);
+    return withFileLock(join(rootDir, ".env.credentials.lock"), async () => {
+        const plan = await planCredentialAssignments({ ...params, rootDir });
+        const publish = () => {
+            const key = params.apiKey ||
+                process.env[plan.apiKeyEnv] ||
+                readSavedApiKey(plan.previousFile.raw ?? "", plan.apiKeyEnv);
+            if (key)
+                process.env[plan.apiKeyEnv] = key;
+        };
+        const result = await operation({
+            rootDir,
+            path: join(rootDir, ".env"),
+            text: plan.next,
+            previous: plan.previousFile,
+            write: () => replaceCredentialFile(rootDir, plan.previousFile.raw, plan.next),
+            publish,
+        });
+        publish();
+        return result;
+    });
+}
 /** 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));
+    return withPlannedRuntimeSetupCredentials(params, async (plan) => {
+        await plan.write();
+        return commitOrRestoreCredentials(plan.rootDir, plan.previous, plan.text, commit);
+    });
 }
 function wouldReplaceConfiguredCredential(preserveExistingCredential, incomingKey, configuredKeys) {
     if (!preserveExistingCredential)
@@ -124,7 +150,7 @@ function wouldReplaceConfiguredCredential(preserveExistingCredential, incomingKe
         return configuredKey !== incomingKey;
     });
 }
-async function saveCredentialAssignments(params, commit) {
+async function planCredentialAssignments(params) {
     const apiKeyEnv = params.apiKeyEnv ?? "OPENAI_API_KEY";
     const previousFile = await readCredentialFileSnapshot(params.rootDir);
     const previous = previousFile.raw ?? "";
@@ -137,12 +163,5 @@ async function saveCredentialAssignments(params, commit) {
     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;
+    return { previousFile, next, apiKeyEnv };
 }

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

@@ -0,0 +1,20 @@
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export type SetupEditFileSnapshot = Readonly<{
+    bytes: string | null;
+    mode: number;
+}>;
+export declare function setupEditRecoveryRequired(): RuntimeSetupError;
+export declare function isMissingSetupEditFile(error: unknown): boolean;
+/** Snapshots preserve bytes, existence and mode; linked or special targets are not owned. */
+export declare function readSetupEditFile(path: string): Promise<SetupEditFileSnapshot>;
+export declare function setupEditFileMatches(actual: SetupEditFileSnapshot, expected: SetupEditFileSnapshot): boolean;
+export declare function setupEditTextSnapshot(text: string, mode: number): SetupEditFileSnapshot;
+export declare function setupEditSnapshotText(snapshot: SetupEditFileSnapshot): string;
+/** Directory sync is available on Unix; Windows does not expose it through Node. */
+export declare function syncSetupEditDirectory(path: string): Promise<void>;
+export declare function syncSetupEditFile(path: string): Promise<void>;
+export declare function requireSetupEditFileSnapshot(path: string, expected: SetupEditFileSnapshot): Promise<void>;
+/** Cooperative locks are held by the caller; recheck immediately before replacement. */
+export declare function restoreSetupEditFile(path: string, expected: SetupEditFileSnapshot, replacement: SetupEditFileSnapshot): Promise<void>;
+/** Publish the marker itself atomically; private mode also protects credential snapshots. */
+export declare function publishSetupEditJournal(path: string, text: string, expected: SetupEditFileSnapshot): Promise<void>;

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

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { canonicalConfigFilePath } from "../../runtime/adapters/config-file-transaction.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export function setupEditRecoveryRequired() {
+    return new RuntimeSetupError("setup_edit_recovery_required", "An interrupted connection edit needs recovery. Restart this Runtime before applying configuration. If recovery reports a conflict, preserve the transaction and review the changed files.", 409);
+}
+export function isMissingSetupEditFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/** Snapshots preserve bytes, existence and mode; linked or special targets are not owned. */
+export async function readSetupEditFile(path) {
+    if ((await canonicalConfigFilePath(path)) !== path)
+        throw setupEditRecoveryRequired();
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw setupEditRecoveryRequired();
+        return {
+            bytes: (await readFile(path)).toString("base64"),
+            mode: info.mode & 0o777,
+        };
+    }
+    catch (error) {
+        if (isMissingSetupEditFile(error))
+            return { bytes: null, mode: 0 };
+        throw error;
+    }
+}
+export function setupEditFileMatches(actual, expected) {
+    if (actual.bytes !== expected.bytes)
+        return false;
+    // Node's Windows chmod only implements the writable bit, unlike POSIX modes.
+    const mask = process.platform === "win32" ? 0o200 : 0o777;
+    return (actual.mode & mask) === (expected.mode & mask);
+}
+export function setupEditTextSnapshot(text, mode) {
+    return { bytes: Buffer.from(text, "utf8").toString("base64"), mode };
+}
+export function setupEditSnapshotText(snapshot) {
+    if (snapshot.bytes === null)
+        throw setupEditRecoveryRequired();
+    return Buffer.from(snapshot.bytes, "base64").toString("utf8");
+}
+/** Directory sync is available on Unix; Windows does not expose it through Node. */
+export async function syncSetupEditDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function syncSetupEditFile(path) {
+    // Windows FlushFileBuffers requires a handle opened for writing.
+    const handle = await open(path, process.platform === "win32" ? "r+" : "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncSetupEditDirectory(dirname(path));
+}
+export async function requireSetupEditFileSnapshot(path, expected) {
+    if (!setupEditFileMatches(await readSetupEditFile(path), expected))
+        throw setupEditRecoveryRequired();
+}
+/** Cooperative locks are held by the caller; recheck immediately before replacement. */
+export async function restoreSetupEditFile(path, expected, replacement) {
+    await requireSetupEditFileSnapshot(path, expected);
+    if (replacement.bytes === null) {
+        await rm(path);
+        await syncSetupEditDirectory(dirname(path));
+        return;
+    }
+    const temporary = `${path}.${randomUUID()}.setup-edit.tmp`;
+    try {
+        const handle = await open(temporary, "wx", replacement.mode);
+        try {
+            await handle.writeFile(Buffer.from(replacement.bytes, "base64"));
+            await handle.chmod(replacement.mode);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await requireSetupEditFileSnapshot(path, expected);
+        await rename(temporary, path);
+        await syncSetupEditDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Publish the marker itself atomically; private mode also protects credential snapshots. */
+export async function publishSetupEditJournal(path, text, expected) {
+    await restoreSetupEditFile(path, expected, setupEditTextSnapshot(text, 0o600));
+    await chmod(path, 0o600);
+}

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

@@ -0,0 +1,29 @@
+import { type SetupEditFileSnapshot } from "./runtime-setup-edit-files.js";
+export declare const SETUP_EDIT_JOURNAL_NAME = ".runtime-setup-edit.json";
+declare const FILE_ROLES: readonly ["model", "config", "receipt", "credentials"];
+type SetupEditFileRole = (typeof FILE_ROLES)[number];
+export type SetupEditJournalFile = Readonly<{
+    role: SetupEditFileRole;
+    path: string;
+    before: SetupEditFileSnapshot;
+    after: SetupEditFileSnapshot;
+}>;
+export type SetupEditJournal = Readonly<{
+    version: 1;
+    id: string;
+    rootDir: string;
+    phase: "pending" | "committed";
+    files: readonly SetupEditJournalFile[];
+}>;
+export type SetupEditFilePlan = Readonly<{
+    role: SetupEditFileRole;
+    path: string;
+    text: string;
+    mode?: number;
+}>;
+export declare function setupEditJournalPath(rootDir: string): string;
+export declare function validateSetupEditJournal(value: unknown, rootDir: string): Promise<SetupEditJournal>;
+export declare function readSetupEditJournal(rootDir: string): Promise<SetupEditJournal | undefined>;
+export declare function createSetupEditJournal(rootDir: string, plans: readonly SetupEditFilePlan[]): Promise<SetupEditJournal>;
+export declare function writeSetupEditJournal(journal: SetupEditJournal, previous?: SetupEditJournal): Promise<void>;
+export {};

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

@@ -0,0 +1,151 @@
+import { parse } from "dotenv";
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { isRecord } from "../../runtime/config/utils.js";
+import { canonicalConfigFilePath } from "../../runtime/adapters/config-file-transaction.js";
+import { readSetupEditFile, setupEditRecoveryRequired, setupEditSnapshotText, setupEditTextSnapshot, publishSetupEditJournal, } from "./runtime-setup-edit-files.js";
+export const SETUP_EDIT_JOURNAL_NAME = ".runtime-setup-edit.json";
+const FILE_ROLES = ["model", "config", "receipt", "credentials"];
+export function setupEditJournalPath(rootDir) {
+    return join(rootDir, SETUP_EDIT_JOURNAL_NAME);
+}
+function isSetupEditSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    if (!Number.isInteger(value.mode))
+        return false;
+    if (typeof value.mode !== "number" || value.mode < 0 || value.mode > 0o777)
+        return false;
+    if (value.bytes === null)
+        return value.mode === 0;
+    if (typeof value.bytes !== "string")
+        return false;
+    return Buffer.from(value.bytes, "base64").toString("base64") === value.bytes;
+}
+function isSetupEditJournalFile(value, index) {
+    if (!isRecord(value))
+        return false;
+    if (value.role !== FILE_ROLES[index])
+        return false;
+    if (typeof value.path !== "string" || value.path !== resolve(value.path))
+        return false;
+    if (!isSetupEditSnapshot(value.before))
+        return false;
+    if (!isSetupEditSnapshot(value.after))
+        return false;
+    if (value.after.bytes === null)
+        return false;
+    if (value.role !== "credentials" && value.before.bytes === null)
+        return false;
+    return true;
+}
+function parseSetupEditObject(snapshot) {
+    const value = JSON.parse(setupEditSnapshotText(snapshot));
+    if (!isRecord(value))
+        throw setupEditRecoveryRequired();
+    return value;
+}
+async function requireSetupEditFileBindings(journal) {
+    const [model, config, receipt, credentials] = journal.files;
+    if (receipt.path !== config.path + ".web-setup.json")
+        throw setupEditRecoveryRequired();
+    if (credentials.path !== join(journal.rootDir, ".env"))
+        throw setupEditRecoveryRequired();
+    if (new Set(journal.files.map((file) => file.path)).size !== FILE_ROLES.length)
+        throw setupEditRecoveryRequired();
+    for (const state of ["before", "after"]) {
+        const draft = parseSetupEditObject(receipt[state]);
+        if (draft.version !== 1 || typeof draft.revision !== "string")
+            throw setupEditRecoveryRequired();
+        if (draft.configPath !== config.path || draft.modelPath !== model.path)
+            throw setupEditRecoveryRequired();
+        if (!isDeepStrictEqual(draft.modelConfig, parseSetupEditObject(model[state])))
+            throw setupEditRecoveryRequired();
+        const saved = parseSetupEditObject(config[state]);
+        const models = isRecord(saved.models) ? saved.models : {};
+        const profiles = isRecord(models.profiles) ? models.profiles : {};
+        if (!isDeepStrictEqual(draft.profileReferences, profiles))
+            throw setupEditRecoveryRequired();
+        if (!isRecord(draft.ownedProviders))
+            throw setupEditRecoveryRequired();
+        const providers = isRecord(models.providers) ? models.providers : {};
+        for (const [id, provider] of Object.entries(draft.ownedProviders)) {
+            if (!isDeepStrictEqual(providers[id], provider))
+                throw setupEditRecoveryRequired();
+        }
+        const profile = isRecord(profiles.default) ? profiles.default : {};
+        if (typeof profile.configRef !== "string")
+            throw setupEditRecoveryRequired();
+        const referenced = await canonicalConfigFilePath(resolve(dirname(config.path), profile.configRef));
+        if (referenced !== model.path)
+            throw setupEditRecoveryRequired();
+    }
+    const env = parse(setupEditSnapshotText(credentials.after));
+    if (typeof env.LLM_RUNTIME_CONFIG_FILE !== "string")
+        throw setupEditRecoveryRequired();
+    const configured = await canonicalConfigFilePath(resolve(journal.rootDir, env.LLM_RUNTIME_CONFIG_FILE));
+    if (configured !== config.path)
+        throw setupEditRecoveryRequired();
+}
+export async function validateSetupEditJournal(value, rootDir) {
+    try {
+        if (!isRecord(value))
+            throw setupEditRecoveryRequired();
+        if (value.version !== 1 || typeof value.id !== "string")
+            throw setupEditRecoveryRequired();
+        if (value.rootDir !== rootDir)
+            throw setupEditRecoveryRequired();
+        if (value.phase !== "pending" && value.phase !== "committed")
+            throw setupEditRecoveryRequired();
+        if (!Array.isArray(value.files) || value.files.length !== FILE_ROLES.length)
+            throw setupEditRecoveryRequired();
+        if (!value.files.every(isSetupEditJournalFile))
+            throw setupEditRecoveryRequired();
+        const journal = value;
+        await requireSetupEditFileBindings(journal);
+        return journal;
+    }
+    catch {
+        throw setupEditRecoveryRequired();
+    }
+}
+export async function readSetupEditJournal(rootDir) {
+    const snapshot = await readSetupEditFile(setupEditJournalPath(rootDir));
+    if (snapshot.bytes === null)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(setupEditSnapshotText(snapshot));
+    }
+    catch {
+        throw setupEditRecoveryRequired();
+    }
+    return validateSetupEditJournal(value, rootDir);
+}
+export async function createSetupEditJournal(rootDir, plans) {
+    const files = [];
+    for (const plan of plans) {
+        const before = await readSetupEditFile(plan.path);
+        files.push({
+            role: plan.role,
+            path: plan.path,
+            before,
+            after: setupEditTextSnapshot(plan.text, plan.mode ?? before.mode),
+        });
+    }
+    return validateSetupEditJournal({
+        version: 1,
+        id: randomUUID(),
+        rootDir,
+        phase: "pending",
+        files,
+    }, rootDir);
+}
+export async function writeSetupEditJournal(journal, previous) {
+    const path = setupEditJournalPath(journal.rootDir);
+    const expected = previous
+        ? setupEditTextSnapshot(JSON.stringify(previous) + "\n", 0o600)
+        : { bytes: null, mode: 0 };
+    await publishSetupEditJournal(path, JSON.stringify(journal) + "\n", expected);
+}

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

@@ -0,0 +1,7 @@
+import { type SetupEditJournal } from "./runtime-setup-edit-journal.js";
+/** Synchronous consumers must not observe any part of an unresolved edit. */
+export declare function requireRuntimeSetupEditSettled(rootDir: string): void;
+/** Caller holds every participant lock; repeatable after interruption at any restore. */
+export declare function reconcileSetupEditJournal(journal: SetupEditJournal): Promise<void>;
+/** Runs before dotenv/configuration loading. No journal means no speculative repair. */
+export declare function recoverRuntimeSetupEdit(rootDir: string): Promise<void>;

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

@@ -0,0 +1,87 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { realpath, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+import { CONFIG_FILE_LOCK_OPTIONS } from "../../runtime/adapters/config-file-transaction.js";
+import { isMissingSetupEditFile, readSetupEditFile, requireSetupEditFileSnapshot, restoreSetupEditFile, setupEditFileMatches, setupEditRecoveryRequired, setupEditTextSnapshot, syncSetupEditDirectory, } from "./runtime-setup-edit-files.js";
+import { readSetupEditJournal, setupEditJournalPath, } from "./runtime-setup-edit-journal.js";
+/** Synchronous consumers must not observe any part of an unresolved edit. */
+export function requireRuntimeSetupEditSettled(rootDir) {
+    let path = resolve(rootDir);
+    try {
+        path = realpathSync(path);
+        lstatSync(setupEditJournalPath(path));
+    }
+    catch (error) {
+        if (isMissingSetupEditFile(error))
+            return;
+        throw setupEditRecoveryRequired();
+    }
+    throw setupEditRecoveryRequired();
+}
+async function requireRecoverableSetupEditFiles(journal) {
+    for (const file of journal.files) {
+        const current = await readSetupEditFile(file.path);
+        if (setupEditFileMatches(current, file.after))
+            continue;
+        if (journal.phase === "pending" &&
+            setupEditFileMatches(current, file.before))
+            continue;
+        throw setupEditRecoveryRequired();
+    }
+}
+/** Caller holds every participant lock; repeatable after interruption at any restore. */
+export async function reconcileSetupEditJournal(journal) {
+    await requireRecoverableSetupEditFiles(journal);
+    if (journal.phase === "pending") {
+        for (const file of [...journal.files].reverse()) {
+            const current = await readSetupEditFile(file.path);
+            if (setupEditFileMatches(current, file.before))
+                continue;
+            if (!setupEditFileMatches(current, file.after))
+                throw setupEditRecoveryRequired();
+            await restoreSetupEditFile(file.path, file.after, file.before);
+        }
+    }
+    const path = setupEditJournalPath(journal.rootDir);
+    await requireSetupEditFileSnapshot(path, setupEditTextSnapshot(JSON.stringify(journal) + "\n", 0o600));
+    await rm(path);
+    await syncSetupEditDirectory(journal.rootDir);
+}
+async function withSetupEditRecoveryLocks(journal, operation) {
+    const [model, config, receipt] = journal.files;
+    const locks = [
+        config.path + ".config.lock",
+        model.path + ".config.lock",
+        join(journal.rootDir, ".env.credentials.lock"),
+        receipt.path + ".config.lock",
+    ];
+    const acquire = (index) => {
+        if (index === locks.length)
+            return operation();
+        return withFileLock(locks[index], () => acquire(index + 1), CONFIG_FILE_LOCK_OPTIONS);
+    };
+    return acquire(0);
+}
+/** Runs before dotenv/configuration loading. No journal means no speculative repair. */
+export async function recoverRuntimeSetupEdit(rootDir) {
+    try {
+        requireRuntimeSetupEditSettled(rootDir);
+        return;
+    }
+    catch {
+        // Parsing and lock acquisition below decide whether recovery is safe.
+    }
+    const root = await realpath(rootDir);
+    await withFileLock(join(root, ".runtime-setup.lock"), async () => {
+        const journal = await readSetupEditJournal(root);
+        if (!journal)
+            return;
+        await withSetupEditRecoveryLocks(journal, async () => {
+            const current = await readSetupEditJournal(root);
+            if (!current || JSON.stringify(current) !== JSON.stringify(journal))
+                throw setupEditRecoveryRequired();
+            await reconcileSetupEditJournal(journal);
+        });
+    }, CONFIG_FILE_LOCK_OPTIONS);
+}

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

@@ -0,0 +1,3 @@
+import { type SetupEditFilePlan } from "./runtime-setup-edit-journal.js";
+/** Setup, config, model and credential locks enclose this complete transaction. */
+export declare function commitRuntimeSetupEdit(rootDir: string, files: readonly SetupEditFilePlan[], commit: () => Promise<void>, publishCommittedCredentials: () => void): Promise<void>;

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

@@ -0,0 +1,37 @@
+import { realpath } from "node:fs/promises";
+import { createSetupEditJournal, readSetupEditJournal, writeSetupEditJournal, } from "./runtime-setup-edit-journal.js";
+import { requireSetupEditFileSnapshot, syncSetupEditFile, } from "./runtime-setup-edit-files.js";
+import { reconcileSetupEditJournal, requireRuntimeSetupEditSettled, } from "./runtime-setup-edit-recovery.js";
+/** Setup, config, model and credential locks enclose this complete transaction. */
+export async function commitRuntimeSetupEdit(rootDir, files, commit, publishCommittedCredentials) {
+    const root = await realpath(rootDir);
+    requireRuntimeSetupEditSettled(root);
+    const journal = await createSetupEditJournal(root, files);
+    await writeSetupEditJournal(journal);
+    try {
+        await commit();
+        for (const file of journal.files) {
+            await requireSetupEditFileSnapshot(file.path, file.after);
+            await syncSetupEditFile(file.path);
+        }
+        await writeSetupEditJournal({ ...journal, phase: "committed" }, journal);
+    }
+    catch (error) {
+        try {
+            const persisted = await readSetupEditJournal(root);
+            if (persisted?.phase === "committed")
+                publishCommittedCredentials();
+            if (persisted)
+                await reconcileSetupEditJournal(persisted);
+            if (persisted?.phase === "committed")
+                return;
+        }
+        catch (recoveryError) {
+            throw new AggregateError([error, recoveryError], "Connection edit failed and needs recovery before it can be applied.");
+        }
+        throw error;
+    }
+    publishCommittedCredentials();
+    // A cleanup failure leaves a committed marker. Never roll it back.
+    await reconcileSetupEditJournal({ ...journal, phase: "committed" });
+}

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

@@ -1,6 +1,7 @@
 import { assertConfigMutationRequest, ConfigMutationRequestError, } from "./config-mutation-request.js";
 import { readBody, readJsonBody, sendJson } from "./http.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { runtimeSetupContextWindowErrorDetails } from "./runtime-setup-context-window.js";
 export class RuntimeSetupRoutes {
     service;
     constructor(service) {
@@ -43,6 +44,7 @@ export class RuntimeSetupRoutes {
                 error instanceof ConfigMutationRequestError;
             sendJson(params.response, isPublicError ? error.statusCode : 400, {
                 ok: false,
+                ...runtimeSetupContextWindowErrorDetails(error),
                 error: error instanceof RuntimeSetupError
                     ? error.code
                     : "runtime_setup_failed",

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

@@ -1,3 +1,4 @@
+import { requireRuntimeSetupEditSettled } from "./runtime-setup-edit-recovery.js";
 import { readDefaultContextWindowTokens } from "../../../scripts/runtime-setup-files.js";
 import { initializeConfiguredRuntimeDirectories } from "../../../scripts/runtime-setup-directories.js";
 import { configuredSetupModel, requiresConfiguredCredential, } from "./runtime-setup-provider.js";
@@ -20,6 +21,7 @@ export class RuntimeSetupService {
         this.options = options;
     }
     source() {
+        requireRuntimeSetupEditSettled(this.options.rootDir);
         return inspectRuntimeConfigFileWithMeta(this.options.rootDir, this.savedConfigPath ?? this.options.getConfigPath());
     }
     async status() {
@@ -156,7 +158,9 @@ export class RuntimeSetupService {
                     draft,
                     input,
                     credentialChanged,
+                    credentialWrite,
                 });
+                credentialsPersisted = true;
                 draft = edited.draft;
                 embeddingInvalidated = edited.embeddingInvalidated;
             }

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

@@ -2,6 +2,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { loadRuntimeConfig } from "../../runtime/config.js";
 import { isRecord } from "../../runtime/config/utils.js";
+import { throwRuntimeSetupValidationError } from "./runtime-setup-context-window.js";
 /** Validate complete effective configuration in isolation before replacing local files. */
 export async function validateRuntimeSetupPlan(params) {
     const staging = await mkdtemp(join(params.rootDir, ".runtime-setup-validation-"));
@@ -26,8 +27,14 @@ export async function validateRuntimeSetupPlan(params) {
             ? Object.keys(environment.profiles)
             : [];
         const environments = profileIds.length ? profileIds : [undefined];
-        for (const profileId of environments)
-            loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+        for (const profileId of environments) {
+            try {
+                loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+            }
+            catch (error) {
+                throwRuntimeSetupValidationError(error, profileId);
+            }
+        }
     }
     finally {
         await rm(staging, { recursive: true, force: true });

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

@@ -3,6 +3,7 @@ import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
 import { WebSessionReadStates } from "../session-read-state/service.js";
 import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
 type SessionRouteRequest = {
+    url?: URL;
     method: string;
     segments: string[];
     body: JsonObject | null;

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

@@ -1,3 +1,4 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
 import { deleteSessionWithAttachments } from "../../runtime/session/session-attachment-deletion.js";
 import { deleteSessionAttachmentsIfSupported } from "./attachment-routes.js";
 import { sendJson } from "./http.js";
@@ -34,13 +35,24 @@ export class WebSessionRoutes {
             });
             return true;
         }
+        if (method === "POST" && sessionId === "page" && !action) {
+            sendJson(response, 200, { ok: true, ...(await this.readStates.list(environmentId, body ?? {})) });
+            return true;
+        }
         if (!sessionId)
             return false;
         const sessions = environment.services.sessions;
         if (method === "GET" && action === "messages") {
-            const snapshot = await sessions.getSessionSnapshot(sessionId, {
-                includeRequests: true,
-            });
+            let snapshot;
+            try {
+                snapshot = await sessions.getSessionSnapshot(sessionId, historyPageOptions(request.url, environment.services.config));
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== "history_cursor_stale")
+                    throw error;
+                sendJson(response, 409, { ok: false, error: error.message });
+                return true;
+            }
             if (!snapshot) {
                 sendJson(response, 404, {
                     ok: false,
@@ -52,7 +64,7 @@ export class WebSessionRoutes {
             }
             sendJson(response, 200, {
                 ok: true,
-                ...snapshot,
+                ...publicHistorySnapshot(snapshot),
                 readState: await this.readStates.project(environmentId, snapshot),
             });
             return true;

package/dist/src/web-ui/local-runtime/spark-chat-routes.js

@@ -1,3 +1,4 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
 import { ensureSparkSession } from "../../sessions/spark-session.js";
 import { acceptConfigMutationRequest } from "./config-mutation-request.js";
 import { loadSparkChatConfiguration, readSparkChatConfigurationUpdate } from "./spark-chat-configuration.js";
@@ -40,11 +41,11 @@ export class SparkChatRoutes {
             if (update)
                 await environment.services.passiveLearning.configure(update);
             const configuration = await loadSparkChatConfiguration(environment.services.passiveLearning);
-            const snapshot = await environment.services.sessions.getSessionSnapshot(session.id, { includeRequests: true });
+            const snapshot = await environment.services.sessions.getSessionSnapshot(session.id, historyPageOptions(new URL(input.request.url ?? "/", "http://localhost"), environment.services.config));
             if (!snapshot)
                 throw new Error("spark_chat_unavailable");
             sendJson(input.response, 200, {
-                ok: true, sessionId: session.id, ...configuration, snapshot,
+                ok: true, sessionId: session.id, ...configuration, snapshot: publicHistorySnapshot(snapshot),
                 readState: await this.reads.project(input.environmentId, snapshot),
             });
             return true;
@@ -52,7 +53,7 @@ export class SparkChatRoutes {
         catch (error) {
             const code = error instanceof Error ? error.message : "spark_chat_unavailable";
             const invalid = ["spark_chat_preferences_invalid", "invalid_spark_tool_permission_mode", "visible_message_ids_invalid", "visible_message_receipts_invalid"].includes(code);
-            const stale = ["read_generation_changed", "visible_message_receipt_stale"].includes(code);
+            const stale = ["read_generation_changed", "visible_message_receipt_stale", "history_cursor_stale"].includes(code);
             sendJson(input.response, invalid ? 400 : 409, {
                 ok: false, error: invalid || stale ? code : "spark_chat_unavailable",
             });