@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/tools/acp/status.ts

@@ -1,11 +1,30 @@
+import { z } from "zod";
+
 import { getAcpSessionManager } from "../../acp/index.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 executeAcpStatus}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools.
+ */
+export const acpStatusInputSchema = z.looseObject({
+  acp_session_id: nullAsOmitted(z.string()),
+});
+
 export async function executeAcpStatus(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acpSessionId = input.acp_session_id as string | undefined;
+  const parsedInput = acpStatusInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("acp_status", parsedInput.error);
+  }
+  const acpSessionId = parsedInput.data.acp_session_id;
   const manager = getAcpSessionManager();
 
   try {

package/src/tools/acp/steer.test.ts

@@ -195,3 +195,23 @@ describe("executeAcpSteer", () => {
     expect(result.content).toContain("is not running");
   });
 });
+
+describe("acp tools — model-input schema validation (LUM-2856)", () => {
+  test("steer rejects a non-string acp_session_id", async () => {
+    const result = await executeAcpSteer(
+      { acp_session_id: 42, instruction: "redirect" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "acp_steer"');
+  });
+
+  test("steer treats explicit null instruction as missing (bespoke error)", async () => {
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-1", instruction: null },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('"instruction" is required');
+  });
+});

package/src/tools/acp/steer.ts

@@ -1,17 +1,38 @@
+import { z } from "zod";
+
 import { getAcpSessionManager } from "../../acp/index.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 import { getSendToClient } from "./context.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeAcpSteer}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools. The bespoke required checks keep their (test-asserted) messages for
+ * the missing/null/empty cases.
+ */
+export const acpSteerInputSchema = z.looseObject({
+  acp_session_id: nullAsOmitted(z.string()),
+  instruction: nullAsOmitted(z.string()),
+});
+
 export async function executeAcpSteer(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acpSessionId = input.acp_session_id as string;
+  const parsedInput = acpSteerInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("acp_steer", parsedInput.error);
+  }
+  const acpSessionId = parsedInput.data.acp_session_id;
   if (!acpSessionId) {
     return { content: '"acp_session_id" is required.', isError: true };
   }
 
-  const instruction = input.instruction as string;
+  const instruction = parsedInput.data.instruction;
   if (!instruction) {
     return { content: '"instruction" is required.', isError: true };
   }

package/src/tools/apps/resolve-app-id.ts

@@ -1,4 +1,7 @@
-import { listAppsByConversation } from "../../apps/app-store.js";
+import {
+  isDirectAppConversation,
+  listAppsByConversation,
+} from "../../apps/app-store.js";
 
 /**
  * Resolve the `app_id` an app-builder tool should operate on.
@@ -14,6 +17,12 @@ import { listAppsByConversation } from "../../apps/app-store.js";
  * Returns `null` when no app_id is supplied and the conversation has no app, so
  * callers can surface an actionable error instead of a raw store throw.
  *
+ * Apps a conversation only inherited — created by a background subagent that
+ * forked from it — rank behind its own. Without that, a background
+ * continuation's freshly created app sits at the head of the parent thread's
+ * list and captures a foreground `app_update` that omitted `app_id`, writing to
+ * an app the user is not looking at.
+ *
  * Not used for destructive operations (`app_delete`): deleting an inferred app
  * is unsafe, so deletion requires an explicit id.
  */
@@ -25,9 +34,12 @@ export function resolveAppId(
     return input.app_id;
   }
   // `listAppsByConversation` preserves `listApps`' updatedAt-descending order,
-  // so the first entry is the app the model is actively working on.
+  // so the first direct entry is the app the model is actively working on.
   const apps = listAppsByConversation(conversationId);
-  return apps.length > 0 ? apps[0].id : null;
+  const direct = apps.find((app) =>
+    isDirectAppConversation(app, conversationId),
+  );
+  return (direct ?? apps[0])?.id ?? null;
 }
 
 /** Error payload returned when no app_id is supplied and none can be inferred. */

package/src/tools/ask-question/ask-question-tool.test.ts

@@ -342,6 +342,71 @@ describe("AskQuestionTool text fallback (supportsDynamicUi === false)", () => {
     expect(calls).toHaveLength(0);
     expect(result.content.toLowerCase()).toContain("no interactive user");
   });
+
+  test("parks a single guardian question on a card-capable channel", async () => {
+    setNextResult(singleCompleted({ decision: "option", optionId: "a" }));
+
+    // A guardian's single-question turn on a channel with a card-rendering
+    // notification adapter parks on the prompter: the guardian-request
+    // pipeline delivers it as a tappable card, so falling back to text would
+    // regress it to an untappable message.
+    await askQuestionTool.execute(
+      validInput,
+      makeContext({
+        supportsDynamicUi: false,
+        supportsGuardianQuestionCards: true,
+        trustClass: "guardian",
+      }),
+    );
+
+    expect(calls).toHaveLength(1);
+  });
+
+  test("text fallback when the channel has no question-card delivery", async () => {
+    const result = await askQuestionTool.execute(
+      validInput,
+      makeContext({
+        supportsDynamicUi: false,
+        supportsGuardianQuestionCards: false,
+        trustClass: "guardian",
+      }),
+    );
+
+    expect(calls).toHaveLength(0);
+    expect(result.content.toLowerCase()).toContain("plain-text");
+  });
+
+  test("text fallback for a non-guardian channel turn even with card delivery", async () => {
+    // The pipeline delivers cards to the guardian; a non-guardian chatter
+    // would never see one, so their turn degrades to text.
+    const result = await askQuestionTool.execute(
+      validInput,
+      makeContext({
+        supportsDynamicUi: false,
+        supportsGuardianQuestionCards: true,
+        trustClass: "trusted_contact",
+      }),
+    );
+
+    expect(calls).toHaveLength(0);
+    expect(result.content.toLowerCase()).toContain("plain-text");
+  });
+
+  test("text fallback for a multi-question batch on a channel", async () => {
+    // One card carries one answer; multi-question batches stay text on
+    // channels (the app card still handles them when dynamic UI is present).
+    const result = await askQuestionTool.execute(
+      { questions: [singleQ, { ...singleQ, question: "Which size?" }] },
+      makeContext({
+        supportsDynamicUi: false,
+        supportsGuardianQuestionCards: true,
+        trustClass: "guardian",
+      }),
+    );
+
+    expect(calls).toHaveLength(0);
+    expect(result.content.toLowerCase()).toContain("plain-text");
+  });
 });
 
 describe("formatQuestionsAsTextFallback", () => {

package/src/tools/ask-question/ask-question-tool.ts

@@ -2,6 +2,10 @@ import { z } from "zod";
 
 import { QuestionPrompter } from "../../permissions/question-prompter.js";
 import { RiskLevel } from "../../permissions/types.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -9,15 +13,21 @@ import type {
 } from "../types.js";
 
 // ── Input schema ────────────────────────────────────────────────────
-// Runtime validation lives in Zod; the wire-level definition surfaced
-// to the LLM is the hand-written JSON Schema in `input_schema` below.
-// (The codebase does not currently use zod-to-json-schema for tool defs,
-// so the two are kept in sync manually.)
+// One Zod source for both runtime validation (via `TOOL_INPUT_SCHEMAS`)
+// and the LLM-facing `input_schema` (derived with `toToolInputSchema`).
 
 const OptionSchema = z.object({
-  id: z.string().min(1),
-  label: z.string().min(1),
-  description: z.string().optional(),
+  id: z
+    .string()
+    .min(1)
+    .describe(
+      "Stable identifier for this option (returned verbatim in the response).",
+    ),
+  label: z.string().min(1).describe("Short human-readable label."),
+  description: z
+    .string()
+    .describe("Optional one-line context shown beneath the label.")
+    .optional(),
 });
 
 // One question in a (possibly single-element) batch. Intentionally has no
@@ -26,13 +36,27 @@ const OptionSchema = z.object({
 // smaller and removes a validation surface (no duplicate-id check, no
 // length cap on ids).
 const SingleQuestionSchema = z.object({
-  question: z.string().min(1),
-  description: z.string().optional(),
+  question: z.string().min(1).describe("The clarifying question to display."),
+  description: z
+    .string()
+    .describe("Optional one-line context shown beneath the question.")
+    .optional(),
   // 2–4 LLM-supplied options. The client renders a fixed 5th "Type
   // something else" slot for free-text, so the model must keep the
   // structured set to 4 or fewer.
-  options: z.array(OptionSchema).min(2).max(4),
-  freeTextPlaceholder: z.string().optional(),
+  options: z
+    .array(OptionSchema)
+    .min(2)
+    .max(4)
+    .describe(
+      "2–4 structured options. The UI always appends a free-text fallback slot, so do not include a 'something else' option here.",
+    ),
+  freeTextPlaceholder: z
+    .string()
+    .describe(
+      "Optional placeholder text shown inside the free-text fallback input.",
+    )
+    .optional(),
 });
 
 // Cap at 5 questions per batch. Past that it starts to feel like a form,
@@ -41,18 +65,22 @@ const SingleQuestionSchema = z.object({
 const MAX_QUESTIONS_PER_BATCH = 5;
 
 // Callers pass a (possibly single-element) batch of questions. `execute()`
-// forwards them straight to the prompter.
-const InputSchema = z.object({
+// forwards them straight to the prompter. Loose so injected fields (e.g.
+// `activity`) never fail validation.
+export const askQuestionInputSchema = z.looseObject({
   questions: z
     .array(SingleQuestionSchema)
     .min(1)
     .max(MAX_QUESTIONS_PER_BATCH, {
       message: `At most ${MAX_QUESTIONS_PER_BATCH} questions per batch; split into multiple turns if you need more.`,
-    }),
+    })
+    .describe(
+      `1–${MAX_QUESTIONS_PER_BATCH} clarifying questions to ask in a single turn. Use a batch when several independent ambiguities block progress; ask one at a time when they're sequentially dependent. Past ${MAX_QUESTIONS_PER_BATCH} questions you should be implementing, not asking.`,
+    ),
 });
 
 export type SingleQuestion = z.infer<typeof SingleQuestionSchema>;
-export type AskQuestionInput = z.infer<typeof InputSchema>;
+export type AskQuestionInput = z.infer<typeof askQuestionInputSchema>;
 
 // ── Tool description ────────────────────────────────────────────────
 
@@ -92,27 +120,6 @@ const DESCRIPTION = [
   "context shown beneath the label.",
 ].join("\n");
 
-// Option-schema fragment for the items in `questions[].options`.
-const OPTION_ITEMS_SCHEMA = {
-  type: "object",
-  properties: {
-    id: {
-      type: "string",
-      description:
-        "Stable identifier for this option (returned verbatim in the response).",
-    },
-    label: {
-      type: "string",
-      description: "Short human-readable label.",
-    },
-    description: {
-      type: "string",
-      description: "Optional one-line context shown beneath the label.",
-    },
-  },
-  required: ["id", "label"],
-} as const;
-
 // ── Text fallback for channels without dynamic UI ───────────────────
 
 /**
@@ -168,57 +175,15 @@ export const askQuestionTool = {
   category: "interaction",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
-  input_schema: {
-    type: "object",
-    properties: {
-      questions: {
-        type: "array",
-        minItems: 1,
-        maxItems: MAX_QUESTIONS_PER_BATCH,
-        description: `1–${MAX_QUESTIONS_PER_BATCH} clarifying questions to ask in a single turn. Use a batch when several independent ambiguities block progress; ask one at a time when they're sequentially dependent. Past ${MAX_QUESTIONS_PER_BATCH} questions you should be implementing, not asking.`,
-        items: {
-          type: "object",
-          properties: {
-            question: {
-              type: "string",
-              description: "The clarifying question to display.",
-            },
-            description: {
-              type: "string",
-              description:
-                "Optional one-line context shown beneath the question.",
-            },
-            options: {
-              type: "array",
-              minItems: 2,
-              maxItems: 4,
-              description:
-                "2–4 structured options. The UI always appends a free-text fallback slot, so do not include a 'something else' option here.",
-              items: OPTION_ITEMS_SCHEMA,
-            },
-            freeTextPlaceholder: {
-              type: "string",
-              description:
-                "Optional placeholder text shown inside the free-text fallback input.",
-            },
-          },
-          required: ["question", "options"],
-        },
-      },
-    },
-    required: ["questions"],
-  },
+  input_schema: toToolInputSchema(askQuestionInputSchema),
 
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const parsed = InputSchema.safeParse(input);
+    const parsed = askQuestionInputSchema.safeParse(input);
     if (!parsed.success) {
-      return {
-        content: `Invalid input: ${parsed.error.message}`,
-        isError: true,
-      };
+      return invalidToolInputResult("ask_question", parsed.error);
     }
 
     const questions: SingleQuestion[] = parsed.data.questions;
@@ -236,17 +201,28 @@ export const askQuestionTool = {
       };
     }
 
-    // The active channel can't render the interactive question card (e.g.
-    // Telegram, SMS). A broadcast question_request would reach app clients but
-    // never the channel the turn came from, so the user would see nothing.
-    // Degrade to text: hand the model the formatted question(s) and options to
-    // present in its reply — which IS what gets delivered to the channel — and
-    // wait for a free-text answer. Mirrors the isInteractive guard above:
-    // return immediately instead of parking on a prompt the surface can't
-    // answer. (UI surface tools like ui_show are instead dropped from the wire
-    // for these channels; ask_question stays available because a question with
-    // options reads cleanly as text.)
-    if (context.supportsDynamicUi === false) {
+    // Channel turns (no dynamic UI) park only when the question can reach the
+    // user as a guardian-request card with tappable options: a single-question
+    // batch, asked by the guardian, on a channel whose notification adapter
+    // renders card actions. The prompter's promotion then delivers the card
+    // through the guardian-request pipeline, and a tap / request-code reply /
+    // bare-text answer resolves the parked prompt.
+    //
+    // Every other channel turn degrades to text: hand the model the formatted
+    // question(s) and options to present in its reply — which IS what gets
+    // delivered to the channel — and wait for a free-text answer. Mirrors the
+    // isInteractive guard above: return immediately instead of parking on a
+    // prompt the surface can't answer. (UI surface tools like ui_show are
+    // instead dropped from the wire for these channels; ask_question stays
+    // available because a question with options reads cleanly as text.)
+    const canDeliverGuardianQuestionCard =
+      questions.length === 1 &&
+      context.trustClass === "guardian" &&
+      context.supportsGuardianQuestionCards === true;
+    if (
+      context.supportsDynamicUi === false &&
+      !canDeliverGuardianQuestionCard
+    ) {
       return {
         content: formatQuestionsAsTextFallback(questions),
         isError: false,

package/src/tools/browser/browser-screencast.ts

@@ -1,11 +1,11 @@
-import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { AssistantEvent } from "../../api/index.js";
 import { browserManager } from "./browser-manager.js";
 
 // Track which conversations have an active browser page.
 const activeBrowserConversations = new Set<string>();
 
 // Registry of sendToClient callbacks per conversation
-const conversationSenders = new Map<string, (msg: ServerMessage) => void>();
+const conversationSenders = new Map<string, (msg: AssistantEvent) => void>();
 
 /**
  * Register a sendToClient callback for a conversation.
@@ -13,7 +13,7 @@ const conversationSenders = new Map<string, (msg: ServerMessage) => void>();
  */
 export function registerConversationSender(
   conversationId: string,
-  sendToClient: (msg: ServerMessage) => void,
+  sendToClient: (msg: AssistantEvent) => void,
 ): void {
   conversationSenders.set(conversationId, sendToClient);
 }
@@ -27,12 +27,12 @@ export function unregisterConversationSender(conversationId: string): void {
 
 function getSender(
   conversationId: string,
-): ((msg: ServerMessage) => void) | undefined {
+): ((msg: AssistantEvent) => void) | undefined {
   return conversationSenders.get(conversationId);
 }
 
 export async function ensureScreencast(conversationId: string): Promise<void> {
-  if (activeBrowserConversations.has(conversationId)) return;
+  if (activeBrowserConversations.has(conversationId)) {return;}
 
   activeBrowserConversations.add(conversationId);
 
@@ -49,7 +49,7 @@ export async function ensureScreencast(conversationId: string): Promise<void> {
 export async function stopBrowserScreencast(
   conversationId: string,
 ): Promise<void> {
-  if (!activeBrowserConversations.has(conversationId)) return;
+  if (!activeBrowserConversations.has(conversationId)) {return;}
 
   // Safe no-op if CDP screencast was never started
   await browserManager.stopScreencast(conversationId);

package/src/tools/calls/call-end.ts

@@ -1,19 +1,40 @@
+import { z } from "zod";
+
 import { cancelCall } from "../../calls/call-domain.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 executeCallEnd}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools. The bespoke required check below keeps its error message for the
+ * missing/null/empty cases.
+ */
+export const callEndInputSchema = z.looseObject({
+  call_session_id: nullAsOmitted(z.string()),
+  end_reason: nullAsOmitted(z.string()),
+});
+
 export async function executeCallEnd(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const callSessionId = input.call_session_id as string | undefined;
-  if (!callSessionId || typeof callSessionId !== "string") {
+  const parsedInput = callEndInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("call_end", parsedInput.error);
+  }
+  const callSessionId = parsedInput.data.call_session_id;
+  if (!callSessionId) {
     return {
       content: "Error: call_session_id is required and must be a string",
       isError: true,
     };
   }
 
-  const reason = input.end_reason as string | undefined;
+  const reason = parsedInput.data.end_reason;
 
   const result = await cancelCall({ callSessionId, reason });
 

package/src/tools/calls/call-start.ts

@@ -1,9 +1,33 @@
+import { z } from "zod";
+
 import { startCall } from "../../calls/call-domain.js";
 import { findActiveSession } from "../../channels/gateway-verification-sessions.js";
 import { getConfig } from "../../config/loader.js";
 import { normalizePhoneNumber } from "../../util/phone.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 executeCallStart}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools — see the schema block in `tools/document/document-tool.ts` for the
+ * framework. The advertised-required fields are required here — schema
+ * rejection is the only guard between a mistyped `phone_number`/`task` and
+ * `startCall`. `skip_disclosure` (deliberate `=== true` coercion) is
+ * UNDECLARED — loose passthrough.
+ */
+export const callStartInputSchema = z.looseObject({
+  phone_number: z.string(),
+  task: z.string(),
+  context: nullAsOmitted(z.string()),
+  caller_identity_mode: nullAsOmitted(
+    z.enum(["assistant_number", "user_number"]),
+  ),
+});
+
 export async function executeCallStart(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -16,10 +40,13 @@ export async function executeCallStart(
     };
   }
 
-  const requestedPhone =
-    typeof input.phone_number === "string"
-      ? normalizePhoneNumber(input.phone_number)
-      : null;
+  const parsedInput = callStartInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("call_start", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+
+  const requestedPhone = normalizePhoneNumber(parsed.phone_number);
   if (requestedPhone) {
     const activeVoiceVerification = await findActiveSession("phone");
     const verificationDestination =
@@ -37,15 +64,12 @@ export async function executeCallStart(
   }
 
   const result = await startCall({
-    phoneNumber: input.phone_number as string,
-    task: input.task as string,
-    context: input.context as string | undefined,
+    phoneNumber: parsed.phone_number,
+    task: parsed.task,
+    context: parsed.context,
     conversationId: context.conversationId,
     assistantId: context.assistantId,
-    callerIdentityMode: input.caller_identity_mode as
-      | "assistant_number"
-      | "user_number"
-      | undefined,
+    callerIdentityMode: parsed.caller_identity_mode,
     skipDisclosure: input.skip_disclosure === true,
   });
 

package/src/tools/calls/call-status.ts

@@ -1,11 +1,30 @@
+import { z } from "zod";
+
 import { getCallStatus } from "../../calls/call-domain.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 executeCallStatus}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools.
+ */
+export const callStatusInputSchema = z.looseObject({
+  call_session_id: nullAsOmitted(z.string()),
+});
+
 export async function executeCallStatus(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const callSessionId = input.call_session_id as string | undefined;
+  const parsedInput = callStatusInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("call_status", parsedInput.error);
+  }
+  const callSessionId = parsedInput.data.call_session_id;
 
   const result = getCallStatus(callSessionId, context.conversationId);