@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/plugins/defaults/memory/context-search/agent-runner.ts

@@ -4,8 +4,13 @@ import type {
   ProviderResponse,
   ToolUseContent,
 } from "@vellumai/plugin-api";
-import { getConfiguredProvider, safeStringSlice } from "@vellumai/plugin-api";
+import { getConfiguredProvider } from "@vellumai/plugin-api";
 
+import type {
+  RecallMetadata,
+  RecallSearchedSource,
+  RecallSource,
+} from "../../../../api/events/tool-result.js";
 import { redactSecrets } from "../../../../security/secret-scanner.js";
 import {
   buildRecallAgentPromptBundle,
@@ -15,6 +20,8 @@ import {
   validateFinishRecallPayload,
 } from "./agent-protocol.js";
 import {
+  buildRecallActivity,
+  compactText,
   formatDeterministicRecallAnswer,
   formatRecallFooter,
 } from "./format.js";
@@ -25,6 +32,7 @@ import {
   normalizeRecallMaxResults,
   normalizeRecallSources,
 } from "./limits.js";
+import type { RecallInput } from "./recall-input.js";
 import {
   type DeterministicRecallSearchOptions,
   type DeterministicRecallSearchResult,
@@ -39,9 +47,7 @@ import {
 import type {
   RecallAnswer,
   RecallEvidence,
-  RecallInput,
   RecallSearchContext,
-  RecallSource,
 } from "./types.js";
 
 type AgenticRecallFallbackReason =
@@ -90,6 +96,7 @@ interface AgenticRecallDebug {
 
 interface AgenticRecallAnswer extends RecallAnswer {
   content: string;
+  activity: RecallMetadata;
   debug: AgenticRecallDebug;
 }
 
@@ -266,6 +273,12 @@ export async function runAgenticRecall(
     options.searchOptions,
   );
   let evidence = [...seedResult.evidence];
+  // How each source fared across every search this recall runs, the latest
+  // search of a source standing: the seed alone would hide a follow-up that
+  // degraded, or keep a degradation a later search recovered from.
+  let searchedSources = seedResult.searchedSources;
+  const currentResult = (): DeterministicRecallSearchResult =>
+    withFallbackEvidence({ ...seedResult, searchedSources }, evidence);
   const autoInspect = await runAutomaticWorkspaceInspection(
     normalizedInput,
     context,
@@ -323,7 +336,7 @@ export async function runAgenticRecall(
         evidence,
         debug,
         normalizedInput,
-        withFallbackEvidence(seedResult, evidence),
+        currentResult(),
       );
       if (finishResult.ok) {
         return finishResult.answer;
@@ -380,6 +393,10 @@ export async function runAgenticRecall(
         );
         debug.searchCalls.push(searchResult.debug);
         evidence = mergeEvidence(evidence, searchResult.evidence);
+        searchedSources = mergeSearchedSources(
+          searchedSources,
+          searchResult.searchedSources,
+        );
       }
     }
 
@@ -396,7 +413,7 @@ export async function runAgenticRecall(
       evidence,
       debug,
       context,
-      searchResult: withFallbackEvidence(seedResult, evidence),
+      searchResult: currentResult(),
     });
     if (finalFinish.ok) {
       return finalFinish.answer;
@@ -406,7 +423,7 @@ export async function runAgenticRecall(
   }
 
   return deterministicFallback(
-    withFallbackEvidence(seedResult, evidence),
+    currentResult(),
     debug,
     fallbackReason,
     fallbackDetail,
@@ -480,6 +497,7 @@ async function runSeedRecallSearch(
   }
 
   let evidence = [...baseResult.evidence];
+  let searchedSources = baseResult.searchedSources;
   for (const query of expansionQueries) {
     const expansionResult = await runDeterministicRecallSearch(
       {
@@ -492,9 +510,33 @@ async function runSeedRecallSearch(
       searchOptions,
     );
     evidence = mergeEvidence(evidence, expansionResult.evidence);
+    searchedSources = mergeSearchedSources(
+      searchedSources,
+      expansionResult.searchedSources,
+    );
   }
 
-  return withFallbackEvidence(baseResult, evidence);
+  return withFallbackEvidence({ ...baseResult, searchedSources }, evidence);
+}
+
+/**
+ * Fold a later search's per-source notes into the running record: a source
+ * the later search covered takes its newer note, in its existing place; a
+ * source it adds goes at the end. Evidence counts are recomputed from the
+ * merged evidence by {@link withFallbackEvidence}.
+ */
+function mergeSearchedSources(
+  current: readonly RecallSearchedSource[],
+  later: readonly RecallSearchedSource[],
+): RecallSearchedSource[] {
+  const laterBySource = new Map(later.map((note) => [note.source, note]));
+  const merged = current.map((note) => laterBySource.get(note.source) ?? note);
+  for (const note of later) {
+    if (!current.some((existing) => existing.source === note.source)) {
+      merged.push(note);
+    }
+  }
+  return merged;
 }
 
 function buildReferentExpansionQueries(query: string): string[] {
@@ -698,11 +740,12 @@ function finishRecallFromToolUse(
     citationIds: finish.citationIds,
     ...(finish.unresolved ? { unresolved: finish.unresolved } : {}),
   };
+  const availableEvidence = shouldAppendAvailableEvidence(finish)
+    ? selectAvailableEvidence(input.query, allEvidence, citedEvidence)
+    : [];
   const content = formatAgenticRecallContent({
     answer: finish.answer,
-    availableEvidence: shouldAppendAvailableEvidence(finish)
-      ? selectAvailableEvidence(input.query, allEvidence, citedEvidence)
-      : [],
+    availableEvidence,
     footer: formatRecallFooter({
       searchedSources: searchResult.searchedSources,
       inspectCalls: debug.inspectCalls,
@@ -715,6 +758,15 @@ function finishRecallFromToolUse(
       content,
       answer: content,
       evidence: citedEvidence,
+      // Available evidence opens with the cited items, so it is the fuller
+      // list whenever the text carries it.
+      activity: buildRecallActivity({
+        input,
+        searchedSources: searchResult.searchedSources,
+        evidence:
+          availableEvidence.length > 0 ? availableEvidence : citedEvidence,
+        answer: finish.answer,
+      }),
       debug,
     },
   };
@@ -856,17 +908,6 @@ function formatAvailableEvidence(evidence: readonly RecallEvidence[]): string {
   ].join("\n");
 }
 
-function compactText(text: string, maxChars: number): string {
-  const compacted = text.trim().replace(/\s+/g, " ");
-  if (compacted.length <= maxChars) {
-    return compacted;
-  }
-  if (maxChars <= 3) {
-    return safeStringSlice(compacted, 0, maxChars);
-  }
-  return `${safeStringSlice(compacted, 0, maxChars - 3).trimEnd()}...`;
-}
-
 function dedupeEvidenceById(
   evidence: readonly RecallEvidence[],
 ): RecallEvidence[] {
@@ -892,6 +933,7 @@ async function executeSearchSources(
   searchOptions: DeterministicRecallSearchOptions | undefined,
 ): Promise<{
   evidence: RecallEvidence[];
+  searchedSources: RecallSearchedSource[];
   debug: AgenticRecallSearchDebug;
 }> {
   const query = readSearchQuery(payload.query);
@@ -915,6 +957,7 @@ async function executeSearchSources(
   if (!query || sources.length === 0) {
     return {
       evidence: [],
+      searchedSources: [],
       debug: {
         ...debug,
         error: !query
@@ -937,12 +980,20 @@ async function executeSearchSources(
     );
     return {
       evidence: result.evidence,
+      searchedSources: result.searchedSources,
       debug: { ...debug, evidenceCount: result.evidence.length },
     };
   } catch (err) {
+    const error = errorToMessage(err);
     return {
       evidence: [],
-      debug: { ...debug, error: errorToMessage(err) },
+      searchedSources: sources.map((source) => ({
+        source,
+        status: "degraded",
+        evidenceCount: 0,
+        error,
+      })),
+      debug: { ...debug, error },
     };
   }
 }
@@ -1296,6 +1347,11 @@ function deterministicFallback(
     content: fallback.answer,
     answer: fallback.answer,
     evidence: fallback.evidence,
+    activity: buildRecallActivity({
+      input: result.input,
+      searchedSources: result.searchedSources,
+      evidence: fallback.evidence,
+    }),
     debug: {
       ...debug,
       mode: "deterministic_fallback",

package/src/plugins/defaults/memory/context-search/format.ts

@@ -1,9 +1,11 @@
 import { safeStringSlice } from "@vellumai/plugin-api";
 
 import type {
-  DeterministicRecallSearchResult,
-  DeterministicRecallSourceNote,
-} from "./search.js";
+  RecallMetadata,
+  RecallSearchedSource,
+} from "../../../../api/events/tool-result.js";
+import type { NormalizedRecallInput } from "./limits.js";
+import type { DeterministicRecallSearchResult } from "./search.js";
 import type { RecallAnswer, RecallEvidence } from "./types.js";
 
 const CITATION_EXCERPT_MAX_CHARS = 280;
@@ -14,7 +16,7 @@ export interface RecallFooterInspectCall {
 }
 
 export interface RecallFooterOptions {
-  searchedSources: readonly DeterministicRecallSourceNote[];
+  searchedSources: readonly RecallSearchedSource[];
   inspectCalls?: readonly RecallFooterInspectCall[];
 }
 
@@ -56,6 +58,48 @@ export function formatDeterministicRecallAnswer(
   };
 }
 
+/**
+ * The recall result as structured data, from the same pieces its text is
+ * built from. `answer` is only the answer written from the evidence, never the
+ * evidence list or footer the text appends to it.
+ */
+export function buildRecallActivity(options: {
+  input: NormalizedRecallInput;
+  searchedSources: readonly RecallSearchedSource[];
+  evidence: readonly RecallEvidence[];
+  answer?: string;
+}): RecallMetadata {
+  const answer = options.answer?.trim();
+  return {
+    query: options.input.query,
+    depth: options.input.depth,
+    sources: [...options.input.sources],
+    ...(answer ? { answer } : {}),
+    evidence: options.evidence.map((item) => {
+      // A path recall could not read is not one a client can open.
+      const path =
+        item.metadata?.inspectError === true ? undefined : item.metadata?.path;
+      const conversationId = item.metadata?.conversationId;
+      const messageId = item.metadata?.messageId;
+      return {
+        source: item.source,
+        title: item.title,
+        locator: item.locator,
+        excerpt: compactText(item.excerpt, CITATION_EXCERPT_MAX_CHARS),
+        ...(item.timestampMs !== undefined
+          ? { timestampMs: item.timestampMs }
+          : {}),
+        ...(typeof path === "string" ? { path } : {}),
+        ...(typeof conversationId === "string" ? { conversationId } : {}),
+        ...(typeof conversationId === "string" && typeof messageId === "string"
+          ? { messageId }
+          : {}),
+      };
+    }),
+    searchedSources: [...options.searchedSources],
+  };
+}
+
 export function formatRecallFooter(options: RecallFooterOptions): string {
   return [
     formatSearchedSources(options.searchedSources),
@@ -73,7 +117,7 @@ function formatCitation(evidence: RecallEvidence, index: number): string {
 }
 
 function formatSearchedSources(
-  searchedSources: readonly DeterministicRecallSourceNote[],
+  searchedSources: readonly RecallSearchedSource[],
 ): string {
   if (searchedSources.length === 0) {
     return "";
@@ -84,7 +128,7 @@ function formatSearchedSources(
 }
 
 function formatDegradedSources(
-  searchedSources: readonly DeterministicRecallSourceNote[],
+  searchedSources: readonly RecallSearchedSource[],
 ): string {
   const degraded = searchedSources.filter((note) => note.status === "degraded");
   if (degraded.length === 0) {
@@ -135,7 +179,7 @@ function formatWorkspaceInspectionIssues(
   return `Workspace inspection issues: ${errors.join(", ")}.`;
 }
 
-function compactText(text: string, maxChars: number): string {
+export function compactText(text: string, maxChars: number): string {
   const compacted = text.trim().replace(/\s+/g, " ");
   if (compacted.length <= maxChars) {
     return compacted;

package/src/plugins/defaults/memory/context-search/limits.ts

@@ -1,12 +1,10 @@
-import type { RecallDepth, RecallInput, RecallSource } from "./types.js";
-
-export const ALL_RECALL_SOURCES: readonly RecallSource[] = [
-  "memory",
-  "conversations",
-  "workspace",
-] as const;
-
-const RECALL_SOURCE_SET: ReadonlySet<unknown> = new Set(ALL_RECALL_SOURCES);
+import {
+  type RecallDepth,
+  RecallDepthSchema,
+  type RecallSource,
+  RecallSourceSchema,
+} from "../../../../api/events/tool-result.js";
+import type { RecallInput } from "./recall-input.js";
 
 export const DEFAULT_RECALL_MAX_RESULTS = 8;
 export const MIN_RECALL_MAX_RESULTS = 1;
@@ -49,7 +47,7 @@ export function normalizeRecallSources(
   sources: readonly RecallSource[] | undefined,
 ): RecallSource[] {
   if (!sources || sources.length === 0) {
-    return [...ALL_RECALL_SOURCES];
+    return [...RecallSourceSchema.options];
   }
 
   const normalized: RecallSource[] = [];
@@ -85,7 +83,7 @@ function normalizeRecallDepth(depth: RecallDepth | undefined): RecallDepth {
     return DEFAULT_RECALL_DEPTH;
   }
 
-  if (depth !== "fast" && depth !== "standard" && depth !== "deep") {
+  if (!RecallDepthSchema.safeParse(depth).success) {
     throw new Error(`Unknown recall depth: ${String(depth)}`);
   }
 
@@ -93,7 +91,7 @@ function normalizeRecallDepth(depth: RecallDepth | undefined): RecallDepth {
 }
 
 export function isRecallSource(source: unknown): source is RecallSource {
-  return RECALL_SOURCE_SET.has(source);
+  return RecallSourceSchema.safeParse(source).success;
 }
 
 function clamp(value: number, min: number, max: number): number {

package/src/plugins/defaults/memory/context-search/recall-input.ts

@@ -0,0 +1,38 @@
+import { nullAsOmitted } from "@vellumai/plugin-api";
+import { z } from "zod";
+
+import {
+  RecallDepthSchema,
+  RecallSourceSchema,
+} from "../../../../api/events/tool-result.js";
+import { MAX_RECALL_MAX_RESULTS, MIN_RECALL_MAX_RESULTS } from "./limits.js";
+
+/**
+ * The `recall` tool's input: parsed at the top of its `execute`, and the
+ * source of the `input_schema` the model is shown, so the two cannot drift.
+ *
+ * `max_results` accepts any number, which `normalizeRecallInput` clamps, and
+ * reads anything else as absent; an explicit `null` on an optional field means
+ * omitted. An unknown source or depth is rejected.
+ */
+export const RecallInputSchema = z.looseObject({
+  query: z
+    .string()
+    .describe(
+      "What you're looking for. Be specific and descriptive: include the topic, person, project, decision, time period, or file clues when known.",
+    ),
+  sources: nullAsOmitted(z.array(RecallSourceSchema)).describe(
+    "Optional local sources to search. Omit to search memory, conversations, and workspace files.",
+  ),
+  max_results: z.number().optional().catch(undefined).meta({
+    type: "integer",
+    minimum: MIN_RECALL_MAX_RESULTS,
+    maximum: MAX_RECALL_MAX_RESULTS,
+    description: "Maximum number of evidence items to return.",
+  }),
+  depth: nullAsOmitted(RecallDepthSchema).describe(
+    "Search effort. Use fast for quick lookups, standard by default, and deep when the answer may require multiple local searches.",
+  ),
+});
+
+export type RecallInput = z.infer<typeof RecallInputSchema>;

package/src/plugins/defaults/memory/context-search/search.ts

@@ -1,32 +1,26 @@
+import {
+  type RecallSearchedSource,
+  type RecallSource,
+  RecallSourceSchema,
+} from "../../../../api/events/tool-result.js";
 import { isAbortReason } from "../host-utils.js";
 import {
-  ALL_RECALL_SOURCES,
   type NormalizedRecallInput,
   normalizeRecallInput,
   RECALL_EVIDENCE_TEXT_CAP_PER_SOURCE,
   RECALL_TOTAL_EVIDENCE_TEXT_CAP,
 } from "./limits.js";
+import type { RecallInput } from "./recall-input.js";
 import type {
   RecallEvidence,
-  RecallInput,
   RecallSearchContext,
   RecallSearchResult,
-  RecallSource,
   RecallSourceAdapter,
 } from "./types.js";
 
-export type DeterministicRecallSourceStatus = "searched" | "degraded";
-
-export interface DeterministicRecallSourceNote {
-  source: RecallSource;
-  status: DeterministicRecallSourceStatus;
-  evidenceCount: number;
-  error?: string;
-}
-
 export interface DeterministicRecallSearchResult extends RecallSearchResult {
   input: NormalizedRecallInput;
-  searchedSources: DeterministicRecallSourceNote[];
+  searchedSources: RecallSearchedSource[];
 }
 
 export interface DeterministicRecallSearchOptions {
@@ -34,7 +28,7 @@ export interface DeterministicRecallSearchOptions {
 }
 
 const SOURCE_PRIORITY = new Map<RecallSource, number>(
-  ALL_RECALL_SOURCES.map((source, index) => [source, index]),
+  RecallSourceSchema.options.map((source, index) => [source, index]),
 );
 
 export async function runDeterministicRecallSearch(

package/src/plugins/defaults/memory/context-search/sources/conversations.ts

@@ -181,6 +181,7 @@ export async function searchConversationSource(
         metadata: {
           role: row.role,
           conversationId: row.conversation_id,
+          messageId: row.message_id,
         },
       })),
     ),

package/src/plugins/defaults/memory/context-search/types.ts

@@ -1,16 +1,6 @@
+import type { RecallSource } from "../../../../api/events/tool-result.js";
 import type { AssistantConfig } from "../../../../config/schema.js";
 
-export type RecallSource = "memory" | "conversations" | "workspace";
-
-export type RecallDepth = "fast" | "standard" | "deep";
-
-export interface RecallInput {
-  query: string;
-  sources?: RecallSource[];
-  max_results?: number;
-  depth?: RecallDepth;
-}
-
 export interface RecallEvidence {
   id: string;
   source: RecallSource;

package/src/plugins/defaults/memory/graph/__tests__/handle-remember-v2.test.ts

@@ -203,8 +203,11 @@ describe("handleRemember — batch (array) content", () => {
       CONFIG,
     );
 
-    expect(result.success).toBe(true);
-    expect(result.message).toContain("3");
+    expect(result).toEqual({
+      success: true,
+      message: "Saved 3 facts to knowledge base.",
+      facts: ["fact one", "fact two", "fact three"],
+    });
 
     const memoryDir = join(tmpWorkspace, "memory");
     const buffer = readFileSync(join(memoryDir, "buffer.md"), "utf-8");
@@ -245,11 +248,15 @@ describe("handleRemember — batch (array) content", () => {
 
   test("drops blank entries and rejects an all-empty array", () => {
     const ok = handleRemember(
-      { content: ["   ", "kept fact", ""] },
+      { content: ["   ", " kept fact ", ""] },
       "conv-batch-3",
       CONFIG,
     );
-    expect(ok.success).toBe(true);
+    expect(ok).toEqual({
+      success: true,
+      message: "Saved to knowledge base.",
+      facts: ["kept fact"],
+    });
     const buffer = readFileSync(
       join(tmpWorkspace, "memory", "buffer.md"),
       "utf-8",

package/src/plugins/defaults/memory/graph/tool-handlers.ts

@@ -8,6 +8,7 @@
 
 import { join } from "node:path";
 
+import type { RememberInput } from "../../../../api/remember-tool.js";
 import {
   isMemoryEnabled,
   usesConceptPageMemory,
@@ -31,33 +32,23 @@ import { type CapabilityKind, capabilityKind } from "./types.js";
 // remember handler — appends to the memory/ buffer + daily archive
 // ---------------------------------------------------------------------------
 
-export interface RememberInput {
-  /**
-   * The fact(s) to remember. A single string records one fact; an array
-   * records several independent facts in one call (each becomes its own
-   * timestamped entry), so a single turn can batch unrelated facts instead of
-   * calling `remember` once per fact.
-   */
-  content: string | string[];
-  finish_turn?: boolean;
-}
-
-export interface RememberResult {
-  success: boolean;
-  message: string;
-}
+export type RememberResult =
+  | {
+      success: true;
+      message: string;
+      /** The facts saved, trimmed, in the order they were given. */
+      facts: string[];
+    }
+  | { success: false; message: string };
 
 /**
  * Normalize the `remember` content input to a list of non-empty facts.
  * Accepts the single-string form or the batch array form, trims each fact, and
  * drops blanks so an empty or whitespace-only input yields no facts.
  */
-function normalizeFacts(content: string | string[]): string[] {
+function normalizeFacts(content: RememberInput["content"]): string[] {
   const raw = Array.isArray(content) ? content : [content];
-  return raw
-    .filter((fact): fact is string => typeof fact === "string")
-    .map((fact) => fact.trim())
-    .filter((fact) => fact.length > 0);
+  return raw.map((fact) => fact.trim()).filter((fact) => fact.length > 0);
 }
 
 function rememberSuccessMessage(count: number): string {
@@ -96,7 +87,7 @@ export function handleRemember(
     now,
   });
 
-  return { success: true, message };
+  return { success: true, message, facts };
 }
 
 // ---------------------------------------------------------------------------