@anuma/sdk 3.6.3 → 3.8.0

package/dist/server/{chunk-66UWDXS3.mjs → chunk-LSKFJNLF.mjs}

@@ -1,7 +1,7 @@
 import {
   callPortalJsonCompletion,
   getLogger
-} from "./chunk-AHJT66EO.mjs";
+} from "./chunk-MIXEASUP.mjs";
 import {
   BASE_URL,
   __commonJS,
@@ -19554,7 +19554,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             legacy.map((r) => ({ id: r.uniqueId, content: r.content, score: r.similarity }))
           );
         }
-        const { recall: recall2 } = await import("./recall-UTVH2XPK.mjs");
+        const { recall: recall2 } = await import("./recall-XEOLXA6P.mjs");
         const result = await recall2(
           query,
           { vaultCtx, embeddingOptions, vaultCache: cache },

package/dist/server/{chunk-AHJT66EO.mjs → chunk-MIXEASUP.mjs}

@@ -14,6 +14,24 @@ function getLogger() {
   return currentLogger;
 }
 
+// src/lib/chat/endpointOverride.ts
+function validateEndpointOverride(override) {
+  const trimmed = override.trim();
+  if (trimmed === "") {
+    return {
+      valid: false,
+      message: 'endpointOverride must be a non-empty, root-relative path (e.g. "/api/v1/utility/responses"); received an empty or whitespace-only string'
+    };
+  }
+  if (trimmed.startsWith("//") || trimmed.includes("://")) {
+    return {
+      valid: false,
+      message: `endpointOverride must be a root-relative path (e.g. "/api/v1/utility/responses"), not a protocol-relative or absolute URL; received "${trimmed}"`
+    };
+  }
+  return { valid: true, endpoint: trimmed.startsWith("/") ? trimmed : `/${trimmed}` };
+}
+
 // src/lib/memory/portalLlm.ts
 function defaultBaseUrl() {
   return typeof process !== "undefined" && process.env?.ANUMA_PORTAL_BASE_URL || BASE_URL;
@@ -65,6 +83,14 @@ async function resolvePortalAuthHeaders(auth, tag) {
 }
 async function callPortalJsonCompletion(req) {
   const log = getLogger();
+  let endpoint = "/api/v1/chat/completions";
+  if (req.endpointOverride !== void 0) {
+    const overrideValidation = validateEndpointOverride(req.endpointOverride);
+    if (!overrideValidation.valid) {
+      throw new Error(overrideValidation.message);
+    }
+    endpoint = overrideValidation.endpoint;
+  }
   const maxAttempts = Math.max(1, req.maxAttempts ?? 3);
   const startedAt = Date.now();
   const overBudget = () => req.totalTimeoutMs !== void 0 && Date.now() - startedAt >= req.totalTimeoutMs;
@@ -80,7 +106,7 @@ async function callPortalJsonCompletion(req) {
         Math.min(req.timeoutMs ?? 6e4, req.totalTimeoutMs - (Date.now() - startedAt))
       )
     } : req;
-    const outcome = await attemptPortalJson(attemptReq);
+    const outcome = await attemptPortalJson(attemptReq, endpoint);
     if (outcome.kind === "ok") return outcome.value;
     if (outcome.kind === "terminal") {
       log.warn(`[${req.tag}] ${outcome.reason}`);
@@ -103,7 +129,7 @@ async function callPortalJsonCompletion(req) {
   }
   return null;
 }
-async function attemptPortalJson(req) {
+async function attemptPortalJson(req, endpoint) {
   const baseUrl = req.baseUrl ?? defaultBaseUrl();
   const fetchImpl = req.fetchFn ?? fetch;
   const timeoutMs = req.timeoutMs ?? 6e4;
@@ -128,7 +154,7 @@ async function attemptPortalJson(req) {
   if (!supportsJsonObjectFormat) delete requestBody.response_format;
   let response;
   try {
-    response = await fetchImpl(`${baseUrl}/api/v1/chat/completions`, {
+    response = await fetchImpl(`${baseUrl}${endpoint}`, {
       method: "POST",
       headers: { ...authHeaders, "Content-Type": "application/json" },
       body: JSON.stringify(requestBody),
@@ -223,6 +249,7 @@ function extractCompletionContent(body) {
 
 export {
   getLogger,
+  validateEndpointOverride,
   supportsResponseFormat,
   resolvePortalAuthHeaders,
   callPortalJsonCompletion,

package/dist/server/{consolidate-CN2GQV4D.mjs → consolidate-BKLNVH5Y.mjs}

@@ -4,7 +4,7 @@ import {
 import {
   callPortalJsonCompletion,
   getLogger
-} from "./chunk-AHJT66EO.mjs";
+} from "./chunk-MIXEASUP.mjs";
 import "./chunk-3RPGXXPZ.mjs";
 
 // src/lib/memory/consolidate.ts
@@ -19,7 +19,7 @@ Decide one of four actions:
 
 - "create": the new memory describes a distinct fact not covered by any existing memory. Write it as new.
 - "update": the new memory describes the SAME FACET as exactly one existing memory and is COMPATIBLE with it \u2014 it adds detail, fixes an incomplete value, or rephrases the same still-true fact. Return targetId of that existing memory + the consolidated content (richest version of the two).
-- "supersede": the new memory REPLACES a standing fact whose value has CHANGED and is now INCOMPATIBLE with an existing memory \u2014 the old fact was true before but is false now (a state change). Return targetId of the STALE existing memory to retire + content = the NEW fact. The old memory is kept as history, not overwritten or deleted; do not re-state it.
+- "supersede": the new memory REPLACES a standing fact whose value has CHANGED and is now INCOMPATIBLE with an existing memory \u2014 the old fact was true before but is false now (a state change). Return "targetIds": an array of the ids of EVERY existing candidate that describes the SAME standing attribute now being changed \u2014 retire ALL stale duplicates of the old value, not just one (the candidate list may contain several paraphrases of the same old fact) + content = the NEW fact. The old memories are kept as history, not overwritten or deleted; do not re-state them.
 - "noop": the new memory is already fully captured by an existing memory \u2014 same facet, no new information. Skip the write.
 
 RULES (carry these strictly):
@@ -35,14 +35,15 @@ RULES (carry these strictly):
 OUTPUT \u2014 strict JSON, no prose:
 {
   "action": "create" | "update" | "supersede" | "noop",
-  "targetId": "<existing memory id \u2014 required for update/supersede/noop, omit for create>",
+  "targetId": "<existing memory id \u2014 required for update/noop, omit for create/supersede>",
+  "targetIds": ["<id>", ...],
   "content": "<content \u2014 required for create/update/supersede, omit for noop>"
 }
 
-For "create": content is the new memory verbatim (or a slight refinement).
-For "update": content is the merged richest-version, \u226480 words.
-For "supersede": content is the NEW fact only (\u226480 words); targetId is the stale memory being retired.
-For "noop": no content (existing memory is already correct).`;
+For "create": content is the new memory verbatim (or a slight refinement); omit targetId/targetIds.
+For "update": content is the merged richest-version, \u226480 words; targetId is the single memory to update.
+For "supersede": content is the NEW fact only (\u226480 words); "targetIds" lists EVERY stale memory being retired (all candidates describing the same now-changed attribute).
+For "noop": no content (existing memory is already correct); targetId is that memory.`;
 async function consolidateMemory(newContent, candidates, options) {
   const fallback = {
     action: "create",
@@ -123,14 +124,27 @@ function validate(parsed, newContent, validIds) {
     const c2 = typeof obj.content === "string" ? obj.content.trim() : "";
     return { action: "create", content: c2.length > 0 ? c2 : newContent };
   }
-  const targetId = typeof obj.targetId === "string" ? obj.targetId : null;
-  if (!targetId || !validIds.has(targetId)) return null;
   if (action === "noop") {
-    return { action: "noop", targetId };
+    const targetId2 = typeof obj.targetId === "string" ? obj.targetId : null;
+    if (!targetId2 || !validIds.has(targetId2)) return null;
+    return { action: "noop", targetId: targetId2 };
   }
   const c = typeof obj.content === "string" ? obj.content.trim() : "";
   if (c.length === 0) return null;
-  return { action, targetId, content: c };
+  if (action === "supersede") {
+    const rawIds = [
+      ...Array.isArray(obj.targetIds) ? obj.targetIds : [],
+      ...typeof obj.targetId === "string" ? [obj.targetId] : []
+    ];
+    const targetIds = [
+      ...new Set(rawIds.filter((id) => typeof id === "string" && validIds.has(id)))
+    ];
+    if (targetIds.length === 0) return null;
+    return { action: "supersede", targetId: targetIds[0], targetIds, content: c };
+  }
+  const targetId = typeof obj.targetId === "string" ? obj.targetId : null;
+  if (!targetId || !validIds.has(targetId)) return null;
+  return { action: "update", targetId, content: c };
 }
 export {
   consolidateMemory

package/dist/server/index.cjs

@@ -19549,6 +19549,29 @@ var init_bm25 = __esm({
   }
 });
 
+// src/lib/chat/endpointOverride.ts
+function validateEndpointOverride(override) {
+  const trimmed = override.trim();
+  if (trimmed === "") {
+    return {
+      valid: false,
+      message: 'endpointOverride must be a non-empty, root-relative path (e.g. "/api/v1/utility/responses"); received an empty or whitespace-only string'
+    };
+  }
+  if (trimmed.startsWith("//") || trimmed.includes("://")) {
+    return {
+      valid: false,
+      message: `endpointOverride must be a root-relative path (e.g. "/api/v1/utility/responses"), not a protocol-relative or absolute URL; received "${trimmed}"`
+    };
+  }
+  return { valid: true, endpoint: trimmed.startsWith("/") ? trimmed : `/${trimmed}` };
+}
+var init_endpointOverride = __esm({
+  "src/lib/chat/endpointOverride.ts"() {
+    "use strict";
+  }
+});
+
 // src/lib/memory/portalLlm.ts
 function defaultBaseUrl() {
   return typeof process !== "undefined" && process.env?.ANUMA_PORTAL_BASE_URL || BASE_URL;
@@ -19597,6 +19620,14 @@ async function resolvePortalAuthHeaders(auth, tag) {
 }
 async function callPortalJsonCompletion(req) {
   const log = getLogger();
+  let endpoint = "/api/v1/chat/completions";
+  if (req.endpointOverride !== void 0) {
+    const overrideValidation = validateEndpointOverride(req.endpointOverride);
+    if (!overrideValidation.valid) {
+      throw new Error(overrideValidation.message);
+    }
+    endpoint = overrideValidation.endpoint;
+  }
   const maxAttempts = Math.max(1, req.maxAttempts ?? 3);
   const startedAt = Date.now();
   const overBudget = () => req.totalTimeoutMs !== void 0 && Date.now() - startedAt >= req.totalTimeoutMs;
@@ -19612,7 +19643,7 @@ async function callPortalJsonCompletion(req) {
         Math.min(req.timeoutMs ?? 6e4, req.totalTimeoutMs - (Date.now() - startedAt))
       )
     } : req;
-    const outcome = await attemptPortalJson(attemptReq);
+    const outcome = await attemptPortalJson(attemptReq, endpoint);
     if (outcome.kind === "ok") return outcome.value;
     if (outcome.kind === "terminal") {
       log.warn(`[${req.tag}] ${outcome.reason}`);
@@ -19635,7 +19666,7 @@ async function callPortalJsonCompletion(req) {
   }
   return null;
 }
-async function attemptPortalJson(req) {
+async function attemptPortalJson(req, endpoint) {
   const baseUrl = req.baseUrl ?? defaultBaseUrl();
   const fetchImpl = req.fetchFn ?? fetch;
   const timeoutMs = req.timeoutMs ?? 6e4;
@@ -19660,7 +19691,7 @@ async function attemptPortalJson(req) {
   if (!supportsJsonObjectFormat) delete requestBody.response_format;
   let response;
   try {
-    response = await fetchImpl(`${baseUrl}/api/v1/chat/completions`, {
+    response = await fetchImpl(`${baseUrl}${endpoint}`, {
       method: "POST",
       headers: { ...authHeaders, "Content-Type": "application/json" },
       body: JSON.stringify(requestBody),
@@ -19757,6 +19788,7 @@ var init_portalLlm = __esm({
   "src/lib/memory/portalLlm.ts"() {
     "use strict";
     init_clientConfig();
+    init_endpointOverride();
     init_logger();
     RESPONSE_FORMAT_OK = /* @__PURE__ */ new Set(["openai", "inclusionai", "deepseek"]);
     RESPONSE_SCHEMA_OK = /* @__PURE__ */ new Set(["openai"]);
@@ -22426,14 +22458,27 @@ function validate2(parsed, newContent, validIds) {
     const c2 = typeof obj.content === "string" ? obj.content.trim() : "";
     return { action: "create", content: c2.length > 0 ? c2 : newContent };
   }
-  const targetId = typeof obj.targetId === "string" ? obj.targetId : null;
-  if (!targetId || !validIds.has(targetId)) return null;
   if (action === "noop") {
-    return { action: "noop", targetId };
+    const targetId2 = typeof obj.targetId === "string" ? obj.targetId : null;
+    if (!targetId2 || !validIds.has(targetId2)) return null;
+    return { action: "noop", targetId: targetId2 };
   }
   const c = typeof obj.content === "string" ? obj.content.trim() : "";
   if (c.length === 0) return null;
-  return { action, targetId, content: c };
+  if (action === "supersede") {
+    const rawIds = [
+      ...Array.isArray(obj.targetIds) ? obj.targetIds : [],
+      ...typeof obj.targetId === "string" ? [obj.targetId] : []
+    ];
+    const targetIds = [
+      ...new Set(rawIds.filter((id) => typeof id === "string" && validIds.has(id)))
+    ];
+    if (targetIds.length === 0) return null;
+    return { action: "supersede", targetId: targetIds[0], targetIds, content: c };
+  }
+  const targetId = typeof obj.targetId === "string" ? obj.targetId : null;
+  if (!targetId || !validIds.has(targetId)) return null;
+  return { action: "update", targetId, content: c };
 }
 var DEFAULT_MODEL3, DEFAULT_CONSOLIDATE_ATTEMPTS, DEFAULT_CONSOLIDATE_TOTAL_TIMEOUT_MS, SYSTEM_PROMPT3;
 var init_consolidate = __esm({
@@ -22453,7 +22498,7 @@ Decide one of four actions:
 
 - "create": the new memory describes a distinct fact not covered by any existing memory. Write it as new.
 - "update": the new memory describes the SAME FACET as exactly one existing memory and is COMPATIBLE with it \u2014 it adds detail, fixes an incomplete value, or rephrases the same still-true fact. Return targetId of that existing memory + the consolidated content (richest version of the two).
-- "supersede": the new memory REPLACES a standing fact whose value has CHANGED and is now INCOMPATIBLE with an existing memory \u2014 the old fact was true before but is false now (a state change). Return targetId of the STALE existing memory to retire + content = the NEW fact. The old memory is kept as history, not overwritten or deleted; do not re-state it.
+- "supersede": the new memory REPLACES a standing fact whose value has CHANGED and is now INCOMPATIBLE with an existing memory \u2014 the old fact was true before but is false now (a state change). Return "targetIds": an array of the ids of EVERY existing candidate that describes the SAME standing attribute now being changed \u2014 retire ALL stale duplicates of the old value, not just one (the candidate list may contain several paraphrases of the same old fact) + content = the NEW fact. The old memories are kept as history, not overwritten or deleted; do not re-state them.
 - "noop": the new memory is already fully captured by an existing memory \u2014 same facet, no new information. Skip the write.
 
 RULES (carry these strictly):
@@ -22469,14 +22514,15 @@ RULES (carry these strictly):
 OUTPUT \u2014 strict JSON, no prose:
 {
   "action": "create" | "update" | "supersede" | "noop",
-  "targetId": "<existing memory id \u2014 required for update/supersede/noop, omit for create>",
+  "targetId": "<existing memory id \u2014 required for update/noop, omit for create/supersede>",
+  "targetIds": ["<id>", ...],
   "content": "<content \u2014 required for create/update/supersede, omit for noop>"
 }
 
-For "create": content is the new memory verbatim (or a slight refinement).
-For "update": content is the merged richest-version, \u226480 words.
-For "supersede": content is the NEW fact only (\u226480 words); targetId is the stale memory being retired.
-For "noop": no content (existing memory is already correct).`;
+For "create": content is the new memory verbatim (or a slight refinement); omit targetId/targetIds.
+For "update": content is the merged richest-version, \u226480 words; targetId is the single memory to update.
+For "supersede": content is the NEW fact only (\u226480 words); "targetIds" lists EVERY stale memory being retired (all candidates describing the same now-changed attribute).
+For "noop": no content (existing memory is already correct); targetId is that memory.`;
   }
 });
 
@@ -27125,14 +27171,15 @@ init_portalLlm();
 
 // src/lib/memory/retain.ts
 init_operations3();
+init_logger();
 init_constants();
 init_embeddings();
 init_vector();
 init_searchTool();
-var DEFAULT_AUTO_MERGE_THRESHOLD = 0.85;
+var DEFAULT_AUTO_MERGE_THRESHOLD = 0.8;
 var DEFAULT_SCOPE = "private";
-var DEFAULT_CONSOLIDATE_THRESHOLD = 0.65;
-var DEFAULT_CONSOLIDATE_TOP_K = 5;
+var DEFAULT_CONSOLIDATE_THRESHOLD = 0.55;
+var DEFAULT_CONSOLIDATE_TOP_K = 20;
 async function retain(content, ctx, options = {}) {
   const trimmed = content.trim();
   if (trimmed.length === 0) {
@@ -27141,18 +27188,18 @@ async function retain(content, ctx, options = {}) {
   const enableAutoMerge = options.enableAutoMerge ?? true;
   const threshold = options.autoMergeThreshold ?? DEFAULT_AUTO_MERGE_THRESHOLD;
   const resolvedScope = options.scope ?? DEFAULT_SCOPE;
-  let supersedeTargetId;
+  let supersedeTargetIds = [];
   let supersedeContent;
   if (enableAutoMerge) {
     if (options.consolidateOptions) {
       const outcome = await tryConsolidate(trimmed, ctx, options);
       if (outcome) {
         if ("done" in outcome) return outcome.done;
-        supersedeTargetId = outcome.supersede;
+        supersedeTargetIds = outcome.supersede;
         supersedeContent = outcome.content;
       }
     }
-    if (!supersedeTargetId) {
+    if (supersedeTargetIds.length === 0) {
       const matches = await searchVaultMemories(
         trimmed,
         ctx.vaultCtx,
@@ -27256,18 +27303,42 @@ async function retain(content, ctx, options = {}) {
     // memory's tier. The DB op re-validates against the known set.
     ...options.trustTier !== void 0 && { trustTier: options.trustTier }
   };
-  if (supersedeTargetId) {
+  if (supersedeTargetIds.length > 0) {
+    const [primaryTargetId, ...restTargetIds] = supersedeTargetIds;
     const { created: created2, retired } = await createSupersedingMemoryOp(
       ctx.vaultCtx,
       createOpts,
-      supersedeTargetId
+      primaryTargetId
     );
     if (created2 && retired) {
       ctx.vaultCache.set(created2.uniqueId, Float32Array.from(embedding));
+      const liveLeftovers = [];
+      for (const staleId of restTargetIds) {
+        let ok = false;
+        try {
+          ok = await supersedeVaultMemoryOp(ctx.vaultCtx, staleId, created2.uniqueId) === true;
+        } catch {
+        }
+        if (ok) continue;
+        const stillLive = await getVaultMemoryOp(ctx.vaultCtx, staleId).catch(() => null);
+        if (stillLive && !stillLive.supersededBy) liveLeftovers.push(staleId);
+      }
+      if (liveLeftovers.length > 0) {
+        getLogger().warn(
+          "[memory/retain] supersede left duplicate row(s) live \u2014 will reconcile at next consolidation",
+          {
+            newMemoryId: created2.uniqueId,
+            leftover: liveLeftovers.length,
+            // Log the specific ids (opaque record ids, not content) so an
+            // operator can identify exactly which rows are still active.
+            leftoverIds: liveLeftovers
+          }
+        );
+      }
       return {
         action: "supersede",
         memoryId: created2.uniqueId,
-        targetId: supersedeTargetId,
+        targetId: primaryTargetId,
         proofCount: 1
       };
     }
@@ -27353,10 +27424,16 @@ async function tryConsolidate(trimmed, ctx, options) {
   const { consolidateMemory: doConsolidate } = await Promise.resolve().then(() => (init_consolidate(), consolidate_exports));
   const decision = await doConsolidate(trimmed, candidates, consolidateOptions);
   if (decision.action === "create") return null;
-  if (decision.action === "supersede" && decision.targetId && decision.content) {
-    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
-    if (!existing || existing.supersededBy) return null;
-    return { supersede: decision.targetId, content: decision.content };
+  if (decision.action === "supersede" && decision.content) {
+    const requestedIds = decision.targetIds?.length ? decision.targetIds : decision.targetId ? [decision.targetId] : [];
+    if (requestedIds.length === 0) return null;
+    const valid = [];
+    for (const id of requestedIds) {
+      const existing = await getVaultMemoryOp(ctx.vaultCtx, id);
+      if (existing && !existing.supersededBy) valid.push(id);
+    }
+    if (valid.length === 0) return null;
+    return { supersede: valid, content: decision.content };
   }
   if (decision.action === "noop" && decision.targetId) {
     const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
@@ -29132,6 +29209,9 @@ When a memory refers to one of these, reuse the EXACT existing name (same spelli
       ...options.apiKey !== void 0 && { apiKey: options.apiKey },
       ...options.getToken !== void 0 && { getToken: options.getToken },
       ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+      ...options.endpointOverride !== void 0 && {
+        endpointOverride: options.endpointOverride
+      },
       model: options.model ?? DEFAULT_EXTRACTION_MODEL,
       systemPrompt: SYSTEM_PROMPT6,
       userMessage: `${vocabularyNote}Memories:
@@ -31283,6 +31363,7 @@ init_serverSentEvents_gen();
 init_clientConfig();
 init_embeddings();
 init_redactor();
+init_endpointOverride();
 
 // src/lib/chat/runHooks.ts
 function composeHooks(hooks) {
@@ -33433,22 +33514,6 @@ function linkAbortSignals(a, b) {
     }
   };
 }
-function validateEndpointOverride(override) {
-  const trimmed = override.trim();
-  if (trimmed === "") {
-    return {
-      valid: false,
-      message: 'endpointOverride must be a non-empty, root-relative path (e.g. "/api/v1/utility/responses"); received an empty or whitespace-only string'
-    };
-  }
-  if (trimmed.startsWith("//") || trimmed.includes("://")) {
-    return {
-      valid: false,
-      message: `endpointOverride must be a root-relative path (e.g. "/api/v1/utility/responses"), not a protocol-relative or absolute URL; received "${trimmed}"`
-    };
-  }
-  return { valid: true, endpoint: trimmed.startsWith("/") ? trimmed : `/${trimmed}` };
-}
 async function runToolLoop(options) {
   const {
     model,

package/dist/server/index.d.mts

@@ -2516,6 +2516,33 @@ type StreamingTransportResult = {
  * transport both honor this contract.
  */
 type StreamingTransport = (options: StreamingTransportOptions) => StreamingTransportResult;
+/**
+ * Framework-agnostic tool execution loop.
+ *
+ * Sends a streaming completion request, auto-executes tools that have executors,
+ * feeds results back to the model, and repeats until the model stops emitting
+ * tool calls or hits the iteration limit.
+ *
+ * This is the same loop that powers `useChat` in the React SDK, extracted so
+ * it can be used from Node.js servers, CLI tools, and background workers.
+ *
+ * @example
+ * ```ts
+ * import { runToolLoop } from "@anuma/sdk/server";
+ *
+ * const result = await runToolLoop({
+ *   messages: [{ role: "user", content: [{ type: "text", text: "What's the weather?" }] }],
+ *   model: "fireworks/accounts/fireworks/models/kimi-k2p5",
+ *   token: "my-api-token",
+ *   tools: [{
+ *     type: "function",
+ *     function: { name: "get_weather", parameters: { type: "object", properties: { city: { type: "string" } } } },
+ *     executor: async ({ city }) => fetchWeather(city),
+ *   }],
+ *   onData: (chunk) => process.stdout.write(chunk),
+ * });
+ * ```
+ */
 declare function runToolLoop(options: RunToolLoopOptions): Promise<RunToolLoopResult>;
 
 /**
@@ -8146,6 +8173,15 @@ interface TopicExtractionInput {
  */
 interface TopicExtractOptions extends PortalLlmAuth {
     baseUrl?: string;
+    /**
+     * Optional per-call request path override, forwarded to
+     * {@link callPortalJsonCompletion}. When set, topic extraction POSTs to
+     * `baseUrl + endpointOverride` instead of the default
+     * `/api/v1/chat/completions` — path only, body unchanged. Lets callers route
+     * this internal-utility pass to a dedicated endpoint. Invalid values throw at
+     * call time (see {@link validateEndpointOverride}).
+     */
+    endpointOverride?: string;
     /** Defaults to {@link DEFAULT_EXTRACTION_MODEL} — the sanctioned extraction
      * model. Don't point this at a second model without an eval. */
     model?: string;

package/dist/server/index.d.ts

@@ -2516,6 +2516,33 @@ type StreamingTransportResult = {
  * transport both honor this contract.
  */
 type StreamingTransport = (options: StreamingTransportOptions) => StreamingTransportResult;
+/**
+ * Framework-agnostic tool execution loop.
+ *
+ * Sends a streaming completion request, auto-executes tools that have executors,
+ * feeds results back to the model, and repeats until the model stops emitting
+ * tool calls or hits the iteration limit.
+ *
+ * This is the same loop that powers `useChat` in the React SDK, extracted so
+ * it can be used from Node.js servers, CLI tools, and background workers.
+ *
+ * @example
+ * ```ts
+ * import { runToolLoop } from "@anuma/sdk/server";
+ *
+ * const result = await runToolLoop({
+ *   messages: [{ role: "user", content: [{ type: "text", text: "What's the weather?" }] }],
+ *   model: "fireworks/accounts/fireworks/models/kimi-k2p5",
+ *   token: "my-api-token",
+ *   tools: [{
+ *     type: "function",
+ *     function: { name: "get_weather", parameters: { type: "object", properties: { city: { type: "string" } } } },
+ *     executor: async ({ city }) => fetchWeather(city),
+ *   }],
+ *   onData: (chunk) => process.stdout.write(chunk),
+ * });
+ * ```
+ */
 declare function runToolLoop(options: RunToolLoopOptions): Promise<RunToolLoopResult>;
 
 /**
@@ -8146,6 +8173,15 @@ interface TopicExtractionInput {
  */
 interface TopicExtractOptions extends PortalLlmAuth {
     baseUrl?: string;
+    /**
+     * Optional per-call request path override, forwarded to
+     * {@link callPortalJsonCompletion}. When set, topic extraction POSTs to
+     * `baseUrl + endpointOverride` instead of the default
+     * `/api/v1/chat/completions` — path only, body unchanged. Lets callers route
+     * this internal-utility pass to a dedicated endpoint. Invalid values throw at
+     * call time (see {@link validateEndpointOverride}).
+     */
+    endpointOverride?: string;
     /** Defaults to {@link DEFAULT_EXTRACTION_MODEL} — the sanctioned extraction
      * model. Don't point this at a second model without an eval. */
     model?: string;