@anuma/sdk 2.1.0 → 2.2.1

package/dist/server/index.mjs

@@ -53,6 +53,7 @@ import {
   getConversationsLazyOp,
   getConversationsOp,
   getEncryptionKey,
+  getMemoriesNeedingTopicExtractionOp,
   getMessagesOp,
   getUnfiledVaultMemoriesOp,
   getVaultMemoryOp,
@@ -66,6 +67,7 @@ import {
   onKeyAvailable,
   preEmbedVaultMemories,
   recall,
+  replaceMemoryEntitiesGuardedOp,
   requestEncryptionKey,
   requestKeyPair,
   require_QueryDescription,
@@ -85,6 +87,7 @@ import {
   searchMessagesOp,
   searchVaultMemories,
   shouldChunkMessage,
+  stampTopicsExtractedAtOp,
   stripToolCalls,
   updateConversationProjectOp,
   updateConversationTitleOp,
@@ -94,8 +97,9 @@ import {
   updateMessageFeedbackOp,
   updateVaultMemoryEmbeddingOp,
   updateVaultMemoryOp,
-  upsertMessageOp
-} from "./chunk-45GOZ3AB.mjs";
+  upsertMessageOp,
+  vaultMemoryToStored
+} from "./chunk-3AWYZRTS.mjs";
 import {
   createStreamingDeAnonymizer,
   resolvePiiRedactor
@@ -1086,6 +1090,9 @@ __decorateClass([
 __decorateClass([
   (0, import_decorators6.field)("topics_user_managed")
 ], VaultMemory.prototype, "topicsUserManaged", 2);
+__decorateClass([
+  (0, import_decorators6.field)("topics_extracted_at")
+], VaultMemory.prototype, "topicsExtractedAt", 2);
 __decorateClass([
   import_decorators6.readonly,
   (0, import_decorators6.date)("created_at")
@@ -1233,7 +1240,7 @@ __decorateClass([
 ], VaultFolder.prototype, "context", 2);
 
 // src/lib/db/schema.ts
-var SDK_SCHEMA_VERSION = 35;
+var SDK_SCHEMA_VERSION = 36;
 var sdkSchema = (0, import_watermelondb12.appSchema)({
   version: SDK_SCHEMA_VERSION,
   tables: [
@@ -1354,7 +1361,11 @@ var sdkSchema = (0, import_watermelondb12.appSchema)({
         // When true, the user has manually set this memory's topics (entity
         // links). Auto-extraction then leaves its links alone — the user owns
         // them. Null/false = topics are auto-derived (default).
-        { name: "topics_user_managed", type: "boolean", isOptional: true }
+        { name: "topics_user_managed", type: "boolean", isOptional: true },
+        // Unix ms of the last LLM topic-extraction pass over this memory's
+        // content. Null = never extracted standalone (legacy rows with entity
+        // links are grandfathered — see getMemoriesNeedingTopicExtractionOp).
+        { name: "topics_extracted_at", type: "number", isOptional: true }
       ]
     }),
     // Entity table — canonical names extracted from auto-extraction (W5).
@@ -1952,6 +1963,19 @@ var sdkMigrations = (0, import_migrations.schemaMigrations)({
           ]
         })
       ]
+    },
+    // v35 -> v36: topics_extracted_at watermark on memory_vault. Existing rows
+    // keep it NULL — rows that already have entity links are grandfathered as
+    // extracted (no mass re-extraction on upgrade), rows without links are the
+    // backfill target. See getMemoriesNeedingTopicExtractionOp.
+    {
+      toVersion: 36,
+      steps: [
+        (0, import_migrations.addColumns)({
+          table: "memory_vault",
+          columns: [{ name: "topics_extracted_at", type: "number", isOptional: true }]
+        })
+      ]
     }
   ]
 });
@@ -4839,7 +4863,7 @@ async function isMemoryTopicsUserManaged(ctx, memoryId) {
     return true;
   }
 }
-var DEFAULT_MODEL = "gpt-oss/gpt-oss-120b";
+var DEFAULT_EXTRACTION_MODEL = "gpt-oss/gpt-oss-120b";
 var DEFAULT_MIN_CONFIDENCE = 0.7;
 var MAX_CONTENT_LENGTH = 200;
 var MIN_CONTENT_LENGTH = 3;
@@ -4852,6 +4876,16 @@ var FACT_TYPES = [
   "constraint",
   "other"
 ];
+var ENTITY_KIND_GUIDELINES = `Choose the MOST SPECIFIC kind:
+    - person: a named individual ("Sara", "Dr. Lee")
+    - organization: a company, team, school, or group ("Google", "the Warriors", "Stanford")
+    - place: a geographic location or venue ("San Francisco", "Blue Bottle on Valencia")
+    - event: a dated or nameable occurrence ("Chicago Marathon", "the Japan trip", "their wedding")
+    - product: a named app, tool, brand, device, book, film, or other media title ("Linear", "iPhone", "Dune", "Ableton")
+    - thing: a concrete physical object that isn't a branded product ("road bike", "sourdough starter")
+    - concept: a topic, skill, field, language, or idea ("machine learning", "Spanish", "async communication")
+    - other: a named entity that genuinely fits none of the above \u2014 use sparingly
+  Prefer organization / product / event / place over the generic "thing"; fall back to "thing" or "other" only when no specific kind fits.`;
 var SYSTEM_PROMPT = `You extract durable user facts from conversations for a personal memory system.
 
 A "durable fact" is something the user shared about themselves that should still be true in future conversations. Examples that ARE durable:
@@ -4880,16 +4914,7 @@ For each durable fact, output:
 - type: one of identity | preference | relationship | plan | ongoing_context | constraint | other
 - confidence: 0.0-1.0; how sure you are this is durable AND true. Only include facts >= 0.7.
 - sourceMessageIds: which message IDs from the conversation contained the evidence
-- entities: named entities mentioned, each as an object { "name": string, "kind": one of "person" | "organization" | "place" | "event" | "product" | "thing" | "concept" | "other" }. Optional \u2014 include only NAMED entities, skip generic/common nouns. Choose the MOST SPECIFIC kind:
-    - person: a named individual ("Sara", "Dr. Lee")
-    - organization: a company, team, school, or group ("Google", "the Warriors", "Stanford")
-    - place: a geographic location or venue ("San Francisco", "Blue Bottle on Valencia")
-    - event: a dated or nameable occurrence ("Chicago Marathon", "the Japan trip", "their wedding")
-    - product: a named app, tool, brand, device, book, film, or other media title ("Linear", "iPhone", "Dune", "Ableton")
-    - thing: a concrete physical object that isn't a branded product ("road bike", "sourdough starter")
-    - concept: a topic, skill, field, language, or idea ("machine learning", "Spanish", "async communication")
-    - other: a named entity that genuinely fits none of the above \u2014 use sparingly
-  Prefer organization / product / event / place over the generic "thing"; fall back to "thing" or "other" only when no specific kind fits. Examples:
+- entities: named entities mentioned, each as an object { "name": string, "kind": one of "person" | "organization" | "place" | "event" | "product" | "thing" | "concept" | "other" }. Optional \u2014 include only NAMED entities, skip generic/common nouns. ${ENTITY_KIND_GUIDELINES} Examples:
     - "started a new job at Hollowpoint Labs and I'm learning Haskell for it" \u2192 entities: [{ "name": "Hollowpoint Labs", "kind": "organization" }, { "name": "Haskell", "kind": "concept" }]
     - "running the Berlin Half in May and I track workouts in Whoop" \u2192 entities: [{ "name": "Berlin Half", "kind": "event" }, { "name": "Whoop", "kind": "product" }]
 - eventTime: when the event in this fact occurs/occurred. Resolve relative phrases ("yesterday", "next week") against the current date given in the user message. Output one of:
@@ -4915,7 +4940,7 @@ async function extractFacts(messages, options) {
     ...options.apiKey !== void 0 && { apiKey: options.apiKey },
     ...options.getToken !== void 0 && { getToken: options.getToken },
     ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
-    model: options.model ?? DEFAULT_MODEL,
+    model: options.model ?? DEFAULT_EXTRACTION_MODEL,
     systemPrompt: SYSTEM_PROMPT,
     userMessage: `Today's date is ${today}. Resolve any relative dates ("yesterday", "next week") against it.
 
@@ -5009,7 +5034,9 @@ async function extractAndRetain(messages, retainCtx, options) {
       if (options.entityCtx && candidate.entities.length > 0) {
         try {
           if (!await isMemoryTopicsUserManaged(options.entityCtx, result.memoryId)) {
-            await linkMemoryEntitiesOp(options.entityCtx, result.memoryId, candidate.entities);
+            await linkMemoryEntitiesOp(options.entityCtx, result.memoryId, candidate.entities, {
+              unlessTopicsUserManaged: true
+            });
           }
         } catch (err) {
           log.warn("[memory/extract] linkMemoryEntitiesOp failed", err);
@@ -5404,7 +5431,7 @@ function createRecallTool(ctx, toolOptions, callbacks) {
 
 // src/lib/memory/reflect.ts
 var DEFAULT_BASE_URL = BASE_URL;
-var DEFAULT_MODEL2 = "anthropic/claude-sonnet-4-6";
+var DEFAULT_MODEL = "anthropic/claude-sonnet-4-6";
 var DEFAULT_MAX_TOKENS = 4096;
 var REQUEST_TIMEOUT_MS = 6e4;
 var DEFAULT_SYSTEM_PROMPT = `You are a personal assistant with access to the user's memory. Answer the user's question using the supplied memories as evidence.
@@ -5436,7 +5463,7 @@ async function reflect(query, ctx, options) {
   const evidence = recalled.memories.map((m, i) => `[${i + 1}] (id: ${m.id}, kind: ${m.kind})
 ${m.content}`).join("\n\n");
   const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
-  const model = options.llmModel ?? DEFAULT_MODEL2;
+  const model = options.llmModel ?? DEFAULT_MODEL;
   const wantsStructured = !!options.responseSchema;
   const sendResponseFormat = wantsStructured && supportsResponseFormat(model, "json_schema");
   const basePrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
@@ -5546,6 +5573,163 @@ function parseAnswer(body, base, parseSchema) {
   };
 }
 
+// src/lib/memory/topicExtract.ts
+var TOPIC_EXTRACTION_BATCH_SIZE = 10;
+var MAX_CHARS_PER_MEMORY = 300;
+var MAX_VOCABULARY_NAMES = 100;
+var SYSTEM_PROMPT2 = `You assign topics to saved memories for a personal memory system.
+
+Each memory is a short statement about the user. For each memory, list the NAMED entities it mentions \u2014 these become the memory's topics, used to connect related memories in a knowledge graph.
+
+Include only NAMED entities, skip generic/common nouns. ${ENTITY_KIND_GUIDELINES}
+
+Output strict JSON: {"memories": [{"id": string, "entities": [{"name": string, "kind": string}]}]}
+- exactly one element per input memory, echoing its id verbatim
+- "entities" may be empty when a memory mentions no named entities \u2014 most short memories have 0-3
+No prose.`;
+async function extractEntitiesForMemories(memories, options) {
+  const out = /* @__PURE__ */ new Map();
+  if (memories.length === 0) return out;
+  const redactor = resolvePiiRedactor(options.piiRedaction);
+  const vocabulary = (options.existingEntityNames ?? []).filter((n) => n.trim().length > 0).slice(0, MAX_VOCABULARY_NAMES).map((n) => redactor ? redactor.redactText(n).text : n);
+  const vocabularyNote = vocabulary.length > 0 ? `The user's existing topics: ${vocabulary.join(", ")}.
+When a memory refers to one of these, reuse the EXACT existing name (same spelling and casing) instead of a variant.
+
+` : "";
+  for (let i = 0; i < memories.length; i += TOPIC_EXTRACTION_BATCH_SIZE) {
+    const batch = memories.slice(i, i + TOPIC_EXTRACTION_BATCH_SIZE);
+    const listing = batch.map((m) => {
+      const content = m.content.slice(0, MAX_CHARS_PER_MEMORY);
+      return `[${m.id}] ${redactor ? redactor.redactText(content).text : content}`;
+    }).join("\n");
+    const parsed = await callPortalJsonCompletion({
+      ...options.apiKey !== void 0 && { apiKey: options.apiKey },
+      ...options.getToken !== void 0 && { getToken: options.getToken },
+      ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+      model: options.model ?? DEFAULT_EXTRACTION_MODEL,
+      systemPrompt: SYSTEM_PROMPT2,
+      userMessage: `${vocabularyNote}Memories:
+${listing}
+
+List each memory's named entities.`,
+      tag: "memory/topics",
+      ...options.fetchFn && { fetchFn: options.fetchFn },
+      ...options.maxAttempts !== void 0 && { maxAttempts: options.maxAttempts },
+      ...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
+      ...options.totalTimeoutMs !== void 0 && { totalTimeoutMs: options.totalTimeoutMs },
+      ...options.backoffMs && { backoffMs: options.backoffMs }
+    });
+    if (parsed === null) {
+      getLogger().warn(
+        `[memory/topics] batch of ${batch.length} failed after retries \u2014 will retry next sweep`
+      );
+      continue;
+    }
+    const validIds = new Set(batch.map((m) => m.id));
+    const byId = parseTopicResponse(parsed, validIds);
+    if (byId === null) {
+      getLogger().warn(
+        `[memory/topics] batch of ${batch.length} returned an unrecognized shape \u2014 will retry next sweep`
+      );
+      continue;
+    }
+    for (const m of batch) {
+      const entities = byId.get(m.id);
+      if (entities === void 0) {
+        continue;
+      }
+      out.set(m.id, redactor ? restoreEntities(entities, redactor) : entities);
+    }
+  }
+  return out;
+}
+function restoreEntities(entities, redactor) {
+  return entities.map((e) => ({ kind: e.kind, restored: redactor.restoreForStorage(e.name) })).filter((e) => !e.restored.unresolved).map(
+    (e) => e.kind !== void 0 ? { name: e.restored.text, kind: e.kind } : { name: e.restored.text }
+  );
+}
+function parseTopicResponse(parsed, validIds) {
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const list = parsed.memories;
+  if (!Array.isArray(list)) return null;
+  const out = /* @__PURE__ */ new Map();
+  for (const raw of list) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const obj = raw;
+    if (typeof obj.id !== "string" || !validIds.has(obj.id) || out.has(obj.id)) continue;
+    const entities = Array.isArray(obj.entities) ? parseEntities(obj.entities) : [];
+    out.set(obj.id, entities);
+  }
+  return out;
+}
+async function extractAndLinkEntitiesForMemoriesOp(ctx, memoryIds, options) {
+  const entityCtx = ctx.entityCtx;
+  if (!entityCtx) {
+    throw new Error("extractAndLinkEntitiesForMemoriesOp requires ctx.entityCtx");
+  }
+  const log = getLogger();
+  const extractedAt = options.now ?? Date.now();
+  const skippedIds = [];
+  const inputs = [];
+  for (const id of memoryIds) {
+    let record;
+    try {
+      record = await ctx.vaultMemoryCollection.find(id);
+    } catch {
+      skippedIds.push(id);
+      continue;
+    }
+    if (record.isDeleted || ctx.userId !== void 0 && record.userId !== ctx.userId || record.topicsUserManaged) {
+      skippedIds.push(id);
+      continue;
+    }
+    try {
+      const stored = await vaultMemoryToStored(
+        record,
+        ctx.walletAddress,
+        ctx.signMessage,
+        ctx.embeddedWalletSigner
+      );
+      inputs.push({ id, content: stored.content });
+    } catch (err) {
+      log.warn("[memory/topics] failed to load memory for extraction", err);
+      skippedIds.push(id);
+    }
+  }
+  const entitiesByMemory = await extractEntitiesForMemories(inputs, options);
+  const toStamp = [];
+  for (const input of inputs) {
+    const entities = entitiesByMemory.get(input.id);
+    if (entities === void 0) {
+      skippedIds.push(input.id);
+      continue;
+    }
+    try {
+      const linked = await replaceMemoryEntitiesGuardedOp(entityCtx, input.id, entities);
+      if (linked === null) {
+        skippedIds.push(input.id);
+        entitiesByMemory.delete(input.id);
+        continue;
+      }
+    } catch (err) {
+      log.warn("[memory/topics] replaceMemoryEntitiesGuardedOp failed", err);
+      skippedIds.push(input.id);
+      entitiesByMemory.delete(input.id);
+      continue;
+    }
+    toStamp.push(input.id);
+  }
+  const stampedIds = await stampTopicsExtractedAtOp(ctx, toStamp, extractedAt);
+  const stampedSet = new Set(stampedIds);
+  for (const id of toStamp) {
+    if (!stampedSet.has(id)) {
+      skippedIds.push(id);
+      entitiesByMemory.delete(id);
+    }
+  }
+  return { entitiesByMemory, stampedIds, skippedIds };
+}
+
 // src/tools/appBuilderPrompt.ts
 var 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.
 
@@ -11087,6 +11271,7 @@ export {
   STREAM_RESUMABLE_HEADER,
   StreamExpiredError,
   TOOL_CATALOG,
+  TOPIC_EXTRACTION_BATCH_SIZE,
   TextProcessor,
   UserPreference,
   VaultFolder,
@@ -11167,7 +11352,9 @@ export {
   estimateMessagesTokens,
   estimateTokens,
   exportPublicKey,
+  extractAndLinkEntitiesForMemoriesOp,
   extractAndRetain,
+  extractEntitiesForMemories,
   extractFacts,
   findMatchingTools,
   generateConversationId,
@@ -11203,6 +11390,7 @@ export {
   getMediaCountsByTypeOp,
   getMediaOp,
   getMediaTypeFromMime,
+  getMemoriesNeedingTopicExtractionOp,
   getMessagesOp,
   getModelPreferenceOp,
   getProjectConversationCountOp,
@@ -11262,6 +11450,7 @@ export {
   shouldChunkMessage,
   shouldRefreshTools,
   splitMessagesAtThreshold,
+  stampTopicsExtractedAtOp,
   streamCancelPath,
   streamReplayPath,
   summaryToSystemMessage,

package/dist/server/{recall-RMBNCEG6.mjs → recall-EWMI64SA.mjs}

@@ -1,6 +1,6 @@
 import {
   recall
-} from "./chunk-45GOZ3AB.mjs";
+} from "./chunk-3AWYZRTS.mjs";
 import "./chunk-AHJT66EO.mjs";
 import "./chunk-3RPGXXPZ.mjs";
 export {

package/dist/tools/index.d.mts

@@ -1516,6 +1516,11 @@ declare function exportAppToHtml(options: ExportAppOptions): string;
  * The workflow this prompt mandates (create → critique → patch → audit →
  * patch → verify) needs 7–8 tool rounds on a substantial turn. Hosts capping
  * `maxToolRounds` below 8 starve the trailing `verify_app` step.
+ *
+ * ⚠ The substring "App Builder tools (create_file, patch_file," is relied on by
+ * backend infrastructure — matched anywhere in the text (substring), not as a
+ * 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.";
 

package/dist/tools/index.d.ts

@@ -1516,6 +1516,11 @@ declare function exportAppToHtml(options: ExportAppOptions): string;
  * The workflow this prompt mandates (create → critique → patch → audit →
  * patch → verify) needs 7–8 tool rounds on a substantial turn. Hosts capping
  * `maxToolRounds` below 8 starve the trailing `verify_app` step.
+ *
+ * ⚠ The substring "App Builder tools (create_file, patch_file," is relied on by
+ * backend infrastructure — matched anywhere in the text (substring), not as a
+ * 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.";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -145,7 +145,7 @@
   "homepage": "https://github.com/anuma-ai/sdk#readme",
   "packageManager": "pnpm@10.23.0",
   "dependencies": {
-    "@anuma/portal": "1.0.0-next.20260715224031",
+    "@anuma/portal": "1.0.0-next.20260717201251",
     "@babel/parser": "^7.29.2",
     "@babel/types": "^7.29.0",
     "ai": "6.0.202",