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

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/src/memory-eval-routes.ts

@@ -23,7 +23,7 @@ import type { RouteDefinition } from "../../../../runtime/routes/types.js";
 import { getLogger } from "../logging.js";
 import { getWorkspaceDir } from "../paths.js";
 import { runMemoryEval } from "../v3-eval/eval-packets.js";
-import { type TallyResult, tallyVerdicts } from "../v3-eval/eval-tally.js";
+import { tallyVerdicts } from "../v3-eval/eval-tally.js";
 
 const log = getLogger("memory-eval-routes");
 
@@ -138,12 +138,11 @@ export type MemoryEvalTallyResult = z.infer<typeof MemoryEvalTallyResultSchema>;
  */
 export function handleMemoryEvalTally(body: unknown): MemoryEvalTallyResult {
   const params = MemoryEvalTallyParamsSchema.parse(body ?? {});
-  const result: TallyResult = tallyVerdicts(
+  return tallyVerdicts(
     params.verdicts,
     params.key,
     params.alpha !== undefined ? { alpha: params.alpha } : {},
   );
-  return result;
 }
 
 const WRITE_POLICY: RoutePolicy = {

package/src/plugins/defaults/memory/src/memory-item-routes.test.ts

@@ -1199,6 +1199,11 @@ describe("Memory Item Routes", () => {
       const body = (await res.json()) as RememberBody;
       expect(body.success).toBe(true);
       expect(body.message.length).toBeGreaterThan(0);
+      // Exactly the declared response fields: the handler's saved-facts list
+      // stays on the tool path.
+      expect(Object.keys(body).sort()).toEqual(
+        ["message", "pendingNodeId", "success"].sort(),
+      );
     });
 
     test("returns the pending node id of the appended entry", async () => {

package/src/plugins/defaults/memory/src/memory-item-routes.ts

@@ -1162,6 +1162,7 @@ export const ROUTES: RouteDefinition[] = [
         return result;
       }
       maybeEnqueueConsolidationForCreate(config);
+      const created = { success: true, message: result.message };
 
       // Resolve the pending graph-node id of the entry just appended so the
       // client can fly the map to it. Matched by this request's content
@@ -1179,7 +1180,7 @@ export const ROUTES: RouteDefinition[] = [
       } catch (err) {
         log.warn({ err }, "Failed to resolve pending node id after create");
       }
-      return pendingNodeId ? { ...result, pendingNodeId } : result;
+      return pendingNodeId ? { ...created, pendingNodeId } : created;
     },
   },
 ];

package/src/plugins/defaults/memory/substrate/prompts/consolidation.ts

@@ -312,7 +312,7 @@ Cutoff timestamp for this run: \`${CUTOFF_PLACEHOLDER}\`. The entries for this p
 - Updated \`memory/threads.md\` (≤10000 chars)
 - Updated \`edges:\` frontmatter in any pages whose outgoing links changed
 
-How retrieval works: high-activation pages are loaded at the start of each turn. Activations spread along **directed** edges from source to target — activating A pulls in the pages A points at, but not the reverse. The immutable archive retains the entire buffer forever, so don't worry about losing information.
+How retrieval works: high-activation pages are loaded at the start of each turn. Activations spread along **directed** edges from source to target: activating A pulls in the pages A points at, but not the reverse.
 
 ---
 
@@ -724,7 +724,7 @@ Three consequences:
 
 1. **The lead IS the card, and the fallback.** Write every lead as a standalone orientation: what this article is, the one or two facts that identify it, where it sits. If the lead only makes sense after reading the sections, the card is useless and so is the fallback. One to three short paragraphs.
 2. **Section names are navigation.** They appear on the selector's card as the table of contents and head every injected section. Name sections so future-you can tell from the name alone whether the answer lives there.
-3. **Sections are the unit of growth and retrieval.** A fact filed in the right section of the right article is findable and arrives in context with its section (kept under the 6000-character chunk window, so the section travels whole); a fact buried mid-paragraph in an overlong lead is not. The immutable archive retains the entire buffer forever, so don't worry about losing information.
+3. **Sections are the unit of growth and retrieval.** A fact filed in the right section of the right article is findable and arrives in context with its section (kept under the 6000-character chunk window, so the section travels whole); a fact buried mid-paragraph in an overlong lead is not.
 
 ---
 

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -11,7 +11,10 @@ import {
   test,
 } from "bun:test";
 
+import { z } from "zod";
+
 import { setConfig } from "../../../__tests__/helpers/set-config.js";
+import type { RecallMetadata } from "../../../api/events/tool-result.js";
 import type { ToolContext } from "../../../tools/types.js";
 
 let tmpWorkspace: string;
@@ -31,6 +34,14 @@ const recallCalls: Array<{
   context: Record<string, unknown>;
 }> = [];
 let recallContent = "agentic recall answer";
+const recallActivity: RecallMetadata = {
+  query: "guardian recall",
+  depth: "standard",
+  sources: ["memory"],
+  answer: "agentic recall answer",
+  evidence: [],
+  searchedSources: [{ source: "memory", status: "searched", evidenceCount: 0 }],
+};
 
 mock.module("./v1/jobs/embed-pkb-file.js", () => ({
   enqueuePkbIndexJob: (input: { pkbRoot: string; absPath: string }) => {
@@ -52,6 +63,7 @@ mock.module("./context-search/agent-runner.js", () => ({
       content: recallContent,
       answer: recallContent,
       evidence: [],
+      activity: recallActivity,
       debug: { mode: "agentic" },
     };
   },
@@ -146,6 +158,7 @@ describe("recallTool.execute", () => {
     expect(result).toEqual({
       content: "agentic recall answer",
       isError: false,
+      activityMetadata: { recall: recallActivity },
     });
     expect(recallCalls).toHaveLength(1);
     expect(recallCalls[0]?.input).toEqual({ query: "guardian recall" });
@@ -179,6 +192,7 @@ describe("recallTool.execute", () => {
     expect(result).toEqual({
       content: "agentic recall answer",
       isError: false,
+      activityMetadata: { recall: recallActivity },
     });
     expect(recallCalls).toHaveLength(1);
     expect(recallCalls[0]?.input).toEqual({
@@ -189,6 +203,37 @@ describe("recallTool.execute", () => {
     });
   });
 
+  test("refuses an unknown source before searching", async () => {
+    const result = await recallTool.execute(
+      { query: "launch notes", sources: ["calendar"] },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "recall"');
+    expect(result.content).toContain("sources.0");
+    expect(recallCalls).toHaveLength(0);
+  });
+
+  test("reads null optionals as omitted and leaves max_results to the clamp", async () => {
+    await recallTool.execute(
+      {
+        query: "launch notes",
+        sources: null,
+        depth: null,
+        max_results: 50,
+        activity: "Looking up launch notes",
+      },
+      makeContext(),
+    );
+
+    expect(recallCalls[0]?.input).toEqual({
+      query: "launch notes",
+      max_results: 50,
+      activity: "Looking up launch notes",
+    });
+  });
+
   test("returns deterministic fallback content directly", async () => {
     recallContent = "Found evidence:\n\n- [workspace] fallback note";
 
@@ -200,6 +245,7 @@ describe("recallTool.execute", () => {
     expect(result).toEqual({
       content: "Found evidence:\n\n- [workspace] fallback note",
       isError: false,
+      activityMetadata: { recall: recallActivity },
     });
   });
 
@@ -305,6 +351,30 @@ describe("rememberTool.execute — buffer writes", () => {
   });
 });
 
+describe("rememberTool.execute — memory access", () => {
+  test.each(["trusted_contact", "unverified_contact", "unknown"] as const)(
+    "refuses a %s write without touching the memory buffer",
+    async (trustClass) => {
+      const fact = `a claim made on a ${trustClass} turn`;
+      const result = await rememberTool.execute(
+        { content: fact, finish_turn: true },
+        makeContext({ trustClass }),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("Not saved");
+      expect(result.activityMetadata).toBeUndefined();
+      // The turn continues so the model can relay the refusal.
+      expect(result.yieldToUser).toBeUndefined();
+      const bufferPath = join(tmpWorkspace, "memory", "buffer.md");
+      const buffer = existsSync(bufferPath)
+        ? readFileSync(bufferPath, "utf-8")
+        : "";
+      expect(buffer).not.toContain(fact);
+    },
+  );
+});
+
 describe("rememberTool.execute — batch (array) content", () => {
   beforeEach(() => {
     enqueueCalls.length = 0;
@@ -313,10 +383,13 @@ describe("rememberTool.execute — batch (array) content", () => {
 
   test("records every fact from an array in the memory buffer", async () => {
     const result = await rememberTool.execute(
-      { content: ["batch fact A", "batch fact B"] },
+      { content: [" batch fact A ", "batch fact B", "  "] },
       makeContext(),
     );
     expect(result.isError).toBe(false);
+    expect(result.activityMetadata).toEqual({
+      remember: { facts: ["batch fact A", "batch fact B"] },
+    });
 
     const bufferContents = readFileSync(
       join(tmpWorkspace, "memory", "buffer.md"),
@@ -328,16 +401,58 @@ describe("rememberTool.execute — batch (array) content", () => {
     expect(enqueueCalls).toHaveLength(0);
   });
 
+  test("refuses a non-string fact without writing any of the batch", async () => {
+    const result = await rememberTool.execute(
+      { content: ["a fact beside a number", 42] },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "remember"');
+    const bufferPath = join(tmpWorkspace, "memory", "buffer.md");
+    const buffer = existsSync(bufferPath)
+      ? readFileSync(bufferPath, "utf-8")
+      : "";
+    expect(buffer).not.toContain("a fact beside a number");
+  });
+
   test("rejects an all-blank array without writing or enqueueing", async () => {
     const result = await rememberTool.execute(
       { content: ["  ", ""] },
       makeContext(),
     );
     expect(result.isError).toBe(true);
+    expect(result.activityMetadata).toBeUndefined();
     expect(enqueueCalls).toHaveLength(0);
   });
 });
 
+/** The advertised `content` description, read as the provider serializes it. */
+function contentDescription(schema: Record<string, unknown>): string {
+  return z
+    .object({
+      properties: z.object({ content: z.object({ description: z.string() }) }),
+    })
+    .parse(schema).properties.content.description;
+}
+
+describe("rememberTool definition", () => {
+  test("advertises the schema it parses with", () => {
+    const schema = rememberTool.input_schema;
+
+    expect(schema.required).toEqual(["content"]);
+    expect(schema.properties).toMatchObject({
+      content: {
+        anyOf: [
+          { type: "string" },
+          { type: "array", items: { type: "string" }, minItems: 1 },
+        ],
+      },
+      finish_turn: { type: "boolean" },
+    });
+  });
+});
+
 describe("rememberTool definition — page-hint guidance gating", () => {
   // The rest of this file seeds the v2 flag off; restore that seed.
   afterAll(() => {
@@ -346,14 +461,14 @@ describe("rememberTool definition — page-hint guidance gating", () => {
 
   test("omits the [[slug]] hint guidance in v1/PKB mode", () => {
     setConfig("memory", { v2: { enabled: false } });
-    expect(
-      rememberTool.input_schema.properties.content.description,
-    ).not.toContain("[[slug]]");
+    expect(contentDescription(rememberTool.input_schema)).not.toContain(
+      "[[slug]]",
+    );
   });
 
   test("includes the [[slug]] hint guidance under concept-page memory (v2)", () => {
     setConfig("memory", { v2: { enabled: true } });
-    expect(rememberTool.input_schema.properties.content.description).toContain(
+    expect(contentDescription(rememberTool.input_schema)).toContain(
       "[[slug]] wikilinks",
     );
     // The gate must survive JSON serialization — that's how the schema
@@ -365,7 +480,7 @@ describe("rememberTool definition — page-hint guidance gating", () => {
 
   test("includes the [[slug]] hint guidance when v3 is live with the v2 flag off", () => {
     setConfig("memory", { v2: { enabled: false }, v3: { live: true } });
-    expect(rememberTool.input_schema.properties.content.description).toContain(
+    expect(contentDescription(rememberTool.input_schema)).toContain(
       "[[slug]] wikilinks",
     );
   });
@@ -373,8 +488,8 @@ describe("rememberTool definition — page-hint guidance gating", () => {
   test("re-resolves against config on each read, without re-registration", () => {
     const schema = rememberTool.input_schema;
     setConfig("memory", { v2: { enabled: true } });
-    expect(schema.properties.content.description).toContain("[[slug]]");
+    expect(contentDescription(schema)).toContain("[[slug]]");
     setConfig("memory", { v2: { enabled: false } });
-    expect(schema.properties.content.description).not.toContain("[[slug]]");
+    expect(contentDescription(schema)).not.toContain("[[slug]]");
   });
 });

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

@@ -3,12 +3,14 @@
  *
  * Core, always-loaded tools registered via the host tool manifest
  * (`tools/tool-manifest.ts`), so they carry core/workspace-override precedence
- * and the `"memory"` tool category. Their implementations source from the
- * memory feature (`src/memory/*`).
+ * and the `"memory"` tool category. The host's central input check covers only
+ * tools it can import, which excludes a plugin's, so each tool here parses its
+ * own input.
  */
 
-import { throwIfCancelled } from "@vellumai/plugin-api";
+import { invalidToolInputResult, throwIfCancelled } from "@vellumai/plugin-api";
 
+import { RememberInputSchema } from "../../../api/remember-tool.js";
 import { getConfig, getConfigReadOnly } from "../../../config/loader.js";
 import { usesConceptPageMemory } from "../../../config/memory-v3-gate.js";
 import { RiskLevel } from "../../../permissions/types.js";
@@ -19,8 +21,8 @@ import type {
   ToolExecutionResult,
 } from "../../../tools/types.js";
 import { runAgenticRecall } from "./context-search/agent-runner.js";
-import type { RecallInput } from "./context-search/types.js";
-import { handleRemember, type RememberInput } from "./graph/tool-handlers.js";
+import { RecallInputSchema } from "./context-search/recall-input.js";
+import { handleRemember } from "./graph/tool-handlers.js";
 import {
   buildRememberInputSchema,
   graphRecallDefinition,
@@ -52,18 +54,35 @@ export const rememberTool = {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const typedInput = input as unknown as RememberInput;
     // The append below writes the memory buffer, so a cancelled turn stops here.
     throwIfCancelled(context);
+    if (!resolveCapabilities(context.trustClass).canAccessMemory) {
+      // No yield even when finish_turn is set: the model has to see this, so
+      // it never tells someone a fact was saved when it was not. An error, not
+      // a quiet no-op: a non-error `remember` result reads as a durable write to
+      // `memory-run-evidence`.
+      return {
+        content:
+          "Not saved: remember writes the guardian's long-term memory, which is only available on the guardian's own turns. Retrying will not help. Tell the person only if they asked you to remember this or you said you would.",
+        isError: true,
+      };
+    }
+    const parsed = RememberInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("remember", parsed.error);
+    }
     const result = handleRemember(
-      typedInput,
+      parsed.data,
       context.conversationId,
       getConfig(),
     );
     return {
       content: result.message,
       isError: !result.success,
-      ...(typedInput.finish_turn === true ? { yieldToUser: true } : {}),
+      ...(result.success
+        ? { activityMetadata: { remember: { facts: result.facts } } }
+        : {}),
+      ...(parsed.data.finish_turn === true ? { yieldToUser: true } : {}),
     };
   },
 } satisfies ToolDefinition;
@@ -90,15 +109,23 @@ export const recallTool = {
       };
     }
 
+    const parsed = RecallInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("recall", parsed.error);
+    }
     const config = getConfig();
-    const result = await runAgenticRecall(input as unknown as RecallInput, {
+    const result = await runAgenticRecall(parsed.data, {
       workingDir: context.workingDir,
       conversationId: context.conversationId,
       config,
       signal: context.signal,
     });
 
-    return { content: result.content, isError: false };
+    return {
+      content: result.content,
+      isError: false,
+      activityMetadata: { recall: result.activity },
+    };
   },
 } satisfies ToolDefinition;
 
@@ -127,7 +154,7 @@ export const recallTool = {
 export const deleteMemoryPageTool = {
   name: "delete_memory_page",
   description:
-    "Delete one concept page from your memory wiki, addressed by slug (its path under `memory/concepts/` minus `.md`, e.g. `alice`, `people/alice`, `procs/git-flow`). Use during a consolidation/maintenance pass to retire a page you merged into another, renamed (write the new page, then delete the old slug), or dropped as a dead stub. Only concept pages can be deleted: the index files (`recent.md`, `essentials.md`, `threads.md`) are rewritten with file_write/file_edit, never deleted, and `buffer.md` is never written by you at all; the runtime removes the entries it handed you once the pass completes. Idempotent: deleting a slug that is already gone is not an error. The immutable archive retains buffer history, so removing a page never loses source facts.",
+    "Delete one concept page from your memory wiki, addressed by slug (its path under `memory/concepts/` minus `.md`, e.g. `alice`, `people/alice`, `procs/git-flow`). Use during a consolidation/maintenance pass to retire a page you merged into another, renamed (write the new page, then delete the old slug), or dropped as a dead stub. Only concept pages can be deleted: the index files (`recent.md`, `essentials.md`, `threads.md`) are rewritten with file_write/file_edit, never deleted, and `buffer.md` is never written by you at all; the runtime removes the entries it handed you once the pass completes. Idempotent: deleting a slug that is already gone is not an error.",
   category: "memory",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,