@agent-native/core 0.165.2 → 0.165.4

package/dist/deploy/workspace-deploy.js

@@ -27,6 +27,7 @@ import { assertEmittedBackgroundFunctionOnDisk, isRecurringJobsDeployEnabled, }
 import { cloneServerBundleForFunction } from "./function-bundle.js";
 import { collectImmutableAssetPaths, IMMUTABLE_ASSET_CACHE_HEADERS, } from "./immutable-assets.js";
 const NETLIFY_WORKSPACE_STATIC_DIR = "_workspace_static";
+const DEFAULT_HOSTED_FEEDBACK_URL = "https://forms.agent-native.com/f/agent-native-feedback/_16ewV";
 const NETLIFY_PUBLIC_ASSET_EXTENSIONS = new Set([
     "avif",
     "css",
@@ -152,6 +153,12 @@ function buildOneApp(workspaceRoot, app, preset, execFile, workspaceApps) {
         AGENT_NATIVE_WORKSPACE_APP_ID: app,
         VITE_AGENT_NATIVE_WORKSPACE: "1",
         VITE_AGENT_NATIVE_WORKSPACE_APP_ID: app,
+        ...(preset === "netlify"
+            ? {
+                VITE_AGENT_NATIVE_FEEDBACK_URL: process.env.VITE_AGENT_NATIVE_FEEDBACK_URL ??
+                    DEFAULT_HOSTED_FEEDBACK_URL,
+            }
+            : {}),
         APP_BASE_PATH: `/${app}`,
         VITE_APP_BASE_PATH: `/${app}`,
         AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: workspaceAppAudience,

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,6 +159,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -174,7 +175,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,6 +190,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -199,7 +200,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,6 +216,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -234,7 +235,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,6 +250,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -263,7 +264,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/mcp-client/oauth-routes.d.ts

@@ -25,6 +25,7 @@ export interface McpOAuthRoutesOptions {
 export declare function redirectWithStagedCookies(event: H3Event, location: string): Response;
 export declare function mountMcpOAuthRoutes(nitroApp: any, options: McpOAuthRoutesOptions): void;
 export declare function resolveMcpOAuthScope(serverUrl: URL, requestedScope: unknown): RemoteMcpScope | null;
+export declare function stripMcpOAuthAppBasePath(path: string, basePath: string): string;
 export declare function resolveManagedMcpOAuthClient(serverUrl: URL): Promise<StoredOAuthClientInformation | undefined>;
 export declare function setMcpOAuthFlowCookie(event: H3Event, flow: McpOAuthFlow, secure: boolean): void;
 export declare function readMcpOAuthFlowCookie(event: H3Event): McpOAuthFlow | null;

package/dist/mcp-client/oauth-routes.js

@@ -5,7 +5,7 @@ import { decryptSecretValue, encryptSecretValue } from "../secrets/crypto.js";
 import { getSession, safeReturnPath } from "../server/auth.js";
 import { resolveSecret } from "../server/credential-provider.js";
 import { getH3App } from "../server/framework-request-handler.js";
-import { getAppUrl, resolveOAuthRedirectUri } from "../server/google-oauth.js";
+import { getAppBasePath, getAppUrl, resolveOAuthRedirectUri, } from "../server/google-oauth.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { finishMcpOAuthAuthorization, startMcpOAuthAuthorization, validateMcpOAuthCallbackIssuer, } from "./oauth-client.js";
 import { addOAuthRemoteServer, listRemoteServers, normalizeServerName, replaceOAuthRemoteServer, validateRemoteUrl, } from "./remote-store.js";
@@ -206,6 +206,19 @@ export function resolveMcpOAuthScope(serverUrl, requestedScope) {
     }
     return requestedScope === "org" ? "org" : "user";
 }
+export function stripMcpOAuthAppBasePath(path, basePath) {
+    const normalizedBase = `/${basePath.replace(/^\/+|\/+$/g, "")}`;
+    if (normalizedBase === "/")
+        return path;
+    const suffixStart = path.search(/[?#]/);
+    const pathname = suffixStart === -1 ? path : path.slice(0, suffixStart);
+    const suffix = suffixStart === -1 ? "" : path.slice(suffixStart);
+    if (pathname === normalizedBase)
+        return `/${suffix}`;
+    return pathname.startsWith(`${normalizedBase}/`)
+        ? `${pathname.slice(normalizedBase.length)}${suffix}`
+        : path;
+}
 export async function resolveManagedMcpOAuthClient(serverUrl) {
     const client = MANAGED_MCP_OAUTH_CLIENTS.find((candidate) => candidate.serverOrigin === serverUrl.origin);
     if (!client)
@@ -286,7 +299,7 @@ async function handleMcpOAuthCallback(event, options) {
         await options.reconfigure();
         const returnPath = flow.returnUrl ??
             `/settings/integrations?connected=mcp-${encodeURIComponent(flow.name)}`;
-        return redirectWithStagedCookies(event, getAppUrl(event, returnPath));
+        return redirectWithStagedCookies(event, getAppUrl(event, stripMcpOAuthAppBasePath(returnPath, getAppBasePath())));
     }
     catch {
         setResponseStatus(event, 400);

package/dist/mcp-client/remote-store.js

@@ -21,8 +21,8 @@
  */
 import { createHash } from "node:crypto";
 import { writeAppSecret, readAppSecret, deleteAppSecret, } from "../secrets/storage.js";
-import { getOrgSetting, putOrgSetting, deleteOrgSetting, } from "../settings/org-settings.js";
-import { getUserSetting, putUserSetting, deleteUserSetting, } from "../settings/user-settings.js";
+import { getOrgSetting, mutateOrgSetting } from "../settings/org-settings.js";
+import { getUserSetting, mutateUserSetting, } from "../settings/user-settings.js";
 import { getMcpOAuthAccessToken, revokeMcpOAuthCredentials, saveMcpOAuthCredentials, } from "./oauth-client.js";
 import { validateRemoteUrl } from "./remote-url.js";
 export { validateRemoteUrl } from "./remote-url.js";
@@ -107,20 +107,21 @@ function sanitiseOrgId(orgId) {
     return orgId.toLowerCase().replace(/[^a-z0-9-]/g, "-");
 }
 async function readList(scope, scopeId) {
-    const raw = scope === "user"
+    return parseServerList(scope === "user"
         ? await getUserSetting(scopeId, SETTINGS_KEY)
-        : await getOrgSetting(scopeId, SETTINGS_KEY);
+        : await getOrgSetting(scopeId, SETTINGS_KEY));
+}
+function parseServerList(raw) {
     if (!raw || !Array.isArray(raw.servers))
         return [];
     return raw.servers.filter((s) => s && typeof s.id === "string" && typeof s.url === "string");
 }
-async function writeList(scope, scopeId, servers) {
-    if (scope === "user") {
-        await putUserSetting(scopeId, SETTINGS_KEY, { servers });
-    }
-    else {
-        await putOrgSetting(scopeId, SETTINGS_KEY, { servers });
-    }
+async function mutateServerList(scope, scopeId, updater) {
+    const mutate = scope === "user" ? mutateUserSetting : mutateOrgSetting;
+    const next = await mutate(scopeId, SETTINGS_KEY, async (raw) => ({
+        servers: await updater(parseServerList(raw)),
+    }));
+    return parseServerList(next);
 }
 export async function listRemoteServers(scope, scopeId) {
     return readList(scope, scopeId);
@@ -228,6 +229,7 @@ export async function replaceOAuthRemoteServer(scope, scopeId, serverId, credent
         ...credentials,
         serverUrl: credentialResource.url.toString(),
     };
+    let updated;
     try {
         await saveMcpOAuthCredentials({
             key: nextSecretKey,
@@ -235,21 +237,22 @@ export async function replaceOAuthRemoteServer(scope, scopeId, serverId, credent
             scopeId,
             credentials: nextCredentials,
         });
-        const server = {
-            ...current,
-            url: nextCredentials.serverUrl,
-            oauthSecretKey: nextSecretKey,
-        };
-        const next = [...existing];
-        next[index] = server;
-        await writeList(scope, scopeId, next);
-        await revokeMcpOAuthCredentials({
-            key: current.oauthSecretKey,
-            scope,
-            scopeId,
-            serverUrl: current.url,
-        }).catch(() => undefined);
-        return { ok: true, server };
+        updated = await mutateServerList(scope, scopeId, (servers) => {
+            const latestIndex = servers.findIndex((server) => server.id === serverId);
+            const latest = latestIndex >= 0 ? servers[latestIndex] : undefined;
+            if (!latest ||
+                latest.oauthSecretKey !== current.oauthSecretKey ||
+                latest.url !== current.url) {
+                throw new Error("MCP server changed while reconnecting");
+            }
+            const next = [...servers];
+            next[latestIndex] = {
+                ...latest,
+                url: nextCredentials.serverUrl,
+                oauthSecretKey: nextSecretKey,
+            };
+            return next;
+        });
     }
     catch (err) {
         await revokeMcpOAuthCredentials({
@@ -263,6 +266,18 @@ export async function replaceOAuthRemoteServer(scope, scopeId, serverId, credent
             error: `Failed to replace MCP OAuth credentials: ${err?.message ?? err}`,
         };
     }
+    // The settings row now points at the replacement grant. Old-grant cleanup
+    // is best effort and must not roll back or invalidate the committed row.
+    await revokeMcpOAuthCredentials({
+        key: current.oauthSecretKey,
+        scope,
+        scopeId,
+        serverUrl: current.url,
+    }).catch(() => undefined);
+    const server = updated.find((candidate) => candidate.id === serverId);
+    return server
+        ? { ok: true, server }
+        : { ok: false, error: "MCP server was not found" };
 }
 export async function addFirstPartyRemoteServer(orgId, input) {
     const trust = await isFirstPartyRemoteEndpointTrusted(orgId, input.appId, input.url);
@@ -327,7 +342,24 @@ async function addRemoteServerInternal(scope, scopeId, input) {
         description: input.description?.trim() || undefined,
         createdAt: Date.now(),
     };
-    await writeList(scope, scopeId, [...existing, server]);
+    try {
+        await mutateServerList(scope, scopeId, (servers) => {
+            if (servers.some((candidate) => candidate.name === name)) {
+                throw new Error(`A server named "${name}" already exists`);
+            }
+            return [...servers, server];
+        });
+    }
+    catch (err) {
+        if (headerSecretKey) {
+            await deleteAppSecret({
+                key: headerSecretKey,
+                scope: toSecretScope(scope),
+                scopeId,
+            }).catch(() => undefined);
+        }
+        return { ok: false, error: err?.message ?? String(err) };
+    }
     return { ok: true, server };
 }
 function normalizeEndpointPath(pathname) {
@@ -396,9 +428,29 @@ export async function isFirstPartyRemoteEndpointTrusted(orgId, appId, endpoint)
 }
 export async function removeRemoteServer(scope, scopeId, id) {
     const existing = await readList(scope, scopeId);
-    const removed = existing.find((s) => s.id === id);
-    const next = existing.filter((s) => s.id !== id);
-    if (next.length === existing.length)
+    const expected = existing.find((s) => s.id === id);
+    if (!expected)
+        return false;
+    let removed;
+    try {
+        await mutateServerList(scope, scopeId, (servers) => {
+            removed = undefined;
+            const latest = servers.find((server) => server.id === id);
+            if (!latest)
+                return servers;
+            if (latest.oauthSecretKey !== expected.oauthSecretKey) {
+                throw new Error(`MCP OAuth credentials changed while removing ${expected.name}`);
+            }
+            removed = latest;
+            return servers.filter((server) => server.id !== id);
+        });
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(`[mcp-client] Failed to remove MCP server ${expected.name}: ${err?.message ?? err}`);
+        return false;
+    }
+    if (!removed)
         return false;
     if (removed?.oauthSecretKey) {
         try {
@@ -409,8 +461,7 @@ export async function removeRemoteServer(scope, scopeId, id) {
                 serverUrl: removed.url,
             });
             if (result.local === "replaced") {
-                console.warn(`[mcp-client] MCP OAuth credentials changed while removing ${removed.name}; the server was kept so the newer connection remains manageable.`);
-                return false;
+                console.warn(`[mcp-client] MCP OAuth credentials changed while removing ${removed.name}; the server row was already removed.`);
             }
             if (result.remote === "failed") {
                 console.warn(`[mcp-client] MCP OAuth revocation failed for ${removed.name}; local credentials were removed.`);
@@ -421,17 +472,6 @@ export async function removeRemoteServer(scope, scopeId, id) {
             console.warn(`[mcp-client] Failed to delete MCP OAuth credentials ${removed.oauthSecretKey}: ${err?.message ?? err}`);
         }
     }
-    if (next.length === 0) {
-        if (scope === "user") {
-            await deleteUserSetting(scopeId, SETTINGS_KEY);
-        }
-        else {
-            await deleteOrgSetting(scopeId, SETTINGS_KEY);
-        }
-    }
-    else {
-        await writeList(scope, scopeId, next);
-    }
     // Best-effort: drop the encrypted-headers secret too. Errors are logged
     // but don't fail the deletion — the settings row is already gone, so a
     // dangling secret is harmless (it just can't be read back).

package/dist/notifications/routes.d.ts

@@ -13,21 +13,21 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
+    count?: undefined;
     updated: number;
-    ok?: undefined;
     error?: undefined;
-    count?: undefined;
+    ok?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
     error: string;
     ok?: undefined;
-    count?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
-    count?: undefined;
+    ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -51,8 +51,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -73,10 +73,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
-    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
+    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/google-oauth-credentials.js

@@ -57,7 +57,20 @@ export async function resolveGoogleProviderCredentialCandidatesWithReader(option
  * remain the backwards-compatible provider OAuth credentials.
  */
 export function resolveGoogleSignInCredentials() {
-    return (readCredentialPair("GOOGLE_SIGN_IN_CLIENT_ID", "GOOGLE_SIGN_IN_CLIENT_SECRET") ?? readCredentialPair("GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"));
+    const signIn = readCredentialPair("GOOGLE_SIGN_IN_CLIENT_ID", "GOOGLE_SIGN_IN_CLIENT_SECRET");
+    const provider = readCredentialPair("GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET");
+    // Both pairs configured for different clients means one of them is dead
+    // config that nothing will ever read. Silence here cost a fleet-wide beta
+    // sign-in outage: GOOGLE_CLIENT_SECRET was repaired and verified while the
+    // callback kept using a stale GOOGLE_SIGN_IN_CLIENT_SECRET, so the repaired
+    // variable looked correct and changed nothing. Name the loser explicitly.
+    if (signIn && provider && signIn.clientId !== provider.clientId) {
+        console.warn("[agent-native][google-oauth] GOOGLE_SIGN_IN_CLIENT_ID and GOOGLE_CLIENT_ID " +
+            "are set to different Google clients. Sign-in uses GOOGLE_SIGN_IN_CLIENT_ID; " +
+            "GOOGLE_CLIENT_ID/SECRET are ignored for sign-in. Editing them will not " +
+            "change sign-in behaviour.");
+    }
+    return signIn ?? provider;
 }
 export function hasGoogleSignInCredentials() {
     return resolveGoogleSignInCredentials() !== null;

package/dist/settings/index.d.ts

@@ -1,4 +1,4 @@
-export { getSetting, mutateSetting, putSetting, deleteSetting, getAllSettings, getSettingsEmitter, type StoreWriteOptions, } from "./store.js";
+export { getSetting, mutateSetting, putSetting, deleteSetting, deleteSettingIfValue, getAllSettings, getSettingsEmitter, type StoreWriteOptions, } from "./store.js";
 export { getSettingHandler, putSettingHandler, deleteSettingHandler, } from "./handlers.js";
 export { readSetting, writeSetting, removeSetting } from "./script-helpers.js";
 export { getUserSetting, putUserSetting, deleteUserSetting, } from "./user-settings.js";

package/dist/settings/index.js

@@ -1,5 +1,5 @@
 // Store
-export { getSetting, mutateSetting, putSetting, deleteSetting, getAllSettings, getSettingsEmitter, } from "./store.js";
+export { getSetting, mutateSetting, putSetting, deleteSetting, deleteSettingIfValue, getAllSettings, getSettingsEmitter, } from "./store.js";
 // H3 route handlers
 export { getSettingHandler, putSettingHandler, deleteSettingHandler, } from "./handlers.js";
 // Script helpers

package/dist/settings/store.d.ts

@@ -1,7 +1,11 @@
 import type { EventEmitter } from "node:events";
 export declare function getSettingsEmitter(): EventEmitter;
 export declare function ensureTable(): Promise<void>;
-export declare function getSetting(key: string): Promise<Record<string, unknown> | null>;
+export interface StoreReadOptions {
+    /** Skip the per-request snapshot when a cross-request race must be checked. */
+    bypassCache?: boolean;
+}
+export declare function getSetting(key: string, options?: StoreReadOptions): Promise<Record<string, unknown> | null>;
 export interface StoreWriteOptions {
     /** Tag identifying who initiated this write (e.g. a tab ID). */
     requestSource?: string;
@@ -16,6 +20,8 @@ export interface StoreWriteOptions {
 export declare function mutateSetting(key: string, updater: (current: Record<string, unknown> | null) => Record<string, unknown> | Promise<Record<string, unknown>>, options?: StoreWriteOptions): Promise<Record<string, unknown>>;
 export declare function putSetting(key: string, value: Record<string, unknown>, options?: StoreWriteOptions): Promise<void>;
 export declare function deleteSetting(key: string, options?: StoreWriteOptions): Promise<boolean>;
+/** Delete a setting only when its stored value still matches the inspected value. */
+export declare function deleteSettingIfValue(key: string, expected: Record<string, unknown>, options?: StoreWriteOptions): Promise<boolean>;
 /**
  * Delete every setting whose key starts with `prefix`. Returns the number of
  * rows removed. Used when an owning entity is deleted (e.g. an organization

package/dist/settings/store.js

@@ -115,9 +115,9 @@ export async function ensureTable() {
     }
     return _initPromise;
 }
-export async function getSetting(key) {
+export async function getSetting(key, options) {
     const cache = requestSettingsCache();
-    if (cache?.has(key)) {
+    if (!options?.bypassCache && cache?.has(key)) {
         const cached = cache.get(key);
         return cached == null ? null : JSON.parse(cached);
     }
@@ -129,7 +129,8 @@ export async function getSetting(key) {
         args: [key],
     });
     const raw = rows.length === 0 ? null : rows[0].value;
-    cache?.set(key, raw);
+    if (!options?.bypassCache)
+        cache?.set(key, raw);
     return raw == null ? null : JSON.parse(raw);
 }
 const SETTINGS_MUTATION_ATTEMPTS = 25;
@@ -221,6 +222,27 @@ export async function deleteSetting(key, options) {
     }
     return false;
 }
+/** Delete a setting only when its stored value still matches the inspected value. */
+export async function deleteSettingIfValue(key, expected, options) {
+    await ensureTable();
+    const client = getDbExec();
+    const table = settingsTable();
+    const result = await client.execute({
+        sql: `DELETE FROM ${table} WHERE key = ? AND value = ?`,
+        args: [key, JSON.stringify(expected)],
+    });
+    if (result.rowsAffected === 0)
+        return false;
+    requestSettingsCache()?.set(key, null);
+    invalidateRequestAllSettings();
+    settingsEmitter().emit("settings", {
+        source: "settings",
+        type: "delete",
+        key,
+        ...(options?.requestSource && { requestSource: options.requestSource }),
+    });
+    return true;
+}
 /**
  * Delete every setting whose key starts with `prefix`. Returns the number of
  * rows removed. Used when an owning entity is deleted (e.g. an organization

package/dist/settings/user-settings.d.ts

@@ -12,5 +12,7 @@ import { type StoreWriteOptions } from "./store.js";
 export declare function getUserSetting(email: string, key: string): Promise<Record<string, unknown> | null>;
 /** Write a user-scoped setting. Always writes to the prefixed key. */
 export declare function putUserSetting(email: string, key: string, value: Record<string, unknown>, options?: StoreWriteOptions): Promise<void>;
+/** Atomically derive and persist one user-scoped setting. */
+export declare function mutateUserSetting(email: string, key: string, updater: (current: Record<string, unknown> | null) => Record<string, unknown> | Promise<Record<string, unknown>>, options?: StoreWriteOptions): Promise<Record<string, unknown>>;
 /** Delete a user-scoped setting. */
 export declare function deleteUserSetting(email: string, key: string, options?: StoreWriteOptions): Promise<boolean>;