@anuma/sdk 6.17.2 → 6.19.0

package/dist/server/index.d.mts

@@ -4766,7 +4766,7 @@ interface EntityOperationsContext {
  *
  * @public
  */
-type TaskType = "title" | "commit_message" | "memory_extract" | "memory_dedup" | "memory_decay" | "memory_injection_check" | "memory_verify_support" | "memory_autosort" | "memory_topic" | "memory_consolidate" | "memory_decompose" | "memory_profile_synth" | "memory_graph" | "folder_context" | "selection_memory" | "summarize" | "style_analysis" | "classify_search" | "app_inspiration_generate" | "app_inspiration_trends" | "app_inspiration_remix" | "spotlight_image" | "slide_image" | "slide_video" | "slide_music" | "slide_sfx" | "media_video" | "media_audio" | "media_bg_removal" | "media_image_preset" | "tool_app_builder" | "tool_document_builder" | "tool_slides" | "tool_slides_image_gen" | "connector_guidance" | "cf_task" | "xbot_intent" | "xbot_council" | "scheduled_task";
+type TaskType = "title" | "commit_message" | "memory_extract" | "memory_import_extract" | "memory_dedup" | "memory_decay" | "memory_injection_check" | "memory_verify_support" | "memory_autosort" | "memory_topic" | "memory_consolidate" | "memory_decompose" | "memory_profile_synth" | "memory_graph" | "folder_context" | "selection_memory" | "summarize" | "style_analysis" | "classify_search" | "app_inspiration_generate" | "app_inspiration_trends" | "app_inspiration_remix" | "spotlight_image" | "slide_image" | "slide_video" | "slide_music" | "slide_sfx" | "media_video" | "media_audio" | "media_bg_removal" | "media_image_preset" | "tool_app_builder" | "tool_document_builder" | "tool_slides" | "tool_slides_image_gen" | "connector_guidance" | "cf_task" | "xbot_intent" | "xbot_council" | "scheduled_task";
 
 /**
  * Shared portal LLM call for the memory pipeline.
@@ -4863,6 +4863,26 @@ type PortalLlmFailureReason =
  | "null-completion"
 /** `totalTimeoutMs` was spent before the next attempt could run. */
  | "time-budget-exhausted";
+/**
+ * One attempt of a {@link callPortalJsonCompletion} call, reported to
+ * `onAttempt` as it settles — success included. The wire-level diagnostic the
+ * give-up hook cannot provide: a call that succeeds on its third try returns a
+ * value and fires no `onFailure`, yet it cost three completions and its first
+ * two answers were unusable. Extraction quality regressions have hidden in
+ * exactly that shape (a prompt change that made the model answer `NONE` first,
+ * JSON on retry), so the extraction eval gates on the first-attempt clean rate.
+ *
+ * @public
+ */
+interface PortalLlmAttempt {
+    /** 1-based attempt index. */
+    attempt: number;
+    /** Whether this attempt produced a parseable JSON value. */
+    ok: boolean;
+    /** Classification when `ok` is false. */
+    reason?: PortalLlmFailureReason;
+    httpStatus?: number;
+}
 /**
  * A give-up report: the classified {@link PortalLlmFailureReason} plus the
  * little context worth carrying into telemetry. Both extra fields are bounded
@@ -6133,6 +6153,12 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * (i.e. redaction silently eating facts) is alarmable.
      */
     onCandidatesDropped?: () => void;
+    /**
+     * Per-attempt wire diagnostic, forwarded to {@link callPortalJsonCompletion}.
+     * The extraction eval gates on it (first-attempt clean rate); production
+     * callers may leave it unset.
+     */
+    onAttempt?: (attempt: PortalLlmAttempt) => void;
 }
 /**
  * Stage 1 — call the LLM to extract candidate facts from the recent
@@ -7792,6 +7818,41 @@ declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, em
  * Each operation can be intercepted by the host app for confirmation/cancellation.
  */
 
+/**
+ * The 7 FactTypes a manual save may self-classify into (PR5). Mirrors the
+ * extractor's `FactType` union in `memory/autoExtract` — kept as a local const
+ * (not imported) to avoid a memoryVault → memory runtime import cycle. Only used
+ * to validate the optional `type` tool argument; an unrecognized value is
+ * dropped (persisted as null, the untyped/medium-decay bucket).
+ */
+declare const MANUAL_FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+/** A FactType the save tool's optional `type` argument may carry. */
+type ManualFactType = (typeof MANUAL_FACT_TYPES)[number];
+/**
+ * What a {@link VaultMemoryWriter} reports back. The action set mirrors
+ * `RetainResult.action` in `memory/retain` — restated here rather than imported
+ * for the same reason MANUAL_FACT_TYPES is (memoryVault → memory import cycle).
+ */
+type VaultWriteAction = "create" | "merge" | "update" | "supersede" | "suppressed" | "skip";
+interface VaultWriteOutcome {
+    /** The memory the write landed on: the fresh row, or the existing one it merged into. */
+    memoryId: string;
+    action: VaultWriteAction;
+}
+/** A NEW memory the tool wants written — `id`-addressed updates never come here. */
+interface VaultWriteInput {
+    content: string;
+    scope: string;
+    folderId?: string;
+    factType?: ManualFactType;
+}
+/**
+ * The seam through which the tool writes NEW memories when the host supplies one.
+ * `useChatStorage` (react + expo) passes a `retain()`-backed writer so a
+ * model-initiated save gets the same cosine auto-merge the background extractor
+ * gets, instead of a bare insert that trusts the model to have de-duplicated.
+ */
+type VaultMemoryWriter = (input: VaultWriteInput) => Promise<VaultWriteOutcome>;
 /**
  * Describes a pending vault save operation for UI confirmation.
  */
@@ -7830,6 +7891,35 @@ interface MemoryVaultToolOptions {
      * When provided, the LLM can specify a folderName argument.
      */
     folderMap?: Map<string, string>;
+    /**
+     * Writer for NEW memories. When set, a save without an `id` goes through it
+     * instead of a bare `createVaultMemoryOp`, and the tool phrases its reply from
+     * the reported action (a merge reads as "already known", not "saved").
+     *
+     * The hooks supply a `retain()`-backed writer, which is what makes this tool
+     * stop being a dedup bypass: until then the only thing standing between the
+     * model and a duplicate row was the prompt asking it to pass an `id`. Omit it
+     * (as a bare `createMemoryVaultTool(vaultCtx, …)` caller must — retain needs
+     * embeddings) and the direct insert path is unchanged.
+     *
+     * Updates addressed by `id` never come here: the model has already named the
+     * row, so there is nothing to de-duplicate against.
+     */
+    write?: VaultMemoryWriter;
+    /**
+     * Fires after a NEW memory's write settles, with what was asked and what the
+     * writer did. The host's analytics hook: `onSave` runs BEFORE the write and so
+     * cannot tell a fresh create from a merge into an existing memory — and that
+     * split is the one number that says whether model-initiated saves duplicate
+     * the vault. Fires on both write paths (a `write` seam, or the direct insert
+     * when none is supplied — reported as `create`). Not called for
+     * `id`-addressed updates or cancelled saves. A throwing or rejecting listener
+     * is awaited and swallowed so it can never fail the tool call.
+     */
+    onWritten?: (event: {
+        input: VaultWriteInput;
+        outcome: VaultWriteOutcome;
+    }) => void | Promise<void>;
 }
 /**
  * Creates a memory vault tool for use with chat completions.

package/dist/server/index.d.ts

@@ -4766,7 +4766,7 @@ interface EntityOperationsContext {
  *
  * @public
  */
-type TaskType = "title" | "commit_message" | "memory_extract" | "memory_dedup" | "memory_decay" | "memory_injection_check" | "memory_verify_support" | "memory_autosort" | "memory_topic" | "memory_consolidate" | "memory_decompose" | "memory_profile_synth" | "memory_graph" | "folder_context" | "selection_memory" | "summarize" | "style_analysis" | "classify_search" | "app_inspiration_generate" | "app_inspiration_trends" | "app_inspiration_remix" | "spotlight_image" | "slide_image" | "slide_video" | "slide_music" | "slide_sfx" | "media_video" | "media_audio" | "media_bg_removal" | "media_image_preset" | "tool_app_builder" | "tool_document_builder" | "tool_slides" | "tool_slides_image_gen" | "connector_guidance" | "cf_task" | "xbot_intent" | "xbot_council" | "scheduled_task";
+type TaskType = "title" | "commit_message" | "memory_extract" | "memory_import_extract" | "memory_dedup" | "memory_decay" | "memory_injection_check" | "memory_verify_support" | "memory_autosort" | "memory_topic" | "memory_consolidate" | "memory_decompose" | "memory_profile_synth" | "memory_graph" | "folder_context" | "selection_memory" | "summarize" | "style_analysis" | "classify_search" | "app_inspiration_generate" | "app_inspiration_trends" | "app_inspiration_remix" | "spotlight_image" | "slide_image" | "slide_video" | "slide_music" | "slide_sfx" | "media_video" | "media_audio" | "media_bg_removal" | "media_image_preset" | "tool_app_builder" | "tool_document_builder" | "tool_slides" | "tool_slides_image_gen" | "connector_guidance" | "cf_task" | "xbot_intent" | "xbot_council" | "scheduled_task";
 
 /**
  * Shared portal LLM call for the memory pipeline.
@@ -4863,6 +4863,26 @@ type PortalLlmFailureReason =
  | "null-completion"
 /** `totalTimeoutMs` was spent before the next attempt could run. */
  | "time-budget-exhausted";
+/**
+ * One attempt of a {@link callPortalJsonCompletion} call, reported to
+ * `onAttempt` as it settles — success included. The wire-level diagnostic the
+ * give-up hook cannot provide: a call that succeeds on its third try returns a
+ * value and fires no `onFailure`, yet it cost three completions and its first
+ * two answers were unusable. Extraction quality regressions have hidden in
+ * exactly that shape (a prompt change that made the model answer `NONE` first,
+ * JSON on retry), so the extraction eval gates on the first-attempt clean rate.
+ *
+ * @public
+ */
+interface PortalLlmAttempt {
+    /** 1-based attempt index. */
+    attempt: number;
+    /** Whether this attempt produced a parseable JSON value. */
+    ok: boolean;
+    /** Classification when `ok` is false. */
+    reason?: PortalLlmFailureReason;
+    httpStatus?: number;
+}
 /**
  * A give-up report: the classified {@link PortalLlmFailureReason} plus the
  * little context worth carrying into telemetry. Both extra fields are bounded
@@ -6133,6 +6153,12 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * (i.e. redaction silently eating facts) is alarmable.
      */
     onCandidatesDropped?: () => void;
+    /**
+     * Per-attempt wire diagnostic, forwarded to {@link callPortalJsonCompletion}.
+     * The extraction eval gates on it (first-attempt clean rate); production
+     * callers may leave it unset.
+     */
+    onAttempt?: (attempt: PortalLlmAttempt) => void;
 }
 /**
  * Stage 1 — call the LLM to extract candidate facts from the recent
@@ -7792,6 +7818,41 @@ declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, em
  * Each operation can be intercepted by the host app for confirmation/cancellation.
  */
 
+/**
+ * The 7 FactTypes a manual save may self-classify into (PR5). Mirrors the
+ * extractor's `FactType` union in `memory/autoExtract` — kept as a local const
+ * (not imported) to avoid a memoryVault → memory runtime import cycle. Only used
+ * to validate the optional `type` tool argument; an unrecognized value is
+ * dropped (persisted as null, the untyped/medium-decay bucket).
+ */
+declare const MANUAL_FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+/** A FactType the save tool's optional `type` argument may carry. */
+type ManualFactType = (typeof MANUAL_FACT_TYPES)[number];
+/**
+ * What a {@link VaultMemoryWriter} reports back. The action set mirrors
+ * `RetainResult.action` in `memory/retain` — restated here rather than imported
+ * for the same reason MANUAL_FACT_TYPES is (memoryVault → memory import cycle).
+ */
+type VaultWriteAction = "create" | "merge" | "update" | "supersede" | "suppressed" | "skip";
+interface VaultWriteOutcome {
+    /** The memory the write landed on: the fresh row, or the existing one it merged into. */
+    memoryId: string;
+    action: VaultWriteAction;
+}
+/** A NEW memory the tool wants written — `id`-addressed updates never come here. */
+interface VaultWriteInput {
+    content: string;
+    scope: string;
+    folderId?: string;
+    factType?: ManualFactType;
+}
+/**
+ * The seam through which the tool writes NEW memories when the host supplies one.
+ * `useChatStorage` (react + expo) passes a `retain()`-backed writer so a
+ * model-initiated save gets the same cosine auto-merge the background extractor
+ * gets, instead of a bare insert that trusts the model to have de-duplicated.
+ */
+type VaultMemoryWriter = (input: VaultWriteInput) => Promise<VaultWriteOutcome>;
 /**
  * Describes a pending vault save operation for UI confirmation.
  */
@@ -7830,6 +7891,35 @@ interface MemoryVaultToolOptions {
      * When provided, the LLM can specify a folderName argument.
      */
     folderMap?: Map<string, string>;
+    /**
+     * Writer for NEW memories. When set, a save without an `id` goes through it
+     * instead of a bare `createVaultMemoryOp`, and the tool phrases its reply from
+     * the reported action (a merge reads as "already known", not "saved").
+     *
+     * The hooks supply a `retain()`-backed writer, which is what makes this tool
+     * stop being a dedup bypass: until then the only thing standing between the
+     * model and a duplicate row was the prompt asking it to pass an `id`. Omit it
+     * (as a bare `createMemoryVaultTool(vaultCtx, …)` caller must — retain needs
+     * embeddings) and the direct insert path is unchanged.
+     *
+     * Updates addressed by `id` never come here: the model has already named the
+     * row, so there is nothing to de-duplicate against.
+     */
+    write?: VaultMemoryWriter;
+    /**
+     * Fires after a NEW memory's write settles, with what was asked and what the
+     * writer did. The host's analytics hook: `onSave` runs BEFORE the write and so
+     * cannot tell a fresh create from a merge into an existing memory — and that
+     * split is the one number that says whether model-initiated saves duplicate
+     * the vault. Fires on both write paths (a `write` seam, or the direct insert
+     * when none is supplied — reported as `create`). Not called for
+     * `id`-addressed updates or cancelled saves. A throwing or rejecting listener
+     * is awaited and swallowed so it can never fail the tool call.
+     */
+    onWritten?: (event: {
+        input: VaultWriteInput;
+        outcome: VaultWriteOutcome;
+    }) => void | Promise<void>;
 }
 /**
  * Creates a memory vault tool for use with chat completions.

package/dist/server/index.mjs

@@ -141,12 +141,12 @@ import {
   updateVaultMemoryOp,
   upsertMessageOp,
   vaultMemoryToStored
-} from "./chunk-K7H7ICPK.mjs";
+} from "./chunk-2A6HXY4P.mjs";
 import {
   createStreamingDeAnonymizer,
   notifyConsolidationFallback,
   resolvePiiRedactor
-} from "./chunk-4LPSEROP.mjs";
+} from "./chunk-RKQ4MRS2.mjs";
 import {
   INTERNAL_FLOW_MARKER,
   callPortalJsonCompletion,
@@ -159,7 +159,7 @@ import {
   taskTypeHeader,
   validateEndpointOverride,
   withInternalFlowMarker
-} from "./chunk-BSCEZOIW.mjs";
+} from "./chunk-YXL5VKCO.mjs";
 import {
   BASE_URL,
   __commonJS,
@@ -4890,6 +4890,26 @@ var MANUAL_FACT_TYPES = [
 function normalizeManualFactType(value) {
   return typeof value === "string" && MANUAL_FACT_TYPES.includes(value) ? value : void 0;
 }
+async function notifyWritten(options, input, outcome) {
+  try {
+    await options?.onWritten?.({ input, outcome });
+  } catch {
+  }
+}
+function describeWriteOutcome(outcome) {
+  switch (outcome.action) {
+    case "create":
+      return `Memory saved successfully (ID: ${outcome.memoryId}).`;
+    case "update":
+    case "supersede":
+      return `Memory saved successfully (ID: ${outcome.memoryId}); it replaces an earlier version of this fact.`;
+    case "merge":
+    case "skip":
+      return `The vault already holds this fact (ID: ${outcome.memoryId}); it was noted as re-observed. Nothing new was created \u2014 do not save it again.`;
+    case "suppressed":
+      return "Not saved: this matches a memory the user previously deleted. Do not re-save it.";
+  }
+}
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
   const hasOnSave = !!options?.onSave;
   const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
@@ -4982,6 +5002,17 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
           return `Memory updated successfully (ID: ${updated.uniqueId}).`;
         } else {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
+          if (options?.write) {
+            const input = {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            };
+            const outcome = await options.write(input);
+            await notifyWritten(options, input, outcome);
+            return describeWriteOutcome(outcome);
+          }
           const created = await createVaultMemoryOp(vaultCtx, {
             content,
             scope,
@@ -5001,6 +5032,16 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               }
             );
           }
+          await notifyWritten(
+            options,
+            {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            },
+            { memoryId: created.uniqueId, action: "create" }
+          );
           return `Memory saved successfully (ID: ${created.uniqueId}).`;
         }
       } catch (error) {
@@ -5702,7 +5743,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     content: m.content,
     similarity: m.similarity
   }));
-  const { consolidateMemory: doConsolidate } = await import("./consolidate-MSAXASHL.mjs");
+  const { consolidateMemory: doConsolidate } = await import("./consolidate-54P6QZKU.mjs");
   const decision = await doConsolidate(trimmed, candidates, consolidateOptions);
   if (decision.action === "create") return null;
   if (decision.action === "supersede" && decision.content) {
@@ -5944,7 +5985,8 @@ Extract durable user facts.`,
     ...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 }
+    ...options.backoffMs && { backoffMs: options.backoffMs },
+    ...options.onAttempt && { onAttempt: options.onAttempt }
   });
   if (parsed === null) {
     options.onExhaustedEmpty?.(failure ?? { reason: "empty-content", attempts: 1 });

package/dist/server/{recall-YXJATOSD.mjs → recall-JPIWNKA7.mjs}

@@ -1,7 +1,7 @@
 import {
   recall
-} from "./chunk-K7H7ICPK.mjs";
-import "./chunk-BSCEZOIW.mjs";
+} from "./chunk-2A6HXY4P.mjs";
+import "./chunk-YXL5VKCO.mjs";
 import "./chunk-3RPGXXPZ.mjs";
 export {
   recall

package/package.json

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