@vellumai/assistant 0.4.49 → 0.4.51

package/src/memory/clarification-resolver.ts

@@ -1,417 +0,0 @@
-import {
-  createTimeout,
-  extractToolUse,
-  getConfiguredProvider,
-  userMessage,
-} from "../providers/provider-send-message.js";
-import type { ModelIntent } from "../providers/types.js";
-import { truncate } from "../util/truncate.js";
-
-const DEFAULT_RESOLVER_MODEL_INTENT: ModelIntent = "latency-optimized";
-const DEFAULT_RESOLVER_TIMEOUT_MS = 12_000;
-
-const DIRECTIONAL_EXISTING_CUES = [
-  "existing",
-  "old",
-  "previous",
-  "first",
-  "earlier",
-  "original",
-];
-const DIRECTIONAL_CANDIDATE_CUES = [
-  "candidate",
-  "new",
-  "latest",
-  "second",
-  "updated",
-  "instead",
-  "replace",
-];
-const MERGE_CUES = [
-  "both",
-  "merge",
-  "combine",
-  "together",
-  "depends",
-  "either",
-  "mix",
-];
-
-const STOP_WORDS = new Set([
-  "about",
-  "after",
-  "again",
-  "also",
-  "because",
-  "been",
-  "before",
-  "being",
-  "between",
-  "could",
-  "doing",
-  "from",
-  "have",
-  "into",
-  "just",
-  "more",
-  "most",
-  "only",
-  "over",
-  "same",
-  "should",
-  "some",
-  "than",
-  "that",
-  "their",
-  "there",
-  "these",
-  "they",
-  "this",
-  "those",
-  "were",
-  "what",
-  "when",
-  "where",
-  "which",
-  "while",
-  "with",
-  "would",
-  "your",
-]);
-
-export type ClarificationResolution =
-  | "keep_existing"
-  | "keep_candidate"
-  | "merge"
-  | "still_unclear";
-
-export type ClarificationStrategy =
-  | "heuristic"
-  | "llm"
-  | "llm_timeout"
-  | "llm_error"
-  | "no_llm_key";
-
-export interface ClarificationResolverInput {
-  existingStatement: string;
-  candidateStatement: string;
-  userMessage: string;
-}
-
-export interface ClarificationResolverOptions {
-  apiKey?: string;
-  model?: string;
-  modelIntent?: ModelIntent;
-  timeoutMs?: number;
-}
-
-export interface ClarificationResolverResult {
-  resolution: ClarificationResolution;
-  strategy: ClarificationStrategy;
-  resolvedStatement: string | null;
-  explanation: string;
-}
-
-export async function resolveConflictClarification(
-  input: ClarificationResolverInput,
-  options?: ClarificationResolverOptions,
-): Promise<ClarificationResolverResult> {
-  const heuristicResult = resolveWithHeuristics(input);
-  if (heuristicResult) return heuristicResult;
-
-  const provider = getConfiguredProvider();
-  if (!provider) {
-    return {
-      resolution: "still_unclear",
-      strategy: "no_llm_key",
-      resolvedStatement: null,
-      explanation:
-        "Configured provider unavailable for clarification fallback.",
-    };
-  }
-
-  try {
-    return await resolveWithLlm(input, {
-      model: options?.model,
-      modelIntent: options?.modelIntent ?? DEFAULT_RESOLVER_MODEL_INTENT,
-      timeoutMs: options?.timeoutMs ?? DEFAULT_RESOLVER_TIMEOUT_MS,
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (message === "clarification_resolver_timeout") {
-      return {
-        resolution: "still_unclear",
-        strategy: "llm_timeout",
-        resolvedStatement: null,
-        explanation: "Clarification resolver timed out.",
-      };
-    }
-    return {
-      resolution: "still_unclear",
-      strategy: "llm_error",
-      resolvedStatement: null,
-      explanation: `Clarification resolver failed: ${truncate(
-        message,
-        300,
-        "",
-      )}`,
-    };
-  }
-}
-
-function resolveWithHeuristics(
-  input: ClarificationResolverInput,
-): ClarificationResolverResult | null {
-  const normalizedMessage = normalize(input.userMessage);
-  if (!normalizedMessage) return null;
-
-  const lowerMessage = normalizedMessage.toLowerCase();
-
-  const hasExistingCue = containsAnyCue(
-    lowerMessage,
-    DIRECTIONAL_EXISTING_CUES,
-  );
-  const hasCandidateCue = containsAnyCue(
-    lowerMessage,
-    DIRECTIONAL_CANDIDATE_CUES,
-  );
-  const hasMergeCue = containsAnyCue(lowerMessage, MERGE_CUES);
-
-  // When multiple cue categories match, delegate to LLM to avoid misclassification
-  const matchCount = [hasExistingCue, hasCandidateCue, hasMergeCue].filter(
-    Boolean,
-  ).length;
-  if (matchCount > 1) return null;
-
-  if (hasMergeCue) {
-    return {
-      resolution: "merge",
-      strategy: "heuristic",
-      resolvedStatement: buildMergedStatement(input),
-      explanation: "User response includes merge cues.",
-    };
-  }
-
-  if (hasExistingCue) {
-    return {
-      resolution: "keep_existing",
-      strategy: "heuristic",
-      resolvedStatement: null,
-      explanation: "User response explicitly points to existing/old statement.",
-    };
-  }
-
-  if (hasCandidateCue) {
-    return {
-      resolution: "keep_candidate",
-      strategy: "heuristic",
-      resolvedStatement: null,
-      explanation:
-        "User response explicitly points to candidate/new statement.",
-    };
-  }
-
-  const messageTokens = tokenize(normalizedMessage);
-  const existingOverlap = overlapScore(
-    messageTokens,
-    tokenize(input.existingStatement),
-  );
-  const candidateOverlap = overlapScore(
-    messageTokens,
-    tokenize(input.candidateStatement),
-  );
-
-  if (existingOverlap >= 2 && existingOverlap >= candidateOverlap + 1) {
-    return {
-      resolution: "keep_existing",
-      strategy: "heuristic",
-      resolvedStatement: null,
-      explanation:
-        "User response overlaps more with existing statement details.",
-    };
-  }
-
-  if (candidateOverlap >= 2 && candidateOverlap >= existingOverlap + 1) {
-    return {
-      resolution: "keep_candidate",
-      strategy: "heuristic",
-      resolvedStatement: null,
-      explanation:
-        "User response overlaps more with candidate statement details.",
-    };
-  }
-
-  if (existingOverlap > 0 && candidateOverlap > 0) {
-    return {
-      resolution: "merge",
-      strategy: "heuristic",
-      resolvedStatement: buildMergedStatement(input),
-      explanation: "User response overlaps with both statements.",
-    };
-  }
-
-  return null;
-}
-
-async function resolveWithLlm(
-  input: ClarificationResolverInput,
-  options: { model?: string; modelIntent: ModelIntent; timeoutMs: number },
-): Promise<ClarificationResolverResult> {
-  const provider = getConfiguredProvider()!;
-  const userPrompt = [
-    "You are resolving a memory clarification response.",
-    "",
-    `Existing statement: ${input.existingStatement}`,
-    `Candidate statement: ${input.candidateStatement}`,
-    `User clarification: ${input.userMessage}`,
-  ].join("\n");
-
-  const { signal, cleanup } = createTimeout(options.timeoutMs);
-
-  try {
-    const response = await provider.sendMessage(
-      [userMessage(userPrompt)],
-      [
-        {
-          name: "resolve_conflict_clarification",
-          description:
-            "Resolve a pending memory contradiction using user clarification.",
-          input_schema: {
-            type: "object" as const,
-            properties: {
-              resolution: {
-                type: "string",
-                enum: [
-                  "keep_existing",
-                  "keep_candidate",
-                  "merge",
-                  "still_unclear",
-                ],
-              },
-              resolved_statement: {
-                type: "string",
-                description: "Required only when resolution is merge.",
-              },
-              explanation: {
-                type: "string",
-                description: "One short rationale for the classification.",
-              },
-            },
-            required: ["resolution", "explanation"],
-          },
-        },
-      ],
-      [
-        "Classify the user clarification for conflicting memory statements.",
-        "Return exactly one resolution:",
-        "- keep_existing",
-        "- keep_candidate",
-        "- merge",
-        "- still_unclear",
-      ].join("\n"),
-      {
-        config: {
-          ...(options.model
-            ? { model: options.model }
-            : { modelIntent: options.modelIntent }),
-          max_tokens: 256,
-          tool_choice: {
-            type: "tool" as const,
-            name: "resolve_conflict_clarification",
-          },
-        },
-        signal,
-      },
-    );
-    cleanup();
-
-    const toolBlock = extractToolUse(response);
-    if (!toolBlock) {
-      throw new Error("No tool_use block in clarification resolver response.");
-    }
-
-    const parsed = toolBlock.input as {
-      resolution?: string;
-      resolved_statement?: string;
-      explanation?: string;
-    };
-
-    if (!isResolution(parsed.resolution)) {
-      throw new Error(
-        `Invalid clarification resolution: ${String(parsed.resolution)}`,
-      );
-    }
-
-    const resolvedStatement =
-      parsed.resolution === "merge"
-        ? normalize(parsed.resolved_statement ?? buildMergedStatement(input)) ||
-          buildMergedStatement(input)
-        : null;
-
-    return {
-      resolution: parsed.resolution,
-      strategy: "llm",
-      resolvedStatement,
-      explanation: truncate(
-        normalize(parsed.explanation ?? "Resolved via LLM fallback."),
-        500,
-        "",
-      ),
-    };
-  } catch (err) {
-    cleanup();
-    if (signal.aborted) {
-      throw new Error("clarification_resolver_timeout");
-    }
-    throw err;
-  }
-}
-
-function isResolution(
-  value: string | undefined,
-): value is ClarificationResolution {
-  return (
-    value === "keep_existing" ||
-    value === "keep_candidate" ||
-    value === "merge" ||
-    value === "still_unclear"
-  );
-}
-
-function containsAnyCue(input: string, cues: readonly string[]): boolean {
-  return cues.some((cue) => new RegExp(`\\b${cue}\\b`).test(input));
-}
-
-function overlapScore(left: Set<string>, right: Set<string>): number {
-  let score = 0;
-  for (const token of left) {
-    if (right.has(token)) score += 1;
-  }
-  return score;
-}
-
-function tokenize(input: string): Set<string> {
-  const words = input
-    .toLowerCase()
-    .split(/[^a-z0-9]+/g)
-    .map((word) => word.trim())
-    .filter((word) => word.length >= 4 && !STOP_WORDS.has(word));
-  return new Set(words);
-}
-
-function normalize(input: string): string {
-  return input.replace(/\s+/g, " ").trim();
-}
-
-function buildMergedStatement(input: ClarificationResolverInput): string {
-  const normalizedUserMessage = normalize(input.userMessage);
-  if (
-    normalizedUserMessage.length >= 8 &&
-    normalizedUserMessage.length <= 320
-  ) {
-    return normalizedUserMessage;
-  }
-  const existing = truncate(normalize(input.existingStatement), 140, "");
-  const candidate = truncate(normalize(input.candidateStatement), 140, "");
-  return truncate(`Merged clarification: ${existing}; ${candidate}`, 320, "");
-}

package/src/memory/conflict-intent.ts

@@ -1,205 +0,0 @@
-/**
- * Shared conflict intent helpers used by both interactive conflict gating and
- * background conflict resolution jobs.
- */
-
-export interface ConflictStatementPair {
-  existingStatement: string;
-  candidateStatement: string;
-}
-
-export function computeConflictRelevance(
-  userMessage: string,
-  conflict: ConflictStatementPair,
-): number {
-  const queryTokens = tokenizeForConflictRelevance(userMessage);
-  if (queryTokens.size === 0) return 0;
-  const existingTokens = tokenizeForConflictRelevance(
-    conflict.existingStatement,
-  );
-  const candidateTokens = tokenizeForConflictRelevance(
-    conflict.candidateStatement,
-  );
-  return Math.max(
-    overlapRatio(queryTokens, existingTokens),
-    overlapRatio(queryTokens, candidateTokens),
-  );
-}
-
-const NOISE_TOKENS = new Set([
-  "http",
-  "https",
-  "github",
-  "gitlab",
-  "www",
-  "com",
-  "org",
-]);
-
-// Matches full URLs (http(s)://...) and scheme-less bare domain URLs for known
-// code hosting sites (e.g. github.com/org/repo/pull/123) so embedded path
-// segments like "pull", "issue", "ticket" don't leak into relevance scoring.
-// The scheme-less branch is restricted to known hosting domains to avoid
-// stripping dotted identifiers like "index.ts/runtime".
-const URL_PATTERN =
-  /https?:\/\/[^\s)>\]]+|(?:github|gitlab|bitbucket)\.(?:com|org|io)\/[^\s)>\]]*/gi;
-
-export function tokenizeForConflictRelevance(input: string): Set<string> {
-  const stripped = input.replace(URL_PATTERN, " ");
-  const tokens = stripped
-    .toLowerCase()
-    .split(/[^a-z0-9]+/g)
-    .map((token) => token.trim())
-    .filter((token) => token.length >= 4)
-    .filter((token) => !/^\d+$/.test(token))
-    .filter((token) => !NOISE_TOKENS.has(token));
-  return new Set(tokens);
-}
-
-export function overlapRatio(left: Set<string>, right: Set<string>): number {
-  if (left.size === 0 || right.size === 0) return 0;
-  let overlap = 0;
-  for (const token of left) {
-    if (right.has(token)) overlap += 1;
-  }
-  return overlap / Math.max(left.size, right.size);
-}
-
-/**
- * Tokenize for statement-to-statement coherence checking.
- * Uses a lower minimum token length (>= 3) than `tokenizeForConflictRelevance`
- * to preserve short technical terms like "vim", "css", "git", "npm", etc.
- */
-function tokenizeForCoherence(input: string): Set<string> {
-  const stripped = input.replace(URL_PATTERN, " ");
-  const tokens = stripped
-    .toLowerCase()
-    .split(/[^a-z0-9]+/g)
-    .map((token) => token.trim())
-    .filter((token) => token.length >= 3)
-    .filter((token) => !/^\d+$/.test(token))
-    .filter((token) => !NOISE_TOKENS.has(token));
-  return new Set(tokens);
-}
-
-/**
- * Check whether two conflict statements have topical coherence.
- * Returns true if the statements share at least one meaningful token.
- * Uses a permissive tokenizer (>= 3 chars) to avoid dropping short
- * technical terms like "vim", "css", "git", etc.
- */
-export function areStatementsCoherent(
-  statementA: string,
-  statementB: string,
-): boolean {
-  const tokensA = tokenizeForCoherence(statementA);
-  const tokensB = tokenizeForCoherence(statementB);
-  return overlapRatio(tokensA, tokensB) > 0;
-}
-
-// Action verbs that signal the user is making a deliberate choice.
-const ACTION_CUES = new Set([
-  "keep",
-  "use",
-  "prefer",
-  "go",
-  "pick",
-  "choose",
-  "take",
-  "want",
-  "select",
-]);
-
-// Directional/merge cue words mirrored from clarification-resolver.ts heuristics.
-const DIRECTIONAL_CUES = new Set([
-  "existing",
-  "old",
-  "previous",
-  "first",
-  "earlier",
-  "original",
-  "candidate",
-  "new",
-  "latest",
-  "second",
-  "updated",
-  "instead",
-  "replace",
-  "both",
-  "merge",
-  "combine",
-  "together",
-  "either",
-  "mix",
-  "option",
-  "former",
-  "latter",
-]);
-
-const MAX_REPLY_WORD_COUNT = 12;
-
-// Direction-only matches (no action verb) must be very short to avoid
-// false positives from unrelated statements that happen to contain
-// common words like "new", "old", "option", etc.
-const MAX_DIRECTION_ONLY_WORD_COUNT = 4;
-
-// Messages starting with a question word are unlikely to be clarification
-// replies even when they lack a trailing question mark.
-const QUESTION_WORD_PREFIXES = new Set([
-  "what",
-  "how",
-  "why",
-  "where",
-  "when",
-  "which",
-  "who",
-  "whom",
-  "whose",
-]);
-
-/**
- * Determines whether a user message looks like a deliberate clarification
- * reply (e.g. "keep the new one", "both", "option B").
- */
-export function looksLikeClarificationReply(userMessage: string): boolean {
-  const trimmed = userMessage.trim();
-  if (trimmed.endsWith("?")) return false;
-
-  const words = trimmed.toLowerCase().split(/\s+/).filter(Boolean);
-  if (words.length === 0 || words.length > MAX_REPLY_WORD_COUNT) return false;
-
-  const normalized = words.map((w) => w.replace(/[^a-z]/g, ""));
-
-  // Reject messages that start with a question word (even without '?').
-  // Match exact question words or contractions (e.g. "what's", "where's"),
-  // but not words that merely share a prefix (e.g. "whichever", "however").
-  const firstWord = words[0];
-  const firstNorm = normalized[0];
-  for (const qw of QUESTION_WORD_PREFIXES) {
-    if (
-      firstNorm === qw ||
-      (firstWord.startsWith(qw) &&
-        "'\u2018\u2019".includes(firstWord[qw.length]))
-    )
-      return false;
-  }
-
-  const hasAction = normalized.some((w) => ACTION_CUES.has(w));
-  const hasDirection = normalized.some((w) => DIRECTIONAL_CUES.has(w));
-
-  if (hasAction) return true;
-  if (hasDirection) return words.length <= MAX_DIRECTION_ONLY_WORD_COUNT;
-  return false;
-}
-
-/**
- * Conflict resolution requires explicit clarification intent with non-zero
- * topical overlap with the conflict statements.
- */
-export function shouldAttemptConflictResolution(input: {
-  clarificationReply: boolean;
-  relevance: number;
-}): boolean {
-  if (!input.clarificationReply) return false;
-  return input.relevance > 0;
-}