@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/tools/conversation-groups/group_create.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+import { createGroup, listGroups } from "../../persistence/group-crud.js";
+import { publishConversationListChanged } from "../../runtime/sync/resource-sync-events.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+
+/**
+ * Model-input schema, `safeParse`d at the top of
+ * {@link executeConversationGroupCreate}. Same in-tool pattern and TOOLS.json
+ * drift guard as the other bundled-skill tools. The bespoke non-empty (trim)
+ * check keeps its own error message.
+ */
+export const conversationGroupCreateInputSchema = z.looseObject({
+  name: nullAsOmitted(z.string()),
+});
+
+export async function executeConversationGroupCreate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const parsedInput = conversationGroupCreateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult(
+      "conversation_group_create",
+      parsedInput.error,
+    );
+  }
+
+  const name = parsedInput.data.name?.trim();
+  if (!name) {
+    return {
+      content: "Error: name is required and must be a non-empty string",
+      isError: true,
+    };
+  }
+
+  const existing = listGroups().find(
+    (g) => g.name.trim().toLowerCase() === name.toLowerCase(),
+  );
+  if (existing?.isSystemGroup) {
+    return {
+      content: `Error: "${existing.name}" is a built-in system group and cannot be recreated. Move conversations into it directly with conversation_move_to_group.`,
+      isError: true,
+    };
+  }
+  if (existing) {
+    return {
+      content: `Group "${existing.name}" already exists (id: ${existing.id}). Reusing it — no new group was created.`,
+      isError: false,
+    };
+  }
+
+  const group = createGroup(name);
+  publishConversationListChanged("created");
+  return {
+    content: `Created group "${group.name}" (id: ${group.id}). It now appears in the sidebar; use conversation_move_to_group to file conversations into it.`,
+    isError: false,
+  };
+}

package/src/tools/conversation-groups/group_list.ts

@@ -0,0 +1,20 @@
+import { listGroups } from "../../persistence/group-crud.js";
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+import { formatGroupList } from "./group_shared.js";
+
+export async function executeConversationGroupList(
+  _input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const groups = listGroups();
+  return {
+    content:
+      "Conversation groups (sidebar order):\n" +
+      formatGroupList(groups) +
+      "\n\nSystem groups are built in: Pinned pins a conversation, Recents " +
+      "(system:all) is the default ungrouped section, and Scheduled/" +
+      "Background hold automated conversations. Custom groups are " +
+      "user-defined sections.",
+    isError: false,
+  };
+}

package/src/tools/conversation-groups/group_shared.ts

@@ -0,0 +1,52 @@
+import {
+  type ConversationGroupRow,
+  listGroups,
+} from "../../persistence/group-crud.js";
+
+/**
+ * Resolve a model-supplied group reference (id or name) against the current
+ * group list. Name matching is case-insensitive on the trimmed input; an id
+ * match always wins. Returns an error string (for the tool result) when the
+ * reference is missing or ambiguous.
+ */
+export function resolveGroupReference(
+  reference: string,
+): { group: ConversationGroupRow } | { error: string } {
+  const groups = listGroups();
+  const trimmed = reference.trim();
+
+  const byId = groups.find((g) => g.id === trimmed);
+  if (byId) {
+    return { group: byId };
+  }
+
+  const lowered = trimmed.toLowerCase();
+  const byName = groups.filter((g) => g.name.trim().toLowerCase() === lowered);
+  if (byName.length === 1) {
+    return { group: byName[0] };
+  }
+  if (byName.length > 1) {
+    return {
+      error:
+        `Group name "${trimmed}" is ambiguous. Matching groups:\n` +
+        byName.map((g) => `- ${g.name} (id: ${g.id})`).join("\n") +
+        "\nRetry with the group id.",
+    };
+  }
+
+  return {
+    error:
+      `No group named "${trimmed}". Available groups:\n` +
+      formatGroupList(groups) +
+      "\nUse conversation_group_create to create a new group.",
+  };
+}
+
+export function formatGroupList(groups: ConversationGroupRow[]): string {
+  return groups
+    .map(
+      (g) =>
+        `- ${g.name} (id: ${g.id})${g.isSystemGroup ? " [system group]" : ""}`,
+    )
+    .join("\n");
+}

package/src/tools/conversation-groups/move_to_group.ts

@@ -0,0 +1,106 @@
+import { z } from "zod";
+
+import {
+  batchSetDisplayOrders,
+  getConversation,
+  getDisplayMetaForConversations,
+} from "../../persistence/conversation-crud.js";
+import { publishConversationListAndMetadataChanged } from "../../runtime/sync/resource-sync-events.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+import { resolveGroupReference } from "./group_shared.js";
+
+/**
+ * Model-input schema, `safeParse`d at the top of
+ * {@link executeConversationMoveToGroup}. Same in-tool pattern and TOOLS.json
+ * drift guard as the other bundled-skill tools.
+ */
+export const conversationMoveToGroupInputSchema = z.looseObject({
+  group: nullAsOmitted(z.string()),
+  conversation_id: nullAsOmitted(z.string()),
+});
+
+export async function executeConversationMoveToGroup(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const parsedInput = conversationMoveToGroupInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult(
+      "conversation_move_to_group",
+      parsedInput.error,
+    );
+  }
+
+  const groupRef = parsedInput.data.group?.trim();
+  if (!groupRef) {
+    return {
+      content: "Error: group is required (a group name or group id)",
+      isError: true,
+    };
+  }
+
+  const resolved = resolveGroupReference(groupRef);
+  if ("error" in resolved) {
+    return { content: `Error: ${resolved.error}`, isError: true };
+  }
+  const group = resolved.group;
+
+  const conversationId =
+    parsedInput.data.conversation_id?.trim() || context.conversationId;
+  const conversation = getConversation(conversationId);
+  if (!conversation) {
+    return {
+      content: `Error: no conversation found with id ${conversationId}`,
+      isError: true,
+    };
+  }
+
+  const label = conversation.title
+    ? `"${conversation.title}"`
+    : `conversation ${conversationId}`;
+
+  const meta = getDisplayMetaForConversations([conversationId]).get(
+    conversationId,
+  );
+  if (meta?.groupId === group.id) {
+    return {
+      content: `${label} is already in group "${group.name}".`,
+      isError: false,
+    };
+  }
+
+  // Preserve the conversation's manual sort slot across the move; only the
+  // group assignment changes.
+  batchSetDisplayOrders([
+    {
+      id: conversationId,
+      displayOrder: meta?.displayOrder ?? null,
+      groupId: group.id,
+    },
+  ]);
+  publishConversationListAndMetadataChanged("reordered", [conversationId]);
+
+  const notes: string[] = [];
+  if (group.id === "system:pinned") {
+    notes.push("It is now pinned.");
+  }
+  if (group.id === "system:scheduled" || group.id === "system:background") {
+    notes.push(
+      `Moving into ${group.name} demotes it out of the Recents listing.`,
+    );
+  }
+  if (conversation.conversationType !== "standard") {
+    notes.push(
+      `Note: this is a ${conversation.conversationType} conversation, which stays hidden from the sidebar regardless of group.`,
+    );
+  }
+
+  return {
+    content: [`Moved ${label} to group "${group.name}".`, ...notes].join(" "),
+    isError: false,
+  };
+}

package/src/tools/document/document-comment-tool.test.ts

@@ -375,3 +375,52 @@ describe("executeCommentReply", () => {
     expect(body.comment.content).toBe("Answer");
   });
 });
+
+// ── model-input schema validation (LUM-2854) ────────────────────────
+
+describe("comment tools — model-input schema validation", () => {
+  test("comment_list rejects a missing surface_id instead of 'Document not found'", () => {
+    const result = executeCommentList({}, makeContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "comment_list"');
+    expect(result.content).toContain("surface_id");
+  });
+
+  test("comment_resolve rejects a non-string comment_id", () => {
+    const result = executeCommentResolve(
+      { surface_id: SURFACE_ID, comment_id: 42 },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Invalid input for tool "comment_resolve"',
+    );
+    expect(result.content).toContain("comment_id");
+  });
+
+  test("comment_reply rejects a non-string content instead of persisting it", () => {
+    const parent = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user",
+      content: "Question",
+    });
+
+    const result = executeCommentReply(
+      { surface_id: SURFACE_ID, comment_id: parent.id, content: 42 },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "comment_reply"');
+    expect(result.content).toContain("content");
+    expect(listComments(SURFACE_ID, {}).length).toBe(1);
+  });
+
+  test("comment tools pass unknown keys through (loose schema)", () => {
+    const result = executeCommentList(
+      { surface_id: SURFACE_ID, activity: "checking comments" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+  });
+});

package/src/tools/document/document-comment-tool.ts

@@ -1,19 +1,49 @@
+import { z } from "zod";
+
 import {
   createComment,
   getComment,
   listComments,
   resolveComment,
 } from "../../documents/document-comments-store.js";
+import { invalidToolInputResult } from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 import { canAccessDocument, documentNotFound } from "./document-tool.js";
 
+// ── Model-input schemas ────────────────────────────────────────────────
+//
+// `safeParse`d at the top of each `execute*` — same in-tool pattern and
+// drift guard as `document-tool.ts` (see the schema block there for the
+// framework). Every advertised-required field is required here; without
+// schema rejection a missing/mistyped field would fall through to a
+// misleading "Document not found".
+
+export const commentListInputSchema = z.looseObject({
+  surface_id: z.string(),
+});
+
+export const commentResolveInputSchema = z.looseObject({
+  surface_id: z.string(),
+  comment_id: z.string(),
+});
+
+export const commentReplyInputSchema = z.looseObject({
+  surface_id: z.string(),
+  comment_id: z.string(),
+  content: z.string(),
+});
+
 // ── Exported execute functions ─────────────────────────────────────────
 
 export function executeCommentList(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const parsedInput = commentListInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("comment_list", parsedInput.error);
+  }
+  const surfaceId = parsedInput.data.surface_id;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -46,8 +76,11 @@ export function executeCommentResolve(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
-  const commentId = input.comment_id as string;
+  const parsedInput = commentResolveInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("comment_resolve", parsedInput.error);
+  }
+  const { surface_id: surfaceId, comment_id: commentId } = parsedInput.data;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -91,9 +124,15 @@ export function executeCommentReply(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
-  const commentId = input.comment_id as string;
-  const content = input.content as string;
+  const parsedInput = commentReplyInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("comment_reply", parsedInput.error);
+  }
+  const {
+    surface_id: surfaceId,
+    comment_id: commentId,
+    content,
+  } = parsedInput.data;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);

package/src/tools/document/document-tool.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
 
+import { z } from "zod";
+
 import {
   addDocumentConversation,
   deleteDocument,
@@ -14,6 +16,10 @@ import {
   updateDocumentContent,
 } from "../../documents/document-store.js";
 import { canActOnPrivilegedDocuments } from "../../runtime/effective-capabilities.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 function isPrivilegedDocumentActor(context: ToolContext): boolean {
@@ -62,14 +68,83 @@ function validateSurfaceId(
   return input.surface_id;
 }
 
+// ── Model-input schemas ─────────────────────────────────────────────
+//
+// One schema per tool entry point, `safeParse`d at the top of each
+// `execute*`. Skill-owned tools are skipped by the central
+// `TOOL_INPUT_SCHEMAS` gate, so validation lives in the executor
+// (`ask_question` pre-registry precedent); the advertised `input_schema`
+// stays hand-written in the document-editor skill's `TOOLS.json`, and
+// `document-tool-input-schemas.test.ts` guards the two against structural
+// drift.
+//
+// Tolerance matches the executors' own reads — the schemas only reject
+// values the executors would otherwise pass downstream unchecked
+// (`document_find`'s `query` reaching `.toLowerCase()` as a non-string) or
+// persist unvalidated (`document_create`'s `title`):
+//
+// - `nullAsOmitted` on optionals where null and absent are equivalent under
+//   the falsy/`??` reads — including `surface_id`, whose bespoke
+//   `validateSurfaceId` / `resolveUpdateSurfaceId` error messages stay the
+//   contract for the missing/empty cases.
+// - `.catch(undefined)` on `document_list`'s `query`, which the executor
+//   silently ignores when malformed (falls back to the conversation list).
+// - `document_update`'s `mode` is deliberately UNDECLARED (loose
+//   passthrough): its bespoke check owns the error message and the
+//   `{ mode: null }` tolerance that mirrors `validateInputAgainstSchema`.
+
+export const documentOpenInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+});
+
+export const documentCreateInputSchema = z.looseObject({
+  title: nullAsOmitted(z.string()),
+  initial_content: nullAsOmitted(z.string()),
+});
+
+export const documentUpdateInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  content: nullAsOmitted(z.string()),
+});
+
+export const documentReadInputSchema = documentOpenInputSchema;
+
+export const documentListInputSchema = z.looseObject({
+  query: z.string().optional().catch(undefined),
+});
+
+export const documentDeleteInputSchema = documentOpenInputSchema;
+
+export const documentFindInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  query: z.string(),
+  regex: nullAsOmitted(z.boolean()),
+  case_sensitive: nullAsOmitted(z.boolean()),
+});
+
+export const documentReplaceTextInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  find: z.string(),
+  replace: nullAsOmitted(z.string()),
+  regex: nullAsOmitted(z.boolean()),
+  case_sensitive: nullAsOmitted(z.boolean()),
+  max_replacements: nullAsOmitted(z.number()),
+});
+
 // ── Exported execute functions ──────────────────────────────────────
 
 export function executeDocumentOpen(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentOpenInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_open", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -140,17 +215,23 @@ function maybeReuseEmptyDocument(
   initialContent: string,
   context: ToolContext,
 ): ToolExecutionResult | null {
-  if (initialContent.length === 0) return null;
+  if (initialContent.length === 0) {
+    return null;
+  }
   const existing = findRecentEmptyDocumentByTitle(
     context.conversationId,
     title,
     EMPTY_DOCUMENT_DEDUPE_WINDOW_MS,
   );
-  if (!existing) return null;
+  if (!existing) {
+    return null;
+  }
 
   const surfaceId = existing.surfaceId;
   const update = updateDocumentContent(surfaceId, initialContent, "replace");
-  if (!update.success) return null;
+  if (!update.success) {
+    return null;
+  }
 
   // Defensive idempotent insert (saveDocument from the create-new path already
   // ran addDocumentConversation; INSERT OR IGNORE makes this a safe no-op).
@@ -200,11 +281,17 @@ export function executeDocumentCreate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const title = (input.title as string | undefined) || "Untitled Document";
-  const initialContent = (input.initial_content as string | undefined) || "";
+  const parsedInput = documentCreateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_create", parsedInput.error);
+  }
+  const title = parsedInput.data.title || "Untitled Document";
+  const initialContent = parsedInput.data.initial_content || "";
 
   const reused = maybeReuseEmptyDocument(title, initialContent, context);
-  if (reused) return reused;
+  if (reused) {
+    return reused;
+  }
 
   const surfaceId = `doc-${randomUUID()}`;
 
@@ -298,11 +385,17 @@ export function executeDocumentUpdate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentUpdateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_update", parsedInput.error);
+  }
   if (typeof input.content !== "string") {
     return invalidInput("content is required and must be a string");
   }
   const surfaceIdOrError = resolveUpdateSurfaceId(input, context);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   // Loose `!= null` to match validateInputAgainstSchema, which treats null as
   // "absent" for enum checks — without this, { mode: null } passes the
@@ -368,8 +461,14 @@ export function executeDocumentRead(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentReadInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_read", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -396,10 +495,11 @@ export function executeDocumentList(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const query =
-    typeof input.query === "string" && input.query.trim().length > 0
-      ? input.query.trim()
-      : undefined;
+  const parsedInput = documentListInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_list", parsedInput.error);
+  }
+  const query = parsedInput.data.query?.trim() || undefined;
   const docs = query
     ? searchDocumentsByTitle(
         query,
@@ -427,8 +527,14 @@ export function executeDocumentDelete(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentDeleteInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_delete", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -452,12 +558,18 @@ export function executeDocumentFind(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentFindInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_find", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
-  const query = input.query as string;
-  const regex = (input.regex as boolean | undefined) ?? false;
-  const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
+  const query = parsedInput.data.query;
+  const regex = parsedInput.data.regex ?? false;
+  const caseSensitive = parsedInput.data.case_sensitive ?? false;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -505,14 +617,20 @@ export function executeDocumentReplaceText(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentReplaceTextInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_replace_text", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
-  const find = input.find as string;
-  const replace = (input.replace as string) ?? "";
-  const regex = (input.regex as boolean | undefined) ?? false;
-  const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
-  const maxReplacements = input.max_replacements as number | undefined;
+  const find = parsedInput.data.find;
+  const replace = parsedInput.data.replace ?? "";
+  const regex = parsedInput.data.regex ?? false;
+  const caseSensitive = parsedInput.data.case_sensitive ?? false;
+  const maxReplacements = parsedInput.data.max_replacements;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);