@anuma/sdk 6.38.0 → 6.39.1

package/dist/tools/index.d.ts

@@ -409,7 +409,9 @@ declare function buildConnectorErrorResult(code: ConnectorErrorCode, provider: s
  * Returned as a structured AuditResult so the model (or a host) can
  * read it programmatically: each issue has a path, line, severity,
  * type, and human-readable message. The model is expected to call this
- * after substantial changes and patch the actionable issues.
+ * on the initial build, when adding new UI, or after a user-requested
+ * design change, and patch only the actionable issues within the
+ * current request. For text, logic, or data edits, the audit is skipped.
  */
 type AuditSeverity = "error" | "warn" | "info";
 type AuditIssueType = "no-design-tokens" | "raw-color" | "inline-style-with-color" | "unused-token" | "missing-focus-state" | "focus-not-keyed" | "low-contrast" | "off-scale-spacing" | "orphaned-class" | "missing-aria-label" | "missing-alt" | "heading-order";
@@ -792,7 +794,7 @@ declare function exportAppToHtml(options: ExportAppOptions): string;
  * prefix/head — so keep it byte-identical; see internal docs.
  * Guarded by the backend-sync test in appBuilderPrompt.test.ts.
  */
-declare const APP_BUILDER_PROMPT = "App Builder tools (create_file, patch_file, and the rest described below) are available this turn, but they are OPTIONAL \u2014 having them does not mean you should build anything.\n\nBuild ONLY when the user gives an explicit instruction to build, create, generate, or change an app, tool, or UI \u2014 e.g. \"build a todo app\", \"make a snake game\", \"add a footer to the app\", \"change the background to blue\". A bare app name or feature reference is NOT a build instruction: if the user just says \"todo app\", \"a snake game\", or \"qr code\", or asks a question about an app, do NOT generate anything \u2014 reply normally, or ask what they'd like you to build. The same holds for greetings, questions, stories, explanations, advice, or code that isn't a runnable app: respond normally and do not create files. When it's unclear whether the user actually wants an app built, ask instead of building.\n\nOnce 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.\n\nDESIGN: 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.\n\nWORKFLOW:\n1. NEVER output code as text or markdown. ALWAYS use tools.\n2. Initial build: state your design brief, then create_file with a \"files\" array writing ALL files in one call. The preview renders automatically.\n3. 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.\n4. 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.\n5. 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.\n6. 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.\n7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.\n\nSTRUCTURE:\n- App.js: default-export React component. For non-trivial apps, define small co-located helpers (Header, CardList, Card, EditDialog, \u2026) above the default export rather than one giant App.\n- App.css: all styles, imported in App.js. No inline style objects.\n- package.json: list ALL imported packages including react. No CDN script tags. Versions are auto-pinned.\n- Do NOT create index.js or index.html (auto-generated).\n\nSTATE & PERSISTENCE:\n- The code runs in the user's browser \u2014 standard browser APIs available (localStorage, URL hash, Date, fetch).\n- Persist user-created data (todos, cards, notes, settings) with localStorage so it survives refresh. Use a versioned key (\"kanban.v1\") and JSON.parse inside try/catch on read.\n- Treat persisted data as untrusted and possibly stale: a saved record may predate a field you just added (a timestamp, id, or setting), so default-fill or skip missing fields on read \u2014 never assume a loaded record has every field the current code expects. Bump the key version when the shape changes.\n- Lift state to App when multiple children need it; keep it local otherwise. Extract non-trivial logic into custom hooks (useTodos, useTimer).\n- useReducer for state shapes with several interrelated fields (cards + columns + filters + drag state).\n\nFILE & IMAGE UPLOAD:\n- Picker: `<input type=\"file\" accept=\"image/*\" multiple>` (vary accept by use case: `.csv,text/csv`, `.txt,.md,text/plain`, etc.).\n- Drag-and-drop: call `e.preventDefault()` in onDragOver (otherwise drop never fires); read files from `event.dataTransfer.files`. Drop and picker should coexist.\n- Previews: `<img src={URL.createObjectURL(file)} />`. Call `URL.revokeObjectURL` on unmount or before replacing \u2014 otherwise the browser leaks memory.\n- localStorage cannot hold large binary. Persist only metadata for big files; re-upload on next visit (or use IndexedDB if you really need durable binary storage).\n- Validate size and type before processing; reject files larger than the app can hold in memory.\n\nAI CAPABILITIES \u2014 `window.app.complete(prompt: string): Promise<string>` is available in this environment. Build for the real call.\n- When the app's core purpose is conversation, generation, grading, recommendation, or any natural-language task, this IS the implementation \u2014 call it. NEVER fake it: no hardcoded or canned replies, no random or `setTimeout` \"thinking\", no demo-mode stub. A chat app, tutor, or assistant that doesn't call `window.app.complete` is wrong, not a placeholder.\n- Don't force it where it isn't needed \u2014 a calculator, todo list, or timer has no reason to call it. Match the implementation to what the app actually does.\n- Async: wrap in try/catch, show a loading state, and disable dependent inputs while waiting. Surface failures gracefully (\"Couldn't reach the AI \u2014 try again\").\n- Structure prompts with clear sections (Role / Context / Task / Format) and pass the relevant state (e.g. the running conversation) as context. Render the response as untrusted text: `white-space: pre-wrap`, never dangerouslySetInnerHTML.\n- Skip the call only when the answer is genuinely static \u2014 no language or reasoning needed. Cache repeated prompts in component state when sensible.\n\nCODE QUALITY \u2014 write as a senior engineer would:\n- Handle edge cases (empty inputs, division by zero, invalid data). Show helpful error states, not crashes.\n- Never let formatting throw during render: guard `new Date(x)` / `Intl` / `toLocaleString` / `.toFixed` against missing or invalid values (e.g. `Number.isNaN(d.getTime())`) and return a fallback \u2014 one bad value from storage or state must not blank the whole app.\n- Semantic HTML: real headings, labels, buttons (not divs with onClick), form elements.\n- Accessible: aria-labels on icon buttons, focus-visible styles, keyboard navigable.\n- Extract into custom hooks or helpers when a component grows past ~80 lines.\n\nSTYLING \u2014 Tailwind is the CHASSIS, custom CSS carries the IDENTITY:\n- Tailwind (via Play CDN) for layout, spacing, state (hover/focus), responsive prefixes \u2014 uniform structure.\n- App.css carries the identity: @import the Google Fonts, declare CSS custom properties (--bg, --panel, --card, --ink, --muted, --accent, --hairline, --radius, --radius-sm, --shadow-card, --shadow-card-hi) in :root, gradients/textures/signature animations Tailwind can't express. Reference tokens from Tailwind via arbitrary values (`className=\"bg-[var(--bg)]\"`) when needed. A well-designed app has 60-200 lines of App.css \u2014 not zero.\n- Modern CSS is how apps stop reading as generic-AI-output: `color-mix(in oklab, var(--accent) 14%, transparent)` for tinting, `oklch()` / `oklab()` for perceptually-uniform color, `:has()`, `conic-gradient` / `radial-gradient`, `backdrop-filter`, `@container` queries, inline SVG `feTurbulence` for texture.\n- Don't pull additional CSS frameworks. Tailwind + custom CSS is enough.\n\nVISUAL DESIGN \u2014 every app should look like a real product, not a wireframe:\n- Let the chosen aesthetic drive every decision. \"Editorial\" wants italic display type and restrained color; \"retro arcade\" wants chunky shadows and saturated gradients. No safe-modern defaults.\n- Atmospheric depth: subtle radial wash, paper grain (inline SVG noise), warm/cool tint \u2014 every canvas should feel like a designed space, not a #fff rectangle.\n- Three shadow tiers (rest / hover / active). Pair drop shadows with inset highlights (`box-shadow: 0 1px 0 rgba(255,255,255,.9) inset, 0 6px 14px -10px ...`) for tactile feel.\n- Typography hierarchy: display font for headlines (italic accents on key words via `<em>`), body font for content, mono for metadata/labels \u2014 different families telegraph different information types.\n- Interactive polish: hover/active/focus on every clickable element, 200-300ms cubic-bezier transitions, keyboard shortcuts where natural (Esc to cancel, Cmd/Ctrl+Enter to commit), focus-visible rings keyed to the accent.\n- Light/dark mode if reasonable: a single CSS variable inversion under `[data-theme=\"dark\"]`.\n- Customization affordance for multi-session apps: small \"Tweaks\" panel with theme / density / accent. Skip for throwaway demos.\n- Responsive: Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) and `@media` in App.css. Mobile-first.";
+declare const APP_BUILDER_PROMPT = "App Builder tools (create_file, patch_file, and the rest described below) are available this turn, but they are OPTIONAL \u2014 having them does not mean you should build anything.\n\nBuild ONLY when the user gives an explicit instruction to build, create, generate, or change an app, tool, or UI \u2014 e.g. \"build a todo app\", \"make a snake game\", \"add a footer to the app\", \"change the background to blue\". A bare app name or feature reference is NOT a build instruction: if the user just says \"todo app\", \"a snake game\", or \"qr code\", or asks a question about an app, do NOT generate anything \u2014 reply normally, or ask what they'd like you to build. The same holds for greetings, questions, stories, explanations, advice, or code that isn't a runnable app: respond normally and do not create files. When it's unclear whether the user actually wants an app built, ask instead of building.\n\nOnce 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.\n\nDESIGN: 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.\n\nEDIT 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.\n\nWORKFLOW:\n1. NEVER output code as text or markdown. ALWAYS use tools.\n2. Initial build: state your design brief, then create_file with a \"files\" array writing ALL files in one call. The preview renders automatically.\n3. 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.\n4. 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.\n5. 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.\n6. 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.\n7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.\n\nSTRUCTURE:\n- App.js: default-export React component. For non-trivial apps, define small co-located helpers (Header, CardList, Card, EditDialog, \u2026) above the default export rather than one giant App.\n- App.css: all styles, imported in App.js. No inline style objects.\n- package.json: list ALL imported packages including react. No CDN script tags. Versions are auto-pinned.\n- Do NOT create index.js or index.html (auto-generated).\n\nSTATE & PERSISTENCE:\n- The code runs in the user's browser \u2014 standard browser APIs available (localStorage, URL hash, Date, fetch).\n- Persist user-created data (todos, cards, notes, settings) with localStorage so it survives refresh. Use a versioned key (\"kanban.v1\") and JSON.parse inside try/catch on read.\n- Treat persisted data as untrusted and possibly stale: a saved record may predate a field you just added (a timestamp, id, or setting), so default-fill or skip missing fields on read \u2014 never assume a loaded record has every field the current code expects. Bump the key version when the shape changes.\n- Lift state to App when multiple children need it; keep it local otherwise. Extract non-trivial logic into custom hooks (useTodos, useTimer).\n- useReducer for state shapes with several interrelated fields (cards + columns + filters + drag state).\n\nFILE & IMAGE UPLOAD:\n- Picker: `<input type=\"file\" accept=\"image/*\" multiple>` (vary accept by use case: `.csv,text/csv`, `.txt,.md,text/plain`, etc.).\n- Drag-and-drop: call `e.preventDefault()` in onDragOver (otherwise drop never fires); read files from `event.dataTransfer.files`. Drop and picker should coexist.\n- Previews: `<img src={URL.createObjectURL(file)} />`. Call `URL.revokeObjectURL` on unmount or before replacing \u2014 otherwise the browser leaks memory.\n- localStorage cannot hold large binary. Persist only metadata for big files; re-upload on next visit (or use IndexedDB if you really need durable binary storage).\n- Validate size and type before processing; reject files larger than the app can hold in memory.\n\nAI CAPABILITIES \u2014 `window.app.complete(prompt: string): Promise<string>` is available in this environment. Build for the real call.\n- When the app's core purpose is conversation, generation, grading, recommendation, or any natural-language task, this IS the implementation \u2014 call it. NEVER fake it: no hardcoded or canned replies, no random or `setTimeout` \"thinking\", no demo-mode stub. A chat app, tutor, or assistant that doesn't call `window.app.complete` is wrong, not a placeholder.\n- Don't force it where it isn't needed \u2014 a calculator, todo list, or timer has no reason to call it. Match the implementation to what the app actually does.\n- Async: wrap in try/catch, show a loading state, and disable dependent inputs while waiting. Surface failures gracefully (\"Couldn't reach the AI \u2014 try again\").\n- Structure prompts with clear sections (Role / Context / Task / Format) and pass the relevant state (e.g. the running conversation) as context. Render the response as untrusted text: `white-space: pre-wrap`, never dangerouslySetInnerHTML.\n- Skip the call only when the answer is genuinely static \u2014 no language or reasoning needed. Cache repeated prompts in component state when sensible.\n\nCODE QUALITY \u2014 write as a senior engineer would:\n- Handle edge cases (empty inputs, division by zero, invalid data). Show helpful error states, not crashes.\n- Never let formatting throw during render: guard `new Date(x)` / `Intl` / `toLocaleString` / `.toFixed` against missing or invalid values (e.g. `Number.isNaN(d.getTime())`) and return a fallback \u2014 one bad value from storage or state must not blank the whole app.\n- Semantic HTML: real headings, labels, buttons (not divs with onClick), form elements.\n- Accessible: aria-labels on icon buttons, focus-visible styles, keyboard navigable.\n- Extract into custom hooks or helpers when a component grows past ~80 lines.\n\nSTYLING \u2014 Tailwind is the CHASSIS, custom CSS carries the IDENTITY:\n- Tailwind (via Play CDN) for layout, spacing, state (hover/focus), responsive prefixes \u2014 uniform structure.\n- App.css carries the identity: @import the Google Fonts, declare CSS custom properties (--bg, --panel, --card, --ink, --muted, --accent, --hairline, --radius, --radius-sm, --shadow-card, --shadow-card-hi) in :root, gradients/textures/signature animations Tailwind can't express. Reference tokens from Tailwind via arbitrary values (`className=\"bg-[var(--bg)]\"`) when needed. A well-designed app has 60-200 lines of App.css \u2014 not zero.\n- Modern CSS is how apps stop reading as generic-AI-output: `color-mix(in oklab, var(--accent) 14%, transparent)` for tinting, `oklch()` / `oklab()` for perceptually-uniform color, `:has()`, `conic-gradient` / `radial-gradient`, `backdrop-filter`, `@container` queries, inline SVG `feTurbulence` for texture.\n- Don't pull additional CSS frameworks. Tailwind + custom CSS is enough.\n\nVISUAL DESIGN \u2014 every app should look like a real product, not a wireframe:\n- Let the chosen aesthetic drive every decision. \"Editorial\" wants italic display type and restrained color; \"retro arcade\" wants chunky shadows and saturated gradients. No safe-modern defaults.\n- Atmospheric depth: subtle radial wash, paper grain (inline SVG noise), warm/cool tint \u2014 every canvas should feel like a designed space, not a #fff rectangle.\n- Three shadow tiers (rest / hover / active). Pair drop shadows with inset highlights (`box-shadow: 0 1px 0 rgba(255,255,255,.9) inset, 0 6px 14px -10px ...`) for tactile feel.\n- Typography hierarchy: display font for headlines (italic accents on key words via `<em>`), body font for content, mono for metadata/labels \u2014 different families telegraph different information types.\n- Interactive polish: hover/active/focus on every clickable element, 200-300ms cubic-bezier transitions, keyboard shortcuts where natural (Esc to cancel, Cmd/Ctrl+Enter to commit), focus-visible rings keyed to the accent.\n- Light/dark mode if reasonable: a single CSS variable inversion under `[data-theme=\"dark\"]`.\n- Customization affordance for multi-session apps: small \"Tweaks\" panel with theme / density / accent. Skip for throwaway demos.\n- Responsive: Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) and `@media` in App.css. Mobile-first.";
 
 /** Strip leading slash and collapse traversal segments so paths are always clean relative paths. */
 declare function normalizePath(p: string): string;
@@ -1018,7 +1020,7 @@ declare const LIST_FILES_SCHEMA: {
 };
 declare const AUDIT_DESIGN_SCHEMA: {
     readonly name: "audit_design";
-    readonly description: "Inspect the current app's design coherence. Reports raw hex colors outside :root (should be tokens), CSS variables declared but unused, missing :focus-visible rules on interactive elements, icon-only buttons without aria-label, images without alt, heading-level skips, and inline styles with hardcoded colors. Returns a 0-100 score and a list of issues with line numbers. Call this after substantial changes to verify the design system is intact, then patch the actionable issues.";
+    readonly description: "Inspect the current app's design coherence. Reports raw hex colors outside :root (should be tokens), CSS variables declared but unused, missing :focus-visible rules on interactive elements, icon-only buttons without aria-label, images without alt, heading-level skips, and inline styles with hardcoded colors. Returns a 0-100 score and a list of issues with line numbers. Call this on the initial build, when adding new UI, or after a user-requested design change, then patch only the actionable issues within the current user request. For text, logic, or data edits, skip this tool.";
     readonly arguments: {
         readonly type: "object";
         readonly properties: {};
@@ -1027,7 +1029,7 @@ declare const AUDIT_DESIGN_SCHEMA: {
 };
 declare const CRITIQUE_DESIGN_SCHEMA: {
     readonly name: "critique_design";
-    readonly description: "Step back and look at what you just made. Returns App.js + App.css plus a rubric of open-ended questions for you to answer honestly in your next response — about intent, hierarchy, distinctiveness, coherence, and what's weakest. This is not a checklist of rules; it's an occasion to apply taste. After answering, patch the 2-3 weakest items you identified. Call this after the initial build and after substantial design changes — complementary to audit_design (which catches mechanical/accessibility issues), where critique_design catches taste and composition.";
+    readonly description: "Review the app after the initial build, when adding new UI, or a user-requested design change. Returns App.js, App.css, and questions about intent, hierarchy, distinctiveness, coherence, and weak design choices. Answer the questions and patch only weaknesses within the current user request. For text, logic, or data edits, skip this tool. Preserve styles, dependencies, and unrelated code on text edits. Use audit_design for mechanical and accessibility checks.";
     readonly arguments: {
         readonly type: "object";
         readonly properties: {};
@@ -1036,7 +1038,7 @@ declare const CRITIQUE_DESIGN_SCHEMA: {
 };
 declare const VERIFY_APP_SCHEMA: {
     readonly name: "verify_app";
-    readonly description: "Ask the host runtime whether the current app actually mounts. The host's bundler / preview iframe (e.g. Sandpack in a chat UI) is already compiling and running your code; this tool collects whatever errors that runtime captured — hallucinated imports, syntax the bundler rejects, undefined components, runtime crashes — and returns them. Use this after substantial changes and before declaring done. If `rendered` is false or `errors` is non-empty, fix every error before doing anything else. If the host did not wire a runtime verifier, the tool returns `{ rendered: true, errors: [] }` with a `note` explaining — degrade to audit_design + critique_design in that case.";
+    readonly description: "Ask the host runtime whether the current app actually mounts. The host's bundler / preview iframe (e.g. Sandpack in a chat UI) is already compiling and running your code; this tool collects whatever errors that runtime captured — hallucinated imports, syntax the bundler rejects, undefined components, runtime crashes — and returns them. Use this after substantial changes and before declaring done. If `rendered` is false or `errors` is non-empty, fix every error before doing anything else. If the host did not wire a runtime verifier, the tool returns `{ rendered: true, errors: [] }` with a note. Preserve the current user request scope. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes.";
     readonly arguments: {
         readonly type: "object";
         readonly properties: {};
@@ -1133,7 +1135,9 @@ interface CreateAppGenerationToolsOptions {
      * after substantial changes; the tool's executor invokes this hook
      * and returns the result to the model. When NOT wired, the tool
      * still exists but returns `{ rendered: true, errors: [], note: … }`
-     * so the model degrades gracefully to audit/critique-only feedback.
+     * so the model degrades gracefully — the note restates that
+     * audit_design / critique_design stay gated to the initial build,
+     * adding new UI, or user-requested design changes.
      *
      * Same host-hook pattern as `displayApp` and `onFileChange` — the
      * SDK never executes anything itself.

package/dist/tools/index.mjs

@@ -1397,15 +1397,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:
@@ -1761,17 +1763,17 @@ var LIST_FILES_SCHEMA = {
 };
 var AUDIT_DESIGN_SCHEMA = {
   name: "audit_design",
-  description: "Inspect the current app's design coherence. Reports raw hex colors outside :root (should be tokens), CSS variables declared but unused, missing :focus-visible rules on interactive elements, icon-only buttons without aria-label, images without alt, heading-level skips, and inline styles with hardcoded colors. Returns a 0-100 score and a list of issues with line numbers. Call this after substantial changes to verify the design system is intact, then patch the actionable issues.",
+  description: "Inspect the current app's design coherence. Reports raw hex colors outside :root (should be tokens), CSS variables declared but unused, missing :focus-visible rules on interactive elements, icon-only buttons without aria-label, images without alt, heading-level skips, and inline styles with hardcoded colors. Returns a 0-100 score and a list of issues with line numbers. Call this on the initial build, when adding new UI, or after a user-requested design change, then patch only the actionable issues within the current user request. For text, logic, or data edits, skip this tool.",
   arguments: { type: "object", properties: {}, required: [] }
 };
 var CRITIQUE_DESIGN_SCHEMA = {
   name: "critique_design",
-  description: "Step back and look at what you just made. Returns App.js + App.css plus a rubric of open-ended questions for you to answer honestly in your next response \u2014 about intent, hierarchy, distinctiveness, coherence, and what's weakest. This is not a checklist of rules; it's an occasion to apply taste. After answering, patch the 2-3 weakest items you identified. Call this after the initial build and after substantial design changes \u2014 complementary to audit_design (which catches mechanical/accessibility issues), where critique_design catches taste and composition.",
+  description: "Review the app after the initial build, when adding new UI, or a user-requested design change. Returns App.js, App.css, and questions about intent, hierarchy, distinctiveness, coherence, and weak design choices. Answer the questions and patch only weaknesses within the current user request. For text, logic, or data edits, skip this tool. Preserve styles, dependencies, and unrelated code on text edits. Use audit_design for mechanical and accessibility checks.",
   arguments: { type: "object", properties: {}, required: [] }
 };
 var VERIFY_APP_SCHEMA = {
   name: "verify_app",
-  description: "Ask the host runtime whether the current app actually mounts. The host's bundler / preview iframe (e.g. Sandpack in a chat UI) is already compiling and running your code; this tool collects whatever errors that runtime captured \u2014 hallucinated imports, syntax the bundler rejects, undefined components, runtime crashes \u2014 and returns them. Use this after substantial changes and before declaring done. If `rendered` is false or `errors` is non-empty, fix every error before doing anything else. If the host did not wire a runtime verifier, the tool returns `{ rendered: true, errors: [] }` with a `note` explaining \u2014 degrade to audit_design + critique_design in that case.",
+  description: "Ask the host runtime whether the current app actually mounts. The host's bundler / preview iframe (e.g. Sandpack in a chat UI) is already compiling and running your code; this tool collects whatever errors that runtime captured \u2014 hallucinated imports, syntax the bundler rejects, undefined components, runtime crashes \u2014 and returns them. Use this after substantial changes and before declaring done. If `rendered` is false or `errors` is non-empty, fix every error before doing anything else. If the host did not wire a runtime verifier, the tool returns `{ rendered: true, errors: [] }` with a note. Preserve the current user request scope. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes.",
   arguments: { type: "object", properties: {}, required: [] }
 };
 var DEFAULT_DESIGN_CRITIQUE_RUBRIC = Object.freeze([
@@ -2204,7 +2206,7 @@ function createAppGenerationTools({
         const appJs = files.find((f) => f.path === "App.js")?.content ?? files.find((f) => f.path === "App.jsx")?.content ?? "";
         const appCss = files.find((f) => f.path === "App.css")?.content ?? "";
         return {
-          instruction: "Read your App.js and App.css below, then answer each of the rubric questions honestly in your next response \u2014 be specific (cite lines, name choices, don't hedge). After answering, identify the 2-3 weakest items you named and patch them now. The point is to step back from the keyboard and actually look, not to satisfy a checklist.",
+          instruction: "For text, logic, or data edits, skip this critique. Preserve styles, dependencies, and unrelated code on text edits. For the initial build, when adding new UI, or a user-requested design change, read App.js and App.css below, then answer each rubric question with specific lines and choices. Identify the 2-3 weakest items within that request. Patch only files and lines required by the current user request.",
           rubric: designCritiqueRubric,
           appJs: {
             path: "App.js",
@@ -2233,7 +2235,7 @@ function createAppGenerationTools({
         return {
           rendered: true,
           errors: [],
-          note: "This host did not wire verify_app \u2014 runtime introspection is unavailable in this environment. Rely on audit_design and critique_design for feedback. Do not interpret the empty errors list as proof the app runs."
+          note: "This host did not wire verify_app. Runtime introspection is unavailable in this environment. Preserve the current user request scope. Use audit_design and critique_design only for the initial build, adding new UI, or user-requested design changes. Do not interpret the empty errors list as proof the app runs."
         };
       }
       try {

package/dist/tools/selection/index.cjs

@@ -1177,15 +1177,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:
@@ -1529,12 +1531,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) {
@@ -1569,19 +1572,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 {
@@ -1613,34 +1633,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/tools/selection/index.d.mts

@@ -141,6 +141,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.
@@ -257,7 +259,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/tools/selection/index.d.ts

@@ -141,6 +141,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.
@@ -257,7 +259,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/tools/selection/index.mjs

@@ -1055,15 +1055,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:
@@ -1407,12 +1409,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) {
@@ -1447,19 +1450,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 {
@@ -1491,34 +1511,30 @@ async function getServerTools(options) {
   try {
     const { BASE_URL: BASE_URL2 } = await import("./clientConfig-WITO4T6L.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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "6.38.0",
+  "version": "6.39.1",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",