@vellumai/assistant 0.12.2 → 0.12.3-staging.2

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

@@ -6,15 +6,16 @@
 // into concept pages.
 // ---------------------------------------------------------------------------
 
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
+import type { RememberInput } from "../../../../api/remember-tool.js";
 import {
   isMemoryEnabled,
   usesConceptPageMemory,
 } from "../../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../../config/types.js";
 import { enqueueMemoryJob } from "../../../../persistence/jobs-store.js";
+import { appendBufferAndArchive } from "../buffer-file.js";
 import { formatRememberEntry } from "../buffer-format.js";
 import { getWorkspaceDir } from "../paths.js";
 import type { GraphStats } from "./store.js";
@@ -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,48 +87,7 @@ export function handleRemember(
     now,
   });
 
-  return { success: true, message };
-}
-
-/**
- * Append `entry` to `<rootDir>/buffer.md` and `<rootDir>/archive/<today>.md`,
- * creating the archive directory and seeding the archive header if missing.
- *
- * Returns the absolute paths of both files so callers can fan out follow-up
- * work.
- *
- * Exported so background jobs (`sweep`, future LLM-driven extractors) can
- * append to `memory/buffer.md` + `memory/archive/<today>.md` with exactly the
- * same format `remember()` produces, keeping the two write paths
- * byte-compatible for downstream consumers (consolidation, search).
- */
-export function appendBufferAndArchive(args: {
-  rootDir: string;
-  entry: string;
-  now: Date;
-}): { bufferPath: string; archivePath: string } {
-  const { rootDir, entry, now } = args;
-  const archiveDir = join(rootDir, "archive");
-  mkdirSync(archiveDir, { recursive: true });
-
-  const bufferPath = join(rootDir, "buffer.md");
-  appendFileSync(bufferPath, entry, "utf-8");
-
-  const yyyy = now.getFullYear();
-  const mm = String(now.getMonth() + 1).padStart(2, "0");
-  const dd = String(now.getDate()).padStart(2, "0");
-  const archivePath = join(archiveDir, `${yyyy}-${mm}-${dd}.md`);
-  if (!existsSync(archivePath)) {
-    const month = now.toLocaleString("en-US", { month: "short" });
-    appendFileSync(
-      archivePath,
-      `# ${month} ${now.getDate()}, ${yyyy}\n\n`,
-      "utf-8",
-    );
-  }
-  appendFileSync(archivePath, entry, "utf-8");
-
-  return { bufferPath, archivePath };
+  return { success: true, message, facts };
 }
 
 // ---------------------------------------------------------------------------

package/src/plugins/defaults/memory/graph/tools.ts

@@ -2,14 +2,11 @@
 // Memory Tool definitions for agentic recall and remember.
 // ---------------------------------------------------------------------------
 
-import {
-  ALL_RECALL_SOURCES,
-  MAX_RECALL_MAX_RESULTS,
-  MIN_RECALL_MAX_RESULTS,
-} from "../context-search/limits.js";
-import type { ToolDefinition } from "../llm-helpers.js";
+import { toToolInputSchema } from "@vellumai/plugin-api";
 
-const RECALL_DEPTHS = ["fast", "standard", "deep"] as const;
+import { RememberInputSchema } from "../../../../api/remember-tool.js";
+import { RecallInputSchema } from "../context-search/recall-input.js";
+import type { ToolDefinition } from "../llm-helpers.js";
 
 /**
  * Explicit local information search across memory, conversations, and
@@ -19,38 +16,7 @@ export const graphRecallDefinition = {
   name: "recall",
   description:
     'Search local information the moment you feel uncertain. Use recall for memory, past conversations, and workspace files — before you guess, before you ask, before you hedge. Auto-injection is incomplete by design; it surfaces patterns, not the specifics you need to answer well. If you catch yourself reaching for "I think", "I believe", "if I remember", "didn\'t we", "last time" — that\'s the signal. Recall. If a turn references someone, a place, a decision, a document, or prior work you should be able to find locally — recall. Call it multiple times per conversation if the turn warrants it. Be specific in your query for best results. Results reflect what was true when the memory was written — do not use recall alone to answer questions about current system state (account connections, watchers, service health); verify those with live checks.',
-  input_schema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description:
-          "What you're looking for. Be specific and descriptive: include the topic, person, project, decision, time period, or file clues when known.",
-      },
-      sources: {
-        type: "array",
-        items: {
-          type: "string",
-          enum: [...ALL_RECALL_SOURCES],
-        },
-        description:
-          "Optional local sources to search. Omit to search memory, conversations, and workspace files.",
-      },
-      max_results: {
-        type: "integer",
-        minimum: MIN_RECALL_MAX_RESULTS,
-        maximum: MAX_RECALL_MAX_RESULTS,
-        description: "Maximum number of evidence items to return.",
-      },
-      depth: {
-        type: "string",
-        enum: [...RECALL_DEPTHS],
-        description:
-          "Search effort. Use fast for quick lookups, standard by default, and deep when the answer may require multiple local searches.",
-      },
-    },
-    required: ["query"],
-  },
+  input_schema: toToolInputSchema(RecallInputSchema),
 } satisfies ToolDefinition;
 
 /**
@@ -77,8 +43,9 @@ export const REMEMBER_PAGE_HINT_GUIDANCE =
   "When a fact relates to memory pages already in your context, reference the most specific ones inline as [[slug]] wikilinks — consolidation reads hinted pages first when filing the fact, which matters most for corrections (the hint names the page carrying the outdated fact). Hint only pages you have actually seen, and prefer specific pages over broad hubs.";
 
 /**
- * Build the `remember` input schema. `pageHints` reflects whether
- * concept-page memory is active and appends
+ * Build the `remember` input schema from {@link RememberInputSchema}, the one
+ * `execute` parses with, adding the descriptions the model reads.
+ * `pageHints` reflects whether concept-page memory is active and appends
  * {@link REMEMBER_PAGE_HINT_GUIDANCE} to the `content` description. It is a
  * thunk re-resolved on every read of that description: the registry's
  * finalized tool shares the returned schema object by reference, so a
@@ -87,29 +54,33 @@ export const REMEMBER_PAGE_HINT_GUIDANCE =
  */
 export function buildRememberInputSchema(options: {
   pageHints: () => boolean;
-}) {
-  return {
-    type: "object",
-    properties: {
-      content: {
-        anyOf: [
-          { type: "string" },
-          { type: "array", items: { type: "string" }, minItems: 1 },
-        ],
-        get description(): string {
-          return options.pageHints()
-            ? `${REMEMBER_CONTENT_DESCRIPTION} ${REMEMBER_PAGE_HINT_GUIDANCE}`
-            : REMEMBER_CONTENT_DESCRIPTION;
-        },
-      },
-      finish_turn: {
-        type: "boolean",
-        description:
-          "When you have nothing else to say and want to yield the turn you MUST set this to true. When true, your turn ends after this tool call. It's critical that you do this in order to avoid unnecessary LLM calls.",
-      },
-    },
-    required: ["content"],
-  };
+}): Record<string, unknown> {
+  const schema = toToolInputSchema(
+    RememberInputSchema.extend({
+      content: RememberInputSchema.shape.content.describe(
+        REMEMBER_CONTENT_DESCRIPTION,
+      ),
+      finish_turn: RememberInputSchema.shape.finish_turn.describe(
+        "When you have nothing else to say and want to yield the turn you MUST set this to true. When true, your turn ends after this tool call. It's critical that you do this in order to avoid unnecessary LLM calls.",
+      ),
+    }),
+  );
+  const properties = schema.properties;
+  const content =
+    typeof properties === "object" && properties !== null
+      ? Reflect.get(properties, "content")
+      : undefined;
+  if (typeof content === "object" && content !== null) {
+    Object.defineProperty(content, "description", {
+      enumerable: true,
+      configurable: true,
+      get: (): string =>
+        options.pageHints()
+          ? `${REMEMBER_CONTENT_DESCRIPTION} ${REMEMBER_PAGE_HINT_GUIDANCE}`
+          : REMEMBER_CONTENT_DESCRIPTION,
+    });
+  }
+  return schema;
 }
 
 /**

package/src/plugins/defaults/memory/host-utils.ts

@@ -25,7 +25,6 @@ import type { SqliteRetryOptions } from "../../../util/sqlite-retry.js";
 import * as hostSqliteRetry from "../../../util/sqlite-retry.js";
 import * as hostStripCommentLines from "../../../util/strip-comment-lines.js";
 import * as hostTruncate from "../../../util/truncate.js";
-import * as hostUnicode from "../../../util/unicode.js";
 import * as hostWorkerCompute from "../../../util/worker-compute.js";
 import * as hostWorkerMemory from "../../../util/worker-memory.js";
 
@@ -77,15 +76,6 @@ export function truncate(str: string, maxLen: number, suffix?: string): string {
     : hostTruncate.truncate(str, maxLen, suffix);
 }
 
-/** `String.prototype.slice` that never cuts a UTF-16 surrogate pair in half. */
-export function safeStringSlice(
-  str: string,
-  start?: number,
-  end?: number,
-): string {
-  return hostUnicode.safeStringSlice(str, start, end);
-}
-
 export function workerMemoryEnv(): Record<string, string | undefined> {
   return hostWorkerMemory.workerMemoryEnv();
 }

package/src/plugins/defaults/memory/injectors.ts

@@ -374,9 +374,10 @@ const memoryV2StaticInjector: Injector = {
     if (mode !== "full") {
       return null;
     }
-    // The consolidation agent reads and rewrites memory/buffer.md through
-    // file tools; injecting the buffer section here would duplicate the
-    // entire backlog into its context (and go stale as it edits the file).
+    // The consolidation run already carries its pass's buffer entries in
+    // the prompt itself, and the job removes them from memory/buffer.md
+    // after the run; injecting the buffer section here would duplicate the
+    // pass and hand the agent entries that are not its to file.
     const content = readGatedMemoryV2Static(ctx.trust, {
       excludeBuffer: ctx.callSite === "memoryV2Consolidation",
     });

package/src/plugins/defaults/memory/memory-retrospective-job.ts

@@ -43,11 +43,11 @@
 import {
   addMessage,
   type AgentLoopExitReason,
-  type ContentBlock,
   type ConversationRow,
   deleteConversation,
   getConversation,
   getConversationProcessingStartedAt,
+  getRecordedConversationToolSurface,
   isConversationProcessing,
 } from "@vellumai/plugin-api";
 
@@ -105,6 +105,12 @@ import {
   upsertRetrospectiveState,
 } from "./memory-retrospective-state.js";
 import { effectiveSweepLookbackMs } from "./memory-retrospective-sweep.js";
+import {
+  collectSuccessfulToolResultIds,
+  countDurableToolUses,
+  extractRememberContents,
+  hasCommittedTextReply,
+} from "./memory-run-evidence.js";
 
 const log = getLogger("memory-retrospective-job");
 
@@ -500,10 +506,9 @@ export async function runForkBasedRetrospective(
   // Persona + tool-context parity pins derived from the source conversation
   // (see `resolveSourceParityPins`), both passed unconditionally. The persona
   // override keeps the system-prompt prefix in parity (and is a review-quality
-  // fix on its own); the tool-context pin keeps the wire tool surface in
-  // parity — the fork always runs execution gate mode below, so the source's
-  // full tool surface stays on the wire while the allowlist holds at
-  // execution time.
+  // fix on its own); the tool-context pin resolves the fork's execution-side
+  // tool inventory under the source's client context and carries the wire
+  // surface when the source has no recorded one (`sourceToolSurface` below).
   // Warm both guardian-delivery cache keys (vellum + unfiltered) so the sync
   // slug resolution inside resolveSourceParityPins (resolveUserSlug(undefined)),
   // including its any-channel fallback, hits fresh keys instead of falling
@@ -514,6 +519,16 @@ export async function runForkBasedRetrospective(
     newMessages,
   );
 
+  // The tools array the source's most recent live turn actually sent,
+  // replayed verbatim on the fork. The wire tool block is the first tier of
+  // the provider cache prefix (tools → system → messages), and re-deriving it
+  // on the fork cannot reproduce the source's bytes: this worker's registry
+  // has no user-plugin tools, host-tool gates read connected clients the
+  // worker never has, and presence derived from a persisted interface stamp
+  // misreads clientless turns. `null` (no live turn has recorded a surface)
+  // leaves the pin's derivation as the wire surface.
+  const sourceToolSurface = await readSourceToolSurface(sourceConversationId);
+
   // `skipHintInjection: true` because the instruction is already a
   // persisted message — the wake's hint sandwich would only duplicate it.
   let wakeSucceeded = false;
@@ -542,16 +557,32 @@ export async function runForkBasedRetrospective(
             "find_similar_skills",
           ]
         : ["remember"],
-      // Always keep the source's full tool surface on the wire and resolve it
-      // under the source's client context (`toolContextPin`). The wire tool
-      // block is the first tier of the provider cache prefix
-      // (tools → system → messages), so a wire filter busts cache parity with
-      // the source's live turns — re-creating the cached prefix instead of
-      // reading it. The allowlist still holds at execution time: non-allowlisted
-      // calls are rejected before any executor or side effect runs. See
+      // Keep the source's full tool surface on the wire: replay the array its
+      // last live turn sent when one is recorded, otherwise resolve the fork's
+      // own surface under the source's client context (`toolContextPin`). The
+      // wire tool block is the first tier of the provider cache prefix
+      // (tools → system → messages), so any wire difference busts cache parity
+      // with the source's live turns, re-creating the cached prefix instead of
+      // reading it. The recorded delegation-section state rides with the array
+      // into the fork's system prompt (the second tier) for the same reason:
+      // this wake's own scope cannot spawn, so deriving the section here
+      // renders it off where an interactive source rendered it on. The
+      // allowlist still holds at execution time: non-allowlisted calls are
+      // rejected before any executor or side effect runs. See
       // {@link SubagentToolGateMode} and {@link WakeToolContextPin}.
       toolGateMode: "execution" as const,
       toolContextPin,
+      ...(sourceToolSurface
+        ? {
+            wireToolDefinitions: sourceToolSurface.tools,
+            ...(sourceToolSurface.delegateIndependentTasks === null
+              ? {}
+              : {
+                  delegateIndependentTasks:
+                    sourceToolSurface.delegateIndependentTasks,
+                }),
+          }
+        : {}),
       // Preactivate skill-management so its authoring tools (`find_similar_skills`
       // / `scaffold_managed_skill` / the `skill_load` target) are in the turn's
       // active set from turn 1; the checker's origin-scoped grant then makes them
@@ -731,6 +762,25 @@ function enqueueFollowUpJobs(): string[] {
   return followUpJobIds;
 }
 
+/**
+ * The source's recorded wire surface (its tool array and the delegation
+ * section state of its system prompt), or `null` when none is recorded or the
+ * read fails (logged; the fork then derives both for itself).
+ */
+async function readSourceToolSurface(
+  sourceConversationId: string,
+): ReturnType<typeof getRecordedConversationToolSurface> {
+  try {
+    return await getRecordedConversationToolSurface(sourceConversationId);
+  } catch (err) {
+    log.warn(
+      { err, sourceConversationId },
+      "memory-retrospective (fork): failed to read the source's recorded tool surface; deriving the wire surface instead",
+    );
+    return null;
+  }
+}
+
 /**
  * The source-derived parity pins the fork wake runs under: the system-prompt
  * persona override and the tool-resolution context pin. Both exist so the
@@ -1252,177 +1302,16 @@ async function collectRetrospectiveRunEvidence(
   const succeededIds = collectSuccessfulToolResultIds(runMessages);
   return {
     remembers: extractRememberContents(runMessages, succeededIds),
-    durableToolCallCount: countDurableToolUses(runMessages, succeededIds),
-    durableToolAttemptCount: countDurableToolUses(runMessages, null),
+    durableToolCallCount: countDurableToolUses(
+      runMessages,
+      DURABLE_RETROSPECTIVE_TOOLS,
+      succeededIds,
+    ),
+    durableToolAttemptCount: countDurableToolUses(
+      runMessages,
+      DURABLE_RETROSPECTIVE_TOOLS,
+      null,
+    ),
     committedTextReply: hasCommittedTextReply(runMessages),
   };
 }
-
-/**
- * Whether the LAST persisted assistant row on the run's tail carries a text
- * block with non-whitespace content. Paired with a model-driven stop and
- * zero memory-write attempts, that closing reply is the persisted artifact
- * of a pass that read its window and had nothing to save: the model spoke
- * and then chose to end the run. Reading only the final row separates it
- * from a run whose narration went live but whose actual conclusion was
- * empty, as well as from a response that committed nothing at all
- * (thinking-only output, an empty content array).
- */
-function hasCommittedTextReply(messages: MessageLike[]): boolean {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i]!;
-    if (msg.role !== "assistant") {
-      continue;
-    }
-    const blocks = parseMessageBlocks(msg);
-    if (blocks === null) {
-      return false;
-    }
-    return blocks.some(
-      (b) =>
-        b.type === "text" && typeof b.text === "string" && b.text.trim() !== "",
-    );
-  }
-  return false;
-}
-
-/**
- * Ids of `tool_result` blocks on the run's user rows whose execution did not
- * report an error. Robust to malformed content JSON the same way
- * `extractRememberContents` is.
- */
-function collectSuccessfulToolResultIds(messages: MessageLike[]): Set<string> {
-  const ids = new Set<string>();
-  for (const msg of messages) {
-    if (msg.role !== "user") {
-      continue;
-    }
-    for (const b of parseMessageBlocks(msg) ?? []) {
-      // guard:allow-tool-result-only: success evidence for locally-executed
-      // durable memory tools; server-side web_search_tool_result never
-      // corresponds to a durable write and carries no is_error flag.
-      if (
-        b.type === "tool_result" &&
-        typeof b.tool_use_id === "string" &&
-        b.is_error !== true
-      ) {
-        ids.add(b.tool_use_id);
-      }
-    }
-  }
-  return ids;
-}
-
-/**
- * Count persisted `tool_use` blocks whose `name` is in
- * {@link DURABLE_RETROSPECTIVE_TOOLS} across the run's assistant rows.
- * With a `succeededIds` set, only calls whose id has a matching successful
- * `tool_result` count (verified executions); with `null`, every attempt
- * counts regardless of outcome.
- */
-function countDurableToolUses(
-  messages: MessageLike[],
-  succeededIds: ReadonlySet<string> | null,
-): number {
-  let count = 0;
-  for (const msg of messages) {
-    if (msg.role !== "assistant") {
-      continue;
-    }
-    for (const b of parseMessageBlocks(msg) ?? []) {
-      if (
-        b.type === "tool_use" &&
-        DURABLE_RETROSPECTIVE_TOOLS.has(String(b.name)) &&
-        (succeededIds === null ||
-          (typeof b.id === "string" && succeededIds.has(b.id)))
-      ) {
-        count += 1;
-      }
-    }
-  }
-  return count;
-}
-
-interface MessageLike {
-  role: string;
-  content: string | ContentBlock[];
-}
-
-/**
- * Parse a message row's content into its block objects, or `null` when the
- * content is malformed (unparseable JSON, not an array). Non-object entries
- * are dropped. Every evidence reader in this module goes through this so
- * malformed rows degrade the same way everywhere: skipped, not propagated.
- */
-function parseMessageBlocks(
-  msg: MessageLike,
-): Record<string, unknown>[] | null {
-  let blocks: unknown = msg.content;
-  if (typeof blocks === "string") {
-    try {
-      blocks = JSON.parse(blocks);
-    } catch {
-      return null;
-    }
-  }
-  if (!Array.isArray(blocks)) {
-    return null;
-  }
-  return blocks.filter(
-    (block): block is Record<string, unknown> =>
-      typeof block === "object" && block !== null,
-  );
-}
-
-/**
- * Scan an array of message rows for `tool_use` blocks where `name` is
- * `"remember"` and return the `input.content` strings in order. Robust to
- * malformed content JSON — unparseable rows are skipped, not propagated.
- */
-function extractRememberContents(
-  messages: MessageLike[],
-  succeededIds?: ReadonlySet<string>,
-): string[] {
-  const contents: string[] = [];
-  for (const msg of messages) {
-    if (msg.role !== "assistant") {
-      continue;
-    }
-    for (const b of parseMessageBlocks(msg) ?? []) {
-      if (b.type !== "tool_use") {
-        continue;
-      }
-      if (b.name !== "remember") {
-        continue;
-      }
-      // When a success set is provided, only executions that reported a
-      // non-error tool_result contribute facts: a failed remember never
-      // wrote the buffer, and logging its facts would suppress the retry's
-      // re-save via <already_remembered>.
-      if (
-        succeededIds !== undefined &&
-        (typeof b.id !== "string" || !succeededIds.has(b.id))
-      ) {
-        continue;
-      }
-      const input = b.input;
-      if (!input || typeof input !== "object") {
-        continue;
-      }
-      const content = (input as Record<string, unknown>).content;
-      // `remember` accepts a single string or an array of facts (batch form);
-      // flatten both so batched saves still feed the dedup baseline.
-      const facts = Array.isArray(content) ? content : [content];
-      for (const fact of facts) {
-        if (typeof fact !== "string") {
-          continue;
-        }
-        const trimmed = fact.trim();
-        if (trimmed.length > 0) {
-          contents.push(trimmed);
-        }
-      }
-    }
-  }
-  return contents;
-}