@anuma/sdk 6.39.0 → 6.39.1

package/dist/react/index.mjs

@@ -6022,15 +6022,17 @@ Build ONLY when the user gives an explicit instruction to build, create, generat
 
 Once the user HAS given an explicit build instruction, you are in App Builder mode: you produce polished, production-quality React apps that feel designed \u2014 not generic.
 
-DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a logic, data, or behavior-only change, skip the brief and just make the change.
+DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a text, logic, data, or behavior-only change, skip the brief and just make the change.
+
+EDIT SCOPE: Change only the files and lines required by the current user request. A title rename is a text edit, not a design change. Preserve styles, dependencies, and unrelated logic on text edits. Design feedback does not authorize unrelated edits.
 
 WORKFLOW:
 1. NEVER output code as text or markdown. ALWAYS use tools.
 2. Initial build: state your design brief, then create_file with a "files" array writing ALL files in one call. The preview renders automatically.
 3. patch_file requires read_file for that path earlier in the conversation (or create_file in the same conversation, which counts). read_file output is numbered "42: <text>" \u2014 the prefix is display-only; never copy it into "find". Each "find" must match exactly one location \u2014 include 2-3 lines of surrounding context. Pass multiple patches per call to change distinct locations.
 4. Prefer patch_file for changes to existing files \u2014 surgical, reviewable, preserves surrounding code. Reserve create_file overwrites for substantial restructuring. Inserts: find the line before, replace with that line + the new line. Deletes: empty replace.
-5. After substantial changes, call critique_design first (taste, hierarchy, distinctiveness, weakest decision) and then audit_design (mechanical: tokens, focus states, aria-labels, alt, heading order). Patch what each surfaces. critique catches taste issues no checklist would; audit catches mechanics you'd miss. Run both; act on both.
-6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip \u2014 audit + critique are your feedback in that case.
+5. On the initial build, when adding new UI, or after user-requested design changes, call critique_design first and then audit_design. Critique checks taste, hierarchy, and distinctiveness. Audit checks tokens, focus states, aria-labels, alt text, and heading order. Patch only issues within the current user request. For text, logic, or data edits, skip both design tools.
+6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip runtime verification. An unavailable runtime verifier does not authorize design changes. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes.
 7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.
 
 STRUCTURE:
@@ -6196,12 +6198,13 @@ function isCacheExpired(cache, expirationMs = DEFAULT_CACHE_EXPIRATION_MS) {
   if (!cache) return true;
   return Date.now() - cache.timestamp > expirationMs;
 }
-function buildCacheEntry(tools, checksum) {
+function buildCacheEntry(tools, checksum, etag) {
   return {
     tools,
     timestamp: Date.now(),
     version: CACHE_VERSION,
-    ...checksum && { checksum }
+    ...checksum && { checksum },
+    ...etag && { etag }
   };
 }
 function writeLocalStorageCache(entry) {
@@ -6236,19 +6239,36 @@ function shouldRefreshTools(responseChecksum, cache = localStorageToolsCache) {
   const cachedChecksum = getToolsChecksum2(cache);
   return cachedChecksum instanceof Promise ? cachedChecksum.then(decide) : decide(cachedChecksum);
 }
-async function fetchServerToolsFromApi(baseUrl, token) {
-  const response = await fetch(`${baseUrl}/api/v1/tools`, {
+async function fetchServerToolsFromApi(baseUrl, authHeaders, etag) {
+  const request = (validator) => fetch(`${baseUrl}/api/v1/tools`, {
     method: "GET",
     headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json"
+      ...authHeaders,
+      "Content-Type": "application/json",
+      ...validator && { "If-None-Match": validator }
     }
   });
+  let response;
+  try {
+    response = await request(etag);
+  } catch (error) {
+    if (!etag || !(error instanceof TypeError)) throw error;
+    etag = void 0;
+    response = await request();
+  }
+  if (etag && response.status === 304) {
+    return { notModified: true };
+  }
   if (!response.ok) {
     throw new Error(`Failed to fetch server tools: ${response.status}`);
   }
   const data = await response.json();
-  return convertServerToolsResponse(data);
+  const responseEtag = response.headers?.get("ETag") ?? void 0;
+  return {
+    notModified: false,
+    ...convertServerToolsResponse(data),
+    ...responseEtag && { etag: responseEtag }
+  };
 }
 async function getServerTools(options) {
   const {
@@ -6280,34 +6300,30 @@ async function getServerTools(options) {
   try {
     const { BASE_URL: BASE_URL2 } = await import("./clientConfig-VPOGQRNP.mjs");
     const effectiveBaseUrl = baseUrl ?? BASE_URL2;
+    const validator = cached && !forceRefresh ? cached.etag : void 0;
+    let authHeaders;
     if (apiKey) {
-      const response = await fetch(`${effectiveBaseUrl}/api/v1/tools`, {
-        method: "GET",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json"
-        }
-      });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch server tools: ${response.status}`);
+      authHeaders = { "X-API-Key": apiKey };
+    } else {
+      if (!getToken) {
+        getLogger().warn("[serverTools] No auth method available for fetching tools");
+        return cached?.tools ?? [];
+      }
+      const token = await getToken();
+      if (!token) {
+        getLogger().warn("[serverTools] No auth token available for fetching tools");
+        return cached?.tools ?? [];
       }
-      const data = await response.json();
-      const { tools: tools2, checksum: checksum2 } = convertServerToolsResponse(data);
-      await persistCache(buildCacheEntry(tools2, checksum2));
-      return tools2;
+      authHeaders = { Authorization: `Bearer ${token}` };
     }
-    if (!getToken) {
-      getLogger().warn("[serverTools] No auth method available for fetching tools");
-      return cached?.tools ?? [];
+    const result = await fetchServerToolsFromApi(effectiveBaseUrl, authHeaders, validator);
+    if (result.notModified) {
+      const confirmed = cached;
+      await persistCache({ ...confirmed, timestamp: Date.now() });
+      return confirmed.tools;
     }
-    const token = await getToken();
-    if (!token) {
-      getLogger().warn("[serverTools] No auth token available for fetching tools");
-      return cached?.tools ?? [];
-    }
-    const { tools, checksum } = await fetchServerToolsFromApi(effectiveBaseUrl, token);
-    await persistCache(buildCacheEntry(tools, checksum));
-    return tools;
+    await persistCache(buildCacheEntry(result.tools, result.checksum, result.etag));
+    return result.tools;
   } catch (error) {
     getLogger().error("[serverTools] Failed to fetch server tools:", error);
     if (cached?.tools) {
@@ -34824,6 +34840,128 @@ function useICloudBackup(options) {
 
 // src/react/useModels.ts
 import { useCallback as useCallback15, useEffect as useEffect10, useRef as useRef6, useState as useState12 } from "react";
+var MODELS_CACHE_TTL_MS = 5 * 60 * 1e3;
+var modelsCache = /* @__PURE__ */ new Map();
+var modelsInFlight = /* @__PURE__ */ new Map();
+var cacheGeneration = 0;
+function clearModelsCache() {
+  cacheGeneration++;
+  modelsCache.clear();
+  modelsInFlight.clear();
+}
+function pruneStaleTokenEntries(newKey) {
+  const [newBaseUrl, newProvider] = JSON.parse(newKey);
+  for (const existingKey of modelsCache.keys()) {
+    if (existingKey === newKey) continue;
+    const [existingBaseUrl, existingProvider] = JSON.parse(existingKey);
+    if (existingBaseUrl === newBaseUrl && existingProvider === newProvider) {
+      modelsCache.delete(existingKey);
+    }
+  }
+}
+function fingerprintToken(token) {
+  if (!token) return "anon";
+  let h1 = 3735928559;
+  let h2 = 1103547991;
+  for (let i = 0; i < token.length; i++) {
+    const ch = token.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+function modelsCacheKey(baseUrl, provider, token) {
+  return JSON.stringify([baseUrl, provider ?? null, fingerprintToken(token)]);
+}
+async function fetchAllModelPages(baseUrl, provider, headers, previous, signal) {
+  const pages = /* @__PURE__ */ new Map();
+  const models = [];
+  let pageToken;
+  do {
+    const pageKey = pageToken ?? "";
+    const stored2 = previous?.pages.get(pageKey);
+    const request = (etag) => getApiV1Models({
+      baseUrl,
+      headers: etag ? { ...headers, "If-None-Match": etag } : headers,
+      query: { provider, page_token: pageToken },
+      signal
+    });
+    let response = await request(stored2?.etag);
+    if (stored2?.etag && !response.response && response.error) {
+      response = await request();
+    }
+    let page;
+    if (response.response?.status === 304) {
+      if (!stored2) throw new Error("Failed to fetch models");
+      page = stored2;
+    } else {
+      if (response.error) {
+        const errorMsg = response.error.error ?? "Failed to fetch models";
+        throw new Error(errorMsg);
+      }
+      page = {
+        body: response.data ?? {},
+        etag: response.response?.headers?.get("ETag") ?? void 0
+      };
+    }
+    pages.set(pageKey, page);
+    models.push(...page.body.data || []);
+    pageToken = page.body.next_page_token;
+  } while (pageToken);
+  return { pages, models, fetchedAt: Date.now() };
+}
+function loadModels(key, baseUrl, provider, headers, force, signal) {
+  const cached = modelsCache.get(key);
+  if (cached && !force && Date.now() - cached.fetchedAt < MODELS_CACHE_TTL_MS) {
+    return Promise.resolve([...cached.models]);
+  }
+  const shared = (force ? void 0 : modelsInFlight.get(key)) ?? startSharedRequest(key, baseUrl, provider, headers, cached);
+  return waitForSharedRequest(key, shared, signal).then((models) => [...models]);
+}
+function startSharedRequest(key, baseUrl, provider, headers, previous) {
+  const controller = new AbortController();
+  const generation = cacheGeneration;
+  const shared = {
+    controller,
+    waiters: 0,
+    promise: Promise.resolve([])
+  };
+  shared.promise = fetchAllModelPages(baseUrl, provider, headers, previous, controller.signal).then((entry) => {
+    if (modelsInFlight.get(key) === shared && generation === cacheGeneration) {
+      pruneStaleTokenEntries(key);
+      modelsCache.set(key, entry);
+    }
+    return entry.models;
+  }).finally(() => {
+    if (modelsInFlight.get(key) === shared) modelsInFlight.delete(key);
+  });
+  modelsInFlight.set(key, shared);
+  return shared;
+}
+function waitForSharedRequest(key, shared, signal) {
+  shared.waiters++;
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    shared.waiters--;
+    if (shared.waiters === 0) {
+      shared.controller.abort();
+      if (modelsInFlight.get(key) === shared) modelsInFlight.delete(key);
+    }
+  };
+  if (signal.aborted) {
+    leave();
+  } else {
+    signal.addEventListener("abort", leave, { once: true });
+  }
+  return shared.promise.finally(() => {
+    left = true;
+    signal.removeEventListener("abort", leave);
+  });
+}
 function useModels(options = {}) {
   const { getToken, baseUrl = BASE_URL, provider, autoFetch = true } = options;
   const [models, setModels] = useState12([]);
@@ -34846,7 +34984,7 @@ function useModels(options = {}) {
       }
     };
   }, []);
-  const fetchModels = useCallback15(async () => {
+  const fetchModels = useCallback15(async (force = false) => {
     if (abortControllerRef.current) {
       abortControllerRef.current.abort();
     }
@@ -34865,35 +35003,17 @@ function useModels(options = {}) {
       if (token) {
         headers["Authorization"] = `Bearer ${token}`;
       }
-      let allModels = [];
-      let nextPageToken;
-      do {
-        if (signal.aborted) return;
-        const response = await getApiV1Models({
-          baseUrl: baseUrlRef.current,
-          headers,
-          query: {
-            provider: providerRef.current,
-            page_token: nextPageToken
-          },
-          signal
-        });
-        if (response.error) {
-          const errorMsg = response.error.error ?? "Failed to fetch models";
-          throw new Error(errorMsg);
-        }
-        if (response.data) {
-          const newModels = response.data.data || [];
-          allModels = [...allModels, ...newModels];
-          nextPageToken = response.data.next_page_token;
-        }
-      } while (nextPageToken);
+      const baseUrl2 = baseUrlRef.current;
+      const provider2 = providerRef.current;
+      const key = modelsCacheKey(baseUrl2, provider2, token);
+      const allModels = await loadModels(key, baseUrl2, provider2, headers, force, signal);
       if (signal.aborted) return;
       setModels(allModels);
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
         return;
       }
+      if (signal.aborted) return;
       setError(err instanceof Error ? err : new Error(String(err)));
     } finally {
       if (!signal.aborted) {
@@ -34906,7 +35026,7 @@ function useModels(options = {}) {
   }, []);
   const refetch = useCallback15(async () => {
     setModels([]);
-    await fetchModels();
+    await fetchModels(true);
   }, [fetchModels]);
   const hasFetchedRef = useRef6(false);
   useEffect10(() => {
@@ -36958,6 +37078,7 @@ export {
   clearKeyPair,
   clearLazyTitleCache,
   clearMemoryTopicsOverrideOp,
+  clearModelsCache,
   clearNotionToken,
   clearServerToolsCache,
   consoleLogger,

package/dist/server/index.cjs

@@ -20430,15 +20430,17 @@ Build ONLY when the user gives an explicit instruction to build, create, generat
 
 Once the user HAS given an explicit build instruction, you are in App Builder mode: you produce polished, production-quality React apps that feel designed \u2014 not generic.
 
-DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a logic, data, or behavior-only change, skip the brief and just make the change.
+DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a text, logic, data, or behavior-only change, skip the brief and just make the change.
+
+EDIT SCOPE: Change only the files and lines required by the current user request. A title rename is a text edit, not a design change. Preserve styles, dependencies, and unrelated logic on text edits. Design feedback does not authorize unrelated edits.
 
 WORKFLOW:
 1. NEVER output code as text or markdown. ALWAYS use tools.
 2. Initial build: state your design brief, then create_file with a "files" array writing ALL files in one call. The preview renders automatically.
 3. patch_file requires read_file for that path earlier in the conversation (or create_file in the same conversation, which counts). read_file output is numbered "42: <text>" \u2014 the prefix is display-only; never copy it into "find". Each "find" must match exactly one location \u2014 include 2-3 lines of surrounding context. Pass multiple patches per call to change distinct locations.
 4. Prefer patch_file for changes to existing files \u2014 surgical, reviewable, preserves surrounding code. Reserve create_file overwrites for substantial restructuring. Inserts: find the line before, replace with that line + the new line. Deletes: empty replace.
-5. After substantial changes, call critique_design first (taste, hierarchy, distinctiveness, weakest decision) and then audit_design (mechanical: tokens, focus states, aria-labels, alt, heading order). Patch what each surfaces. critique catches taste issues no checklist would; audit catches mechanics you'd miss. Run both; act on both.
-6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip \u2014 audit + critique are your feedback in that case.
+5. On the initial build, when adding new UI, or after user-requested design changes, call critique_design first and then audit_design. Critique checks taste, hierarchy, and distinctiveness. Audit checks tokens, focus states, aria-labels, alt text, and heading order. Patch only issues within the current user request. For text, logic, or data edits, skip both design tools.
+6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip runtime verification. An unavailable runtime verifier does not authorize design changes. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes.
 7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.
 
 STRUCTURE:
@@ -20584,12 +20586,13 @@ function isCacheExpired(cache, expirationMs = DEFAULT_CACHE_EXPIRATION_MS) {
   if (!cache) return true;
   return Date.now() - cache.timestamp > expirationMs;
 }
-function buildCacheEntry(tools, checksum) {
+function buildCacheEntry(tools, checksum, etag) {
   return {
     tools,
     timestamp: Date.now(),
     version: CACHE_VERSION,
-    ...checksum && { checksum }
+    ...checksum && { checksum },
+    ...etag && { etag }
   };
 }
 function writeLocalStorageCache(entry) {
@@ -20624,19 +20627,36 @@ function shouldRefreshTools(responseChecksum, cache = localStorageToolsCache) {
   const cachedChecksum = getToolsChecksum(cache);
   return cachedChecksum instanceof Promise ? cachedChecksum.then(decide) : decide(cachedChecksum);
 }
-async function fetchServerToolsFromApi(baseUrl, token) {
-  const response = await fetch(`${baseUrl}/api/v1/tools`, {
+async function fetchServerToolsFromApi(baseUrl, authHeaders, etag) {
+  const request = (validator) => fetch(`${baseUrl}/api/v1/tools`, {
     method: "GET",
     headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json"
+      ...authHeaders,
+      "Content-Type": "application/json",
+      ...validator && { "If-None-Match": validator }
     }
   });
+  let response;
+  try {
+    response = await request(etag);
+  } catch (error) {
+    if (!etag || !(error instanceof TypeError)) throw error;
+    etag = void 0;
+    response = await request();
+  }
+  if (etag && response.status === 304) {
+    return { notModified: true };
+  }
   if (!response.ok) {
     throw new Error(`Failed to fetch server tools: ${response.status}`);
   }
   const data = await response.json();
-  return convertServerToolsResponse(data);
+  const responseEtag = response.headers?.get("ETag") ?? void 0;
+  return {
+    notModified: false,
+    ...convertServerToolsResponse(data),
+    ...responseEtag && { etag: responseEtag }
+  };
 }
 async function getServerTools(options) {
   const {
@@ -20668,34 +20688,30 @@ async function getServerTools(options) {
   try {
     const { BASE_URL: BASE_URL2 } = await Promise.resolve().then(() => (init_clientConfig(), clientConfig_exports));
     const effectiveBaseUrl = baseUrl ?? BASE_URL2;
+    const validator = cached && !forceRefresh ? cached.etag : void 0;
+    let authHeaders;
     if (apiKey) {
-      const response = await fetch(`${effectiveBaseUrl}/api/v1/tools`, {
-        method: "GET",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json"
-        }
-      });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch server tools: ${response.status}`);
+      authHeaders = { "X-API-Key": apiKey };
+    } else {
+      if (!getToken) {
+        getLogger().warn("[serverTools] No auth method available for fetching tools");
+        return cached?.tools ?? [];
       }
-      const data = await response.json();
-      const { tools: tools2, checksum: checksum2 } = convertServerToolsResponse(data);
-      await persistCache(buildCacheEntry(tools2, checksum2));
-      return tools2;
-    }
-    if (!getToken) {
-      getLogger().warn("[serverTools] No auth method available for fetching tools");
-      return cached?.tools ?? [];
+      const token = await getToken();
+      if (!token) {
+        getLogger().warn("[serverTools] No auth token available for fetching tools");
+        return cached?.tools ?? [];
+      }
+      authHeaders = { Authorization: `Bearer ${token}` };
     }
-    const token = await getToken();
-    if (!token) {
-      getLogger().warn("[serverTools] No auth token available for fetching tools");
-      return cached?.tools ?? [];
+    const result = await fetchServerToolsFromApi(effectiveBaseUrl, authHeaders, validator);
+    if (result.notModified) {
+      const confirmed = cached;
+      await persistCache({ ...confirmed, timestamp: Date.now() });
+      return confirmed.tools;
     }
-    const { tools, checksum } = await fetchServerToolsFromApi(effectiveBaseUrl, token);
-    await persistCache(buildCacheEntry(tools, checksum));
-    return tools;
+    await persistCache(buildCacheEntry(result.tools, result.checksum, result.etag));
+    return result.tools;
   } catch (error) {
     getLogger().error("[serverTools] Failed to fetch server tools:", error);
     if (cached?.tools) {

package/dist/server/index.d.mts

@@ -6468,6 +6468,8 @@ interface CachedServerTools {
     version: string;
     /** Checksum from the server for cache invalidation */
     checksum?: string;
+    /** ETag from the server. The next refresh sends it in an If-None-Match header. */
+    etag?: string;
 }
 /**
  * Pluggable persistence for the fetched server-tools list.
@@ -6564,7 +6566,9 @@ declare function shouldRefreshTools(responseChecksum: string | undefined, cache:
  * Flow:
  * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
- * 3. Otherwise, fetch from API, cache, and return
+ * 3. Otherwise, fetch from API, cache, and return. When the cache holds an ETag,
+ *    the request sends If-None-Match. On 304 the cached tools stay and only the
+ *    stored timestamp changes.
  * 4. On fetch failure, return cached tools if available (stale-while-error)
  */
 declare function getServerTools(options: ServerToolsOptions): Promise<ServerTool[]>;

package/dist/server/index.d.ts

@@ -6468,6 +6468,8 @@ interface CachedServerTools {
     version: string;
     /** Checksum from the server for cache invalidation */
     checksum?: string;
+    /** ETag from the server. The next refresh sends it in an If-None-Match header. */
+    etag?: string;
 }
 /**
  * Pluggable persistence for the fetched server-tools list.
@@ -6564,7 +6566,9 @@ declare function shouldRefreshTools(responseChecksum: string | undefined, cache:
  * Flow:
  * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
- * 3. Otherwise, fetch from API, cache, and return
+ * 3. Otherwise, fetch from API, cache, and return. When the cache holds an ETag,
+ *    the request sends If-None-Match. On 304 the cached tools stay and only the
+ *    stored timestamp changes.
  * 4. On fetch failure, return cached tools if available (stale-while-error)
  */
 declare function getServerTools(options: ServerToolsOptions): Promise<ServerTool[]>;

package/dist/server/index.mjs

@@ -18764,15 +18764,17 @@ Build ONLY when the user gives an explicit instruction to build, create, generat
 
 Once the user HAS given an explicit build instruction, you are in App Builder mode: you produce polished, production-quality React apps that feel designed \u2014 not generic.
 
-DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a logic, data, or behavior-only change, skip the brief and just make the change.
+DESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: "Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise" is the kind of specificity that anchors the build. Default to nothing: don't pick "safe modern productivity" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a text, logic, data, or behavior-only change, skip the brief and just make the change.
+
+EDIT SCOPE: Change only the files and lines required by the current user request. A title rename is a text edit, not a design change. Preserve styles, dependencies, and unrelated logic on text edits. Design feedback does not authorize unrelated edits.
 
 WORKFLOW:
 1. NEVER output code as text or markdown. ALWAYS use tools.
 2. Initial build: state your design brief, then create_file with a "files" array writing ALL files in one call. The preview renders automatically.
 3. patch_file requires read_file for that path earlier in the conversation (or create_file in the same conversation, which counts). read_file output is numbered "42: <text>" \u2014 the prefix is display-only; never copy it into "find". Each "find" must match exactly one location \u2014 include 2-3 lines of surrounding context. Pass multiple patches per call to change distinct locations.
 4. Prefer patch_file for changes to existing files \u2014 surgical, reviewable, preserves surrounding code. Reserve create_file overwrites for substantial restructuring. Inserts: find the line before, replace with that line + the new line. Deletes: empty replace.
-5. After substantial changes, call critique_design first (taste, hierarchy, distinctiveness, weakest decision) and then audit_design (mechanical: tokens, focus states, aria-labels, alt, heading order). Patch what each surfaces. critique catches taste issues no checklist would; audit catches mechanics you'd miss. Run both; act on both.
-6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip \u2014 audit + critique are your feedback in that case.
+5. On the initial build, when adding new UI, or after user-requested design changes, call critique_design first and then audit_design. Critique checks taste, hierarchy, and distinctiveness. Audit checks tokens, focus states, aria-labels, alt text, and heading order. Patch only issues within the current user request. For text, logic, or data edits, skip both design tools.
+6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If \`rendered\` is false or \`errors\` is non-empty, fix every error before the next message. If the response includes a \`note\` that verify_app isn't wired in this host, skip runtime verification. An unavailable runtime verifier does not authorize design changes. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes.
 7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.
 
 STRUCTURE:
@@ -18917,12 +18919,13 @@ function isCacheExpired(cache, expirationMs = DEFAULT_CACHE_EXPIRATION_MS) {
   if (!cache) return true;
   return Date.now() - cache.timestamp > expirationMs;
 }
-function buildCacheEntry(tools, checksum) {
+function buildCacheEntry(tools, checksum, etag) {
   return {
     tools,
     timestamp: Date.now(),
     version: CACHE_VERSION,
-    ...checksum && { checksum }
+    ...checksum && { checksum },
+    ...etag && { etag }
   };
 }
 function writeLocalStorageCache(entry) {
@@ -18957,19 +18960,36 @@ function shouldRefreshTools(responseChecksum, cache = localStorageToolsCache) {
   const cachedChecksum = getToolsChecksum(cache);
   return cachedChecksum instanceof Promise ? cachedChecksum.then(decide) : decide(cachedChecksum);
 }
-async function fetchServerToolsFromApi(baseUrl, token) {
-  const response = await fetch(`${baseUrl}/api/v1/tools`, {
+async function fetchServerToolsFromApi(baseUrl, authHeaders, etag) {
+  const request = (validator) => fetch(`${baseUrl}/api/v1/tools`, {
     method: "GET",
     headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json"
+      ...authHeaders,
+      "Content-Type": "application/json",
+      ...validator && { "If-None-Match": validator }
     }
   });
+  let response;
+  try {
+    response = await request(etag);
+  } catch (error) {
+    if (!etag || !(error instanceof TypeError)) throw error;
+    etag = void 0;
+    response = await request();
+  }
+  if (etag && response.status === 304) {
+    return { notModified: true };
+  }
   if (!response.ok) {
     throw new Error(`Failed to fetch server tools: ${response.status}`);
   }
   const data = await response.json();
-  return convertServerToolsResponse(data);
+  const responseEtag = response.headers?.get("ETag") ?? void 0;
+  return {
+    notModified: false,
+    ...convertServerToolsResponse(data),
+    ...responseEtag && { etag: responseEtag }
+  };
 }
 async function getServerTools(options) {
   const {
@@ -19001,34 +19021,30 @@ async function getServerTools(options) {
   try {
     const { BASE_URL: BASE_URL2 } = await import("./clientConfig-VIMT6Q32.mjs");
     const effectiveBaseUrl = baseUrl ?? BASE_URL2;
+    const validator = cached && !forceRefresh ? cached.etag : void 0;
+    let authHeaders;
     if (apiKey) {
-      const response = await fetch(`${effectiveBaseUrl}/api/v1/tools`, {
-        method: "GET",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json"
-        }
-      });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch server tools: ${response.status}`);
+      authHeaders = { "X-API-Key": apiKey };
+    } else {
+      if (!getToken) {
+        getLogger().warn("[serverTools] No auth method available for fetching tools");
+        return cached?.tools ?? [];
       }
-      const data = await response.json();
-      const { tools: tools2, checksum: checksum2 } = convertServerToolsResponse(data);
-      await persistCache(buildCacheEntry(tools2, checksum2));
-      return tools2;
-    }
-    if (!getToken) {
-      getLogger().warn("[serverTools] No auth method available for fetching tools");
-      return cached?.tools ?? [];
+      const token = await getToken();
+      if (!token) {
+        getLogger().warn("[serverTools] No auth token available for fetching tools");
+        return cached?.tools ?? [];
+      }
+      authHeaders = { Authorization: `Bearer ${token}` };
     }
-    const token = await getToken();
-    if (!token) {
-      getLogger().warn("[serverTools] No auth token available for fetching tools");
-      return cached?.tools ?? [];
+    const result = await fetchServerToolsFromApi(effectiveBaseUrl, authHeaders, validator);
+    if (result.notModified) {
+      const confirmed = cached;
+      await persistCache({ ...confirmed, timestamp: Date.now() });
+      return confirmed.tools;
     }
-    const { tools, checksum } = await fetchServerToolsFromApi(effectiveBaseUrl, token);
-    await persistCache(buildCacheEntry(tools, checksum));
-    return tools;
+    await persistCache(buildCacheEntry(result.tools, result.checksum, result.etag));
+    return result.tools;
   } catch (error) {
     getLogger().error("[serverTools] Failed to fetch server tools:", error);
     if (cached?.tools) {